@datalackey/update-markdown-toc 1.1.7 → 1.1.9

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/package.json

@@ -1,20 +1,20 @@
 {
   "name": "@datalackey/update-markdown-toc",
-  "version": "1.1.7",
+  "version": "1.1.9",
   "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"
   }
-}
+}