@datalackey/update-markdown-toc 1.1.13 → 1.3.0

package/README.md

@@ -32,7 +32,7 @@
   - [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)
+  - [Contributing and Releasing](#contributing-and-releasing)
 <!-- TOC:END -->
 
 
@@ -40,14 +40,14 @@
 
 A Node.js command-line **documentation helper** which automatically:
 
-- generates Table of Contents (TOC) blocks for Markdown files
+- generates Table of Contents (TOC) blocks for Markdown files (using GitHub's Markdown renderer)
 - operates on either a single file, or recursively finds all `*.md` files from a root path
 - regenerates TOCs from headings, targeting only regions explicitly marked with [TOC markers](#toc-markers)
 - avoids gratuitous reformatting or changes of any kind outside of regions marked by the aforementioned [TOC markers](#toc-markers)
 - avoids updating files when the generated TOC is already correct
 - provides a `--check` mode which flags Markdown files with stale TOCs (intended for CI)
-- generates TOC links with GitHub’s Markdown renderer.
-
+  - validates intra-document links (i.e., those between Markdown docs in the repo (including #fragments, image paths) 
+  - validates external HTTP/HTTPS links, with configurable timeout 
 
 
 ## Why not Some Other Markdown TOC Generator ?
@@ -316,11 +316,6 @@ When such errors occur, the tool prints an error message and exits non-zero with
 
 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
-
-
-
 ```bash
 update-markdown-toc --recursive docs/ --verbose
 ```
@@ -355,7 +350,7 @@ The intended workflow is:
 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 design and architectural principles policies
-that are more completely described [here](../README.md).
+that are more completely described [here](../../README.md).
 
 ## Known Limitations
 
@@ -369,7 +364,9 @@ 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
+## Contributing and Releasing
 
-Contributors to the project should consult [this document](docs/CONTRIBUTING.md)
+For development setup, build workflow, and release procedures (including how to
+trigger a publish via Changesets), see
+[CONTRIBUTING.md](../docs/CONTRIBUTING.md).
 

package/bin/update-markdown-toc.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 
-import { runCli } from "@datalackey/tooling-core"
-import { TocFileProcessor } from "../dist/engine/TocFileProcessor.js"
-import { descriptor } from "../dist/cli/descriptor.js"
+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()
-})
+  processor: new TocFileProcessor(),
+});

package/dist/cli/TocRunConfig.d.ts

@@ -0,0 +1,2 @@
+import type { RunConfig } from "@datalackey/tooling-core";
+export type TocRunConfig = RunConfig;

package/dist/cli/TocRunConfig.js

@@ -0,0 +1 @@
+export {};

package/dist/cli/descriptor.d.ts

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

package/dist/cli/descriptor.js

@@ -1,40 +1,12 @@
-import { parseBooleanOption, parseNumberOption } from "@datalackey/tooling-core";
-const DEFAULT_LINK_TIMEOUT_MS = 3000;
+import { runLinkValidation } from "@datalackey/tooling-core";
 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"
+    options: [],
+    async afterRun(files, config) {
+        if (config.runMode !== "check") {
+            return;
         }
-    ],
-    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
-        };
-    }
+        await runLinkValidation(files, config);
+    },
 };

package/dist/engine/TocFileProcessor.d.ts

@@ -1,5 +1,5 @@
-import type { FileProcessor } from "@datalackey/tooling-core";
+import type { FileProcessor, ProcessingStatus } 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;
+    process(filePath: string, config: RunConfig): ProcessingStatus;
 }

package/dist/engine/generateToc.js

@@ -1,6 +1,21 @@
 import GithubSlugger from "github-slugger";
 const START = "<!-- TOC:START -->";
 const END = "<!-- TOC:END -->";
+function stripFencedLines(lines) {
+    let inFence = false;
+    const result = [];
+    for (const line of lines) {
+        if (line.startsWith("```")) {
+            inFence = !inFence;
+            continue;
+        }
+        if (!inFence)
+            result.push(line);
+    }
+    if (inFence)
+        throw new Error("Unclosed code fence (```) in document");
+    return result;
+}
 function detectLineEnding(text) {
     return text.includes("\r\n") ? "\r\n" : "\n";
 }
@@ -18,13 +33,11 @@ export function generateTOC(content) {
     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 contentWithoutTOC = before.replace(/\s*$/, "") + lineEnding + after.replace(/^\s*/, "");
     const lines = contentWithoutTOC.split(lineEnding);
     const headings = [];
     const slugger = new GithubSlugger();
-    for (const line of lines) {
+    for (const line of stripFencedLines(lines)) {
         const m = /^(#{1,6})\s+(.*)$/.exec(line);
         if (!m)
             continue;
@@ -41,8 +54,6 @@ export function generateTOC(content) {
         const indent = "  ".repeat(h.level - minLevel);
         return `${indent}- [${h.title}](#${h.anchor})`;
     });
-    const tocBlock = lineEnding +
-        tocLines.join(lineEnding) +
-        lineEnding;
+    const tocBlock = lineEnding + tocLines.join(lineEnding) + lineEnding;
     return before + START + tocBlock + END + after;
 }

package/dist/engine/processFile.js

@@ -29,8 +29,8 @@ export function processFile(filePath, config) {
         return "unchanged";
     }
     if (config.runMode === "check") {
-        debugLog(config, `processFile: stale filePath=${absolutePath}`);
-        return "stale";
+        debugLog(config, `processFile: needsUpdate filePath=${absolutePath}`);
+        return "needsUpdate";
     }
     fs.writeFileSync(filePath, updated, "utf8");
     debugLog(config, `processFile: updated filePath=${absolutePath}`);

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@datalackey/update-markdown-toc",
-  "version": "1.1.13",
+  "version": "1.3.0",
   "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": {
     "build": "tsc -p tsconfig.json",
-    "test": "bash scripts/run-all-tests.sh"
+    "test": "npx vitest run --config vitest.config.ts && bash scripts/run-all-tests.sh"
   },
   "bin": {
     "update-markdown-toc": "./bin/update-markdown-toc.js"
@@ -50,7 +50,7 @@
   },
   "devDependencies": {
     "@types/node": "^18.19.130",
-    "jest": "^30.2.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^1.0.0"
   }
 }