@doccident/doccident 0.0.1

package/LICENSE

@@ -0,0 +1,24 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Nick Johnstone
+
+Copyright (c) 2025 Billaud Cipher
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,179 @@
+[![npm version](https://badge.fury.io/js/doccident.svg)](http://badge.fury.io/js/doccident)
+[![Build Status](https://travis-ci.org/Widdershin/doccident.svg?branch=master)](https://travis-ci.org/Widdershin/doccident)
+[![Greenkeeper badge](https://badges.greenkeeper.io/Widdershin/doccident.svg)](https://greenkeeper.io/)
+
+* * *
+
+# doccident
+
+Test all the code in your markdown docs!
+
+Why on earth?
+---
+
+As an open source developer, there are few things more embarrassing than a user opening an issue to inform you that your README example is broken! With  `doccident`, you can rest easy knowing that your example code is *actually runnable*.
+
+Installation
+---
+Just `npm install @doccident/doccident` and run `doccident`. It will run all of the Javascript code examples tucked away in your markdown, and let you know if any blow up.
+
+Okay, how do I use it?
+---
+
+Let's try it on this repo!
+
+```js
+var a = 5;
+
+var b = 10;
+
+console.log(a + c);
+```
+
+There's a problem with that example. `doccident` finds it for us:
+
+```bash
+$ doccident
+x..
+
+Failed - README.md:32:17
+evalmachine.<anonymous>:7
+console.log(a + c);
+                ^
+
+ReferenceError: c is not defined
+```
+
+Awesome! No excuse for broken documentation ever again, right? :wink:
+
+We can also run specific files or folders by running `doccident` with a glob, like `doccident docs/**/*.md`. By default `doccident` will recursively run all the `.md` or `.markdown` files starting with the current directory, with the exception of the `node_modules` directory.
+
+Note: `doccident` doesn't actually attempt to provide any guarantee that your code worked, only that it didn't explode in a horrible fashion. If you would like to use `doccident` for actually testing the correctness of your code, you can add some `assert`s to your examples.
+
+`doccident` is not a replacement for your test suite. It's designed to run with your CI build and give you peace of mind that all of your examples are at least vaguely runnable.
+
+So how do I write those examples?
+---
+
+In your markdown files, anything inside of code blocks with 'js' or 'es6' will be run. E.g:
+
+    ```js
+    console.log("Yay, tests in my docs");
+    ```
+
+    ```es6
+    const a = 5;
+    console.log({a, foo: 'test'});
+    ```
+
+I have a code example I don't want tested!
+---
+You can tell `doccident` to skip examples by adding `<!-- skip-example -->` before the example. E.g:
+
+    <!-- skip-example -->
+    ```js
+    // not a runnable example
+
+    var foo = download(...);
+    ```
+
+How do requires work? And other setup logic?
+---
+
+You can `require` any needed modules or example helpers in `.doccident-setup.js`. E.g:
+
+<!-- skip-example -->
+```js
+// .doccident-setup.js
+module.exports = {
+  require: {
+    Rx: require('rx')
+  },
+
+  globals: {
+    $: require('jquery')
+  }
+}
+```
+
+Anything exported under `require` will then be used by any examples that `require` that key.
+You must explicitly configure all of the dependencies used in your examples.
+
+Anything exported under `globals` will be available globally across all examples.
+
+You can also specify a regexRequire section to handle anything more complex than an exact string match!
+
+<!-- skip-example -->
+```js
+// .doccident-setup.js
+module.exports = {
+  require: {
+    Rx: require('rx')
+  },
+
+  regexRequire: {
+    'rx/(.*)': function (fullPath, matchedModuleName) {
+      return require('./dist/' + matchedModuleName);
+    }
+  }
+}
+```
+
+Do I have to enable es6 support?
+---
+
+Nope, ES6 support is on by default. You can disable `babel` support
+in your `.doccident-setup.js` file.
+This will speed things up drastically:
+
+<!-- skip-example -->
+```js
+//.doccident-setup.js
+module.exports = {
+  babel: false
+}
+```
+
+What if I have global state that needs to be reset after my examples run?
+---
+<!-- skip-example -->
+```js
+//.doccident-setup.js
+module.exports = {
+  beforeEach: function () {
+    // reset your awesome global state
+  }
+}
+```
+
+You can specify a function to be run before each example in your `.doccident-setup.js`.
+
+What if I want to remove custom syntax from examples before processing?
+---
+
+<!-- skip-example -->
+```js
+//.doccident-setup.js
+module.exports = {
+  transformCode(code) {
+    // Remove ... from code syntax
+    return code.replace(/\.\.\./g, "");
+  }
+}
+```
+
+Who uses doccident?
+---
+
+All of these projects either run `doccident` with `npm test` or as part of their CI process:
+
+* [lodash](https://github.com/lodash/lodash)
+* [Moment](https://github.com/moment/momentjs.com)
+* [RxJS](https://github.com/ReactiveX/RxJS)
+* [most](https://github.com/cujojs/most)
+* [xstream](https://github.com/staltz/xstream)
+* [cyclejs/time](https://github.com/cyclejs/time)
+* [rx.schedulers](https://github.com/Reactive-Extensions/rx.schedulers)
+* [rx.priorityqueue](https://github.com/Reactive-Extensions/rx.priorityqueue)
+* [rx.disposables](https://github.com/Reactive-Extensions/rx.disposables)
+* [rx-undoable](https://github.com/Widdershin/rx-undoable)

package/bin/cmd.js

@@ -0,0 +1,83 @@
+#! /usr/bin/env node
+/* eslint-disable no-console */
+/* eslint-disable @typescript-eslint/no-require-imports */
+'use strict';
+
+const { version } = require('../package');
+const doctest = require('..');
+const program = require('commander');
+const path = require('path');
+const glob = require('glob');
+const fs = require('fs');
+const { pathToFileURL } = require('url');
+
+const DEFAULT_GLOB = '**/*.+(md|markdown)';
+const DEFAULT_IGNORE = [
+    '**/node_modules/**',
+    '**/bower_components/**'
+];
+
+// Config
+const config = {
+    require: {},
+    globals: {},
+    ignore: [],
+    testOutput: false
+};
+
+// Setup commander
+program
+    .name('doccident')
+    .description('Test all the code in your markdown docs!')
+    .version(version, '-v, --version', 'output the current version')
+    .helpOption('-h, --help', 'output usage informations')
+    .option('-c, --config <path>', 'custom config location', path.join(process.cwd(), '/.doccident-setup.js'))
+    .option('--test-output', 'output the test results to the console')
+    .parse(process.argv);
+
+// Parse config file
+(async () => {
+    if (program.config) {
+        const configPath = path.resolve(program.config);
+
+        if (fs.existsSync(configPath)) {
+            try {
+                const customConfig = await import(pathToFileURL(configPath).href);
+                Object.assign(config, customConfig.default || customConfig);
+            } catch (e) {
+                console.error(`Cannot load config "${configPath}":`, e);
+                process.exit(1);
+            }
+        }
+    }
+
+    if (program.testOutput) {
+        config.testOutput = true;
+    }
+
+    // Resolve files
+    glob(
+        program.args[0] || DEFAULT_GLOB,
+        {
+            ignore: [...config.ignore, ...DEFAULT_IGNORE]
+        },
+        (err, files) => {
+
+            if (err) {
+                console.trace(err);
+            }
+
+            // Run tests
+            const results = doctest.runTests(files, config);
+
+            console.log('\n');
+            doctest.printResults(results);
+
+            // Exit with error-code if any test failed
+            const failures = results.filter(result => result.status === 'fail');
+            if (failures.length > 0) {
+                process.exit(1);
+            }
+        }
+    );
+})();

package/dist/doctest.js

@@ -0,0 +1,158 @@
+/* eslint-disable no-console */
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runTests = runTests;
+exports.printResults = printResults;
+var fs_1 = require("fs");
+var vm_1 = require("vm");
+var core_1 = require("@babel/core");
+var preset_env_1 = require("@babel/preset-env");
+var chalk_1 = require("chalk");
+function flatten(arr) {
+    return Array.prototype.concat.apply([], arr);
+}
+var parse_code_snippets_from_markdown_1 = require("./parse-code-snippets-from-markdown");
+function runTests(files, config) {
+    var results = files
+        .map(read)
+        .map(parse_code_snippets_from_markdown_1.default)
+        .map(testFile(config));
+    return flatten(results);
+}
+function read(fileName) {
+    return { contents: (0, fs_1.readFileSync)(fileName, "utf8"), fileName: fileName };
+}
+function makeTestSandbox(config) {
+    function sandboxRequire(moduleName) {
+        for (var regexRequire in config.regexRequire) {
+            var regex = new RegExp(regexRequire);
+            var match = regex.exec(moduleName);
+            var handler = config.regexRequire[regexRequire];
+            if (match) {
+                return handler.apply(void 0, match);
+            }
+        }
+        if (config.require[moduleName] === undefined) {
+            throw moduleNotFoundError(moduleName);
+        }
+        return config.require[moduleName];
+    }
+    var sandboxConsole = {
+        log: function () { return null; },
+    };
+    var sandboxGlobals = { require: sandboxRequire, console: config.testOutput ? console : sandboxConsole };
+    var sandbox = Object.assign({}, sandboxGlobals, config.globals);
+    return sandbox;
+}
+function testFile(config) {
+    return function testFileWithConfig(args) {
+        var codeSnippets = args.codeSnippets;
+        var fileName = args.fileName;
+        var shareCodeInFile = args.shareCodeInFile;
+        var results;
+        if (shareCodeInFile) {
+            var sandbox = makeTestSandbox(config);
+            results = codeSnippets.map(test(config, fileName, sandbox));
+        }
+        else {
+            results = codeSnippets.map(test(config, fileName));
+        }
+        return results;
+    };
+}
+function test(config, filename, sandbox) {
+    return function (codeSnippet) {
+        if (codeSnippet.skip) {
+            return { status: "skip", codeSnippet: codeSnippet, stack: "" };
+        }
+        var success = false;
+        var stack = "";
+        var code = codeSnippet.code;
+        if (config.transformCode) {
+            try {
+                code = config.transformCode(code);
+            }
+            catch (e) {
+                return { status: "fail", codeSnippet: codeSnippet, stack: "Encountered an error while transforming snippet: \n" + e.stack };
+            }
+        }
+        var perSnippetSandbox;
+        if (sandbox === undefined) {
+            perSnippetSandbox = makeTestSandbox(config);
+        }
+        if (config.beforeEach) {
+            config.beforeEach();
+        }
+        var options = {
+            presets: [preset_env_1.default],
+        };
+        try {
+            if (config.babel !== false) {
+                code = (0, core_1.transformSync)(code, options).code;
+            }
+            (0, vm_1.runInNewContext)(code, perSnippetSandbox || sandbox);
+            success = true;
+        }
+        catch (e) {
+            stack = e.stack || "";
+        }
+        var status = success ? "pass" : "fail";
+        process.stdout.write(success ? chalk_1.default.green(".") : chalk_1.default.red("x"));
+        return { status: status, codeSnippet: codeSnippet, stack: stack };
+    };
+}
+function printResults(results) {
+    results.filter(function (result) { return result.status === "fail"; }).forEach(printFailure);
+    var passingCount = results.filter(function (result) { return result.status === "pass"; })
+        .length;
+    var failingCount = results.filter(function (result) { return result.status === "fail"; })
+        .length;
+    var skippingCount = results.filter(function (result) { return result.status === "skip"; })
+        .length;
+    function successfulRun() {
+        return failingCount === 0;
+    }
+    console.log(chalk_1.default.green("Passed: " + passingCount));
+    if (skippingCount > 0) {
+        console.log(chalk_1.default.yellow("Skipped: " + skippingCount));
+    }
+    if (successfulRun()) {
+        console.log(chalk_1.default.green("\nSuccess!"));
+    }
+    else {
+        console.log(chalk_1.default.red("Failed: " + failingCount));
+    }
+}
+function printFailure(result) {
+    console.log(chalk_1.default.red("Failed - ".concat(markDownErrorLocation(result))));
+    var stackDetails = relevantStackDetails(result.stack);
+    console.log(stackDetails);
+    var variableNotDefined = stackDetails.match(/(\w+) is not defined/);
+    if (variableNotDefined) {
+        var variableName = variableNotDefined[1];
+        console.log("You can declare ".concat(chalk_1.default.blue(variableName), " in the ").concat(chalk_1.default.blue("globals"), " section in ").concat(chalk_1.default.grey(".doccident-setup.js")));
+        console.log("\nFor example:\n".concat(chalk_1.default.grey("// .doccident-setup.js"), "\nmodule.exports = {\n  globals: {\n    ").concat(chalk_1.default.blue(variableName), ": ...\n  }\n}\n    "));
+    }
+}
+function relevantStackDetails(stack) {
+    var match = stack.match(/([\w\W]*?)at eval/) ||
+        // eslint-disable-next-line no-useless-escape
+        stack.match(/([\w\W]*)at [\w*\/]*?doctest.js/);
+    if (match !== null) {
+        return match[1];
+    }
+    return stack;
+}
+function moduleNotFoundError(moduleName) {
+    return new Error("\nAttempted to require '".concat(chalk_1.default.blue(moduleName), "' but was not found in config.\nYou need to include it in the require section of your ").concat(chalk_1.default.grey(".doccident-setup.js"), " file.\n\nFor example:\n").concat(chalk_1.default.grey("// .doccident-setup.js"), "\nmodule.exports = {\n  require: {\n    ").concat(chalk_1.default.blue("'".concat(moduleName, "': require('").concat(moduleName, "')")), "\n  }\n}\n  "));
+}
+function markDownErrorLocation(result) {
+    var match = result.stack.match(/eval.*<.*>:(\d+):(\d+)/);
+    if (match) {
+        var mdLineNumber = parseInt(match[1], 10);
+        var columnNumber = parseInt(match[2], 10);
+        var lineNumber = result.codeSnippet.lineNumber + mdLineNumber;
+        return "".concat(result.codeSnippet.fileName, ":").concat(lineNumber, ":").concat(columnNumber);
+    }
+    return "".concat(result.codeSnippet.fileName, ":").concat(result.codeSnippet.lineNumber);
+}

package/dist/parse-code-snippets-from-markdown.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+var isStartOfSnippet = function (line) {
+    return line.trim().match(/```\W*(JavaScript|js|es6)\s?$/i);
+};
+var isEndOfSnippet = function (line) { return line.trim() === "```"; };
+var isSkip = function (line) { return line.trim() === "<!-- skip-example -->"; };
+var isCodeSharedInFile = function (line) {
+    return line.trim() === "<!-- share-code-between-examples -->";
+};
+function startNewSnippet(snippets, fileName, lineNumber) {
+    var skip = snippets.skip;
+    snippets.skip = false;
+    return Object.assign(snippets, {
+        snippets: snippets.snippets.concat([
+            { code: "", fileName: fileName, lineNumber: lineNumber, complete: false, skip: skip }
+        ])
+    });
+}
+function addLineToLastSnippet(line) {
+    return function addLine(snippets) {
+        var lastSnippet = snippets.snippets[snippets.snippets.length - 1];
+        if (lastSnippet && !lastSnippet.complete) {
+            lastSnippet.code += line + "\n";
+        }
+        return snippets;
+    };
+}
+function endSnippet(snippets, fileName, lineNumber) {
+    // eslint-disable-next-line no-console
+    console.log("endSnippet", snippets, fileName, lineNumber);
+    var lastSnippet = snippets.snippets[snippets.snippets.length - 1];
+    if (lastSnippet) {
+        lastSnippet.complete = true;
+    }
+    return snippets;
+}
+function skip(snippets) {
+    snippets.skip = true;
+    return snippets;
+}
+function shareCodeInFile(snippets) {
+    snippets.shareCodeInFile = true;
+    return snippets;
+}
+function parseLine(line) {
+    if (isStartOfSnippet(line)) {
+        return startNewSnippet;
+    }
+    if (isEndOfSnippet(line)) {
+        return endSnippet;
+    }
+    if (isSkip(line)) {
+        return skip;
+    }
+    if (isCodeSharedInFile(line)) {
+        return shareCodeInFile;
+    }
+    return addLineToLastSnippet(line);
+}
+function parseCodeSnippets(args) {
+    var contents = args.contents;
+    var fileName = args.fileName;
+    var initialState = {
+        snippets: [],
+        shareCodeInFile: false,
+        complete: false
+    };
+    var results = contents
+        .split("\n")
+        .map(parseLine)
+        .reduce(function (snippets, lineAction, index) {
+        return lineAction(snippets, fileName, index + 1);
+    }, initialState);
+    var codeSnippets = results.snippets;
+    var lastSnippet = codeSnippets[codeSnippets.length - 1];
+    if (lastSnippet && !lastSnippet.complete) {
+        throw new Error("Snippet parsing was incomplete");
+    }
+    return {
+        fileName: fileName,
+        codeSnippets: codeSnippets,
+        shareCodeInFile: results.shareCodeInFile
+    };
+}
+exports.default = parseCodeSnippets;

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@doccident/doccident",
+  "version": "0.0.1",
+  "description": "Test all the code in your markdown docs!",
+  "main": "dist/doctest.js",
+  "files": [
+    "dist",
+    "bin"
+  ],
+  "bin": {
+    "doccident": "bin/cmd.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/BillaudCipher/doccident"
+  },
+  "keywords": [
+    "markdown",
+    "test",
+    "documentation"
+  ],
+  "contributors": [
+    "Nick Johnstone",
+    "Billaud Cipher <BillaudCipher@proton.me>"
+  ],
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/BillaudCipher/doccident/issues"
+  },
+  "homepage": "https://github.com/BillaudCipher/doccident",
+  "devDependencies": {
+    "@babel/preset-typescript": "^7.27.1",
+    "@eslint/eslintrc": "^3.3.1",
+    "@eslint/js": "^9.23.0",
+    "@types/node": "^22.15.17",
+    "@typescript-eslint/eslint-plugin": "^8.32.0",
+    "@typescript-eslint/parser": "^8.32.0",
+    "eslint": "^9.24.0",
+    "eslint-plugin-import": "^2.31.0",
+    "jest": "^29.7.0",
+    "typescript": "^5.8.3"
+  },
+  "dependencies": {
+    "@babel/core": "^7.27.1",
+    "@babel/preset-env": "^7.27.2",
+    "chalk": "^2.4.2",
+    "commander": "^4.1.1",
+    "glob": "^7.2.3",
+    "globals": "^16.1.0"
+  },
+  "babel": {
+    "presets": [
+      "@babel/preset-env",
+      "@babel/preset-typescript"
+    ]
+  },
+  "scripts": {
+    "build": "tsc",
+    "lint": "eslint . --ext .ts",
+    "test": "jest",
+    "prepublish": "pnpm run build",
+    "clean": "rm -rf dist"
+  }
+}