gaspersic/freeCodeCamp
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

feat: update challenge helpers to handle id filenames (#44769)

Browse Source 
* refactor: light tweaks for readability

* refactor: simplify metadata functions

* fix: most tests

* test: fix utils tests

* test: simplify mocks

* WIP: update get-last-step-file-content

* feat: finish create-next-step

* fix: type error

* test: provide mock meta.json for test

* refactor: get meta path from project path

* refactor: get project name from path

* refactor: simplify getProjectMetaPath further

Also removes some excessive mocking

* refactor: remove more mocks, always clear .env

* feat: update create-next-step

* feat: update create-empty steps

Also refactors slightly, so it's easier to insert steps into the meta

* docs: update challenge-helper-script docs

* feat: create-step-between

* refactor: allow metadata parse errors to propagate

* fix: convert reorderSteps to renameSteps

* refactor: create-step-between -> insert-step

* feat: update delete-step

* refactor: consolidate commands into commands.ts

* refactor: clean up and consolidation

* refactor: more cleanup

* fix: make cli args consistent

Everything accepts a single integer and nothing else

* refactor: renameSteps -> updateStepTitles

* docs: update with the names and args

* feat: add step validating meta + files are synced
This commit is contained in:
Oliver Eyton-Williams
2022-03-02 16:12:20 +01:00
committed by GitHub
parent 16e7cdedb1
commit 339c6713d2
35 changed files with 535 additions and 724 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
tools/challenge-helper-scripts/helpers/get-arg-value.test.ts Normal file
View File

@ -0,0 +1,18 @@
import { getArgValue } from './get-arg-value';
describe('getArgValue helper', () => {
it('should throw if there no arguments', () => {
const args = ['/Path/to/node', '/Path/to/script'];
expect(() => getArgValue(args)).toThrow('only one argument allowed');
});
it('should throw if the argument is not an integer', () => {
expect.assertions(3);
const args = ['/Path/to/node', '/Path/to/script', 'num=4'];
expect(() => getArgValue(args)).toThrow('argument must be an integer');
const args2 = ['/Path/to/node', '/Path/to/script', '4.1'];
expect(() => getArgValue(args2)).toThrow('argument must be an integer');
const args3 = ['/Path/to/node', '/Path/to/script', '4'];
expect(getArgValue(args3)).toBe(4);
});
});

11
tools/challenge-helper-scripts/helpers/get-arg-value.ts Normal file
View File

@ -0,0 +1,11 @@
const isIntRE = /^\d+$/;
function getArgValue(argv: string[] = []): number {
if (argv.length !== 3) throw `only one argument allowed`;
const value = argv[2];
const intValue = parseInt(value, 10);
if (!isIntRE.test(value) || !Number.isInteger(intValue))
throw `argument must be an integer`;
return intValue;
}
export { getArgValue };

34
tools/challenge-helper-scripts/helpers/get-arg-values.test.ts
View File

@ -1,34 +0,0 @@
import { getArgValues } from './get-arg-values';
describe('getArgValues helper', () => {
it('should be able to run if there are no values to process', () => {
const args = ['/Path/to/node', '/Path/to/script'];
expect(getArgValues(args)).toEqual({});
expect(getArgValues()).toEqual({});
});
it('should parse the third element (key/value) if provided', () => {
const args = ['/Path/to/node', '/Path/to/script', 'num=4'];
expect(getArgValues(args)).toEqual({ num: '4' });
});
it('should parse multiple arguments (key/value) if provided', () => {
const args = ['/Path/to/node', '/Path/to/script', 'num=4', 'another=5'];
expect(getArgValues(args)).toEqual({ another: '5', num: '4' });
});
it('should parse the arguments with spaces (key/value) if provided', () => {
const args = ['/Path/to/node', '/Path/to/script', 'num = 3'];
expect(getArgValues(args)).toEqual({ num: '3' });
});
it('should throw error on invalid key/value arguments', () => {
const items = [
['/Path/to/node', '/Path/to/script', 'num='],
['/Path/to/node', '/Path/to/script', '='],
['/Path/to/node', '/Path/to/script', 'num=2', '= 3']
];
items.forEach(item => expect(() => getArgValues(item)).toThrow());
});
});

15
tools/challenge-helper-scripts/helpers/get-arg-values.ts
View File

@ -1,15 +0,0 @@
// Creates an object with the values starting at the third position of argv,
// ['lorem', 'ipsum', 'one=1', 'two=2', ...] => { one: 1, two: 2, ...}
function getArgValues(argv: string[] = []): Record<string, string> {
return argv.slice(2).reduce((argsObj, arg) => {
const [argument, value] = arg.replace(/\s/g, '').split('=');
if (!argument || !value) {
throw `Invalid argument/value specified: ${arg}`;
}
return { ...argsObj, [argument]: value };
}, {});
}
export { getArgValues };

74
tools/challenge-helper-scripts/helpers/get-existing-step-nums.test.ts
View File

@ -1,74 +0,0 @@
import mock from 'mock-fs';
import { getExistingStepNums } from './get-existing-step-nums';
// NOTE:
// Use `console.log()` before mocking the filesystem or use
// `process.stdout.write()` instead. There are issues when using `mock-fs` and
// `require`.
describe('getExistingStepNums helper', () => {
it('should return the number portion of the project paths', () => {
mock({
'mock-project': {
'step-001.md': 'Lorem ipsum...',
'step-002.md': 'Lorem ipsum...'
}
});
const folder = `${process.cwd()}/mock-project/`;
const steps = getExistingStepNums(folder);
const expected = [1, 2];
expect(steps).toEqual(expected);
});
it('should ignore text formatting and files named final.md', () => {
mock({
'mock-project': {
'final.md': 'Lorem ipsum...',
'step-001.md': 'Lorem ipsum...'
}
});
const folder = `${process.cwd()}/mock-project/`;
const steps = getExistingStepNums(folder);
const expected = [1];
expect(steps).toEqual(expected);
});
it('should throw if file names do not follow naming convention', () => {
mock({
'mock-project': {
'step-001.md': 'Lorem ipsum...',
'step-002.md': 'Lorem ipsum...',
'step002.md': 'Lorem ipsum...'
}
});
const folder = `${process.cwd()}/mock-project/`;
expect(() => {
getExistingStepNums(folder);
}).toThrow();
});
it('should return empty array if there are no markdown files', () => {
mock({
'mock-project': {
'step-001.js': 'Lorem ipsum...',
'step-002.css': 'Lorem ipsum...'
}
});
const folder = `${process.cwd()}/mock-project/`;
const steps = getExistingStepNums(folder);
const expected: number[] = [];
expect(steps).toEqual(expected);
});
afterEach(() => {
mock.restore();
});
});

30
tools/challenge-helper-scripts/helpers/get-existing-step-nums.ts
View File

@ -1,30 +0,0 @@
import fs from 'fs';
import path from 'path';
// Generates an array with the output of processing filenames with an expected
// format (`step-###.md`).
// ['step-001.md', 'step-002.md'] => [1, 2]
function getExistingStepNums(projectPath: string): number[] {
return fs.readdirSync(projectPath).reduce((stepNums, fileName) => {
if (
path.extname(fileName).toLowerCase() === '.md' &&
!fileName.endsWith('final.md')
) {
const stepNumString = fileName.split('.')[0].split('-')[1];
if (!/^\d{3}$/.test(stepNumString)) {
throw (
`Step not created. File ${fileName} has a step number containing non-digits.` +
' Please run reorder-steps script first.'
);
}
const stepNum = parseInt(stepNumString, 10);
stepNums.push(stepNum);
}
return stepNums;
}, [] as number[]);
}
export { getExistingStepNums };

57
tools/challenge-helper-scripts/helpers/get-last-step-file-content.test.ts
View File

@ -1,57 +0,0 @@
import mock from 'mock-fs';
import { getLastStepFileContent } from './get-last-step-file-content';
jest.mock('./get-project-path', () => {
return {
getProjectPath: jest.fn(() => 'mock-project/')
};
});
jest.mock('../utils', () => {
return {
getChallengeSeeds: jest.fn(() => {
return {
lorem: 'ipsum'
};
})
};
});
describe('getLastStepFileContent helper', () => {
it('should throw if last step count does not match with numbers of steps', () => {
mock({
'mock-project/': {
'step-001.md': 'Lorem ipsum...',
'step-004.md': 'Lorem ipsum...',
'final.md': 'Lorem ipsum...'
}
});
expect(() => {
getLastStepFileContent();
}).toThrow();
});
it('should return information if steps count is correct', () => {
mock({
'mock-project': {
'step-001.md': 'Lorem ipsum...',
'step-002.md': 'Lorem ipsum...',
'final.md': 'Lorem ipsum...'
}
});
const expected = {
nextStepNum: 3,
challengeSeeds: {
lorem: 'ipsum'
}
};
expect(getLastStepFileContent()).toEqual(expected);
});
afterEach(() => {
mock.restore();
});
});

41
tools/challenge-helper-scripts/helpers/get-last-step-file-content.ts
View File

@ -1,41 +0,0 @@
import fs from 'fs';
import path from 'path';
import { getChallengeSeeds } from '../utils';
import { getProjectPath } from './get-project-path';
import { ChallengeSeed } from './get-step-template';
// Looks up the last file found with format `step-###.md` in a directory and
// returns associated information to it. At the same time validates that the
// number of files match the names used to name these.
function getLastStepFileContent(): {
challengeSeeds: Record<string, ChallengeSeed>;
nextStepNum: number;
} {
const filesArr: string[] = [];
const projectPath = getProjectPath();
fs.readdirSync(projectPath).forEach(fileName => {
if (
path.extname(fileName).toLowerCase() === '.md' &&
!fileName.endsWith('final.md')
) {
filesArr.push(fileName);
}
});
const fileName = filesArr[filesArr.length - 1];
// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call
const lastStepFileString: string = fileName.split('.')[0].split('-')[1];
const lastStepFileNum = parseInt(lastStepFileString, 10);
if (filesArr.length !== lastStepFileNum) {
throw `Error: The last file step is ${lastStepFileNum} and there are ${filesArr.length} files.`;
}
return {
// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
challengeSeeds: getChallengeSeeds(projectPath + fileName),
nextStepNum: lastStepFileNum + 1
};
}
export { getLastStepFileContent };

13
tools/challenge-helper-scripts/helpers/get-last-step-file-number.ts Normal file
View File

@ -0,0 +1,13 @@
import { last } from 'lodash';
import { getMetaData } from './project-metadata';
function getLastStep(): { stepNum: number } {
const meta = getMetaData();
const challengeOrder: string[][] = meta.challengeOrder;
const step = last(challengeOrder);
if (!step) throw new Error('No steps found');
return { stepNum: challengeOrder.length };
}
export { getLastStep };

17
tools/challenge-helper-scripts/helpers/get-project-path.test.ts → tools/challenge-helper-scripts/helpers/get-project-info.test.ts
View File

@ -1,4 +1,4 @@
import { getProjectPath } from './get-project-path';
import { getProjectName, getProjectPath } from './get-project-info';
describe('getProjectPath helper', () => {
it('should return the calling dir path', () => {
@ -20,3 +20,18 @@ describe('getProjectPath helper', () => {
expect(getProjectPath()).toEqual(expected);
});
});
describe('getProjectName helper', () => {
it('should return the last path segment of the calling dir', () => {
const mockCallingDir = 'calling/dir';
const expected = `dir`;
// Add mock to test condition
process.env.CALLING_DIR = mockCallingDir;
expect(getProjectName()).toEqual(expected);
// Remove mock to not affect other tests
delete process.env.CALLING_DIR;
});
});

9
tools/challenge-helper-scripts/helpers/get-project-info.ts Normal file
View File

@ -0,0 +1,9 @@
import path from 'path';
export function getProjectPath(): string {
return (process.env.CALLING_DIR || process.cwd()) + path.sep;
}
export function getProjectName(): string {
return getProjectPath().split(path.sep).slice(-2)[0];
}

19
tools/challenge-helper-scripts/helpers/get-project-meta-path.test.ts
View File

@ -1,19 +0,0 @@
import { getProjectMetaPath } from './get-project-meta-path';
describe('getProjectMetaPath helper', () => {
it('should throw if args are invalid', () => {
expect(() => {
getProjectMetaPath('', '');
}).toThrow();
});
it('should return the meta path', () => {
const curriculum = 'test-curriculum';
const project = 'test-project';
const expected = `${process.cwd()}/${curriculum}/challenges/_meta/${project}/meta.json`;
const expectedB = `${process.cwd()}/challenges/_meta/${project}/meta.json`;
expect(getProjectMetaPath(curriculum, project)).toEqual(expected);
expect(getProjectMetaPath('', project)).toEqual(expectedB);
});
});

25
tools/challenge-helper-scripts/helpers/get-project-meta-path.ts
View File

@ -1,25 +0,0 @@
import path from 'path';
// Returns the path of the meta file associated to arguments provided.
const getProjectMetaPath = (
curriculumPath: string,
projectName: string
): string => {
if (typeof curriculumPath !== 'string' || typeof projectName !== 'string') {
throw `${curriculumPath} and ${projectName} should be of type string`;
}
if (!projectName) {
throw `${projectName} can't be an empty string`;
}
return path.resolve(
curriculumPath,
'challenges',
'_meta',
projectName,
'meta.json'
);
};
export { getProjectMetaPath };

36
tools/challenge-helper-scripts/helpers/get-project-path-metadata.test.ts
View File

@ -1,36 +0,0 @@
import { readFileSync } from 'fs';
import { getMetaData } from './get-project-path-metadata';
jest.mock('fs', () => {
return {
readFileSync: jest.fn()
};
});
const mockPath = '/mock/path';
describe('getMetaData helper', () => {
it('should process requested file', () => {
// @ts-expect-error - readFileSync is mocked
// eslint-disable-next-line @typescript-eslint/no-unsafe-call
readFileSync.mockImplementation(() => '{"name": "Test Project"}');
const expected = {
name: 'Test Project'
};
expect(getMetaData(mockPath)).toEqual(expected);
});
it('should throw if file is not found', () => {
// @ts-expect-error - readFileSync is mocked
// eslint-disable-next-line @typescript-eslint/no-unsafe-call
readFileSync.mockImplementation(() => {
throw new Error();
});
expect(() => {
getMetaData(mockPath);
}).toThrowError(new Error(`No _meta.json file exists at ${mockPath}`));
});
});

16
tools/challenge-helper-scripts/helpers/get-project-path-metadata.ts
View File

@ -1,16 +0,0 @@
import fs from 'fs';
// Process the contents of a argument (json) to an Object
function getMetaData(file: string): Record<string, unknown> {
let metaData;
try {
metaData = fs.readFileSync(file, 'utf8');
} catch (err) {
throw `No _meta.json file exists at ${file}`;
}
return JSON.parse(metaData) as Record<string, unknown>;
}
export { getMetaData };

8
tools/challenge-helper-scripts/helpers/get-project-path.ts
View File

@ -1,8 +0,0 @@
import path from 'path';
// Returns the path of a project
function getProjectPath(): string {
return (process.env.CALLING_DIR || process.cwd()) + path.sep;
}
export { getProjectPath };

1
tools/challenge-helper-scripts/helpers/get-step-template.test.ts
View File

@ -48,7 +48,6 @@ Test 1
tail: ''
}
},
stepBetween: false,
stepNum: 5
};

9
tools/challenge-helper-scripts/helpers/get-step-template.ts
View File

@ -22,7 +22,6 @@ ${content}`
type StepOptions = {
challengeId: ObjectID;
challengeSeeds: Record<string, ChallengeSeed>;
stepBetween: boolean;
stepNum: number;
};
@ -38,7 +37,6 @@ export interface ChallengeSeed {
function getStepTemplate({
challengeId,
challengeSeeds,
stepBetween,
stepNum
}: StepOptions): string {
const seedTexts = Object.values(challengeSeeds)
@ -61,12 +59,7 @@ function getStepTemplate({
.map(({ ext, tail }: ChallengeSeed) => getCodeBlock(ext, tail))
.join('\n');
const descStepNum = stepBetween ? stepNum + 1 : stepNum;
const stepDescription = `${
stepBetween ? 'new ' : ''
}step ${descStepNum} instructions`;
const stepDescription = `step ${stepNum} instructions`;
const seedChallengeSection = getSeedSection(seedTexts, 'seed-contents');
const seedHeadSection = getSeedSection(seedHeads, 'before-user-code');
const seedTailSection = getSeedSection(seedTails, 'after-user-code');

21
tools/challenge-helper-scripts/helpers/pad-with-leading-zeros.test.js
View File

@ -1,21 +0,0 @@
const { padWithLeadingZeros } = require('./pad-with-leading-zeros');
describe('padWithLeadingZeros helper', () => {
it('should return a string of 3 digits for valid values', () => {
const items = ['1', '11', '111'];
items.forEach(item => expect(padWithLeadingZeros(item).length).toEqual(3));
});
it('should prepend 0s on valid values while length is less than 3', () => {
expect(padWithLeadingZeros('1')).toEqual('001');
expect(padWithLeadingZeros('11')).toEqual('011');
expect(padWithLeadingZeros('111')).toEqual('111');
});
it('should throw on valid values that are longer that 3 characters', () => {
expect(() => {
padWithLeadingZeros('19850809');
}).toThrow();
});
});

14
tools/challenge-helper-scripts/helpers/pad-with-leading-zeros.ts
View File

@ -1,14 +0,0 @@
// Prepends zero's to the given value until length is equal to 3:
// '1' -> '001', '12' -> '012', ...
// Note: always want file step numbers 3 digits
function padWithLeadingZeros(value: number): string {
const valueString = value.toString();
if (valueString.length > 3) {
throw `${valueString} should be less than 4 characters`;
}
return valueString.padStart(3, '0');
}
export { padWithLeadingZeros };

161
tools/challenge-helper-scripts/helpers/project-metadata.test.ts Normal file
View File

@ -0,0 +1,161 @@
import path from 'path';
import mock from 'mock-fs';
import {
getMetaData,
getProjectMetaPath,
validateMetaData
} from './project-metadata';
describe('getProjectMetaPath helper', () => {
it('should return the meta path', () => {
const expected = path.join(
'curriculum',
'challenges',
`_meta/mock-project/meta.json`
);
process.env.CALLING_DIR =
'curriculum/challenges/english/superblock/mock-project';
expect(getProjectMetaPath()).toEqual(expected);
});
afterEach(() => {
delete process.env.CALLING_DIR;
});
});
describe('getMetaData helper', () => {
beforeEach(() => {
mock({
curriculum: {
challenges: {
english: {
superblock: {
'mock-project': {
'step-001.md': 'Lorem ipsum...',
'step-002.md': 'Lorem ipsum...',
'step-003.md': 'Lorem ipsum...'
}
}
},
_meta: {
'mock-project': {
'meta.json': `{
"id": "mock-id",
"challengeOrder": [["1","step1"], ["2","step2"], ["1","step3"]]}
`
}
}
}
}
});
});
it('should process requested file', () => {
const expected = {
id: 'mock-id',
challengeOrder: [
['1', 'step1'],
['2', 'step2'],
['1', 'step3']
]
};
process.env.CALLING_DIR =
'curriculum/challenges/english/superblock/mock-project';
expect(getMetaData()).toEqual(expected);
});
it('should throw if file is not found', () => {
process.env.CALLING_DIR =
'curriculum/challenges/english/superblock/mick-priject';
expect(() => {
getMetaData();
}).toThrowError(
new Error(
`ENOENT: no such file or directory, open 'curriculum/challenges/_meta/mick-priject/meta.json'`
)
);
});
afterEach(() => {
mock.restore();
delete process.env.CALLING_DIR;
});
});
describe('validateMetaData helper', () => {
it('should throw if a stepfile is missing', () => {
mock({
'_meta/project/': {
'meta.json':
'{"id": "mock-id", "challengeOrder": [["id-1", "Step 1"], ["id-3", "Step 2"], ["id-2", "Step 3"]]}'
},
'english/superblock/project/': {
'id-1.md': `---
id: id-1
title: Step 2
challengeType: a
dashedName: step-2
---
`,
'id-3.md': `---
id: id-3
title: Step 3
challengeType: c
dashedName: step-3
---
`
}
});
process.env.CALLING_DIR = 'english/superblock/project';
expect(() => validateMetaData()).toThrow(
"ENOENT: no such file or directory, access 'english/superblock/project/id-2.md'"
);
});
it('should throw if a step is present in the project, but not the meta', () => {
mock({
'_meta/project/': {
'meta.json':
'{"id": "mock-id", "challengeOrder": [["id-1", "Step 1"], ["id-2", "Step 3"]]}'
},
'english/superblock/project/': {
'id-1.md': `---
id: id-1
title: Step 2
challengeType: a
dashedName: step-2
---
`,
'id-2.md': `---
id: id-2
title: Step 1
challengeType: b
dashedName: step-1
---
`,
'id-3.md': `---
id: id-3
title: Step 3
challengeType: c
dashedName: step-3
---
`
}
});
process.env.CALLING_DIR = 'english/superblock/project';
expect(() => validateMetaData()).toThrow(
"File english/superblock/project/id-3.md should be in the meta.json's challengeOrder"
);
});
afterEach(() => {
mock.restore();
delete process.env.CALLING_DIR;
});
});

46
tools/challenge-helper-scripts/helpers/project-metadata.ts Normal file
View File

@ -0,0 +1,46 @@
import fs from 'fs';
import path from 'path';
import glob from 'glob';
import { Meta } from '../create-project';
import { getProjectName, getProjectPath } from './get-project-info';
function getMetaData(): Meta {
const metaData = fs.readFileSync(getProjectMetaPath(), 'utf8');
return JSON.parse(metaData) as Meta;
}
function updateMetaData(newMetaData: Record<string, unknown>): void {
fs.writeFileSync(getProjectMetaPath(), JSON.stringify(newMetaData, null, 2));
}
function getProjectMetaPath(): string {
return path.join(
getProjectPath(),
'../../..',
'_meta',
getProjectName(),
'meta.json'
);
}
// This (and everything else) should be async, but it's fast enough
// for the moment.
function validateMetaData(): void {
const { challengeOrder } = getMetaData();
// each step in the challengeOrder should correspond to a file
challengeOrder.forEach(([id]) => {
fs.accessSync(`${getProjectPath()}${id}.md`);
});
// each file should have a corresponding step in the challengeOrder
glob.sync(`${getProjectPath()}/*.md`).forEach(file => {
const id = path.basename(file, '.md');
if (!challengeOrder.find(([stepId]) => stepId === id))
throw new Error(
`File ${file} should be in the meta.json's challengeOrder`
);
});
}
export { getMetaData, updateMetaData, getProjectMetaPath, validateMetaData };