@datalackey/update-markdown-toc 1.1.9 → 1.1.11

package/README.md

@@ -354,7 +354,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 architectural policies (ESM-only, Node 18+, strict TypeScript configuration)
+the packages adhere to common design and architectural principles policies
 that are more completely described [here](../README.md).
 
 ## Known Limitations

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,6 +1,6 @@
 {
   "name": "@datalackey/update-markdown-toc",
-  "version": "1.1.9",
+  "version": "1.1.11",
   "description": "Auto-generate Table of Contents for a Markdown file (or files, recursively from a top level folder)",
   "license": "MIT",
   "type": "module",