@wixc3/docs - npm Package Compare versions

Comparing version 3.0.4 to 3.0.5

dist/cjs/build-docs/build-docs.d.ts

@@ -9,2 +9,3 @@ import type { Config } from '../common';
     prettify: boolean;
+    validateExamples: boolean;
 };
@@ -11,0 +12,0 @@ export type BuildSteps = Partial<typeof all>;

dist/cjs/build-docs/build-docs.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildDocs = void 0;
+const validate_examples_1 = require("../validate-examples");
 const build_steps_1 = require("./build-steps");
@@ -9,3 +10,4 @@ const all = {
     generateMarkdown: true,
-    prettify: true
+    prettify: true,
+    validateExamples: true,
 };
@@ -16,8 +18,7 @@ /**
 function buildDocs(config, steps = all, macros) {
-    const { error } = console;
-    // suppress console.error abuse by apiDocumenter
-    console.error = () => { };
     steps = { ...all, ...steps };
     if (steps.analyze)
         (0, build_steps_1.analyze)(config);
+    if (steps.validateExamples)
+        (0, validate_examples_1.validateExamples)(config);
     if (steps.generateMarkdown)
@@ -29,5 +30,4 @@ (0, build_steps_1.generateMarkdown)(config);
         (0, build_steps_1.prettify)(config);
-    console.error = error;
 }
 exports.buildDocs = buildDocs;
 //# sourceMappingURL=build-docs.js.map

dist/cjs/cli.js

 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
 var __importDefault = (this && this.__importDefault) || function (mod) {
@@ -14,25 +37,61 @@ return (mod && mod.__esModule) ? mod : { "default": mod };
 const cli_options_1 = require("./cli.options");
+const args = __importStar(require("./cli.options"));
+const validate_examples_1 = require("./validate-examples");
+const common_2 = require("@wixc3/common");
 function cli() {
     (0, yargs_1.default)(process.argv.slice(2))
+        .fail((msg, err, yargs) => {
+        // eslint-disable-next-line no-console
+        console.log(yargs.help());
+    })
         .scriptName('docs')
         .usage('$0 <cmd> [args]')
         .command('build', 'Build doc markdown from packages TSDocs', { conf: cli_options_1.conf, base: cli_options_1.base, skipAnalyze: cli_options_1.skipAnalyze }, ({ base, conf, skipAnalyze }) => {
-        (0, build_docs_1.buildDocs)((0, common_1.loadConfig)((0, path_1.join)(base, conf)), { analyze: !skipAnalyze });
+        try {
+            (0, build_docs_1.buildDocs)((0, common_1.loadConfig)((0, path_1.join)(base, conf)), { analyze: !skipAnalyze });
+        }
+        catch (e) {
+            // eslint-disable-next-line no-console
+            console.error(e.stack);
+            process.exit(1);
+        }
     })
-        .command('init', 'initialize docs config and github pages action', { packages: cli_options_1.packages, conf: cli_options_1.conf, docs: cli_options_1.docs, siteUrl: cli_options_1.siteUrl, base: cli_options_1.base, temp: cli_options_1.temp, force: cli_options_1.force, origin: cli_options_1.origin }, ({ packages, conf, docs, siteUrl, base, temp, force, origin }) => {
-        (0, init_1.init)({ packages, conf, docs, siteUrl, base, temp, origin }, force);
+        .command('init', 'initialize docs config and github pages action', { packages: cli_options_1.packages, conf: cli_options_1.conf, docs: cli_options_1.docs, siteUrl: cli_options_1.siteUrl, base: cli_options_1.base, temp: cli_options_1.temp, force: cli_options_1.force, origin: cli_options_1.origin, examples: cli_options_1.examples }, (params) => {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            const { force, ...rest } = params;
+            const config = Object.fromEntries((0, common_2.filter)(Object.entries(rest), ([key, _]) => key in args));
+            (0, init_1.init)(config, force);
+        }
+        catch (e) {
+            // eslint-disable-next-line no-console
+            console.error(e.stack);
+            process.exit(1);
+        }
     })
         .command('readme', 'create README.md for all the packages', { conf: cli_options_1.conf, base: cli_options_1.base, siteUrl: cli_options_1.siteUrl }, ({ conf, base, siteUrl }) => {
-        (0, create_readme_1.createReadme)((0, common_1.loadConfig)((0, path_1.join)(base, conf)), siteUrl);
+        try {
+            (0, create_readme_1.createReadme)((0, common_1.loadConfig)((0, path_1.join)(base, conf)), siteUrl);
+        }
+        catch (e) {
+            // eslint-disable-next-line no-console
+            console.error(e.stack);
+            process.exit(1);
+        }
     })
+        .command('validate', 'create README.md for all the packages', { conf: cli_options_1.conf }, ({ conf }) => {
+        try {
+            (0, validate_examples_1.validateExamples)((0, common_1.loadConfig)(conf));
+        }
+        catch (e) {
+            // eslint-disable-next-line no-console
+            console.error(e.stack);
+            process.exit(1);
+        }
+    })
         .demandCommand()
         .help()
-        .parseAsync()
-        .catch((e) => {
-        // eslint-disable-next-line no-console
-        console.error(e);
-        process.exit(1);
-    });
+        .parseSync();
 }
 exports.cli = cli;
 //# sourceMappingURL=cli.js.map

dist/cjs/cli.options.d.ts

@@ -55,2 +55,8 @@ export declare const packages: {
 };
+export declare const examples: {
+    alias: string;
+    default: string;
+    describe: string;
+    string: boolean;
+};
 //# sourceMappingURL=cli.options.d.ts.map

dist/cjs/cli.options.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.siteUrl = exports.force = exports.temp = exports.base = exports.conf = exports.docs = exports.skipAnalyze = exports.origin = exports.packages = void 0;
+exports.examples = exports.siteUrl = exports.force = exports.temp = exports.base = exports.conf = exports.docs = exports.skipAnalyze = exports.origin = exports.packages = void 0;
 exports.packages = {
@@ -58,2 +58,8 @@ alias: 'p',
 };
+exports.examples = {
+    alias: 'e',
+    default: 'src/test',
+    describe: 'examples source root',
+    string: true,
+};
 //# sourceMappingURL=cli.options.js.map

dist/cjs/common.d.ts

@@ -10,2 +10,3 @@ import { Nullable } from '@wixc3/common';
 export declare const getPackageByUnscopedName: (config: Config, unscopedName: string) => Package;
+export declare const getPackageByName: (config: Config, name: string) => Package;
 export declare const stripName: (name: string) => string;
@@ -36,2 +37,3 @@ export declare const unscopedPackageName: (name: string) => string;
     siteUrl?: string;
+    examples: string;
 };
@@ -38,0 +40,0 @@ export type Config = UserConfig & {

dist/cjs/common.js

@@ -6,3 +6,3 @@ "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isWixDocs = exports._temp = exports._config = exports._docs = exports._packages = exports.writeConfig = exports.loadConfig = exports.getRepo = exports.execMacro = exports.parseMacro = exports.unscopedPackageName = exports.stripName = exports.getPackageByUnscopedName = exports.listPackages = void 0;
+exports.isWixDocs = exports._temp = exports._config = exports._docs = exports._packages = exports.writeConfig = exports.loadConfig = exports.getRepo = exports.execMacro = exports.parseMacro = exports.unscopedPackageName = exports.stripName = exports.getPackageByName = exports.getPackageByUnscopedName = exports.listPackages = void 0;
 const common_1 = require("@wixc3/common");
@@ -34,2 +34,15 @@ const fs_utils_1 = require("@wixc3/fs-utils");
 exports.getPackageByUnscopedName = getPackageByUnscopedName;
+const getPackageByName = (config, name) => {
+    const found = listPackages(config).find(({ name: pkg }) => {
+        if (isWixDocs(config) && name === '@wixc3/docs-macros') {
+            return pkg === '@wixc3/docs';
+        }
+        return pkg === name;
+    });
+    if (!found) {
+        throw new Error(`Packages not found: "${name}"`);
+    }
+    return found;
+};
+exports.getPackageByName = getPackageByName;
 const stripName = (name) => {
@@ -36,0 +49,0 @@ const base = (0, path_1.basename)(name).split('.')[0];

dist/cjs/create-readme.js

@@ -22,3 +22,3 @@ "use strict";
     };
-    (0, common_1.listPackages)(config).map(pkg => copyWithSiteUrlLinks(pkg));
+    (0, common_1.listPackages)(config).map((pkg) => copyWithSiteUrlLinks(pkg));
     copyWithSiteUrlLinks({ dir: '..', name: 'index', unscopedName: 'index' });
@@ -25,0 +25,0 @@ }

dist/cjs/init.js

@@ -41,3 +41,3 @@ "use strict";
             ? undefined
-            : `origin	${config.origin} (fetch)\norigin	${config.origin} (push)`)
+            : `origin	${config.origin} (fetch)\norigin	${config.origin} (push)`),
     }, force);
@@ -44,0 +44,0 @@ template('api-extractor.base.json');

dist/cjs/macros.js

@@ -11,3 +11,2 @@ "use strict";
 const process_macros_1 = require("./process-macros");
-const common_2 = require("@wixc3/common");
 /**
@@ -166,3 +165,3 @@ *
  */
-const h = (_, __, level, ...title) => `${(0, common_2.repeat)('#', parseInt(level))} ${title.join(' ')}\n`;
+const h = (_, __, level, ...title) => `${'#'.repeat(parseInt(level))} ${title.join(' ')}\n`;
 exports.h = h;
@@ -169,0 +168,0 @@ /**

dist/esm/build-docs/build-docs.d.ts

@@ -9,2 +9,3 @@ import type { Config } from '../common';
     prettify: boolean;
+    validateExamples: boolean;
 };
@@ -11,0 +12,0 @@ export type BuildSteps = Partial<typeof all>;

dist/esm/build-docs/build-docs.js

@@ -0,1 +1,2 @@
+import { validateExamples } from '../validate-examples';
 import { analyze, evaluateMacros, generateMarkdown, prettify } from './build-steps';
@@ -6,3 +7,4 @@ const all = {
     generateMarkdown: true,
-    prettify: true
+    prettify: true,
+    validateExamples: true,
 };
@@ -13,8 +15,7 @@ /**
 export function buildDocs(config, steps = all, macros) {
-    const { error } = console;
-    // suppress console.error abuse by apiDocumenter
-    console.error = () => { };
     steps = { ...all, ...steps };
     if (steps.analyze)
         analyze(config);
+    if (steps.validateExamples)
+        validateExamples(config);
     if (steps.generateMarkdown)
@@ -26,4 +27,3 @@ generateMarkdown(config);
         prettify(config);
-    console.error = error;
 }
 //# sourceMappingURL=build-docs.js.map

dist/esm/cli.js

@@ -7,25 +7,61 @@ import { join } from 'path';
 import { init } from './init';
-import { base, conf, docs, force, origin, packages, siteUrl, skipAnalyze, temp } from './cli.options';
+import { base, conf, docs, examples, force, origin, packages, siteUrl, skipAnalyze, temp } from './cli.options';
+import * as args from './cli.options';
+import { validateExamples } from './validate-examples';
+import { filter } from '@wixc3/common';
 export function cli() {
     yargs(process.argv.slice(2))
+        .fail((msg, err, yargs) => {
+        // eslint-disable-next-line no-console
+        console.log(yargs.help());
+    })
         .scriptName('docs')
         .usage('$0 <cmd> [args]')
         .command('build', 'Build doc markdown from packages TSDocs', { conf, base, skipAnalyze }, ({ base, conf, skipAnalyze }) => {
-        buildDocs(loadConfig(join(base, conf)), { analyze: !skipAnalyze });
+        try {
+            buildDocs(loadConfig(join(base, conf)), { analyze: !skipAnalyze });
+        }
+        catch (e) {
+            // eslint-disable-next-line no-console
+            console.error(e.stack);
+            process.exit(1);
+        }
     })
-        .command('init', 'initialize docs config and github pages action', { packages, conf, docs, siteUrl, base, temp, force, origin }, ({ packages, conf, docs, siteUrl, base, temp, force, origin }) => {
-        init({ packages, conf, docs, siteUrl, base, temp, origin }, force);
+        .command('init', 'initialize docs config and github pages action', { packages, conf, docs, siteUrl, base, temp, force, origin, examples }, (params) => {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            const { force, ...rest } = params;
+            const config = Object.fromEntries(filter(Object.entries(rest), ([key, _]) => key in args));
+            init(config, force);
+        }
+        catch (e) {
+            // eslint-disable-next-line no-console
+            console.error(e.stack);
+            process.exit(1);
+        }
     })
         .command('readme', 'create README.md for all the packages', { conf, base, siteUrl }, ({ conf, base, siteUrl }) => {
-        createReadme(loadConfig(join(base, conf)), siteUrl);
+        try {
+            createReadme(loadConfig(join(base, conf)), siteUrl);
+        }
+        catch (e) {
+            // eslint-disable-next-line no-console
+            console.error(e.stack);
+            process.exit(1);
+        }
     })
+        .command('validate', 'create README.md for all the packages', { conf }, ({ conf }) => {
+        try {
+            validateExamples(loadConfig(conf));
+        }
+        catch (e) {
+            // eslint-disable-next-line no-console
+            console.error(e.stack);
+            process.exit(1);
+        }
+    })
         .demandCommand()
         .help()
-        .parseAsync()
-        .catch((e) => {
-        // eslint-disable-next-line no-console
-        console.error(e);
-        process.exit(1);
-    });
+        .parseSync();
 }
 //# sourceMappingURL=cli.js.map

dist/esm/cli.options.d.ts

@@ -55,2 +55,8 @@ export declare const packages: {
 };
+export declare const examples: {
+    alias: string;
+    default: string;
+    describe: string;
+    string: boolean;
+};
 //# sourceMappingURL=cli.options.d.ts.map

dist/esm/cli.options.js

@@ -55,2 +55,8 @@ export const packages = {
 };
+export const examples = {
+    alias: 'e',
+    default: 'src/test',
+    describe: 'examples source root',
+    string: true,
+};
 //# sourceMappingURL=cli.options.js.map

dist/esm/common.d.ts

@@ -10,2 +10,3 @@ import { Nullable } from '@wixc3/common';
 export declare const getPackageByUnscopedName: (config: Config, unscopedName: string) => Package;
+export declare const getPackageByName: (config: Config, name: string) => Package;
 export declare const stripName: (name: string) => string;
@@ -36,2 +37,3 @@ export declare const unscopedPackageName: (name: string) => string;
     siteUrl?: string;
+    examples: string;
 };
@@ -38,0 +40,0 @@ export type Config = UserConfig & {

dist/esm/common.js

@@ -25,2 +25,14 @@ import { first } from '@wixc3/common';
 };
+export const getPackageByName = (config, name) => {
+    const found = listPackages(config).find(({ name: pkg }) => {
+        if (isWixDocs(config) && name === '@wixc3/docs-macros') {
+            return pkg === '@wixc3/docs';
+        }
+        return pkg === name;
+    });
+    if (!found) {
+        throw new Error(`Packages not found: "${name}"`);
+    }
+    return found;
+};
 export const stripName = (name) => {
@@ -27,0 +39,0 @@ const base = basename(name).split('.')[0];

dist/esm/create-readme.js

@@ -19,5 +19,5 @@ import { backSlash } from '@wixc3/fs-utils';
     };
-    listPackages(config).map(pkg => copyWithSiteUrlLinks(pkg));
+    listPackages(config).map((pkg) => copyWithSiteUrlLinks(pkg));
     copyWithSiteUrlLinks({ dir: '..', name: 'index', unscopedName: 'index' });
 }
 //# sourceMappingURL=create-readme.js.map

dist/esm/init.js

@@ -38,3 +38,3 @@ import { join, relative } from 'path';
             ? undefined
-            : `origin	${config.origin} (fetch)\norigin	${config.origin} (push)`)
+            : `origin	${config.origin} (fetch)\norigin	${config.origin} (push)`),
     }, force);
@@ -41,0 +41,0 @@ template('api-extractor.base.json');

dist/esm/macros.js

@@ -5,3 +5,2 @@ import { readPackageJson } from '@wixc3/fs-utils';
 import { processMacros } from './process-macros';
-import { repeat } from '@wixc3/common';
 /**
@@ -150,3 +149,3 @@ *
  */
-export const h = (_, __, level, ...title) => `${repeat('#', parseInt(level))} ${title.join(' ')}\n`;
+export const h = (_, __, level, ...title) => `${'#'.repeat(parseInt(level))} ${title.join(' ')}\n`;
 /**
@@ -153,0 +152,0 @@ * Lists all the available macros

package.json

 {
   "name": "@wixc3/docs",
-  "version": "3.0.4",
+  "version": "3.0.5",
   "description": "API ",
@@ -28,7 +28,8 @@ "main": "dist/cjs/index.js",
     "@microsoft/api-extractor-model": "^7.25.2",
-    "@wixc3/common": "^3.0.4",
-    "@wixc3/fs-utils": "^3.0.4",
-    "prettier": "^2.7.1",
+    "@wixc3/common": "^3.0.5",
+    "@wixc3/fs-utils": "^3.0.5",
+    "glob": "^8.0.3",
+    "prettier": "^2.8.0",
     "yargs": "^17.6.2"
   }
 }

src/build-docs/build-docs.ts

 /* eslint-disable no-console */
 import type { Config } from '../common';
 import type { Macros } from '../macros.types';
+import { validateExamples } from '../validate-examples';
 import { analyze, evaluateMacros, generateMarkdown, prettify } from './build-steps';
@@ -11,6 +12,7 @@ export type { Macros };
     generateMarkdown: true,
-    prettify: true
-}
+    prettify: true,
+    validateExamples: true,
+};
 
-export type BuildSteps = Partial<typeof all>
+export type BuildSteps = Partial<typeof all>;
 
@@ -21,12 +23,8 @@ /**
 export function buildDocs(config: Config, steps: BuildSteps = all, macros?: Macros) {
-    const { error } = console
-    // suppress console.error abuse by apiDocumenter
-    console.error = () => {/* */ };
-    steps = { ...all, ...steps }
+    steps = { ...all, ...steps };
     if (steps.analyze) analyze(config);
+    if (steps.validateExamples) validateExamples(config);
     if (steps.generateMarkdown) generateMarkdown(config);
     if (steps.evaluateMacros) evaluateMacros(config, macros);
-    if (steps.prettify) prettify(config)
-    console.error = error
+    if (steps.prettify) prettify(config);
 }
-

src/build-docs/build-steps.ts

@@ -81,2 +81,2 @@ /* eslint-disable no-console */
     console.timeEnd('Prettifying');
-}
+}

src/build-docs/index.ts

@@ -1,1 +0,1 @@
-export { buildDocs } from './build-docs'
+export { buildDocs } from './build-docs';

src/cli.options.ts

@@ -1,2 +0,1 @@
-
 export const packages = {
@@ -56,1 +55,8 @@ alias: 'p',
 };
+
+export const examples = {
+    alias: 'e',
+    default: 'src/test',
+    describe: 'examples source root',
+    string: true,
+};

src/cli.ts

 import { join } from 'path';
 import yargs from 'yargs/yargs';
 import { buildDocs } from './build-docs/build-docs';
-import { loadConfig } from './common';
+import { loadConfig, UserConfig } from './common';
 import { createReadme } from './create-readme';
 import { init } from './init';
-import { base, conf, docs, force, origin, packages, siteUrl, skipAnalyze, temp } from './cli.options'
+import { base, conf, docs, examples, force, origin, packages, siteUrl, skipAnalyze, temp } from './cli.options';
+import * as args from './cli.options';
+import { validateExamples } from './validate-examples';
+import { filter } from '@wixc3/common';
 
 export function cli() {
     yargs(process.argv.slice(2))
+        .fail((msg, err, yargs) => {
+            // eslint-disable-next-line no-console
+            console.log(yargs.help());
+        })
         .scriptName('docs')
         .usage('$0 <cmd> [args]')
-        .command('build', 'Build doc markdown from packages TSDocs', { conf, base, skipAnalyze }, ({ base, conf, skipAnalyze }) => {
-            buildDocs(loadConfig(join(base, conf)), { analyze: !skipAnalyze });
-        })
         .command(
+            'build',
+            'Build doc markdown from packages TSDocs',
+            { conf, base, skipAnalyze },
+            ({ base, conf, skipAnalyze }) => {
+                try {
+                    buildDocs(loadConfig(join(base, conf)), { analyze: !skipAnalyze });
+                } catch (e) {
+                    // eslint-disable-next-line no-console
+                    console.error((e as Error).stack);
+                    process.exit(1);
+                }
+            }
+        )
+        .command(
             'init',
             'initialize docs config and github pages action',
-            { packages, conf, docs, siteUrl, base, temp, force, origin },
-            ({ packages, conf, docs, siteUrl, base, temp, force, origin }) => {
-                init({ packages, conf, docs, siteUrl, base, temp, origin }, force);
+            { packages, conf, docs, siteUrl, base, temp, force, origin, examples },
+            (params) => {
+                try {
+                    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+                    const { force, ...rest } = params;
+                    const config = Object.fromEntries(
+                        filter(Object.entries(rest), ([key, _]) => key in args)
+                    ) as UserConfig;
+                    init(config, force);
+                } catch (e) {
+                    // eslint-disable-next-line no-console
+                    console.error((e as Error).stack);
+                    process.exit(1);
+                }
             }
         )
-        .command('readme', 'create README.md for all the packages', { conf, base, siteUrl }, ({ conf, base, siteUrl }) => {
-            createReadme(loadConfig(join(base, conf)), siteUrl);
+        .command(
+            'readme',
+            'create README.md for all the packages',
+            { conf, base, siteUrl },
+            ({ conf, base, siteUrl }) => {
+                try {
+                    createReadme(loadConfig(join(base, conf)), siteUrl);
+                } catch (e) {
+                    // eslint-disable-next-line no-console
+                    console.error((e as Error).stack);
+                    process.exit(1);
+                }
+            }
+        )
+        .command('validate', 'create README.md for all the packages', { conf }, ({ conf }) => {
+            try {
+                validateExamples(loadConfig(conf));
+            } catch (e) {
+                // eslint-disable-next-line no-console
+                console.error((e as Error).stack);
+                process.exit(1);
+            }
         })
         .demandCommand()
         .help()
-        .parseAsync()
-        .catch((e) => {
-            // eslint-disable-next-line no-console
-            console.error(e);
-            process.exit(1);
-        });
+        .parseSync();
 }

src/common.ts

@@ -13,3 +13,3 @@ import { first, Nullable } from '@wixc3/common';
     unscopedName: string;
-}
+};
 
@@ -36,2 +36,15 @@ export function listPackages(config: UserConfig): Package[] {
 
+export const getPackageByName = (config: Config, name: string) => {
+    const found = listPackages(config).find(({ name: pkg }) => {
+        if (isWixDocs(config) && name === '@wixc3/docs-macros') {
+            return pkg === '@wixc3/docs';
+        }
+        return pkg === name;
+    });
+    if (!found) {
+        throw new Error(`Packages not found: "${name}"`);
+    }
+    return found;
+};
+
 export const stripName = (name: string) => {
@@ -50,2 +63,3 @@ const base = basename(name).split('.')[0]!;
 }
+
 export const execMacro = (data: string, replace: Record<string, string | ((...args: string[]) => string)>) => {
@@ -69,2 +83,3 @@ for (const match of data.matchAll(/(?<!`|<code>)((\\?)\[){3}(.+?)(\2\]){3}/g)) {
 };
+
 export function getRepo(assert: true, overrideOrigin?: string): Repo;
@@ -105,2 +120,3 @@ export function getRepo(): Nullable<Repo>;
     siteUrl?: string;
+    examples: string;
 };
@@ -107,0 +123,0 @@

src/create-readme.ts

@@ -20,4 +20,4 @@ import { backSlash } from '@wixc3/fs-utils';
     };
-    listPackages(config).map(pkg => copyWithSiteUrlLinks(pkg));
+    listPackages(config).map((pkg) => copyWithSiteUrlLinks(pkg));
     copyWithSiteUrlLinks({ dir: '..', name: 'index', unscopedName: 'index' });
 }

src/init.ts

@@ -41,5 +41,8 @@ import { join, relative } from 'path';
             ...config,
-            git: getRepo(true, config.origin === origin.default
-                ? undefined
-                : `origin	${config.origin} (fetch)\norigin	${config.origin} (push)`)
+            git: getRepo(
+                true,
+                config.origin === origin.default
+                    ? undefined
+                    : `origin	${config.origin} (fetch)\norigin	${config.origin} (push)`
+            ),
         },
@@ -46,0 +49,0 @@ force

src/macros.ts

@@ -5,3 +5,2 @@ import { readPackageJson } from '@wixc3/fs-utils';
 import { processMacros } from './process-macros';
-import { repeat } from '@wixc3/common';
 import type { Macro } from './macros.types';
@@ -166,3 +165,3 @@
  */
-export const h: Macro = (_, __, level, ...title) => `${repeat('#', parseInt(level))} ${title.join(' ')}\n`;
+export const h: Macro = (_, __, level, ...title) => `${'#'.repeat(parseInt(level))} ${title.join(' ')}\n`;
 
@@ -169,0 +168,0 @@ /**

src/test/build.unit.ts

@@ -14,35 +14,47 @@ /* eslint-disable @typescript-eslint/no-unsafe-return */
         this.timeout(15_000);
-        buildDocs(config);
+        // analyze once for all the tests
+        buildDocs(config, {
+            analyze: true,
+            validateExamples: false,
+            evaluateMacros: false,
+            generateMarkdown: false,
+            prettify: false,
+        });
     });
     after(clean);
-    it('builds readme files in the docs directory', function () {
-        expect(docExists('index.md')).to.equal(true);
-        expect(docExists('one.md')).to.equal(true);
-        expect(docExists('one.test1.md')).to.equal(true);
-        expect(docExists('two.md')).to.equal(true);
-        expect(docExists('two.test1.md')).to.equal(true);
+    describe('analyze step', () => {
+        it('generate api jsons in the temp directory', () => {
+            expect(existsSync(_temp(config, 'one.api.json'))).to.equal(true);
+            expect(existsSync(_temp(config, 'two.api.json'))).to.equal(true);
+        });
+        it('generate api jsons for packages with names that are different than their directory name', () => {
+            expect(existsSync(_temp(config, 'different-name.api.json'))).to.equal(true);
+        });
     });
-    it('generate api jsons in the temp directory', () => {
-        expect(existsSync(_temp(config, 'one.api.json'))).to.equal(true);
-        expect(existsSync(_temp(config, 'two.api.json'))).to.equal(true);
-    });
-    it('generate api jsons for packages with names that are different than their directory name', () => {
-        expect(existsSync(_temp(config, 'different-name.api.json'))).to.equal(true);
-    });
-    it('includes headers', function () {
-        overwriteTemplate('index.md', 'INDEX_HEADER');
-        overwriteTemplate('item.md', 'ITEM_HEADER');
-        overwriteTemplate('package.md', 'PACKAGE_HEADER');
 
-        buildDocs(config, { analyze: false, prettify: false });
+    describe('generateMarkdown step', () => {
+        it('builds readme files in the docs directory', function () {
+            buildDocs(config, { validateExamples: false, analyze: false });
 
-        expect(readDoc('index.md')).to.match(/INDEX_HEADER/);
-        expect(readDoc('one.md')).to.match(/PACKAGE_HEADER/);
-        expect(readDoc('two.test1.md')).to.match(/ITEM_HEADER/);
-    });
-    it('evaluates macros, passing config filename and args', function () {
-        overwriteTemplate('index.md', '[[[macro 1 !]]]');
+            expect(docExists('index.md')).to.equal(true);
+            expect(docExists('one.md')).to.equal(true);
+            expect(docExists('one.test1.md')).to.equal(true);
+            expect(docExists('two.md')).to.equal(true);
+            expect(docExists('two.test1.md')).to.equal(true);
+        });
+        it('includes headers', function () {
+            overwriteTemplate('index.md', 'INDEX_HEADER');
+            overwriteTemplate('item.md', 'ITEM_HEADER');
+            overwriteTemplate('package.md', 'PACKAGE_HEADER');
 
-        buildDocs(config, { analyze: false, prettify: false },
-            {
+            buildDocs(config, { analyze: false, prettify: false, validateExamples: false });
+
+            expect(readDoc('index.md')).to.match(/INDEX_HEADER/);
+            expect(readDoc('one.md')).to.match(/PACKAGE_HEADER/);
+            expect(readDoc('two.test1.md')).to.match(/ITEM_HEADER/);
+        });
+        it('evaluates macros, passing config filename and args', function () {
+            overwriteTemplate('index.md', '[[[macro 1 !]]]');
+
+            buildDocs(config, { analyze: false, prettify: false, validateExamples: false }, {
                 macro: (conf, docFileName, a, b) => {
@@ -55,3 +67,4 @@ expect(conf).to.deep.include(config);
 
-        expect(readDoc('index.md')).to.match(/MACRO1!/);
+            expect(readDoc('index.md')).to.match(/MACRO1!/);
+        });
     });
@@ -62,4 +75,3 @@
             this.timeout(10_000);
-            buildDocs(config, { analyze: false, prettify: false });
-
+            buildDocs(config, { analyze: false, prettify: false, validateExamples: false });
         });
@@ -78,3 +90,3 @@ beforeEach(() => {
             overwriteTemplate('index.md', '`[[[comment]]]`');
-            buildDocs(config, { analyze: false, prettify: false }, { comment });
+            buildDocs(config, { analyze: false, prettify: false, validateExamples: false }, { comment });
             const content = readDoc('index.md');
@@ -81,0 +93,0 @@ expect(content).to.match(/`\[\[\[comment\]\]\]`/g);

src/test/cli.unit.ts

@@ -1,34 +0,88 @@
-import { expect } from "chai";
-import { spawnSync } from "child_process";
-import { existsSync, readFileSync } from "fs";
-import { after } from "mocha";
-import { _config, _docs, _packages } from "../common";
-import { clean, config, setup } from "./test-common";
+import { expect } from 'chai';
+import { spawnSync } from 'child_process';
+import { existsSync, readFileSync, rmSync } from 'fs';
+import { after } from 'mocha';
+import { _config, _docs, _packages, _temp } from '../common';
+import { clean, config, setup } from './test-common';
 
+const args = ['-b', config.base, '-c', config.conf];
+
 describe('cli', function () {
-    this.timeout(25_000)
-    before(() => setup(false))
-    after(clean)
+    this.timeout(25_000);
+    before(() => setup(false));
+    before(() => {
+        spawnSync('yarn', [
+            'docs',
+            'init',
+            ...args,
+            '-d',
+            config.docs,
+            '-t',
+            config.temp,
+            '-s',
+            'https:/test.site.com',
+            '-o',
+            '[e-mail]:test/docs.git',
+            '-e',
+            'src',
+        ]);
+    });
+    afterEach(() => {
+        rmSync(_temp(config), { force: true, recursive: true });
+    });
+    after(clean);
 
-    it('init, build, readme', () => {
-        spawnSync('yarn', ['docs', 'init', '-b', config.base, '-c', config.conf, '-d', config.docs, '-t', config.temp, '-s', 'https:/test.site.com', '-o', '[e-mail]:test/docs.git'])
-        expect(JSON.parse(readFileSync(_config(config, 'config.json'), 'utf8'))).to.eql({
-            ...config,
-            siteUrl: "https:/test.site.com",
-            origin: "[e-mail]:test/docs.git",
-            git: {
-                host: "github.com",
-                org: "test",
-                repo: "docs",
-                pages: "https://test.github.io/docs",
-                github: "https://github.com/test/docs"
-            }
-        }, 'failed docs init')
+    describe('docs init', () => {
+        it('creates the config file', () => {
+            expect(JSON.parse(readFileSync(_config(config, 'config.json'), 'utf8'))).to.eql(
+                {
+                    ...config,
+                    siteUrl: 'https:/test.site.com',
+                    origin: '[e-mail]:test/docs.git',
+                    examples: 'src',
+                    git: {
+                        host: 'github.com',
+                        org: 'test',
+                        repo: 'docs',
+                        pages: 'https://test.github.io/docs',
+                        github: 'https://github.com/test/docs',
+                    },
+                },
+                'failed docs init'
+            );
+        });
+    });
 
-        spawnSync('yarn', ['docs', 'build', '-b', config.base, '-c', config.conf])
-        expect(existsSync(_docs(config, 'index.md'))).to.equal(true, 'failed docs build')
+    describe('docs build', () => {
+        it('validates examples', () => {
+            const exec = spawnSync('yarn', ['docs', 'build', ...args]);
+            expect(exec.status, exec.stderr.toString()).to.equal(1);
+        });
+        it('generates docs', () => {
+            rmSync(_packages(config, 'one'), { force: true, recursive: true });
+            rmSync(_packages(config, 'weird'), { force: true, recursive: true });
 
-        spawnSync('yarn', ['docs', 'readme', '-b', config.base, '-c', config.conf])
-        expect(existsSync(_packages(config, '..', 'README.md'))).to.equal(true, 'failed docs readme')
-    })
+            const exec = spawnSync('yarn', ['docs', 'build', '-b', config.base, '-c', config.conf]);
+            expect(exec.status, exec.stderr.toString()).to.equal(0);
+            expect(existsSync(_docs(config, 'index.md'))).to.equal(true, 'failed docs build');
+            expect(existsSync(_docs(config, 'two.md'))).to.equal(true, 'failed docs build');
+            expect(existsSync(_docs(config, 'two.test1.md'))).to.equal(true, 'failed docs build');
+        });
+    });
+    describe('readme', () => {
+        before(() => {
+            rmSync(_packages(config, 'one'), { force: true, recursive: true });
+            rmSync(_packages(config, 'weird'), { force: true, recursive: true });
+
+            const exec = spawnSync('yarn', ['docs', 'build', '-b', config.base, '-c', config.conf]);
+            expect(exec.status, exec.stderr.toString()).to.equal(0);
+        });
+        it('generated readme in packages root', () => {
+            const exec = spawnSync('yarn', ['docs', 'readme', ...args]);
+            expect(exec.status, exec.stderr.toString()).to.equal(0);
+
+            expect(existsSync(_packages(config, '..', 'README.md'))).to.equal(true, 'failed docs readme');
+            expect(existsSync(_packages(config, 'two', 'README.md'))).to.equal(true, 'failed docs readme');
+        });
+    });
 });

src/test/readme.unit.ts

@@ -17,4 +17,4 @@ /* eslint-disable @typescript-eslint/no-unsafe-return */
         this.timeout(15_000);
-        buildDocs(config);
-        createReadme(config)
+        buildDocs(config, { validateExamples: false });
+        createReadme(config);
     });
@@ -29,3 +29,3 @@ after(clean);
         expect(existsSync(_packages(config, '..', 'README.md'))).to.equal(true);
-        const content = readFileSync(_packages(config, '..', 'README.md'), 'utf8')
+        const content = readFileSync(_packages(config, '..', 'README.md'), 'utf8');
         expect(content).to.match(/\[@test\/one\]/);
@@ -32,0 +32,0 @@ expect(content).to.match(/\[@test\/two\]/);

src/test/resources/project/packages/one/dist/cjs/index.d.ts

@@ -0,2 +1,8 @@
+/**
+ * @example
+ * ```ts (Example1)
+ * 'outdated example'
+ * ```
+ */
 export declare function test1(): number;
 //# sourceMappingURL=index.d.ts.map

src/test/resources/project/packages/one/dist/cjs/index.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.test1 = void 0;
+/**
+ * @example
+ * ```ts (Example1)
+ * 'outdated example'
+ * ```
+ */
 function test1() {
@@ -5,0 +11,0 @@ const a = 1;

src/test/resources/project/packages/one/src/index.ts

@@ -0,1 +1,7 @@
+/**
+ * @example
+ * ```ts (Example1)
+ * 'outdated example'
+ * ```
+ */
 export function test1() {
@@ -2,0 +8,0 @@ const a = 1;

src/test/resources/project/packages/two/dist/cjs/index.d.ts

@@ -0,2 +1,23 @@
+/**
+ *
+ * @example
+ * ```ts (Example1)
+ * expect(test1()).to.equal(1)
+ * ```
+ */
 export declare function test1(): number;
+/**
+ * @example
+ * ```ts
+ * test2() // => 2
+ * ```
+ */
+export declare function test2(): number;
+/**
+ * @example
+ * ```ts (Example3)
+ * test3() // => 3
+ * ```
+ */
+export declare function test3(): number;
 //# sourceMappingURL=index.d.ts.map

src/test/resources/project/packages/two/dist/cjs/index.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.test1 = void 0;
+exports.test3 = exports.test2 = exports.test1 = void 0;
+/**
+ *
+ * @example
+ * ```ts (Example1)
+ * expect(test1()).to.equal(1)
+ * ```
+ */
 function test1() {
@@ -8,2 +15,22 @@ return 1;
 exports.test1 = test1;
+/**
+ * @example
+ * ```ts
+ * test2() // => 2
+ * ```
+ */
+function test2() {
+    return 2;
+}
+exports.test2 = test2;
+/**
+ * @example
+ * ```ts (Example3)
+ * test3() // => 3
+ * ```
+ */
+function test3() {
+    return 3;
+}
+exports.test3 = test3;
 //# sourceMappingURL=index.js.map

src/test/resources/project/packages/two/src/index.ts

@@ -0,3 +1,30 @@
+/**
+ *
+ * @example
+ * ```ts (Example1)
+ * expect(test1()).to.equal(1)
+ * ```
+ */
 export function test1() {
     return 1;
 }
+
+/**
+ * @example
+ * ```ts
+ * test2() // => 2
+ * ```
+ */
+export function test2() {
+    return 2;
+}
+
+/**
+ * @example
+ * ```ts (Example3)
+ * test3() // => 3
+ * ```
+ */
+export function test3() {
+    return 3;
+}

src/test/resources/project/packages/weird/dist/cjs/index.d.ts

@@ -0,2 +1,9 @@
+/**
+ *
+ * @example
+ * ```ts (Example1)
+ * expect(test1()).to.equal(1)
+ * ```
+ */
 export declare function test1(): number;
 //# sourceMappingURL=index.d.ts.map

src/test/resources/project/packages/weird/dist/cjs/index.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.test1 = void 0;
+/**
+ *
+ * @example
+ * ```ts (Example1)
+ * expect(test1()).to.equal(1)
+ * ```
+ */
 function test1() {
@@ -5,0 +12,0 @@ return 1;

src/test/resources/project/packages/weird/src/index.ts

@@ -0,3 +1,10 @@
+/**
+ *
+ * @example
+ * ```ts (Example1)
+ * expect(test1()).to.equal(1)
+ * ```
+ */
 export function test1() {
     return 1;
 }

src/test/test-common.ts

@@ -15,2 +15,3 @@ import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
     temp: 'test-temp',
+    examples: 'src/test',
     git: {
@@ -21,4 +22,4 @@ github: 'https://github.com/org/repo',
         pages: 'https://org.github.io/repo',
-        repo: 'repo'
-    }
+        repo: 'repo',
+    },
 };
@@ -42,2 +43,3 @@
     clean();
+    // Suppress logs during test
     // eslint-disable-next-line no-console
@@ -47,2 +49,6 @@ console.log = () => {
     };
+    // eslint-disable-next-line no-console
+    console.warn = () => {
+        /* */
+    };
     mkdirSync(config.base, { recursive: true });
@@ -53,6 +59,3 @@ cpSync(join(__dirname, '..', '..', '..', 'src', 'test', 'resources', 'project'), config.base, { recursive: true });
     if (_init) {
-        init(
-            userConfig,
-            true
-        );
+        init(userConfig, true);
     }
@@ -86,3 +89,3 @@ };
 
-    buildDocs(config, { analyze: false, prettify: false });
+    buildDocs(config, { analyze: false, prettify: false, validateExamples: false });
     return readDoc(filename)
@@ -89,0 +92,0 @@ .replaceAll(/>>>>>>>(.*)<<<<<<<.*$/gs, '$1')

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

233402

increased by18.97%

Number of package files

169

increased by13.42%

Lines of code

4181

increased by21.58%

Worsened metrics

Dependency count

8

increased by14.29%

Number of low supply chain risk alerts

13

increased by18.18%

Dependency changes

• + Addedglob@^8.0.3

• + Addedbrace-expansion@2.0.1(transitive)

• + Addedfs.realpath@1.0.0(transitive)

• + Addedglob@8.1.0(transitive)

• + Addedinflight@1.0.6(transitive)

• + Addedinherits@2.0.4(transitive)

• + Addedminimatch@5.1.6(transitive)

• + Addedonce@1.4.0(transitive)

• + Addedwrappy@1.0.2(transitive)

• Updated@wixc3/common@^3.0.5

• Updated@wixc3/fs-utils@^3.0.5

• Updatedprettier@^2.8.0