@datalackey/update-markdown-toc 1.1.12 → 1.2.1

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 ?
@@ -355,7 +355,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 +369,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,3 @@
-import type { RunConfig } from "@datalackey/tooling-core";
 import type { PluginDescriptor } from "@datalackey/tooling-core";
-export declare const descriptor: PluginDescriptor<RunConfig>;
+import type { TocRunConfig } from "./TocRunConfig.js";
+export declare const descriptor: PluginDescriptor<TocRunConfig>;

package/dist/cli/descriptor.js

@@ -1,4 +1,4 @@
-import { parseBooleanOption, parseNumberOption } from "@datalackey/tooling-core";
+import { parseBooleanOption, parseNumberOption, runLinkValidation, } from "@datalackey/tooling-core";
 const DEFAULT_LINK_TIMEOUT_MS = 3000;
 export const descriptor = {
     name: "update-markdown-toc",
@@ -6,24 +6,24 @@ export const descriptor = {
     options: [
         {
             flag: "--no-external-link-check",
-            description: "Skip external link validation in check mode"
+            description: "Skip external link validation in check mode",
         },
         {
             flag: "-n",
-            description: "Skip external link validation in check mode (short form)"
+            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"
+            valueName: "ms",
         },
         {
             flag: "-l",
             description: "Timeout in milliseconds for external link requests (short form)",
             requiresValue: true,
-            valueName: "ms"
-        }
+            valueName: "ms",
+        },
     ],
     parseOptions(standard, passthrough) {
         const noExternalCheck = parseBooleanOption("--no-external-link-check", passthrough) ||
@@ -33,8 +33,18 @@ export const descriptor = {
             DEFAULT_LINK_TIMEOUT_MS;
         return {
             ...standard,
-            validateExternalLinks: noExternalCheck ? false : standard.validateExternalLinks,
-            linkTimeoutMs: timeoutMs
+            validateExternalLinks: noExternalCheck ? false : true,
+            linkTimeoutMs: timeoutMs,
         };
-    }
+    },
+    async afterRun(files, config) {
+        if (config.runMode !== "check") {
+            return;
+        }
+        await runLinkValidation(files, {
+            ...config,
+            validateExternalLinks: config.validateExternalLinks,
+            linkTimeoutMs: config.linkTimeoutMs,
+        });
+    },
 };

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

@@ -18,9 +18,7 @@ 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();
@@ -41,8 +39,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.12",
+  "version": "1.2.1",
   "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"
   }
 }