Jun 7, 2020 · Jun 5, 2020 · Jun 7, 2020 · Jun 7, 2020 · Jun 7, 2020 · Jun 7, 2020
diff --git a/src/build.ts b/src/build.ts
 import { parse } from "./utils/parse";
 import { getArg } from "./utils/args";
 import { getCommits, CommitLogObject } from "./utils/commits";
 import skeletonSchema from "./schema/skeleton";
 import tutorialSchema from "./schema/tutorial";
 import { validateSchema } from "./utils/validateSchema";
 import * as T from "../typings/tutorial";

    return;
  }

  // parse yaml config
  letconfig;
  // parse yamlskeletonconfig
  letskeleton;
  try {
    config = yamlParser.load(_yaml);
    skeleton = yamlParser.load(_yaml);
    if (!skeleton || !Object.keys(skeleton).length) {
      throw new Error(`Skeleton at "${options.yaml}" is invalid`);
    }
  } catch (e) {
    console.error("Error parsing yaml");
    console.error(e.message);
    return;
  }

  // validate skeleton based on skeleton json schema
  try {
    const valid = validateSchema(skeletonSchema, skeleton);
    if (!valid) {
      console.error("Tutorial validation failed. See above to see what to fix");
      return;
    }
  } catch (e) {
    console.error("Error validating tutorial schema:");
    console.error(e.message);
  }

  // load git commits to use in parse step
  let commits: CommitLogObject;
  try {
    commits = await getCommits({
      localDir: localPath,
      codeBranch:config.config.repo.branch,
      codeBranch:skeleton.config.repo.branch,
    });
  } catch (e) {
    console.error("Error loading commits:");
  try {
    tutorial = await parse({
      text: _markdown,
 config,
 skeleton,
      commits,
    });
  } catch (e) {
    return;
  }

  // validate tutorial based on json schema
  // validate tutorial based ontutorialjson schema
  try {
    const valid = validateSchema(tutorial);
    const valid = validateSchema(tutorialSchema,tutorial);
    if (!valid) {
      console.error("Tutorial validation failed. See above to see what to fix");
      return;
diff --git a/src/schema/meta.ts b/src/schema/meta.ts
 export default {
  $schema: "http://json-schema.org/draft-07/schema#",
  $id: "https://coderoad.io/tutorial-schema.json",
  title: "Tutorial Schema",
  description:
    "A CodeRoad tutorial schema data. This JSON data is converted into a tutorial with the CodeRoad editor extension",
  definitions: {
    semantic_version: {
      type: "string",
        "An array of command line commands that will be called when the user enters the level or step. Currently commands are limited for security purposes",
      items: {
        type: "string",
        enum: ["npm install"],
      },
    },
    commit_array: {
diff --git a/src/schema/skeleton.ts b/src/schema/skeleton.ts
 import meta from "./meta";

 export default {
  title: "Skeleton Schema",
  description:
    "A CodeRoad tutorial config schema. This data is paired up with the markdown to create a tutorial",
  ...meta,
  type: "object",
  properties: {
    version: {
      $ref: "#/definitions/semantic_version",
      description: "The tutorial version. Must be unique for the tutorial.",
      examples: ["0.1.0", "1.0.0"],
    },

    // config
    config: {
      type: "object",
      properties: {
        testRunner: {
          type: "object",
          description: "The test runner configuration",
          properties: {
            command: {
              type: "string",
              description: "Command line to start the test runner",
              examples: ["./node_modules/.bin/mocha"],
            },
            args: {
              type: "object",
              description:
                "A configuration of command line args for your test runner",
              properties: {
                filter: {
                  type: "string",
                  description:
                    "the command line arg for filtering tests with a regex pattern",
                  examples: ["--grep"],
                },
                tap: {
                  type: "string",
                  description:
                    "The command line arg for configuring a TAP reporter. See https://github.com/sindresorhus/awesome-tap for examples.",
                  examples: ["--reporter=mocha-tap-reporter"],
                },
              },
              additionalProperties: false,
              required: ["tap"],
            },
            directory: {
              type: "string",
              description: "An optional folder for the test runner",
              examples: ["coderoad"],
            },
            setup: {
              $ref: "#/definitions/setup_action",
              description:
                "Setup commits or commands used for setting up the test runner on tutorial launch",
            },
          },
          required: ["command", "args"],
        },
        repo: {
          type: "object",
          description: "The repo holding the git commits for the tutorial",
          properties: {
            uri: {
              type: "string",
              description: "The uri source of the tutorial",
              format: "uri",
              examples: ["https://github.com/name/tutorial-name.git"],
            },
            branch: {
              description:
                "The branch of the repo where the tutorial config file exists",
              type: "string",
              examples: ["master"],
            },
          },
          additionalProperties: false,
          required: ["uri", "branch"],
        },

        dependencies: {
          type: "array",
          description: "A list of tutorial dependencies",
          items: {
            type: "object",
            properties: {
              name: {
                type: "string",
                description:
                  "The command line process name of the dependency. It will be checked by running `name --version`",
                examples: ["node", "python"],
              },
              version: {
                type: "string",
                description:
                  "The version requirement. See https://github.com/npm/node-semver for options",
                examples: [">=10"],
              },
            },
            required: ["name", "version"],
          },
        },
        appVersions: {
          type: "object",
          description:
            "A list of compatable coderoad versions. Currently only a VSCode extension.",
          properties: {
            vscode: {
              type: "string",
              description:
                "The version range for coderoad-vscode that this tutorial is compatable with",
              examples: [">=0.7.0"],
            },
          },
        },
      },
      additionalProperties: false,
      required: ["testRunner", "repo"],
    },

    // levels
    levels: {
      type: "array",
      description:
        'Levels are the stages a user goes through in the tutorial. A level may contain a group of tasks called "steps" that must be completed to proceed',
      items: {
        type: "object",
        properties: {
          id: {
            type: "string",
            description: "A level id",
            examples: ["L1", "L11"],
          },
          setup: {
            $ref: "#/definitions/setup_action",
            description:
              "An optional point for loading commits, running commands or opening files",
          },
          steps: {
            type: "array",
            items: {
              type: "object",
              properties: {
                id: {
                  type: "string",
                  description: "A level id",
                  examples: ["L1S1", "L11S12"],
                },
                setup: {
                  allOf: [
                    {
                      $ref: "#/definitions/setup_action",
                      description:
                        "A point for loading commits. It can also run commands and/or open files",
                    },
                  ],
                },
                solution: {
                  allOf: [
                    {
                      $ref: "#/definitions/setup_action",
                      description:
                        "The solution commits that can be loaded if the user gets stuck. It can also run commands and/or open files",
                    },
                    {
                      required: [],
                    },
                  ],
                },
              },
              required: ["id", "setup"],
            },
          },
        },
        required: ["id"],
      },
      minItems: 1,
    },
  },
  additionalProperties: false,
  required: ["version", "config", "levels"],
 };
diff --git a/src/schema/index.ts → src/schema/tutorial.ts b/src/schema/index.ts → src/schema/tutorial.ts
 import meta from "./meta";

 export default {
  title: "Tutorial Schema",
  description:
    "A CodeRoad tutorial schema data. This JSON data is converted into a tutorial with the CodeRoad editor extension",
  ...meta,
  type: "object",
  properties: {
diff --git a/src/templates/js-mocha/coderoad.yaml b/src/templates/js-mocha/coderoad.yaml
      ## Example Four: Subtasks
      - id: L1S4
        setup:
          commands:
            ## A filter is a regex that limits the test results
            - filter: "^Example 2"
            ## A feature that shows subtasks: all filtered active test names and the status of the tests (pass/fail).
            - subtasks: true
          ## A filter is a regex that limits the test results
          filter: "^Example 2"
          ## A feature that shows subtasks: all filtered active test names and the status of the tests (pass/fail).
          subtasks: true
diff --git a/src/utils/commits.ts b/src/utils/commits.ts
 import util from "util";
 import * as path from "path";
 import gitP, { SimpleGit } from "simple-git/promise";
 import {addToCommitOrder,validateCommitOrder } from "./commitOrder";
 import { validateCommitOrder } from "./validateCommits";

 const mkdir = util.promisify(fs.mkdir);
 const exists = util.promisify(fs.exists);
diff --git a/src/utils/parse.ts b/src/utils/parse.ts

 type ParseParams = {
  text: string;
 config: Partial<T.Tutorial | any>;
 skeleton: Partial<T.Tutorial | any>;
  commits: CommitLogObject;
 };

 export function parse(params: ParseParams): any {
  const mdContent: TutorialFrame = parseMdContent(params.text);

  const parsed: Partial<T.Tutorial> = {
    version: params.config.version,
    version: params.skeleton.version,
    summary: mdContent.summary,
    config: params.config.config || {},
    config: params.skeleton.config || {},
    levels: [],
  };

  // add init commits
  if (params.commits.INIT && params.commits.INIT.length) {
    console.log(JSON.stringify(parsed.config?.testRunner));
    // @ts-ignore
    parsed.config.testRunner.setup = {
      ...(parsed.config?.testRunner?.setup || {}),
  }

  // merge content and tutorial
  if (params.config.levels && params.config.levels.length) {
    parsed.levels = params.config.levels
  if (params.skeleton.levels && params.skeleton.levels.length) {
    parsed.levels = params.skeleton.levels
      .map((level: T.Level, levelIndex: number) => {
        const levelContent = mdContent.levels[level.id];

diff --git a/src/utils/commitOrder.ts → src/utils/validateCommits.ts b/src/utils/commitOrder.ts → src/utils/validateCommits.ts
 // should flag commits that are out of order based on the previous commit
 // position is a string like 'INIT', 'L1', 'L1S1'
 export function addToCommitOrder(position: string) {
  // add position to list
 }

 export function validateCommitOrder(positions: string[]): boolean {
  // loop over positions
  const errors: number[] = [];
  positions.forEach((position: string, index: number) => {
    if (position === "INIT") {
      if (previous.level !== 0 && previous.step !== 0) {
        console.log("ERROR HERE");
        errors.push(index);
      }
      current = { level: 0, step: 0 };
    previous = current;
  });

  if (errors.length) {
  if (errors.length && process.env.NODE_ENV !== "test") {
    console.warn("Found commit positions out of order");
    positions.forEach((position, index) => {
      if (errors.includes(index)) {
diff --git a/src/utils/validateSchema.ts b/src/utils/validateSchema.ts
 import schema from "../schema";

 // https://www.npmjs.com/package/ajv
 // @ts-ignore ajv typings not working
 import JsonSchema from "ajv";

 export function validateSchema(json: any): boolean | PromiseLike<boolean> {
 export function validateSchema(
  schema: any,
  json: any
 ): boolean | PromiseLike<boolean> {
  // validate using https://json-schema.org/
  const jsonSchema = new JsonSchema({
    allErrors: true,
Original file line number	Diff line number	Diff line change
Expand Up		@@ -5,6 +5,8 @@ import * as util from "util";
		import { parse } from "./utils/parse";
		import { getArg } from "./utils/args";
		import { getCommits, CommitLogObject } from "./utils/commits";
		import skeletonSchema from "./schema/skeleton";
		import tutorialSchema from "./schema/tutorial";
		import { validateSchema } from "./utils/validateSchema";
		import * as T from "../typings/tutorial";

Expand DownExpand Up		@@ -70,21 +72,37 @@ async function build(args: string[]) {
		return;
		}

		// parse yaml config
		letconfig;
		// parse yamlskeletonconfig
		letskeleton;
		try {
		config = yamlParser.load(_yaml);
		skeleton = yamlParser.load(_yaml);
		if (!skeleton \|\| !Object.keys(skeleton).length) {
		throw new Error(`Skeleton at "${options.yaml}" is invalid`);
		}
		} catch (e) {
		console.error("Error parsing yaml");
		console.error(e.message);
		return;
		}

		// validate skeleton based on skeleton json schema
		try {
		const valid = validateSchema(skeletonSchema, skeleton);
		if (!valid) {
		console.error("Tutorial validation failed. See above to see what to fix");
		return;
		}
		} catch (e) {
		console.error("Error validating tutorial schema:");
		console.error(e.message);
		}

		// load git commits to use in parse step
		let commits: CommitLogObject;
		try {
		commits = await getCommits({
		localDir: localPath,
		codeBranch:config.config.repo.branch,
		codeBranch:skeleton.config.repo.branch,
		});
		} catch (e) {
		console.error("Error loading commits:");
Expand All		@@ -97,7 +115,7 @@ async function build(args: string[]) {
		try {
		tutorial = await parse({
		text: _markdown,
		config,
		skeleton,
		commits,
		});
		} catch (e) {
Expand All		@@ -106,9 +124,9 @@ async function build(args: string[]) {
		return;
		}

		// validate tutorial based on json schema
		// validate tutorial based ontutorialjson schema
		try {
		const valid = validateSchema(tutorial);
		const valid = validateSchema(tutorialSchema,tutorial);
		if (!valid) {
		console.error("Tutorial validation failed. See above to see what to fix");
		return;
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -1,9 +1,6 @@
		export default {
		$schema: "http://json-schema.org/draft-07/schema#",
		$id: "https://coderoad.io/tutorial-schema.json",
		title: "Tutorial Schema",
		description:
		"A CodeRoad tutorial schema data. This JSON data is converted into a tutorial with the CodeRoad editor extension",
		definitions: {
		semantic_version: {
		type: "string",
Expand DownExpand Up		@@ -48,7 +45,6 @@ export default {
		"An array of command line commands that will be called when the user enters the level or step. Currently commands are limited for security purposes",
		items: {
		type: "string",
		enum: ["npm install"],
		},
		},
		commit_array: {
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,185 @@
		import meta from "./meta";

		export default {
		title: "Skeleton Schema",
		description:
		"A CodeRoad tutorial config schema. This data is paired up with the markdown to create a tutorial",
		...meta,
		type: "object",
		properties: {
		version: {
		$ref: "#/definitions/semantic_version",
		description: "The tutorial version. Must be unique for the tutorial.",
		examples: ["0.1.0", "1.0.0"],
		},

		// config
		config: {
		type: "object",
		properties: {
		testRunner: {
		type: "object",
		description: "The test runner configuration",
		properties: {
		command: {
		type: "string",
		description: "Command line to start the test runner",
		examples: ["./node_modules/.bin/mocha"],
		},
		args: {
		type: "object",
		description:
		"A configuration of command line args for your test runner",
		properties: {
		filter: {
		type: "string",
		description:
		"the command line arg for filtering tests with a regex pattern",
		examples: ["--grep"],
		},
		tap: {
		type: "string",
		description:
		"The command line arg for configuring a TAP reporter. See https://github.com/sindresorhus/awesome-tap for examples.",
		examples: ["--reporter=mocha-tap-reporter"],
		},
		},
		additionalProperties: false,
		required: ["tap"],
		},
		directory: {
		type: "string",
		description: "An optional folder for the test runner",
		examples: ["coderoad"],
		},
		setup: {
		$ref: "#/definitions/setup_action",
		description:
		"Setup commits or commands used for setting up the test runner on tutorial launch",
		},
		},
		required: ["command", "args"],
		},
		repo: {
		type: "object",
		description: "The repo holding the git commits for the tutorial",
		properties: {
		uri: {
		type: "string",
		description: "The uri source of the tutorial",
		format: "uri",
		examples: ["https://github.com/name/tutorial-name.git"],
		},
		branch: {
		description:
		"The branch of the repo where the tutorial config file exists",
		type: "string",
		examples: ["master"],
		},
		},
		additionalProperties: false,
		required: ["uri", "branch"],
		},

		dependencies: {
		type: "array",
		description: "A list of tutorial dependencies",
		items: {
		type: "object",
		properties: {
		name: {
		type: "string",
		description:
		"The command line process name of the dependency. It will be checked by running `name --version`",
		examples: ["node", "python"],
		},
		version: {
		type: "string",
		description:
		"The version requirement. See https://github.com/npm/node-semver for options",
		examples: [">=10"],
		},
		},
		required: ["name", "version"],
		},
		},
		appVersions: {
		type: "object",
		description:
		"A list of compatable coderoad versions. Currently only a VSCode extension.",
		properties: {
		vscode: {
		type: "string",
		description:
		"The version range for coderoad-vscode that this tutorial is compatable with",
		examples: [">=0.7.0"],
		},
		},
		},
		},
		additionalProperties: false,
		required: ["testRunner", "repo"],
		},

		// levels
		levels: {
		type: "array",
		description:
		'Levels are the stages a user goes through in the tutorial. A level may contain a group of tasks called "steps" that must be completed to proceed',
		items: {
		type: "object",
		properties: {
		id: {
		type: "string",
		description: "A level id",
		examples: ["L1", "L11"],
		},
		setup: {
		$ref: "#/definitions/setup_action",
		description:
		"An optional point for loading commits, running commands or opening files",
		},
		steps: {
		type: "array",
		items: {
		type: "object",
		properties: {
		id: {
		type: "string",
		description: "A level id",
		examples: ["L1S1", "L11S12"],
		},
		setup: {
		allOf: [
		{
		$ref: "#/definitions/setup_action",
		description:
		"A point for loading commits. It can also run commands and/or open files",
		},
		],
		},
		solution: {
		allOf: [
		{
		$ref: "#/definitions/setup_action",
		description:
		"The solution commits that can be loaded if the user gets stuck. It can also run commands and/or open files",
		},
		{
		required: [],
		},
		],
		},
		},
		required: ["id", "setup"],
		},
		},
		},
		required: ["id"],
		},
		minItems: 1,
		},
		},
		additionalProperties: false,
		required: ["version", "config", "levels"],
		};
Original file line number	Diff line number	Diff line change
		@@ -1,6 +1,9 @@
		import meta from "./meta";

		export default {
		title: "Tutorial Schema",
		description:
		"A CodeRoad tutorial schema data. This JSON data is converted into a tutorial with the CodeRoad editor extension",
		...meta,
		type: "object",
		properties: {
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -92,8 +92,7 @@ levels:
		## Example Four: Subtasks
		- id: L1S4
		setup:
		commands:
		## A filter is a regex that limits the test results
		- filter: "^Example 2"
		## A feature that shows subtasks: all filtered active test names and the status of the tests (pass/fail).
		- subtasks: true
		## A filter is a regex that limits the test results
		filter: "^Example 2"
		## A feature that shows subtasks: all filtered active test names and the status of the tests (pass/fail).
		subtasks: true
Original file line number	Diff line number	Diff line change
Expand Up		@@ -2,7 +2,7 @@ import * as fs from "fs";
		import util from "util";
		import * as path from "path";
		import gitP, { SimpleGit } from "simple-git/promise";
		import {addToCommitOrder,validateCommitOrder } from "./commitOrder";
		import { validateCommitOrder } from "./validateCommits";

		const mkdir = util.promisify(fs.mkdir);
		const exists = util.promisify(fs.exists);
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -90,23 +90,22 @@ export function parseMdContent(md: string): TutorialFrame \| never {

		type ParseParams = {
		text: string;
		config: Partial<T.Tutorial \| any>;
		skeleton: Partial<T.Tutorial \| any>;
		commits: CommitLogObject;
		};

		export function parse(params: ParseParams): any {
		const mdContent: TutorialFrame = parseMdContent(params.text);

		const parsed: Partial<T.Tutorial> = {
		version: params.config.version,
		version: params.skeleton.version,
		summary: mdContent.summary,
		config: params.config.config \|\| {},
		config: params.skeleton.config \|\| {},
		levels: [],
		};

		// add init commits
		if (params.commits.INIT && params.commits.INIT.length) {
		console.log(JSON.stringify(parsed.config?.testRunner));
		// @ts-ignore
		parsed.config.testRunner.setup = {
		...(parsed.config?.testRunner?.setup \|\| {}),
Expand All		@@ -115,8 +114,8 @@ export function parse(params: ParseParams): any {
		}

		// merge content and tutorial
		if (params.config.levels && params.config.levels.length) {
		parsed.levels = params.config.levels
		if (params.skeleton.levels && params.skeleton.levels.length) {
		parsed.levels = params.skeleton.levels
		.map((level: T.Level, levelIndex: number) => {
		const levelContent = mdContent.levels[level.id];

Expand Down
Original file line number	Diff line number	Diff line change
		@@ -1,9 +1,5 @@
		// should flag commits that are out of order based on the previous commit
		// position is a string like 'INIT', 'L1', 'L1S1'
		export function addToCommitOrder(position: string) {
		// add position to list
		}

		export function validateCommitOrder(positions: string[]): boolean {
		// loop over positions
		const errors: number[] = [];
Expand All		@@ -12,7 +8,6 @@ export function validateCommitOrder(positions: string[]): boolean {
		positions.forEach((position: string, index: number) => {
		if (position === "INIT") {
		if (previous.level !== 0 && previous.step !== 0) {
		console.log("ERROR HERE");
		errors.push(index);
		}
		current = { level: 0, step: 0 };
Expand DownExpand Up		@@ -46,7 +41,7 @@ export function validateCommitOrder(positions: string[]): boolean {
		previous = current;
		});

		if (errors.length) {
		if (errors.length && process.env.NODE_ENV !== "test") {
		console.warn("Found commit positions out of order");
		positions.forEach((position, index) => {
		if (errors.includes(index)) {
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -1,10 +1,11 @@
		import schema from "../schema";

		// https://www.npmjs.com/package/ajv
		// @ts-ignore ajv typings not working
		import JsonSchema from "ajv";

		export function validateSchema(json: any): boolean \| PromiseLike<boolean> {
		export function validateSchema(
		schema: any,
		json: any
		): boolean \| PromiseLike<boolean> {
		// validate using https://json-schema.org/
		const jsonSchema = new JsonSchema({
		allErrors: true,
Expand Down