@datalackey/update-markdown-toc 1.1.8 → 1.1.10

package/README.md

@@ -1,4 +1,4 @@
-# update-markdown-toc
+# @datalackey/update-markdown-toc
 
 <p align="center">
   <img
@@ -10,7 +10,7 @@
 
 
 <!-- TOC:START -->
-- [update-markdown-toc](#update-markdown-toc)
+- [@datalackey/update-markdown-toc](#datalackeyupdate-markdown-toc)
   - [Introduction](#introduction)
   - [Why not Some Other Markdown TOC Generator ?](#why-not-some-other-markdown-toc-generator-)
   - [Installation](#installation)
@@ -25,13 +25,17 @@
   - [Usage Scenarios](#usage-scenarios)
     - [As Part of code/test/debug Work Flow](#as-part-of-codetestdebug-work-flow)
     - [Continuous Integration](#continuous-integration)
+      - [Link Validation in Check Mode](#link-validation-in-check-mode)
     - [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)
   - [Design Goals and Philosophy](#design-goals-and-philosophy)
+  - [Packaging, Publishing, and Inter-relationship with Other Plugins](#packaging-publishing-and-inter-relationship-with-other-plugins)
+  - [Known Limitations](#known-limitations)
   - [Guidelines For Project Contributors](#guidelines-for-project-contributors)
 <!-- TOC:END -->
 
+
 ## Introduction
 
 A Node.js command-line **documentation helper** which automatically:
@@ -121,16 +125,27 @@ update-markdown-toc [options] [file]
 
 Options:
   -c, --check     <path-to-file-or-folder>  Do not write files; exit non-zero if TOC is stale
+  -n, --no-external-link-check              Skip external HTTP/HTTPS link validation during --check
+  -l, --link-timeout-ms <ms>                Per-request timeout for external link checks (default: 3000)
   -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)
+  -e, --exclude   <dir1,dir2,...>           Directory names to exclude during recursive traversal (overrides default)
   -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.
+When using `--check`, if no file is specified, the tool defaults to `README.md`
+in the current working directory. This means the following two commands are equivalent:
+
+```bash
+npx update-markdown-toc --check
+npx update-markdown-toc --check README.md
+````
+
+To check an entire documentation tree in CI, use `--check --recursive <path>.`
+
+
 
 ### Configurable Exclusion List for Recursive Traversal
 
@@ -226,8 +241,26 @@ Example:
 npx update-markdown-toc --check --recursive docs/
 ```
 
+#### Link Validation in Check Mode
+
+When running with `--check`, the tool performs three tiers of link validation in these scopes:
+  - table of contents links, 
+  - intra-document links, and 
+  - external links.
+
+For full details on behavior, failure output, and performance considerations
+see [Common CLI Behavior — Check Mode](../CLI-BEHAVIOR.md#
 
-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.
+
+To skip external link validation:
+```bash
+npx update-markdown-toc --check README.md --no-external-link-check
+```
+
+
+If a pull request modifies documentation headings but forgets to update TOCs or other links targeted for 
+validation in a particular run, then the above command will fail the build, 
+forcing the contributor to regenerate and commit with corrected TOC and other links.
 
 ### Recursively Traversing a Folder Hierarchy to Process all files vs. Single File Processing
 
@@ -239,6 +272,9 @@ The tool supports two distinct operating modes with intentionally different erro
 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.
 
+Refer to [this document](../CLI-BEHAVIOR.md) for information on these processing modes and a discussion of other behavioral 
+commonalities that all focused-use plugins in this repository share.
+
 #### Single-File Processing (Strict Mode)
 
 
@@ -257,15 +293,33 @@ If either marker is missing, the tool prints an error message and exits with a n
 
 #### 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.
-(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 with an error -- processing continues for all files found.
+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 skipped silently (unless `--verbose` is specified).
+- Files with valid TOC markers are processed normally.
+- Stale files are reported (unless `--quiet` is specified).
+- When running in `--check` mode, stale files cause a non-zero exit code after traversal completes.
+
+Recursive mode is designed for gradual adoption across larger repositories, where not every Markdown file may yet contain TOC markers.
+Unlike single-file mode, recursive mode does **not** treat missing TOC markers as an error. This allows incremental rollout of TOC enforcement.
+
+However, structural or filesystem errors still abort the run immediately. These include:
+
+- unreadable files (e.g., permission errors),
+- mismatched TOC delimiters,
+- malformed TOC marker pairs,
+- files containing TOC markers but no Markdown headings.
+
+When such errors occur, the tool prints an error message and exits non-zero without continuing further traversal.
+
+When combined with `--verbose`, skipped files (Markdown files without start/end region markers) are reported explicitly. For example:
+
+```bash
+update-markdown-toc --recursive docs/ --verbose
+
 
-When combined with --verbose, skipped files (Markdown files without start/end region markers) 
-are reported explicitly in this mode. For example: 
 
 ```bash
 update-markdown-toc --recursive docs/ --verbose
@@ -295,8 +349,27 @@ The intended workflow is:
 3. CI runs in `--check` mode to ensure no drift exists.
 
 
-## Guidelines For Project Contributors
 
-Contributors to the project should consult [this document](GUIDELINES-FOR-PROJECT-CONTRIBUTORS.md)
+## Packaging, Publishing, and Inter-relationship with Other Plugins
+
+This package is one component of a small ecosystem of JavaScript tooling plugins maintained as individual npm packages in this repository.
+The versioning and release of these packages is governed by a coordinated release policy, and
+the packages adhere to common architectural policies (ESM-only, Node 18+, strict TypeScript configuration)
+that are more completely described [here](../README.md).
+
+## Known Limitations
+
+**Fragment link validation with formatted headings**
+
+Fragment link validation uses AST-based heading extraction, which may produce
+different slugs than the TOC generator for headings containing inline formatting
+such as code spans or bold text (e.g. `## Install \`foo\``).
+
+In practice this affects only headings with inline code, bold, or italic syntax.
+Plain-text headings are unaffected. A fix to unify both paths is planned for a
+future release.
+
+## Guidelines For Project Contributors
 
+Contributors to the project should consult [this document](docs/CONTRIBUTING.md)
 

package/bin/update-markdown-toc.js

@@ -1,57 +1,10 @@
 #!/usr/bin/env node
 
-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";
-
-function printHelp() {
-    console.log(`
-update-markdown-toc [options] [file]
-
-Options:
-  -c, --check
-  -r, --recursive <path>
-  -e, --exclude <dir1,dir2,...>
-  -v, --verbose
-  -q, --quiet
-  -d, --debug
-  -h, --help
-`);
-}
-
-try {
-    const config = parseCli(process.argv.slice(2));
-
-    if (config.help) {
-        printHelp();
-        process.exit(0);
-    }
-
-    if (config.isRecursive) {
-        const resolved = resolve(process.cwd(), config.recursivePath);
-
-        if (!existsSync(resolved)) {
-            console.error("ERROR: Recursive path does not exist");
-            process.exit(1);
-        }
-
-        if (!statSync(resolved).isDirectory()) {
-            console.error("ERROR: --recursive requires a directory");
-            process.exit(1);
-        }
-
-        process.exit(runRecursive(resolved, config));
-    }
-
-    const resolved = resolve(
-        process.cwd(),
-        config.targetFile || "README.md"
-    );
-
-    process.exit(runSingleFile(resolved, config));
-
-} catch (err) {
-    console.error(`ERROR: ${err.message}`);
-    process.exit(1);
-}
+import { runCli } from "@datalackey/tooling-core"
+import { TocFileProcessor } from "../dist/engine/TocFileProcessor.js"
+import { descriptor } from "../dist/cli/descriptor.js"
+
+await runCli({
+  descriptor: descriptor,
+  processor: new TocFileProcessor()
+})

package/dist/cli/descriptor.d.ts

@@ -0,0 +1,3 @@
+import type { RunConfig } from "@datalackey/tooling-core";
+import type { PluginDescriptor } from "@datalackey/tooling-core";
+export declare const descriptor: PluginDescriptor<RunConfig>;

package/dist/cli/descriptor.js

@@ -0,0 +1,40 @@
+import { parseBooleanOption, parseNumberOption } from "@datalackey/tooling-core";
+const DEFAULT_LINK_TIMEOUT_MS = 3000;
+export const descriptor = {
+    name: "update-markdown-toc",
+    description: "Auto-generate Table of Contents for Markdown files",
+    options: [
+        {
+            flag: "--no-external-link-check",
+            description: "Skip external link validation in check mode"
+        },
+        {
+            flag: "-n",
+            description: "Skip external link validation in check mode (short form)"
+        },
+        {
+            flag: "--link-timeout-ms",
+            description: "Timeout in milliseconds for external link requests (default: 3000)",
+            requiresValue: true,
+            valueName: "ms"
+        },
+        {
+            flag: "-l",
+            description: "Timeout in milliseconds for external link requests (short form)",
+            requiresValue: true,
+            valueName: "ms"
+        }
+    ],
+    parseOptions(standard, passthrough) {
+        const noExternalCheck = parseBooleanOption("--no-external-link-check", passthrough) ||
+            parseBooleanOption("-n", passthrough);
+        const timeoutMs = parseNumberOption("--link-timeout-ms", passthrough) ??
+            parseNumberOption("-l", passthrough) ??
+            DEFAULT_LINK_TIMEOUT_MS;
+        return {
+            ...standard,
+            validateExternalLinks: noExternalCheck ? false : standard.validateExternalLinks,
+            linkTimeoutMs: timeoutMs
+        };
+    }
+};

package/dist/engine/TocFileProcessor.d.ts

@@ -0,0 +1,5 @@
+import type { FileProcessor } from "@datalackey/tooling-core";
+import type { RunConfig } from "@datalackey/tooling-core";
+export declare class TocFileProcessor implements FileProcessor<RunConfig> {
+    process(filePath: string, config: RunConfig): import("@datalackey/tooling-core").ProcessingStatus;
+}

package/dist/engine/TocFileProcessor.js

@@ -0,0 +1,6 @@
+import { processFile } from "./processFile.js";
+export class TocFileProcessor {
+    process(filePath, config) {
+        return processFile(filePath, config);
+    }
+}

package/dist/engine/generateToc.d.ts

@@ -0,0 +1 @@
+export declare function generateTOC(content: string): string;

package/dist/engine/generateToc.js

@@ -0,0 +1,48 @@
+import GithubSlugger from "github-slugger";
+const START = "<!-- TOC:START -->";
+const END = "<!-- TOC:END -->";
+function detectLineEnding(text) {
+    return text.includes("\r\n") ? "\r\n" : "\n";
+}
+export 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);
+    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: level, title: title, anchor: 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;
+}

package/dist/engine/processFile.d.ts

@@ -0,0 +1,2 @@
+import type { RunConfig, ProcessingStatus } from "@datalackey/tooling-core";
+export declare function processFile(filePath: string, config: RunConfig): ProcessingStatus;

package/dist/engine/processFile.js

@@ -0,0 +1,38 @@
+import fs from "node:fs";
+import path from "node:path";
+import { generateTOC } from "./generateToc.js";
+import { debugLog } from "@datalackey/tooling-core";
+export function processFile(filePath, config) {
+    const absolutePath = path.resolve(filePath);
+    debugLog(config, `processFile: entry filePath=${absolutePath} runMode=${config.runMode}`);
+    let content;
+    try {
+        content = fs.readFileSync(filePath, "utf8");
+    }
+    catch {
+        throw new Error(`Unable to read markdown file: ${absolutePath}`);
+    }
+    let updated;
+    try {
+        updated = generateTOC(content);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message === "TOC delimiters not found" && config.mode === "recursive") {
+            debugLog(config, `processFile: skipped (no markers) filePath=${absolutePath}`);
+            return "skipped";
+        }
+        throw new Error(`${absolutePath}: ${message}`);
+    }
+    if (updated === content) {
+        debugLog(config, `processFile: unchanged filePath=${absolutePath}`);
+        return "unchanged";
+    }
+    if (config.runMode === "check") {
+        debugLog(config, `processFile: stale filePath=${absolutePath}`);
+        return "stale";
+    }
+    fs.writeFileSync(filePath, updated, "utf8");
+    debugLog(config, `processFile: updated filePath=${absolutePath}`);
+    return "updated";
+}

package/package.json

@@ -1,20 +1,20 @@
 {
   "name": "@datalackey/update-markdown-toc",
-  "version": "1.1.8",
+  "version": "1.1.10",
   "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",
-    "test:unit": "node --experimental-vm-modules ./node_modules/jest/bin/jest.js tests/unit"
+    "build": "tsc -p tsconfig.json",
+    "test": "bash scripts/run-all-tests.sh"
   },
   "bin": {
     "update-markdown-toc": "./bin/update-markdown-toc.js"
   },
   "files": [
-    "bin/"
+    "bin/",
+    "dist/"
   ],
   "engines": {
     "node": ">=18"
@@ -44,10 +44,13 @@
   },
   "homepage": "https://github.com/datalackey/build-tools/tree/main/javascript/update-markdown-toc",
   "dependencies": {
+    "@datalackey/tooling-core": "*",
     "github-slugger": "^2.0.0",
     "ts-dedent": "^2.2.0"
   },
   "devDependencies": {
-    "jest": "^30.2.0"
+    "@types/node": "^18.19.130",
+    "jest": "^30.2.0",
+    "typescript": "^5.9.3"
   }
-}
+}