hdlinter 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Siem Kleuskens
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# hdlinter
+
+Cursor/VS Code extension and CLI for validating Markdown planning headers.
+
+The linter enforces this header shape at the top of every Markdown file:
+
+```md
+Status: Draft
+Owner: Project Manager
+Reviewers: Siem, Vansh
+Last updated: 2026-05-10
+Milestone: M1
+Depends on: Markdown links with bracketed dependency dates
+Supersedes: None
+```
+
+## Rules
+
+- Required fields must appear in order.
+- `Status` must be one of `Draft`, `In Review`, `Approved`, or `Superseded`.
+- `Last updated` must be a valid ISO date.
+- `Depends on` and `Supersedes` must be either `None` or Markdown links.
+- Header links must include the referenced document's `Last updated` date in brackets
+  after the link.
+- Referenced files must exist when they point at local Markdown files.
+- A dependency newer than the current document is flagged as possible drift.
+- A superseded document newer than the superseding document is flagged as suspicious.
+
+The extension writes hidden graph/hash state to `.hdlinter/state.json`. That file
+is implementation state, not a planning artifact. Older builds used `.hdlint/` for
+the same file; rename that directory to `.hdlinter` or run `--write-state` to recreate it.
+
+## Cursor Setup
+
+From this directory:
+
+```sh
+npm install
+npm run compile
+```
+
+Then in Cursor:
+
+1. Open this folder.
+2. Press `F5` to launch the extension development host.
+3. In the launched Cursor/VS Code window, open the target Markdown project.
+4. Diagnostics and Quick Fixes appear for Markdown files.
+
+For regular use, package/install it as a VS Code-compatible extension later:
+
+```sh
+npm install -g @vscode/vsce
+npm run package
+```
+
+Then install the generated `.vsix` in Cursor.
+
+## CLI
+
+Run without installing:
+
+```sh
+npx hdlinter .
+```
+
+Lint a workspace and rebuild hidden graph state:
+
+```sh
+npx hdlinter ../aicompliance --write-state
+```
+
+Autofix a workspace and rebuild hidden graph state:
+
+```sh
+npx hdlinter ../aicompliance --fix
+```
+
+The CLI exits non-zero when errors are found.
+
+## Local Development
+
+For quick local CLI testing from this repo:
+
+```sh
+npm install
+npm run build
+npm exec -- hdlinter samples
+```
+
+`npm link` works for local development, but publishing to npm is the intended path for
+normal `npx hdlinter` usage.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_module_1 = require("node:module");
+const node_path_1 = __importDefault(require("node:path"));
+const graph_1 = require("./graph");
+const linter_1 = require("./linter");
+const types_1 = require("./types");
+const DEFAULT_STATE_FILE = ".hdlinter/state.json";
+const EXCLUDED_DIRS = new Set([".git", "node_modules", ".hdlinter", "dist"]);
+const VALID_FLAGS = new Set(["--fix", "--write-state", "--help", "-h", "--version", "-v"]);
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.includes("--help") || args.includes("-h")) {
+        printHelp();
+        return;
+    }
+    if (args.includes("--version") || args.includes("-v")) {
+        console.log(readPackageVersion());
+        return;
+    }
+    const unknownFlag = args.find((arg) => arg.startsWith("-") && !VALID_FLAGS.has(arg));
+    if (unknownFlag) {
+        console.error(`Unknown option: ${unknownFlag}`);
+        console.error("Run `hdlinter --help` for usage.");
+        process.exitCode = 2;
+        return;
+    }
+    const writeState = args.includes("--write-state");
+    const fix = args.includes("--fix");
+    const workspaceArg = args.find((arg) => !arg.startsWith("--")) ?? process.cwd();
+    const workspaceRoot = node_path_1.default.resolve(workspaceArg);
+    const documents = await collectMarkdownDocuments(workspaceRoot);
+    let graph = (0, graph_1.buildDocumentGraph)(workspaceRoot, documents);
+    if (fix) {
+        const changed = await fixDocuments(workspaceRoot, documents, graph);
+        graph = (0, graph_1.buildDocumentGraph)(workspaceRoot, documents);
+        console.log(`Fixed ${changed} Markdown file${changed === 1 ? "" : "s"}.`);
+    }
+    if (writeState || fix) {
+        await (0, graph_1.writeGraphState)(workspaceRoot, DEFAULT_STATE_FILE, graph);
+    }
+    let errorCount = 0;
+    let warningCount = 0;
+    for (const document of documents) {
+        const diagnostics = (0, linter_1.lintMarkdownDocument)(document.path, document.text, graph, types_1.DEFAULT_LINT_OPTIONS);
+        for (const diagnostic of diagnostics) {
+            printDiagnostic(document.path, diagnostic);
+            if (diagnostic.severity === "error") {
+                errorCount += 1;
+            }
+            else if (diagnostic.severity === "warning") {
+                warningCount += 1;
+            }
+        }
+    }
+    console.log(`\nChecked ${documents.length} Markdown files: ${errorCount} errors, ${warningCount} warnings.`);
+    process.exitCode = errorCount > 0 ? 1 : 0;
+}
+async function fixDocuments(workspaceRoot, documents, initialGraph) {
+    let graph = initialGraph;
+    const changedPaths = new Set();
+    for (let pass = 0; pass < 3; pass += 1) {
+        let passChanged = 0;
+        for (const document of documents) {
+            const fixed = (0, linter_1.fixMarkdownDocument)(document.path, document.text, graph);
+            if (fixed !== document.text) {
+                document.text = fixed;
+                changedPaths.add(document.path);
+                passChanged += 1;
+            }
+        }
+        graph = (0, graph_1.buildDocumentGraph)(workspaceRoot, documents);
+        if (passChanged === 0) {
+            break;
+        }
+    }
+    for (const documentPath of changedPaths) {
+        const document = documents.find((candidate) => candidate.path === documentPath);
+        if (!document) {
+            continue;
+        }
+        await promises_1.default.writeFile(node_path_1.default.join(workspaceRoot, document.path), document.text, "utf8");
+    }
+    return changedPaths.size;
+}
+async function collectMarkdownDocuments(workspaceRoot) {
+    const absolutePaths = await walk(workspaceRoot);
+    const documents = [];
+    for (const absolutePath of absolutePaths) {
+        if (!absolutePath.endsWith(".md")) {
+            continue;
+        }
+        const text = await promises_1.default.readFile(absolutePath, "utf8");
+        documents.push({
+            path: (0, graph_1.normalizeWorkspacePath)(node_path_1.default.relative(workspaceRoot, absolutePath)),
+            text
+        });
+    }
+    documents.sort((a, b) => a.path.localeCompare(b.path));
+    return documents;
+}
+async function walk(directory) {
+    const entries = await promises_1.default.readdir(directory, { withFileTypes: true });
+    const results = [];
+    for (const entry of entries) {
+        if (EXCLUDED_DIRS.has(entry.name)) {
+            continue;
+        }
+        const absolutePath = node_path_1.default.join(directory, entry.name);
+        if (entry.isDirectory()) {
+            results.push(...(await walk(absolutePath)));
+        }
+        else if (entry.isFile()) {
+            results.push(absolutePath);
+        }
+    }
+    return results;
+}
+function printDiagnostic(documentPath, diagnostic) {
+    const severity = diagnostic.severity.toUpperCase();
+    console.log(`${documentPath}:${diagnostic.line + 1}:${diagnostic.character + 1} ${severity} ${diagnostic.code} ${diagnostic.message}`);
+}
+function printHelp() {
+    console.log(`hdlinter
+
+Usage:
+  hdlinter [workspace] [options]
+
+Options:
+  --fix          Autofix Markdown header issues and write .hdlinter/state.json
+  --write-state  Rebuild .hdlinter/state.json without modifying documents
+  -v, --version  Print version
+  -h, --help     Print this help
+
+Examples:
+  hdlinter
+  hdlinter docs --write-state
+  hdlinter ../aicompliance --fix`);
+}
+function readPackageVersion() {
+    const require = (0, node_module_1.createRequire)(__filename);
+    const packageJson = require("../package.json");
+    return packageJson.version ?? "0.0.0";
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 2;
+});
+//# sourceMappingURL=cli.js.map

package/dist/extension.d.ts

@@ -0,0 +1,3 @@
+import * as vscode from "vscode";
+export declare function activate(context: vscode.ExtensionContext): void;
+export declare function deactivate(): void;

package/dist/extension.js

@@ -0,0 +1,296 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.activate = activate;
+exports.deactivate = deactivate;
+const node_path_1 = __importDefault(require("node:path"));
+const vscode = __importStar(require("vscode"));
+const graph_1 = require("./graph");
+const linter_1 = require("./linter");
+const types_1 = require("./types");
+const SOURCE = "hdlinter";
+function activate(context) {
+    const controller = new HeaderLintController(context);
+    context.subscriptions.push(controller);
+    controller.activate();
+}
+function deactivate() {
+    // VS Code disposes subscriptions registered in activate.
+}
+class HeaderLintController {
+    context;
+    diagnostics = vscode.languages.createDiagnosticCollection(SOURCE);
+    output = vscode.window.createOutputChannel("hdlinter");
+    graphByRoot = new Map();
+    disposed = false;
+    constructor(context) {
+        this.context = context;
+    }
+    activate() {
+        this.context.subscriptions.push(this.diagnostics, this.output);
+        this.context.subscriptions.push(vscode.languages.registerCodeActionsProvider({ language: "markdown", scheme: "file" }, new HeaderCodeActionProvider(() => this.graphByRoot), { providedCodeActionKinds: [vscode.CodeActionKind.QuickFix, vscode.CodeActionKind.SourceFixAll] }));
+        this.context.subscriptions.push(vscode.commands.registerCommand("hdlinter.fixCurrentDocumentHeader", async () => {
+            const editor = vscode.window.activeTextEditor;
+            if (!editor || editor.document.languageId !== "markdown") {
+                return;
+            }
+            await this.rebuildGraphsAndValidate();
+            const graph = this.graphForDocument(editor.document);
+            if (!graph) {
+                return;
+            }
+            await applyHeaderFix(editor.document, graph);
+        }));
+        this.context.subscriptions.push(vscode.commands.registerCommand("hdlinter.fixWorkspaceHeaders", async () => {
+            await this.fixWorkspaceHeaders();
+        }));
+        this.context.subscriptions.push(vscode.commands.registerCommand("hdlinter.rebuildGraphState", async () => {
+            await this.rebuildGraphsAndValidate();
+            vscode.window.showInformationMessage("hdlinter graph state rebuilt.");
+        }));
+        this.context.subscriptions.push(vscode.workspace.onDidSaveTextDocument(async (document) => {
+            if (document.languageId === "markdown") {
+                await this.rebuildGraphsAndValidate();
+            }
+        }));
+        this.context.subscriptions.push(vscode.workspace.onDidChangeTextDocument((event) => {
+            if (event.document.languageId === "markdown") {
+                this.validateOpenDocument(event.document);
+            }
+        }));
+        this.context.subscriptions.push(vscode.workspace.onDidChangeConfiguration((event) => {
+            if (event.affectsConfiguration("hdlinter")) {
+                void this.rebuildGraphsAndValidate();
+            }
+        }));
+        void this.rebuildGraphsAndValidate();
+    }
+    dispose() {
+        this.disposed = true;
+        this.diagnostics.dispose();
+        this.output.dispose();
+    }
+    async rebuildGraphsAndValidate() {
+        if (this.disposed) {
+            return;
+        }
+        const settings = getSettings();
+        if (!settings.enabled) {
+            this.diagnostics.clear();
+            return;
+        }
+        this.graphByRoot.clear();
+        const folders = vscode.workspace.workspaceFolders ?? [];
+        for (const folder of folders) {
+            const documents = await collectWorkspaceDocuments(folder, settings);
+            const graph = (0, graph_1.buildDocumentGraph)(folder.uri.fsPath, documents);
+            this.graphByRoot.set(folder.uri.toString(), graph);
+            try {
+                await (0, graph_1.writeGraphState)(folder.uri.fsPath, settings.stateFile, graph);
+            }
+            catch (error) {
+                this.output.appendLine(`Failed to write graph state for ${folder.uri.fsPath}: ${String(error)}`);
+            }
+            for (const document of documents) {
+                const uri = vscode.Uri.file(node_path_1.default.join(folder.uri.fsPath, document.path));
+                const diagnostics = (0, linter_1.lintMarkdownDocument)(document.path, document.text, graph, settings.lintOptions);
+                this.diagnostics.set(uri, diagnostics.map(toVsCodeDiagnostic));
+            }
+        }
+        for (const document of vscode.workspace.textDocuments) {
+            if (document.languageId === "markdown" && document.isDirty) {
+                this.validateOpenDocument(document);
+            }
+        }
+    }
+    validateOpenDocument(document) {
+        const settings = getSettings();
+        if (!settings.enabled || document.uri.scheme !== "file") {
+            return;
+        }
+        const graph = this.graphForDocument(document);
+        const folder = vscode.workspace.getWorkspaceFolder(document.uri);
+        if (!graph || !folder) {
+            return;
+        }
+        const documentPath = (0, graph_1.normalizeWorkspacePath)(node_path_1.default.relative(folder.uri.fsPath, document.uri.fsPath));
+        const diagnostics = (0, linter_1.lintMarkdownDocument)(documentPath, document.getText(), graph, settings.lintOptions);
+        this.diagnostics.set(document.uri, diagnostics.map(toVsCodeDiagnostic));
+    }
+    graphForDocument(document) {
+        const folder = vscode.workspace.getWorkspaceFolder(document.uri);
+        if (!folder) {
+            return undefined;
+        }
+        return this.graphByRoot.get(folder.uri.toString());
+    }
+    async fixWorkspaceHeaders() {
+        const settings = getSettings();
+        const folders = vscode.workspace.workspaceFolders ?? [];
+        let changed = 0;
+        for (const folder of folders) {
+            const documents = await collectWorkspaceDocuments(folder, settings);
+            let graph = (0, graph_1.buildDocumentGraph)(folder.uri.fsPath, documents);
+            const edit = new vscode.WorkspaceEdit();
+            for (const document of documents) {
+                const fixed = (0, linter_1.fixMarkdownDocument)(document.path, document.text, graph);
+                if (fixed !== document.text) {
+                    const uri = vscode.Uri.file(node_path_1.default.join(folder.uri.fsPath, document.path));
+                    edit.replace(uri, fullDocumentRangeFromText(document.text), fixed);
+                    document.text = fixed;
+                    changed += 1;
+                }
+            }
+            if (changed > 0) {
+                await vscode.workspace.applyEdit(edit);
+            }
+            graph = (0, graph_1.buildDocumentGraph)(folder.uri.fsPath, documents);
+            await (0, graph_1.writeGraphState)(folder.uri.fsPath, settings.stateFile, graph);
+        }
+        await this.rebuildGraphsAndValidate();
+        vscode.window.showInformationMessage(`hdlinter fixed ${changed} Markdown file${changed === 1 ? "" : "s"}.`);
+    }
+}
+class HeaderCodeActionProvider {
+    graphByRoot;
+    constructor(graphByRoot) {
+        this.graphByRoot = graphByRoot;
+    }
+    provideCodeActions(document, _range, context) {
+        const folder = vscode.workspace.getWorkspaceFolder(document.uri);
+        if (!folder) {
+            return [];
+        }
+        const graph = this.graphByRoot().get(folder.uri.toString());
+        if (!graph) {
+            return [];
+        }
+        const diagnostics = context.diagnostics.filter((diagnostic) => diagnostic.source === SOURCE);
+        if (diagnostics.length === 0) {
+            return [];
+        }
+        return [createFixDocumentAction(document, graph)];
+    }
+}
+async function collectWorkspaceDocuments(folder, settings) {
+    const seen = new Set();
+    const documents = [];
+    const exclude = toGlobUnion(settings.exclude);
+    for (const include of settings.include) {
+        const uris = await vscode.workspace.findFiles(new vscode.RelativePattern(folder, include), exclude);
+        for (const uri of uris) {
+            if (seen.has(uri.fsPath)) {
+                continue;
+            }
+            seen.add(uri.fsPath);
+            const bytes = await vscode.workspace.fs.readFile(uri);
+            documents.push({
+                path: (0, graph_1.normalizeWorkspacePath)(node_path_1.default.relative(folder.uri.fsPath, uri.fsPath)),
+                text: Buffer.from(bytes).toString("utf8")
+            });
+        }
+    }
+    documents.sort((a, b) => a.path.localeCompare(b.path));
+    return documents;
+}
+function getSettings() {
+    const config = vscode.workspace.getConfiguration("hdlinter");
+    return {
+        enabled: config.get("enabled", true),
+        include: config.get("include", ["**/*.md"]),
+        exclude: config.get("exclude", ["**/.git/**", "**/node_modules/**", "**/.hdlinter/**"]),
+        stateFile: config.get("stateFile", ".hdlinter/state.json"),
+        lintOptions: {
+            allowedStatuses: config.get("allowedStatuses", types_1.DEFAULT_LINT_OPTIONS.allowedStatuses),
+            requireReferenceDates: config.get("requireReferenceDates", types_1.DEFAULT_LINT_OPTIONS.requireReferenceDates),
+            warnWhenDependencyNewer: config.get("warnWhenDependencyNewer", types_1.DEFAULT_LINT_OPTIONS.warnWhenDependencyNewer),
+            validateSupersedesNotNewer: config.get("validateSupersedesNotNewer", types_1.DEFAULT_LINT_OPTIONS.validateSupersedesNotNewer)
+        }
+    };
+}
+function toGlobUnion(patterns) {
+    if (patterns.length === 0) {
+        return "";
+    }
+    if (patterns.length === 1) {
+        return patterns[0];
+    }
+    return `{${patterns.join(",")}}`;
+}
+function toVsCodeDiagnostic(diagnostic) {
+    const range = new vscode.Range(new vscode.Position(diagnostic.line, diagnostic.character), new vscode.Position(diagnostic.endLine, diagnostic.endCharacter));
+    const severity = diagnostic.severity === "error"
+        ? vscode.DiagnosticSeverity.Error
+        : diagnostic.severity === "warning"
+            ? vscode.DiagnosticSeverity.Warning
+            : vscode.DiagnosticSeverity.Information;
+    const vscodeDiagnostic = new vscode.Diagnostic(range, diagnostic.message, severity);
+    vscodeDiagnostic.source = SOURCE;
+    vscodeDiagnostic.code = diagnostic.code;
+    return vscodeDiagnostic;
+}
+function createFixDocumentAction(document, graph) {
+    const action = new vscode.CodeAction("Fix document header lint issues", vscode.CodeActionKind.QuickFix);
+    action.edit = new vscode.WorkspaceEdit();
+    action.edit.replace(document.uri, fullDocumentRange(document), (0, linter_1.fixMarkdownDocument)(documentPath(document), document.getText(), graph));
+    action.diagnostics = [];
+    action.isPreferred = true;
+    return action;
+}
+async function applyHeaderFix(document, graph) {
+    const edit = new vscode.WorkspaceEdit();
+    edit.replace(document.uri, fullDocumentRange(document), (0, linter_1.fixMarkdownDocument)(documentPath(document), document.getText(), graph));
+    await vscode.workspace.applyEdit(edit);
+}
+function fullDocumentRange(document) {
+    const lastLine = document.lineAt(Math.max(0, document.lineCount - 1));
+    return new vscode.Range(new vscode.Position(0, 0), lastLine.range.end);
+}
+function fullDocumentRangeFromText(text) {
+    const lines = text.split(/\r?\n/);
+    const lastLineIndex = Math.max(0, lines.length - 1);
+    return new vscode.Range(new vscode.Position(0, 0), new vscode.Position(lastLineIndex, lines[lastLineIndex].length));
+}
+function documentPath(document) {
+    const folder = vscode.workspace.getWorkspaceFolder(document.uri);
+    if (!folder) {
+        return (0, graph_1.normalizeWorkspacePath)(node_path_1.default.basename(document.uri.fsPath));
+    }
+    return (0, graph_1.normalizeWorkspacePath)(node_path_1.default.relative(folder.uri.fsPath, document.uri.fsPath));
+}
+//# sourceMappingURL=extension.js.map

package/dist/graph.d.ts

@@ -0,0 +1,6 @@
+import { DocumentGraph, DocumentInput } from "./types";
+export declare function normalizeWorkspacePath(filePath: string): string;
+export declare function hashSha256(text: string): string;
+export declare function buildDocumentGraph(workspaceRoot: string, documents: DocumentInput[]): DocumentGraph;
+export declare function writeGraphState(workspaceRoot: string, stateFile: string, graph: DocumentGraph): Promise<void>;
+export declare function readGraphState(workspaceRoot: string, stateFile: string): Promise<DocumentGraph | undefined>;

package/dist/graph.js

@@ -0,0 +1,84 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeWorkspacePath = normalizeWorkspacePath;
+exports.hashSha256 = hashSha256;
+exports.buildDocumentGraph = buildDocumentGraph;
+exports.writeGraphState = writeGraphState;
+exports.readGraphState = readGraphState;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const header_1 = require("./header");
+function normalizeWorkspacePath(filePath) {
+    return filePath.split(node_path_1.default.sep).join(node_path_1.default.posix.sep).replace(/^\.\//, "");
+}
+function hashSha256(text) {
+    return node_crypto_1.default.createHash("sha256").update(text, "utf8").digest("hex");
+}
+function buildDocumentGraph(workspaceRoot, documents) {
+    const normalizedRoot = node_path_1.default.resolve(workspaceRoot);
+    const nodes = {};
+    for (const document of documents) {
+        const documentPath = normalizeWorkspacePath(document.path);
+        const header = (0, header_1.parseHeader)(document.text);
+        nodes[documentPath] = {
+            path: documentPath,
+            hashSha256: hashSha256(document.text),
+            status: header.values.Status,
+            owner: header.values.Owner,
+            reviewers: header.values.Reviewers,
+            lastUpdated: header.values["Last updated"],
+            milestone: header.values.Milestone,
+            title: (0, header_1.titleFromMarkdown)(document.text)
+        };
+    }
+    const edges = [];
+    for (const document of documents) {
+        const from = normalizeWorkspacePath(document.path);
+        const header = (0, header_1.parseHeader)(document.text);
+        collectEdges("dependsOn", from, header.values["Depends on"], nodes, edges);
+        collectEdges("supersedes", from, header.values.Supersedes, nodes, edges);
+    }
+    return {
+        version: 1,
+        generatedAt: new Date().toISOString(),
+        workspaceRoot: normalizedRoot,
+        documents: nodes,
+        edges
+    };
+}
+function collectEdges(kind, from, value, nodes, edges) {
+    const candidates = (0, header_1.extractReferenceCandidates)(value);
+    for (const reference of candidates) {
+        const to = (0, header_1.resolveReferenceTarget)(from, reference.target) ?? reference.target;
+        const targetNode = nodes[to];
+        edges.push({
+            from,
+            to,
+            kind,
+            label: reference.label,
+            declaredLastUpdated: reference.declaredLastUpdated,
+            actualLastUpdated: targetNode?.lastUpdated,
+            targetExists: Boolean(targetNode)
+        });
+    }
+}
+async function writeGraphState(workspaceRoot, stateFile, graph) {
+    const absolutePath = node_path_1.default.resolve(workspaceRoot, stateFile);
+    await promises_1.default.mkdir(node_path_1.default.dirname(absolutePath), { recursive: true });
+    await promises_1.default.writeFile(absolutePath, `${JSON.stringify(graph, null, 2)}\n`, "utf8");
+}
+async function readGraphState(workspaceRoot, stateFile) {
+    try {
+        const absolutePath = node_path_1.default.resolve(workspaceRoot, stateFile);
+        const raw = await promises_1.default.readFile(absolutePath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=graph.js.map

package/dist/header.d.ts

@@ -0,0 +1,19 @@
+import { HeaderValues, ParsedHeader, ReferenceParseResult } from "./types";
+export declare function splitLines(text: string): string[];
+export declare function parseHeader(text: string): ParsedHeader;
+export declare function extractHeaderValuesLoose(text: string): HeaderValues;
+export declare function isValidIsoDate(value: string | undefined): boolean;
+export declare function todayIso(): string;
+export declare function compareIsoDate(a: string | undefined, b: string | undefined): number | undefined;
+export declare function parseReferenceValue(value: string | undefined): ReferenceParseResult;
+export interface ReferenceCandidate {
+    label: string;
+    target: string;
+    declaredLastUpdated?: string;
+}
+export declare function extractReferenceCandidates(value: string | undefined): ReferenceCandidate[];
+export declare function isExternalTarget(target: string): boolean;
+export declare function stripAnchor(target: string): string;
+export declare function resolveReferenceTarget(currentDocumentPath: string, target: string): string | undefined;
+export declare function formatReference(label: string, target: string, lastUpdated: string): string;
+export declare function titleFromMarkdown(text: string): string | undefined;

package/dist/header.js

@@ -0,0 +1,193 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.splitLines = splitLines;
+exports.parseHeader = parseHeader;
+exports.extractHeaderValuesLoose = extractHeaderValuesLoose;
+exports.isValidIsoDate = isValidIsoDate;
+exports.todayIso = todayIso;
+exports.compareIsoDate = compareIsoDate;
+exports.parseReferenceValue = parseReferenceValue;
+exports.extractReferenceCandidates = extractReferenceCandidates;
+exports.isExternalTarget = isExternalTarget;
+exports.stripAnchor = stripAnchor;
+exports.resolveReferenceTarget = resolveReferenceTarget;
+exports.formatReference = formatReference;
+exports.titleFromMarkdown = titleFromMarkdown;
+const node_path_1 = __importDefault(require("node:path"));
+const types_1 = require("./types");
+const REFERENCE_TOKEN = /^\[([^\]]+)\]\(([^)]+)\)(?:\s+\[(\d{4}-\d{2}-\d{2})\])?/;
+const MARKDOWN_LINK_CANDIDATE = /^\[([^\]]+)\]\(([^)]+)\)(?:\s+\[([^\]]+)\])?$/;
+function splitLines(text) {
+    return text.replace(/^\uFEFF/, "").split(/\r?\n/);
+}
+function parseHeader(text) {
+    const lines = splitLines(text);
+    const values = {};
+    const parsedLines = types_1.HEADER_FIELDS.map((expectedField, index) => {
+        const raw = lines[index] ?? "";
+        const cleaned = index === 0 ? raw.replace(/^\uFEFF/, "") : raw;
+        const match = /^([^:]+):\s*(.*)$/.exec(cleaned);
+        const actualField = match?.[1]?.trim();
+        const value = match?.[2]?.trim();
+        if (actualField && types_1.HEADER_FIELDS.includes(actualField)) {
+            values[actualField] = value ?? "";
+        }
+        return {
+            expectedField,
+            actualField,
+            value,
+            line: index,
+            raw
+        };
+    });
+    return {
+        values,
+        lines: parsedLines,
+        hasHeaderStart: parsedLines[0]?.actualField === "Status",
+        headerLineCount: types_1.HEADER_FIELDS.length
+    };
+}
+function extractHeaderValuesLoose(text) {
+    const lines = splitLines(text).slice(0, 20);
+    const values = {};
+    for (const line of lines) {
+        const match = /^([^:]+):\s*(.*)$/.exec(line);
+        if (!match) {
+            continue;
+        }
+        const field = match[1].trim();
+        if (types_1.HEADER_FIELDS.includes(field)) {
+            values[field] = match[2].trim();
+        }
+    }
+    return values;
+}
+function isValidIsoDate(value) {
+    if (!value || !/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+        return false;
+    }
+    const parsed = new Date(`${value}T00:00:00.000Z`);
+    if (Number.isNaN(parsed.getTime())) {
+        return false;
+    }
+    return parsed.toISOString().slice(0, 10) === value;
+}
+function todayIso() {
+    return new Date().toISOString().slice(0, 10);
+}
+function compareIsoDate(a, b) {
+    if (!a || !b || !isValidIsoDate(a) || !isValidIsoDate(b)) {
+        return undefined;
+    }
+    const left = a;
+    const right = b;
+    return left === right ? 0 : left < right ? -1 : 1;
+}
+function parseReferenceValue(value) {
+    const rawValue = (value ?? "").trim();
+    if (!rawValue || rawValue === "None") {
+        return { none: rawValue === "None", references: [], invalidFragments: rawValue ? [] : [""] };
+    }
+    const references = [];
+    const invalidFragments = [];
+    let cursor = 0;
+    while (cursor < rawValue.length) {
+        while (cursor < rawValue.length && /[\s,]/.test(rawValue[cursor])) {
+            cursor += 1;
+        }
+        if (cursor >= rawValue.length) {
+            break;
+        }
+        const remainder = rawValue.slice(cursor);
+        const match = REFERENCE_TOKEN.exec(remainder);
+        if (match) {
+            const raw = match[0];
+            references.push({
+                label: match[1],
+                target: match[2],
+                declaredLastUpdated: match[3],
+                raw,
+                start: cursor,
+                end: cursor + raw.length
+            });
+            cursor += raw.length;
+            continue;
+        }
+        const nextComma = rawValue.indexOf(",", cursor);
+        const end = nextComma === -1 ? rawValue.length : nextComma;
+        const fragment = rawValue.slice(cursor, end).trim();
+        if (fragment) {
+            invalidFragments.push(fragment);
+        }
+        cursor = end + 1;
+    }
+    return { none: false, references, invalidFragments };
+}
+function extractReferenceCandidates(value) {
+    const rawValue = (value ?? "").trim();
+    if (!rawValue || rawValue === "None") {
+        return [];
+    }
+    const parsed = parseReferenceValue(rawValue);
+    if (parsed.invalidFragments.length === 0 && parsed.references.length > 0) {
+        return parsed.references.map((reference) => ({
+            label: reference.label,
+            target: reference.target,
+            declaredLastUpdated: reference.declaredLastUpdated
+        }));
+    }
+    return rawValue
+        .split(",")
+        .map((part) => part.trim())
+        .filter(Boolean)
+        .map((part) => {
+        const cleaned = part.replace(/^`|`$/g, "");
+        const linkMatch = MARKDOWN_LINK_CANDIDATE.exec(cleaned);
+        if (linkMatch) {
+            return {
+                label: linkMatch[1],
+                target: linkMatch[2],
+                declaredLastUpdated: /^\d{4}-\d{2}-\d{2}$/.test(linkMatch[3] ?? "") ? linkMatch[3] : undefined
+            };
+        }
+        return {
+            label: node_path_1.default.posix.basename(cleaned) || cleaned,
+            target: cleaned
+        };
+    });
+}
+function isExternalTarget(target) {
+    return /^(https?:|mailto:|#)/i.test(target);
+}
+function stripAnchor(target) {
+    return target.split("#", 1)[0];
+}
+function resolveReferenceTarget(currentDocumentPath, target) {
+    if (isExternalTarget(target)) {
+        return undefined;
+    }
+    const targetWithoutAnchor = stripAnchor(target);
+    if (!targetWithoutAnchor) {
+        return undefined;
+    }
+    if (targetWithoutAnchor.startsWith("/")) {
+        return node_path_1.default.posix.normalize(targetWithoutAnchor.slice(1));
+    }
+    return node_path_1.default.posix.normalize(node_path_1.default.posix.join(node_path_1.default.posix.dirname(currentDocumentPath), targetWithoutAnchor));
+}
+function formatReference(label, target, lastUpdated) {
+    return `[${label}](${target}) [${lastUpdated}]`;
+}
+function titleFromMarkdown(text) {
+    for (const line of splitLines(text)) {
+        const match = /^#\s+(.+?)\s*$/.exec(line);
+        if (match) {
+            return match[1];
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=header.js.map

package/dist/linter.d.ts

@@ -0,0 +1,10 @@
+import { DocumentGraph, LintDiagnostic, LintOptions } from "./types";
+export declare function lintMarkdownDocument(documentPath: string, text: string, graph: DocumentGraph, options: LintOptions): LintDiagnostic[];
+export declare function buildNormalizedHeaderText(documentPath: string, text: string, graph: DocumentGraph, today?: string, forceLastUpdated?: boolean): string;
+export declare function fixMarkdownDocument(documentPath: string, text: string, graph: DocumentGraph, today?: string, forceLastUpdated?: boolean): string;
+export declare function normalizeReferenceValue(documentPath: string, value: string, graph: DocumentGraph, today?: string): string;
+export declare function headerReplacementRange(text: string): {
+    startLine: number;
+    endLineExclusive: number;
+};
+export declare function recommendedReviewDate(documentPath: string, graph: DocumentGraph, fallbackToday?: string): string;

package/dist/linter.js

@@ -0,0 +1,210 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lintMarkdownDocument = lintMarkdownDocument;
+exports.buildNormalizedHeaderText = buildNormalizedHeaderText;
+exports.fixMarkdownDocument = fixMarkdownDocument;
+exports.normalizeReferenceValue = normalizeReferenceValue;
+exports.headerReplacementRange = headerReplacementRange;
+exports.recommendedReviewDate = recommendedReviewDate;
+const header_1 = require("./header");
+const types_1 = require("./types");
+const EMPTY_RANGE = { character: 0, endCharacter: 1 };
+function lintMarkdownDocument(documentPath, text, graph, options) {
+    const diagnostics = [];
+    const lines = (0, header_1.splitLines)(text);
+    const header = (0, header_1.parseHeader)(text);
+    if (!header.hasHeaderStart) {
+        diagnostics.push(diagnostic("missing-header", "error", "Markdown file must start with a document metadata header.", 0, 0, 1));
+    }
+    for (const headerLine of header.lines) {
+        const expected = headerLine.expectedField;
+        const rawLength = headerLine.raw.length || 1;
+        if (headerLine.actualField !== expected) {
+            diagnostics.push(diagnostic("invalid-field-order", "error", `Expected header field \`${expected}:\` on line ${headerLine.line + 1}.`, headerLine.line, 0, rawLength));
+            continue;
+        }
+        if ((headerLine.value ?? "").trim() === "") {
+            diagnostics.push(diagnostic("empty-header-field", "error", `Header field \`${expected}\` must not be empty.`, headerLine.line, 0, rawLength));
+        }
+    }
+    if (lines.length > types_1.HEADER_FIELDS.length && lines[types_1.HEADER_FIELDS.length].trim() !== "") {
+        diagnostics.push(diagnostic("missing-header-separator", "warning", "Header should be followed by one blank line before document content.", types_1.HEADER_FIELDS.length, 0, lines[types_1.HEADER_FIELDS.length].length || 1));
+    }
+    const status = header.values.Status;
+    if (status && !options.allowedStatuses.includes(status)) {
+        diagnostics.push(diagnostic("invalid-status", "error", `Status must be one of: ${options.allowedStatuses.join(", ")}.`, fieldLine("Status"), 0, lines[fieldLine("Status")]?.length || 1));
+    }
+    const lastUpdated = header.values["Last updated"];
+    if (lastUpdated && !(0, header_1.isValidIsoDate)(lastUpdated)) {
+        diagnostics.push(diagnostic("invalid-last-updated", "error", "`Last updated` must be a valid YYYY-MM-DD date.", fieldLine("Last updated"), 0, lines[fieldLine("Last updated")]?.length || 1));
+    }
+    validateReferences("Depends on", "dependsOn", documentPath, header.values["Depends on"], lastUpdated, graph, options, diagnostics);
+    validateReferences("Supersedes", "supersedes", documentPath, header.values.Supersedes, lastUpdated, graph, options, diagnostics);
+    return diagnostics;
+    function fieldLine(field) {
+        return types_1.HEADER_FIELDS.indexOf(field);
+    }
+}
+function validateReferences(field, kind, documentPath, value, currentLastUpdated, graph, options, diagnostics) {
+    const line = types_1.HEADER_FIELDS.indexOf(field);
+    const parsed = (0, header_1.parseReferenceValue)(value);
+    if (!value || value.trim() === "") {
+        diagnostics.push(diagnostic("empty-reference-field", "error", `\`${field}\` must be \`None\` or one or more dated Markdown links.`, line, 0, 1));
+        return;
+    }
+    if (parsed.none) {
+        return;
+    }
+    if (parsed.invalidFragments.length > 0 || parsed.references.length === 0) {
+        diagnostics.push(diagnostic("raw-header-reference", "error", `\`${field}\` references must be clickable Markdown links with bracketed Last updated dates.`, line, 0, value.length || 1));
+    }
+    for (const reference of parsed.references) {
+        if (options.requireReferenceDates && !reference.declaredLastUpdated) {
+            diagnostics.push(diagnostic("missing-reference-date", "error", `Reference \`${reference.target}\` must include the target document's Last updated date in brackets.`, line, reference.start, reference.end));
+        }
+        if (reference.declaredLastUpdated && !(0, header_1.isValidIsoDate)(reference.declaredLastUpdated)) {
+            diagnostics.push(diagnostic("invalid-reference-date", "error", `Reference date for \`${reference.target}\` must be YYYY-MM-DD.`, line, reference.start, reference.end));
+        }
+        const resolvedTarget = (0, header_1.resolveReferenceTarget)(documentPath, reference.target);
+        if (!resolvedTarget) {
+            continue;
+        }
+        const targetNode = graph.documents[resolvedTarget];
+        if (!targetNode) {
+            diagnostics.push(diagnostic("missing-reference-target", "error", `Referenced Markdown document does not exist in the workspace graph: ${reference.target}`, line, reference.start, reference.end));
+            continue;
+        }
+        if (targetNode.lastUpdated && reference.declaredLastUpdated && targetNode.lastUpdated !== reference.declaredLastUpdated) {
+            diagnostics.push(diagnostic("stale-reference-date", "error", `Reference date for \`${reference.target}\` is ${reference.declaredLastUpdated}, but target Last updated is ${targetNode.lastUpdated}.`, line, reference.start, reference.end));
+        }
+        if (kind === "dependsOn" && options.warnWhenDependencyNewer) {
+            const comparison = (0, header_1.compareIsoDate)(currentLastUpdated, targetNode.lastUpdated);
+            if (comparison !== undefined && comparison < 0) {
+                diagnostics.push(diagnostic("dependency-newer-than-document", "warning", `Dependency \`${reference.target}\` was updated after this document; review for drift.`, line, reference.start, reference.end));
+            }
+        }
+        if (kind === "supersedes" && options.validateSupersedesNotNewer) {
+            const comparison = (0, header_1.compareIsoDate)(currentLastUpdated, targetNode.lastUpdated);
+            if (comparison !== undefined && comparison < 0) {
+                diagnostics.push(diagnostic("superseded-document-newer", "warning", `Superseded document \`${reference.target}\` is newer than this document.`, line, reference.start, reference.end));
+            }
+        }
+    }
+}
+function buildNormalizedHeaderText(documentPath, text, graph, today = (0, header_1.todayIso)(), forceLastUpdated = false) {
+    const loose = (0, header_1.extractHeaderValuesLoose)(text);
+    const lastUpdated = forceLastUpdated
+        ? recommendedReviewDate(documentPath, graph, today)
+        : (0, header_1.isValidIsoDate)(loose["Last updated"])
+            ? loose["Last updated"]
+            : today;
+    const values = {
+        Status: normalizeStatus(loose.Status),
+        Owner: loose.Owner || "TODO",
+        Reviewers: loose.Reviewers || "TODO",
+        "Last updated": lastUpdated,
+        Milestone: loose.Milestone || "M0",
+        "Depends on": normalizeReferenceValue(documentPath, loose["Depends on"] || "None", graph, today),
+        Supersedes: normalizeReferenceValue(documentPath, loose.Supersedes || "None", graph, today)
+    };
+    return types_1.HEADER_FIELDS.map((field) => `${field}: ${values[field]}`).join("\n");
+}
+function fixMarkdownDocument(documentPath, text, graph, today = (0, header_1.todayIso)(), forceLastUpdated = true) {
+    const header = buildNormalizedHeaderText(documentPath, text, graph, today, forceLastUpdated);
+    const body = stripExistingHeader(text);
+    return body ? `${header}\n\n${body}` : `${header}\n`;
+}
+function normalizeStatus(value) {
+    const trimmed = (value ?? "").trim();
+    if (!trimmed) {
+        return "Draft";
+    }
+    const canonical = DEFAULT_STATUSES.find((status) => status.toLowerCase() === trimmed.toLowerCase());
+    return canonical ?? "Draft";
+}
+function normalizeReferenceValue(documentPath, value, graph, today = (0, header_1.todayIso)()) {
+    const trimmed = value.trim();
+    if (!trimmed || trimmed === "None") {
+        return "None";
+    }
+    const candidates = (0, header_1.extractReferenceCandidates)(trimmed);
+    if (candidates.length === 0) {
+        return "None";
+    }
+    const references = candidates
+        .map((candidate) => {
+        const resolvedTarget = (0, header_1.resolveReferenceTarget)(documentPath, candidate.target);
+        const targetNode = resolvedTarget ? graph.documents[resolvedTarget] : undefined;
+        if (resolvedTarget && !targetNode) {
+            return undefined;
+        }
+        const targetLastUpdated = targetNode?.lastUpdated;
+        const date = (0, header_1.isValidIsoDate)(targetLastUpdated)
+            ? targetLastUpdated
+            : (0, header_1.isValidIsoDate)(candidate.declaredLastUpdated)
+                ? candidate.declaredLastUpdated
+                : (0, header_1.isExternalTarget)(candidate.target)
+                    ? today
+                    : targetNode
+                        ? today
+                        : undefined;
+        if (!date) {
+            return undefined;
+        }
+        return (0, header_1.formatReference)(candidate.label, candidate.target, date);
+    })
+        .filter((reference) => Boolean(reference));
+    return references.length > 0 ? references.join(", ") : "None";
+}
+function headerReplacementRange(text) {
+    const loose = (0, header_1.extractHeaderValuesLoose)(text);
+    const hasAnyHeaderField = Object.keys(loose).length > 0;
+    if (!hasAnyHeaderField) {
+        return { startLine: 0, endLineExclusive: 0 };
+    }
+    const lines = (0, header_1.splitLines)(text);
+    const includeSeparator = lines[types_1.HEADER_FIELDS.length]?.trim() === "";
+    return {
+        startLine: 0,
+        endLineExclusive: types_1.HEADER_FIELDS.length + (includeSeparator ? 1 : 0)
+    };
+}
+function recommendedReviewDate(documentPath, graph, fallbackToday = (0, header_1.todayIso)()) {
+    const relatedDates = graph.edges
+        .filter((edge) => edge.from === documentPath)
+        .map((edge) => edge.actualLastUpdated)
+        .filter(header_1.isValidIsoDate);
+    return [fallbackToday, ...relatedDates].sort().at(-1) ?? fallbackToday;
+}
+function stripExistingHeader(text) {
+    const lines = (0, header_1.splitLines)(text);
+    const removable = new Set();
+    const scanLimit = Math.min(lines.length, 30);
+    for (let index = 0; index < scanLimit; index += 1) {
+        const match = /^([^:]+):\s*(.*)$/.exec(lines[index]);
+        if (match && types_1.HEADER_FIELDS.includes(match[1].trim())) {
+            removable.add(index);
+        }
+    }
+    const remaining = lines.filter((_line, index) => !removable.has(index));
+    while (remaining.length > 0 && remaining[0].trim() === "") {
+        remaining.shift();
+    }
+    while (remaining.length > 1 && remaining[0].trim() === "" && remaining[1].trim() === "") {
+        remaining.shift();
+    }
+    return remaining.join("\n").replace(/^\s*\n/, "").replace(/\s+$/, "");
+}
+function diagnostic(code, severity, message, line, character, endCharacter) {
+    return {
+        code,
+        severity,
+        message,
+        line,
+        character,
+        endLine: line,
+        endCharacter: Math.max(endCharacter, character + EMPTY_RANGE.endCharacter)
+    };
+}
+const DEFAULT_STATUSES = ["Draft", "In Review", "Approved", "Superseded"];
+//# sourceMappingURL=linter.js.map

package/dist/types.d.ts

@@ -0,0 +1,77 @@
+export declare const HEADER_FIELDS: readonly ["Status", "Owner", "Reviewers", "Last updated", "Milestone", "Depends on", "Supersedes"];
+export type HeaderField = (typeof HEADER_FIELDS)[number];
+export type HeaderValues = Partial<Record<HeaderField, string>>;
+export type Severity = "error" | "warning" | "info";
+export interface HeaderLine {
+    expectedField: HeaderField;
+    actualField?: string;
+    value?: string;
+    line: number;
+    raw: string;
+}
+export interface ParsedHeader {
+    values: HeaderValues;
+    lines: HeaderLine[];
+    hasHeaderStart: boolean;
+    headerLineCount: number;
+}
+export interface HeaderReference {
+    label: string;
+    target: string;
+    declaredLastUpdated?: string;
+    raw: string;
+    start: number;
+    end: number;
+}
+export interface ReferenceParseResult {
+    none: boolean;
+    references: HeaderReference[];
+    invalidFragments: string[];
+}
+export interface DocumentInput {
+    path: string;
+    text: string;
+}
+export interface DocumentNode {
+    path: string;
+    hashSha256: string;
+    status?: string;
+    owner?: string;
+    reviewers?: string;
+    lastUpdated?: string;
+    milestone?: string;
+    title?: string;
+}
+export type GraphEdgeKind = "dependsOn" | "supersedes";
+export interface GraphEdge {
+    from: string;
+    to: string;
+    kind: GraphEdgeKind;
+    label: string;
+    declaredLastUpdated?: string;
+    actualLastUpdated?: string;
+    targetExists: boolean;
+}
+export interface DocumentGraph {
+    version: 1;
+    generatedAt: string;
+    workspaceRoot: string;
+    documents: Record<string, DocumentNode>;
+    edges: GraphEdge[];
+}
+export interface LintOptions {
+    allowedStatuses: string[];
+    requireReferenceDates: boolean;
+    warnWhenDependencyNewer: boolean;
+    validateSupersedesNotNewer: boolean;
+}
+export interface LintDiagnostic {
+    code: string;
+    severity: Severity;
+    message: string;
+    line: number;
+    character: number;
+    endLine: number;
+    endCharacter: number;
+}
+export declare const DEFAULT_LINT_OPTIONS: LintOptions;

package/dist/types.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_LINT_OPTIONS = exports.HEADER_FIELDS = void 0;
+exports.HEADER_FIELDS = [
+    "Status",
+    "Owner",
+    "Reviewers",
+    "Last updated",
+    "Milestone",
+    "Depends on",
+    "Supersedes"
+];
+exports.DEFAULT_LINT_OPTIONS = {
+    allowedStatuses: ["Draft", "In Review", "Approved", "Superseded"],
+    requireReferenceDates: true,
+    warnWhenDependencyNewer: true,
+    validateSupersedesNotNewer: true
+};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,148 @@
+{
+  "name": "hdlinter",
+  "publisher": "swekkiekekkie",
+  "displayName": "hdlinter",
+  "description": "Cursor/VS Code extension and CLI for validating project document metadata headers.",
+  "version": "0.1.0",
+  "license": "MIT",
+  "keywords": [
+    "markdown",
+    "lint",
+    "metadata",
+    "headers",
+    "cursor",
+    "vscode",
+    "documentation"
+  ],
+  "files": [
+    "dist/*.js",
+    "dist/*.d.ts",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/swekkiekekkie/hdlinter.git"
+  },
+  "bugs": {
+    "url": "https://github.com/swekkiekekkie/hdlinter/issues"
+  },
+  "homepage": "https://github.com/swekkiekekkie/hdlinter#readme",
+  "engines": {
+    "vscode": "^1.85.0"
+  },
+  "categories": [
+    "Linters",
+    "Other"
+  ],
+  "main": "./dist/extension.js",
+  "bin": {
+    "hdlinter": "dist/cli.js"
+  },
+  "activationEvents": [
+    "onLanguage:markdown",
+    "workspaceContains:**/*.md",
+    "onCommand:hdlinter.fixCurrentDocumentHeader",
+    "onCommand:hdlinter.rebuildGraphState",
+    "onCommand:hdlinter.fixWorkspaceHeaders"
+  ],
+  "contributes": {
+    "commands": [
+      {
+        "command": "hdlinter.fixCurrentDocumentHeader",
+        "title": "hdlinter: Fix Current Document Header"
+      },
+      {
+        "command": "hdlinter.rebuildGraphState",
+        "title": "hdlinter: Rebuild Hidden Graph State"
+      },
+      {
+        "command": "hdlinter.fixWorkspaceHeaders",
+        "title": "hdlinter: Fix All Workspace Headers"
+      }
+    ],
+    "configuration": {
+      "title": "hdlinter",
+      "properties": {
+        "hdlinter.enabled": {
+          "type": "boolean",
+          "default": true,
+          "description": "Enable document header lint diagnostics."
+        },
+        "hdlinter.include": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "default": [
+            "**/*.md"
+          ],
+          "description": "Markdown file globs to lint."
+        },
+        "hdlinter.exclude": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "default": [
+            "**/.git/**",
+            "**/node_modules/**",
+            "**/.hdlinter/**"
+          ],
+          "description": "Globs to exclude from linting."
+        },
+        "hdlinter.stateFile": {
+          "type": "string",
+          "default": ".hdlinter/state.json",
+          "description": "Workspace-relative hidden graph/hash state file."
+        },
+        "hdlinter.allowedStatuses": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "default": [
+            "Draft",
+            "In Review",
+            "Approved",
+            "Superseded"
+          ],
+          "description": "Allowed Status header values."
+        },
+        "hdlinter.requireReferenceDates": {
+          "type": "boolean",
+          "default": true,
+          "description": "Require header references to include a bracketed target Last updated date."
+        },
+        "hdlinter.warnWhenDependencyNewer": {
+          "type": "boolean",
+          "default": true,
+          "description": "Warn when a dependency has a later Last updated date than the current document."
+        },
+        "hdlinter.validateSupersedesNotNewer": {
+          "type": "boolean",
+          "default": true,
+          "description": "Warn when a superseded document has a later Last updated date than the superseding document."
+        }
+      }
+    }
+  },
+  "scripts": {
+    "build": "npm run compile",
+    "compile": "tsc -p ./",
+    "watch": "tsc -watch -p ./",
+    "test": "npm run compile && node --test dist/test/*.test.js",
+    "vscode:prepublish": "npm run compile",
+    "prepack": "npm run compile",
+    "prepublishOnly": "npm test",
+    "package": "vsce package --allow-missing-repository",
+    "package:vsix": "vsce package --allow-missing-repository",
+    "publish:dry-run": "npm publish --dry-run",
+    "lint:aicompliance": "npm run compile && node dist/cli.js ../aicompliance --write-state"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.0",
+    "@types/vscode": "^1.85.0",
+    "@vscode/vsce": "^2.32.0",
+    "typescript": "^5.6.0"
+  }
+}