@datalackey/update-markdown-toc 1.1.5 → 1.1.7

package/README.md

@@ -19,6 +19,8 @@
     - [Using npm scripts](#using-npm-scripts)
     - [Using a direct path (advanced)](#using-a-direct-path-advanced)
   - [Options](#options)
+    - [Configurable Exclusion List for Recursive Traversal](#configurable-exclusion-list-for-recursive-traversal)
+      - [Examples:](#examples)
   - [TOC Markers](#toc-markers)
   - [Usage Scenarios](#usage-scenarios)
     - [As Part of code/test/debug Work Flow](#as-part-of-codetestdebug-work-flow)
@@ -28,7 +30,6 @@
       - [Recursive Folder Traversal (Lenient Mode)](#recursive-folder-traversal-lenient-mode)
   - [Design Goals and Philosophy](#design-goals-and-philosophy)
   - [Guidelines For Project Contributors](#guidelines-for-project-contributors)
-  - [Known limitations](#known-limitations)
 <!-- TOC:END -->
 
 ## Introduction
@@ -74,12 +75,13 @@ node_modules/.bin/ directory.
 
 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.
+All examples below invoke the tool with the default README.md file as the TOC update target.
 
 
 ### Using npx (recommended)
 
 ```bash
-npx update-markdown-toc README.md
+npx update-markdown-toc 
 ````
 
 
@@ -90,7 +92,7 @@ You may also add a script entry to your package.json:
 ```json
 {
   "scripts": {
-    "docs:toc": "update-markdown-toc README.md"
+    "docs:toc": "update-markdown-toc"
   }
 }
 ```
@@ -103,7 +105,7 @@ npm run docs:toc
 ### Using a direct path (advanced)
 
 ```bash
-./node_modules/.bin/update-markdown-toc README.md
+./node_modules/.bin/update-markdown-toc 
 ```
 
 
@@ -120,6 +122,7 @@ 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
+  -e, --exclude   <dir1,dir2,...>           Comma-separated list of directory names to exclude during recursive traversal (overrides default exclusion list)
   -v, --verbose                             Print status for every file processed
   -q, --quiet                               Suppress all non-error output
   -d, --debug                               Print debug diagnostics to stderr
@@ -129,6 +132,37 @@ Options:
 When using --check, a target file or a recursive folder must be specified
 explicitly. Unlike normal operation, --check does not default to README.md.
 
+### Configurable Exclusion List for Recursive Traversal
+
+The `--exclude` option only applies when `--recursive` is specified.
+It accepts a comma-separated list of directory names (exact match, not glob patterns), and 
+when provided, it replaces the default exclusion list.
+
+By default, the recursive traversal excludes only: `node_modules`.
+
+#### Examples:
+
+Exclude node_modules and dist:
+
+```bash 
+npx update-markdown-toc --recursive . --exclude node_modules,dist
+```
+
+Exclude only dist (this allows traversal into node_modules):
+
+```bash 
+npx update-markdown-toc --recursive . --exclude dist
+```
+
+Disable exclusions entirely:
+
+```bash 
+npx update-markdown-toc --recursive . --exclude ""
+```
+
+
+
+
 
 ## TOC Markers
 
@@ -228,7 +262,7 @@ In this mode, files without TOC markers are silently skipped, and files with TOC
 (Rational: for larger repos, it may not be feasible to add TOC markers to every Markdown file at once.)
 Stale files are reported (unless --quiet is specified) and will 
 result in a non-zero return value at the end of processing, but the 
-script will not immediately bail wiht an error -- processing continues for all files found.
+script will not immediately bail with an error -- processing continues for all files found.
 
 When combined with --verbose, skipped files (Markdown files without start/end region markers) 
 are reported explicitly in this mode. For example: 
@@ -251,12 +285,12 @@ This tool was designed in accordance with the top-level
 [Build Philosophy](../../README.md#build-philosophy) of this repository.
 
 
-- **update mode** (writes files: this should be run locally by developers, and should never run in CI)
+- **update mode** (writes files: this should be run locally by developers, and should never run in CI. It is the default if `--check` not specified)
 - **check mode** (validates and exits non-zero if stale:  mainly intended to be run in CI -- optional for local use) 
 
 The intended workflow is:
 
-1. Developers run the update command locally.
+1. Developers run the command locally  in default mode (update mode, a.k.a. non `--check` mode) in their workspace
 2. Generated TOC content is reviewed and committed.
 3. CI runs in `--check` mode to ensure no drift exists.
 
@@ -266,8 +300,3 @@ The intended workflow is:
 Contributors to the project should consult [this document](GUIDELINES-FOR-PROJECT-CONTRIBUTORS.md)
 
 
-## Known limitations
-
-- node_modules is excluded from recursive traversal: when using `--recursive` the tool will skip any directory 
-  named `node_modules` and its contents. This prevents accidental processing or modification of third-party files.
-  This exclusion is currently hard-coded and not configurable via command-line flags or configuration files.

package/bin/update-markdown-toc.js

@@ -1,279 +1,57 @@
 #!/usr/bin/env node
 
-import fs from "fs";
-import path from "path";
-import { parseCli } from "./parseCli.js";
-import GithubSlugger from "github-slugger";
+import { parseCli } from "../src/cli/parseCli.js";
+import { runSingleFile, runRecursive } from "../src/index.js";
+import { resolve } from "node:path";
+import { existsSync, statSync } from "node:fs";
 
-/* ============================================================
- * Constants
- * ============================================================ */
+function printHelp() {
+    console.log(`
+update-markdown-toc [options] [file]
 
-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 detectLineEnding(text) {
-    return text.includes("\r\n") ? "\r\n" : "\n";
-}
-
-function collectMarkdownFiles(dir) {
-    const results = [];
-
-    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-        const full = path.join(dir, entry.name);
-
-        if (entry.isDirectory()) {
-            // Exclude node_modules from recursive traversal to avoid processing third-party files
-            if (entry.name === 'node_modules') continue;
-
-            results.push(...collectMarkdownFiles(full));
-        } else if (entry.isFile() && entry.name.endsWith(".md")) {
-            results.push(full);
-        }
-    }
-
-    return results;
-}
-
-function generateTOC(content) {
-    const lineEnding = detectLineEnding(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);
-    const after  = content.slice(endIndex + END.length);
-
-    // Preserve exactly one line boundary for parsing
-    const contentWithoutTOC =
-        before.replace(/\s*$/, "") +
-        lineEnding +
-        after.replace(/^\s*/, "");
-
-    const lines = contentWithoutTOC.split(lineEnding);
-    const headings = [];
-
-    const slugger = new GithubSlugger();
-
-    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 = slugger.slug(title);
-
-        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 =
-        lineEnding +
-        tocLines.join(lineEnding) +
-        lineEnding;
-
-    return (
-        before +
-        START +
-        tocBlock +
-        END +
-        after
-    );
+Options:
+  -c, --check
+  -r, --recursive <path>
+  -e, --exclude <dir1,dir2,...>
+  -v, --verbose
+  -q, --quiet
+  -d, --debug
+  -h, --help
+`);
 }
 
-/* ============================================================
- * File processing
- * ============================================================ */
-
-function processFile(filePath) {
-    debugLog(`processing file: ${filePath}`);
-
-    let content;
-    try {
-        content = fs.readFileSync(filePath, "utf8");
-    } catch {
-        const absolutePath = path.resolve(filePath);
-        throw new Error(`Unable to read markdown file: ${absolutePath}`);
-    }
-
-    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" };
-            }
-        }
+try {
+    const config = parseCli(process.argv.slice(2));
 
-        const absolutePath = path.resolve(filePath);
-        throw new Error(`${absolutePath}: ${err.message}`);
+    if (config.help) {
+        printHelp();
+        process.exit(0);
     }
 
-    if (updated === content) {
-        debugLog("result: unchanged");
-        return { status: "unchanged" };
-    }
+    if (config.isRecursive) {
+        const resolved = resolve(process.cwd(), config.recursivePath);
 
-    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) {
-        if (status === "stale") {
-            console.log(`Stale: ${filePath}`);
-            return;
+        if (!existsSync(resolved)) {
+            console.error("ERROR: Recursive path does not exist");
+            process.exit(1);
         }
 
-        if (status === "skipped") {
-            if (verbose) {
-                console.log(`Skipped (no markers): ${filePath}`);
-            }
-            return;
+        if (!statSync(resolved).isDirectory()) {
+            console.error("ERROR: --recursive requires a directory");
+            process.exit(1);
         }
 
-        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;
+        process.exit(runRecursive(resolved, config));
     }
 
-    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();
-} else {
-    const resolved = path.resolve(
+    const resolved = resolve(
         process.cwd(),
-        targetFile || "README.md"
+        config.targetFile || "README.md"
     );
-    files = [resolved];
-}
-
-let staleFound = false;
 
-for (const file of files) {
-    try {
-        const result = processFile(file);
+    process.exit(runSingleFile(resolved, config));
 
-        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");
+} catch (err) {
+    console.error(`ERROR: ${err.message}`);
     process.exit(1);
-}
-
-debugLog("exiting with status 0");
-process.exit(0);
+}

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@datalackey/update-markdown-toc",
-  "version": "1.1.5",
+  "version": "1.1.7",
   "description": "Auto-generate Table of Contents for a Markdown file (or files, recursively from a top level folder)",
   "license": "MIT",
   "type": "module",
   "private": false,
   "scripts": {
     "test": "bash scripts/run-all-tests.sh",
-    "prepack": "npm run test"
+    "prepack": "npm run test",
+    "test:unit": "node --experimental-vm-modules ./node_modules/jest/bin/jest.js tests/unit"
   },
   "bin": {
     "update-markdown-toc": "./bin/update-markdown-toc.js"
@@ -45,5 +46,8 @@
   "dependencies": {
     "github-slugger": "^2.0.0",
     "ts-dedent": "^2.2.0"
+  },
+  "devDependencies": {
+    "jest": "^30.2.0"
   }
-}
+}

package/bin/parseCli.js

@@ -1,97 +0,0 @@
-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
-      
-      When using --check, a target file or a recursive folder must be specified
-      explicitly. Unlike normal operation, --check does not default to README.md.
-
-  `);
-}