@datalackey/update-markdown-toc 0.1.3

package/README.md

@@ -0,0 +1,211 @@
+# update-markdown-toc
+
+- [update-markdown-toc](#update-markdown-toc)
+    - [Introduction](#introduction)
+    - [Installation](#installation)
+    - [Usage](#usage)
+        - [Using npx (recommended)](#using-npx-recommended)
+        - [Using npm scripts](#using-npm-scripts)
+        - [Using a direct path (advanced)](#using-a-direct-path-advanced)
+    - [Options](#options)
+    - [TOC Markers](#toc-markers)
+    - [Usage Scenarios](#usage-scenarios)
+        - [As Part of code/test/debug Work Flow](#as-part-of-codetestdebug-work-flow)
+        - [Continuous Integration  (CI)](#continuous-integration--ci)
+        - [Recursively Traversing a Folder Hierarchy to Process all files vs. Single File Processing](#recursively-traversing-a-folder-hierarchy-to-process-all-files-vs-single-file-processing)
+            - [Single-File Processing (Strict Mode)](#single-file-processing-strict-mode)
+            - [Recursive Folder Traversal (Lenient Mode)](#recursive-folder-traversal-lenient-mode)
+    - [Guidelines For Project Contributors](#guidelines-for-project-contributors)
+
+## Introduction
+
+A Node.js command-line **documentation helper** which automatically:
+
+- generates Table of Contents (TOC) blocks for Markdown files
+- operates on either a single file, or recursively finds all `*.md` files from a root path
+- regenerates TOCs from headings, replacing only explicitly marked regions, with no gratuitous reformatting
+- avoids updating files when the generated TOC is already correct
+- provides a `--check` mode which flags Markdown files with stale TOCs (intended for CI)
+
+
+
+## Installation
+
+Install as a development dependency (recommended):
+
+
+```bash
+npm install --save-dev @datalackey/update-markdown-toc
+```
+
+This installs the update-markdown-toc command into your project’s
+node_modules/.bin/ directory.
+
+
+
+## Usage
+
+
+After installation, the `update-markdown-toc` command can be invoked in any
+of the following ways from the project root (or a subdirectory) where the package was installed.
+
+
+### Using npx (recommended)
+
+```bash
+npx update-markdown-toc README.md
+````
+
+
+### Using npm scripts
+
+You may also add a script entry to your package.json:
+
+```json
+{
+  "scripts": {
+    "docs:toc": "update-markdown-toc README.md"
+  }
+}
+```
+Then run:
+
+```bash
+npm run docs:toc
+```
+
+### Using a direct path (advanced)
+
+```bash
+./node_modules/.bin/update-markdown-toc README.md
+```
+
+
+
+## Options
+
+This section assumes the command is invoked using `npx`, an npm script,
+or another method that resolves the local `update-markdown-toc` binary.
+
+
+```text
+update-markdown-toc [options] [file]
+
+Options:
+  -c, --check     <path-to-file-or-folder>  Do not write files; exit non-zero if TOC is stale
+  -r, --recursive <path-to-folder>          Recursively process all .md files under the given folder
+  -v, --verbose                             Print status for every file processed
+  -q, --quiet                               Suppress all non-error output
+  -d, --debug                               Print debug diagnostics to stderr
+  -h, --help                                Show this help message and exit
+```
+
+## TOC Markers
+
+The tool operates only on files containing **both** markers:
+
+```md
+<!-- TOC:START -->
+<!-- TOC:END -->
+```
+
+Any existing content between these markers is lost. The new content will be the generated TOC that
+reflects the section headers marked with '#'s in the Markdown document.
+ 
+Content outside the markers is preserved verbatim.
+
+
+## Usage Scenarios 
+
+
+
+
+### As Part of code/test/debug Work Flow  
+
+To ensure that your code is built afresh, passes tests, and that your documentation TOCs are up to date, you could 
+use invoke the tool in something akin to the package.json below. 
+Before commit and push, you would type:  'npm run build' 
+
+
+Your `package.json` might look like this:
+```json
+{
+  "scripts": {
+    "clean": "rm -rf dist",
+    "compile": "tsc -p tsconfig.json",
+    "pretest": "npm run compile",
+    "test": "jest",
+    "docs:toc": "update-markdown-toc --recursive docs/",
+    "bundle": "esbuild src/index.ts --bundle --platform=node --outdir=dist",
+    "package": "npm run clean && npm run compile && npm run bundle",
+    "build": "npm run docs:toc && npm run test && npm run package"
+  }
+}
+```
+
+### Continuous Integration  (CI)
+
+The --check flag is designed primarily for continuous integration.
+
+In this mode, the tool:
+
+- never writes files
+- compares the existing TOC block against the generated TOC
+- exits with a non-zero status if any TOC is stale
+
+
+Example: 
+
+```bash
+npx update-markdown-toc --check --recursive docs/
+```
+
+
+If a pull request modifies documentation headings but forgets to update TOCs, this command will fail the build, forcing the contributor to regenerate and commit the correct TOC.
+
+### Recursively Traversing a Folder Hierarchy to Process all files vs. Single File Processing
+
+The tool supports two distinct operating modes with intentionally different error-handling semantics:
+
+- Single-file mode (--recursive not specified)
+- Recursive folder traversal mode (--recursive specified)
+
+These modes are designed to support both strict validation and incremental adoption across real-world repositories.
+In the case of the latter mode, we assume some files may not yet have TOC markers, and that this is acceptable.
+
+#### Single-File Processing (Strict Mode)
+
+When a single Markdown file is explicitly specified (or when the default README.md is used), the tool operates in strict mode.
+
+In this mode:
+
+The file must contain both TOC markers:
+```md
+<!-- TOC:START -->
+<!-- TOC:END -->
+
+```
+
+If either marker is missing, the tool prints an error message and exits with a non-zero status code.
+
+
+#### Recursive Folder Traversal (Lenient Mode)
+
+When operating in recursive mode, the tool traverses a directory tree and processes all *.md files it finds.
+In this mode, files without TOC markers are silently skipped, and files with TOC markers are processed normally.
+
+When combined with --verbose, skipped files are reported explicitly in this mode.
+
+update-markdown-toc --recursive docs/ --verbose
+
+Example output:
+
+```
+Skipped (no markers): docs/legacy-notes.md
+Updated: docs/guide.md
+Up-to-date: docs/api.md
+```
+
+## Guidelines For Project Contributors
+
+Contributors to the project should consult [this document](GUIDELINES-FOR-PROJECT-CONTRIBUTORS.md)

package/bin/parseCli.js

@@ -0,0 +1,93 @@
+import { parseArgs } from "node:util";
+import { dedent } from "ts-dedent";
+
+export function parseCli() {
+    let values, positionals;
+
+    try {
+        ({ values, positionals } = parseArgs({
+            options: {
+                check:      { type: "boolean", short: "c" },
+                recursive:  { type: "string",  short: "r" },
+                verbose:    { type: "boolean", short: "v" },
+                quiet:      { type: "boolean", short: "q" },
+                debug:      { type: "boolean", short: "d" },
+                help:       { type: "boolean", short: "h" }
+            },
+            allowShort: true,
+            allowPositionals: true
+        }));
+    } catch (err) {
+        console.error(`ERROR: ${err.message}`);
+        process.exit(1);
+    }
+
+    if (values.help) {
+        printHelp();
+        process.exit(0);
+    }
+
+    const checkMode = values.check === true;
+    const verbose   = values.verbose === true;
+    const quiet     = values.quiet === true;
+    const debug     = values.debug === true;
+
+    const recursivePath =
+        typeof values.recursive === "string" ? values.recursive : null;
+
+    let targetFile = null;
+
+    if (positionals.length > 1) {
+        console.error("ERROR: Only one file argument may be provided");
+        process.exit(1);
+    }
+
+    if (positionals.length === 1) {
+        targetFile = positionals[0];
+    }
+
+    // -------------------------
+    // Contract validation
+    // -------------------------
+
+    if (quiet && verbose) {
+        console.error("ERROR: --quiet and --verbose cannot be used together");
+        process.exit(1);
+    }
+
+    if (checkMode && !recursivePath && !targetFile) {
+        console.error("ERROR: --check requires a file or --recursive <path>");
+        process.exit(1);
+    }
+
+    if (recursivePath && targetFile) {
+        console.error("ERROR: Cannot use --recursive with a file argument");
+        process.exit(1);
+    }
+
+    return Object.freeze({
+        checkMode,
+        verbose,
+        quiet,
+        debug,
+
+        recursivePath,
+        targetFile,
+
+        isRecursive: Boolean(recursivePath)
+    });
+}
+
+function printHelp() {
+    console.log(dedent`
+    update-markdown-toc [options] [file]
+
+    Options:
+      -c, --check     <path-to-file-or-folder>  Do not write files; exit non-zero if TOC is stale
+      -r, --recursive <path-to-folder>          Recursively process all .md files under the given folder
+      -v, --verbose                             Print status for every file processed
+      -q, --quiet                               Suppress all non-error output
+      -d, --debug                               Print debug diagnostics to stderr
+      -h, --help                                Show this help message and exit
+  `);
+}

package/bin/update-markdown-toc.js

@@ -0,0 +1,263 @@
+#!/usr/bin/env node
+
+import fs from "fs";
+import path from "path";
+import { parseCli } from "./parseCli.js";
+
+/* ============================================================
+ * Constants
+ * ============================================================ */
+
+const START = "<!-- TOC:START -->";
+const END   = "<!-- TOC:END -->";
+
+/* ============================================================
+ * CLI configuration
+ * ============================================================ */
+
+const {
+    checkMode,
+    verbose,
+    quiet,
+    debug,
+    recursivePath,
+    targetFile,
+    isRecursive
+} = parseCli();
+
+/* ============================================================
+ * Debug helper
+ * ============================================================ */
+
+function debugLog(msg) {
+    if (debug) {
+        console.error(`[debug] ${msg}`);
+    }
+}
+
+/* ============================================================
+ * Helpers
+ * ============================================================ */
+
+function collectMarkdownFiles(dir) {
+    const results = [];
+
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+
+        if (entry.isDirectory()) {
+            results.push(...collectMarkdownFiles(full));
+        } else if (entry.isFile() && entry.name.endsWith(".md")) {
+            results.push(full);
+        }
+    }
+
+    return results;
+}
+
+function generateTOC(content) {
+    const hasStart = content.includes(START);
+    const hasEnd   = content.includes(END);
+
+    if (!hasStart && !hasEnd) {
+        throw new Error("TOC delimiters not found");
+    }
+    if (hasStart && !hasEnd) {
+        throw new Error("TOC start delimiter found without end");
+    }
+    if (!hasStart && hasEnd) {
+        throw new Error("TOC end delimiter found without start");
+    }
+
+    const startIndex = content.indexOf(START);
+    const endIndex   = content.indexOf(END);
+
+    const before = content.slice(0, startIndex + START.length);
+    const after  = content.slice(endIndex);
+
+    const contentWithoutTOC =
+        content.slice(0, startIndex) +
+        content.slice(endIndex + END.length);
+
+    const lines = contentWithoutTOC.split("\n");
+    const headings = [];
+
+    for (const line of lines) {
+        const m = /^(#{1,6})\s+(.*)$/.exec(line);
+        if (!m) continue;
+
+        const level = m[1].length;
+        const title = m[2].trim();
+
+        const anchor = title
+            .toLowerCase()
+            .replace(/[^\w\s-]/g, "")
+            .replace(/\s/g, "-")
+            .replace(/^-|-$/g, "");
+
+        headings.push({ level, title, anchor });
+    }
+
+    if (headings.length === 0) {
+        throw new Error("No headings found to generate TOC");
+    }
+
+    const minLevel = Math.min(...headings.map(h => h.level));
+    const tocLines = headings.map(h => {
+        const indent = "  ".repeat(h.level - minLevel);
+        return `${indent}- [${h.title}](#${h.anchor})`;
+    });
+
+    const tocBlock = "\n" + tocLines.join("\n") + "\n";
+    return before + tocBlock + after;
+}
+
+/* ============================================================
+ * File processing
+ * ============================================================ */
+
+function processFile(filePath) {
+    debugLog(`processing file: ${filePath}`);
+
+    let content;
+    try {
+        content = fs.readFileSync(filePath, "utf8");
+    } catch {
+        throw new Error(`Unable to read markdown file: ${filePath}`);
+    }
+
+    let updated;
+    try {
+        updated = generateTOC(content);
+    } catch (err) {
+        if (err.message === "TOC delimiters not found") {
+            if (isRecursive) {
+                debugLog("result: skipped (no markers)");
+                return { status: "skipped" };
+            }
+            throw err; // single-file mode → hard error
+        }
+        throw err;
+    }
+
+    if (updated === content) {
+        debugLog("result: unchanged");
+        return { status: "unchanged" };
+    }
+
+    if (checkMode) {
+        debugLog("result: stale");
+        return { status: "stale" };
+    }
+
+    fs.writeFileSync(filePath, updated, "utf8");
+    debugLog("result: updated");
+    return { status: "updated" };
+}
+
+/* ============================================================
+ * Output
+ * ============================================================ */
+
+function maybePrintStatus(status, filePath) {
+    debugLog(`printing decision: status=${status}`);
+
+    if (quiet) return;
+
+    if (checkMode) {
+        // In --check mode we ALWAYS report stale files (unless --quiet).
+        // This makes CI output actionable without requiring --verbose.
+        if (status === "stale") {
+            console.log(`Stale: ${filePath}`);
+            return;
+        }
+
+        // In recursive mode, files without markers are intentionally ignored.
+        // They should not cause failures and do not need reporting by default.
+        if (status === "skipped") {
+            if (verbose) {
+                console.log(`Skipped (no markers): ${filePath}`);
+            }
+            return;
+        }
+
+        if (status === "unchanged") {
+            if (verbose) {
+                console.log(`Up-to-date: ${filePath}`);
+            }
+            return;
+        }
+
+        return;
+    }
+
+    if (verbose) {
+        if (status === "updated") {
+            console.log(`Updated: ${filePath}`);
+        } else if (status === "unchanged") {
+            console.log(`Up-to-date: ${filePath}`);
+        } else if (status === "skipped") {
+            console.log(`Skipped (no markers): ${filePath}`);
+        }
+        return;
+    }
+
+    if (status === "updated") {
+        console.log(`Updated: ${filePath}`);
+    }
+}
+
+
+/* ============================================================
+ * Execution
+ * ============================================================ */
+
+let files = [];
+
+if (recursivePath) {
+    const resolved = path.resolve(process.cwd(), recursivePath);
+
+    if (!fs.existsSync(resolved)) {
+        console.error("ERROR: Recursive path does not exist");
+        process.exit(1);
+    }
+    if (!fs.statSync(resolved).isDirectory()) {
+        console.error("ERROR: --recursive requires a directory");
+        process.exit(1);
+    }
+
+    files = collectMarkdownFiles(resolved);
+    files.sort(); // deterministic order
+} else {
+    const resolved = path.resolve(
+        process.cwd(),
+        targetFile || "README.md"
+    );
+    files = [resolved];
+}
+
+let staleFound = false;
+
+for (const file of files) {
+    try {
+        const result = processFile(file);
+
+        if (checkMode && result.status === "stale") {
+            staleFound = true;
+            debugLog("staleFound set true");
+        }
+
+        maybePrintStatus(result.status, file);
+    } catch (err) {
+        console.error(`ERROR: ${err.message}`);
+        process.exit(1);
+    }
+}
+
+if (checkMode && staleFound) {
+    debugLog("exiting with status 1 due to stale TOC");
+    process.exit(1);
+}
+
+debugLog("exiting with status 0");
+process.exit(0);

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@datalackey/update-markdown-toc",
+  "version": "0.1.3",
+  "description": "Auto-generate Table of Contents for a Markdown file (or files, recursively from a top level folder)",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "update-markdown-toc": "./bin/update-markdown-toc.js"
+  },
+  "files": [
+    "bin/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "build",
+    "automation",
+    "javascript",
+    "node",
+    "documentation",
+    "readme",
+    "toc",
+    "markdown",
+    "ci"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/datalackey/build-tools.git",
+    "directory": "javascript/update-markdown-toc"
+  },
+  "bugs": {
+    "url": "https://github.com/datalackey/build-tools/issues"
+  },
+  "homepage": "https://github.com/datalackey/build-tools/tree/main/javascript/update-markdown-toc",
+  "dependencies": {
+    "ts-dedent": "^2.2.0"
+  }
+}