okf-kit 0.3.0

package/dist/report.js

@@ -0,0 +1,51 @@
+export function summarize(findings) {
+    const summary = { errors: 0, warnings: 0, notices: 0 };
+    for (const finding of findings) {
+        if (finding.severity === "error")
+            summary.errors++;
+        else if (finding.severity === "warning")
+            summary.warnings++;
+        else
+            summary.notices++;
+    }
+    return summary;
+}
+export function renderText(bundleDir, findings) {
+    if (findings.length === 0) {
+        return `okf-kit: clean, no findings in ${bundleDir}\n`;
+    }
+    const byFile = new Map();
+    for (const finding of findings) {
+        const group = byFile.get(finding.file);
+        if (group)
+            group.push(finding);
+        else
+            byFile.set(finding.file, [finding]);
+    }
+    const lines = [];
+    for (const [file, group] of byFile) {
+        for (const finding of group) {
+            lines.push(`${severityLabel(finding.severity)} ${finding.ruleId} ${file}: ${finding.message}`);
+            if (finding.detail)
+                lines.push(`  ${finding.detail}`);
+        }
+    }
+    const summary = summarize(findings);
+    lines.push(`${findings.length} findings (errors ${summary.errors}, warnings ${summary.warnings}, notices ${summary.notices})`);
+    return lines.join("\n") + "\n";
+}
+export function renderJson(bundleDir, findings) {
+    const summary = summarize(findings);
+    return JSON.stringify({ bundleDir, findings, summary }, null, 2) + "\n";
+}
+function severityLabel(s) {
+    switch (s) {
+        case "error":
+            return "ERROR ";
+        case "warning":
+            return "WARN  ";
+        case "notice":
+            return "NOTICE";
+    }
+}
+//# sourceMappingURL=report.js.map

package/dist/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../src/report.ts"],"names":[],"mappings":"AAQA,MAAM,UAAU,SAAS,CAAC,QAAmB;IAC3C,MAAM,OAAO,GAAY,EAAE,MAAM,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;IAChE,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO;YAAE,OAAO,CAAC,MAAM,EAAE,CAAC;aAC9C,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS;YAAE,OAAO,CAAC,QAAQ,EAAE,CAAC;;YACvD,OAAO,CAAC,OAAO,EAAE,CAAC;IACzB,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,SAAiB,EAAE,QAAmB;IAC/D,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,kCAAkC,SAAS,IAAI,CAAC;IACzD,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,GAAG,EAAqB,CAAC;IAC5C,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACvC,IAAI,KAAK;YAAE,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;;YAC1B,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IAC3C,CAAC;IAED,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,EAAE,CAAC;QACnC,KAAK,MAAM,OAAO,IAAI,KAAK,EAAE,CAAC;YAC5B,KAAK,CAAC,IAAI,CACR,GAAG,aAAa,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,OAAO,CAAC,MAAM,IAAI,IAAI,KAAK,OAAO,CAAC,OAAO,EAAE,CACnF,CAAC;YACF,IAAI,OAAO,CAAC,MAAM;gBAAE,KAAK,CAAC,IAAI,CAAC,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;QACxD,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;IACpC,KAAK,CAAC,IAAI,CACR,GAAG,QAAQ,CAAC,MAAM,qBAAqB,OAAO,CAAC,MAAM,cAAc,OAAO,CAAC,QAAQ,aAAa,OAAO,CAAC,OAAO,GAAG,CACnH,CAAC;IACF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,SAAiB,EAAE,QAAmB;IAC/D,MAAM,OAAO,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;IACpC,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC;AAC1E,CAAC;AAED,SAAS,aAAa,CAAC,CAAW;IAChC,QAAQ,CAAC,EAAE,CAAC;QACV,KAAK,OAAO;YACV,OAAO,QAAQ,CAAC;QAClB,KAAK,SAAS;YACZ,OAAO,QAAQ,CAAC;QAClB,KAAK,QAAQ;YACX,OAAO,QAAQ,CAAC;IACpB,CAAC;AACH,CAAC"}

package/dist/rules/frontmatter-required.d.ts

@@ -0,0 +1,2 @@
+import type { Rule } from "../types.js";
+export declare const frontmatterRequiredRule: Rule;

package/dist/rules/frontmatter-required.js

@@ -0,0 +1,46 @@
+import { isRecord } from "../util.js";
+const RULE_ID = "frontmatter-required";
+export const frontmatterRequiredRule = {
+    id: RULE_ID,
+    description: "Every non-reserved markdown file must have a frontmatter block that parses and carries a non-empty string `type`.",
+    run(ctx) {
+        const findings = [];
+        for (const doc of ctx.docs) {
+            if (doc.isReserved)
+                continue;
+            const { frontmatter } = doc;
+            if (!frontmatter.present) {
+                findings.push({
+                    ruleId: RULE_ID,
+                    severity: "error",
+                    file: doc.relPath,
+                    message: "Missing frontmatter block: the file must open with a `---` line and close with a matching `---` line.",
+                });
+                continue;
+            }
+            if (frontmatter.parseError) {
+                findings.push({
+                    ruleId: RULE_ID,
+                    severity: "error",
+                    file: doc.relPath,
+                    message: "Frontmatter block is not parseable YAML.",
+                    detail: frontmatter.parseError,
+                });
+                continue;
+            }
+            const type = isRecord(frontmatter.parsed)
+                ? frontmatter.parsed.type
+                : undefined;
+            if (typeof type !== "string" || type.trim() === "") {
+                findings.push({
+                    ruleId: RULE_ID,
+                    severity: "error",
+                    file: doc.relPath,
+                    message: "Frontmatter `type` must be present and a non-empty string.",
+                });
+            }
+        }
+        return findings;
+    },
+};
+//# sourceMappingURL=frontmatter-required.js.map

package/dist/rules/frontmatter-required.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter-required.js","sourceRoot":"","sources":["../../src/rules/frontmatter-required.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGtC,MAAM,OAAO,GAAG,sBAAsB,CAAC;AAEvC,MAAM,CAAC,MAAM,uBAAuB,GAAS;IAC3C,EAAE,EAAE,OAAO;IACX,WAAW,EACT,mHAAmH;IACrH,GAAG,CAAC,GAAG;QACL,MAAM,QAAQ,GAAc,EAAE,CAAC;QAC/B,KAAK,MAAM,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;YAC3B,IAAI,GAAG,CAAC,UAAU;gBAAE,SAAS;YAC7B,MAAM,EAAE,WAAW,EAAE,GAAG,GAAG,CAAC;YAE5B,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC;gBACzB,QAAQ,CAAC,IAAI,CAAC;oBACZ,MAAM,EAAE,OAAO;oBACf,QAAQ,EAAE,OAAO;oBACjB,IAAI,EAAE,GAAG,CAAC,OAAO;oBACjB,OAAO,EACL,uGAAuG;iBAC1G,CAAC,CAAC;gBACH,SAAS;YACX,CAAC;YAED,IAAI,WAAW,CAAC,UAAU,EAAE,CAAC;gBAC3B,QAAQ,CAAC,IAAI,CAAC;oBACZ,MAAM,EAAE,OAAO;oBACf,QAAQ,EAAE,OAAO;oBACjB,IAAI,EAAE,GAAG,CAAC,OAAO;oBACjB,OAAO,EAAE,0CAA0C;oBACnD,MAAM,EAAE,WAAW,CAAC,UAAU;iBAC/B,CAAC,CAAC;gBACH,SAAS;YACX,CAAC;YAED,MAAM,IAAI,GAAG,QAAQ,CAAC,WAAW,CAAC,MAAM,CAAC;gBACvC,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,IAAI;gBACzB,CAAC,CAAC,SAAS,CAAC;YACd,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;gBACnD,QAAQ,CAAC,IAAI,CAAC;oBACZ,MAAM,EAAE,OAAO;oBACf,QAAQ,EAAE,OAAO;oBACjB,IAAI,EAAE,GAAG,CAAC,OAAO;oBACjB,OAAO,EAAE,4DAA4D;iBACtE,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF,CAAC"}

package/dist/rules/index.d.ts

@@ -0,0 +1,9 @@
+import type { Rule } from "../types.js";
+import { frontmatterRequiredRule } from "./frontmatter-required.js";
+import { reservedFilesBareRule } from "./reserved-files-bare.js";
+import { linksResolveRule } from "./links-resolve.js";
+import { noAbsoluteLinksRule } from "./no-absolute-links.js";
+import { sourcesShapeRule } from "./sources-shape.js";
+import { sourcesFreshRule } from "./sources-fresh.js";
+export declare const allRules: Rule[];
+export { frontmatterRequiredRule, reservedFilesBareRule, linksResolveRule, noAbsoluteLinksRule, sourcesShapeRule, sourcesFreshRule, };

package/dist/rules/index.js

@@ -0,0 +1,16 @@
+import { frontmatterRequiredRule } from "./frontmatter-required.js";
+import { reservedFilesBareRule } from "./reserved-files-bare.js";
+import { linksResolveRule } from "./links-resolve.js";
+import { noAbsoluteLinksRule } from "./no-absolute-links.js";
+import { sourcesShapeRule } from "./sources-shape.js";
+import { sourcesFreshRule } from "./sources-fresh.js";
+export const allRules = [
+    frontmatterRequiredRule,
+    reservedFilesBareRule,
+    linksResolveRule,
+    noAbsoluteLinksRule,
+    sourcesShapeRule,
+    sourcesFreshRule,
+];
+export { frontmatterRequiredRule, reservedFilesBareRule, linksResolveRule, noAbsoluteLinksRule, sourcesShapeRule, sourcesFreshRule, };
+//# sourceMappingURL=index.js.map

package/dist/rules/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/rules/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD,MAAM,CAAC,MAAM,QAAQ,GAAW;IAC9B,uBAAuB;IACvB,qBAAqB;IACrB,gBAAgB;IAChB,mBAAmB;IACnB,gBAAgB;IAChB,gBAAgB;CACjB,CAAC;AAEF,OAAO,EACL,uBAAuB,EACvB,qBAAqB,EACrB,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,GACjB,CAAC"}

package/dist/rules/links-resolve.d.ts

@@ -0,0 +1,2 @@
+import type { Rule } from "../types.js";
+export declare const linksResolveRule: Rule;

package/dist/rules/links-resolve.js

@@ -0,0 +1,39 @@
+import fs from "node:fs";
+import path from "node:path";
+import { extractMarkdownLinks } from "../links.js";
+const RULE_ID = "links-resolve";
+export const linksResolveRule = {
+    id: RULE_ID,
+    description: "Markdown links to `.md` files must resolve to a real file in the bundle.",
+    run(ctx) {
+        const findings = [];
+        for (const doc of ctx.docs) {
+            for (const link of extractMarkdownLinks(doc.body)) {
+                const resolved = resolveLinkPath(ctx.bundleDir, doc.relPath, link.pathPart);
+                if (!fs.existsSync(resolved)) {
+                    findings.push({
+                        ruleId: RULE_ID,
+                        severity: "error",
+                        file: doc.relPath,
+                        message: `Link target does not resolve: \`${link.target}\``,
+                    });
+                }
+            }
+        }
+        return findings;
+    },
+};
+/**
+ * Relative targets resolve against the containing file's directory. Targets
+ * starting with `/` resolve against the bundle root, not the repo root or
+ * filesystem root (see the `no-absolute-links` rule for why that leading
+ * slash is still worth flagging).
+ */
+function resolveLinkPath(bundleDir, docRelPath, pathPart) {
+    if (pathPart.startsWith("/")) {
+        return path.join(bundleDir, pathPart.slice(1));
+    }
+    const docDir = path.dirname(path.join(bundleDir, docRelPath));
+    return path.resolve(docDir, pathPart);
+}
+//# sourceMappingURL=links-resolve.js.map

package/dist/rules/links-resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"links-resolve.js","sourceRoot":"","sources":["../../src/rules/links-resolve.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAGnD,MAAM,OAAO,GAAG,eAAe,CAAC;AAEhC,MAAM,CAAC,MAAM,gBAAgB,GAAS;IACpC,EAAE,EAAE,OAAO;IACX,WAAW,EACT,0EAA0E;IAC5E,GAAG,CAAC,GAAG;QACL,MAAM,QAAQ,GAAc,EAAE,CAAC;QAC/B,KAAK,MAAM,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;YAC3B,KAAK,MAAM,IAAI,IAAI,oBAAoB,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBAClD,MAAM,QAAQ,GAAG,eAAe,CAC9B,GAAG,CAAC,SAAS,EACb,GAAG,CAAC,OAAO,EACX,IAAI,CAAC,QAAQ,CACd,CAAC;gBACF,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;oBAC7B,QAAQ,CAAC,IAAI,CAAC;wBACZ,MAAM,EAAE,OAAO;wBACf,QAAQ,EAAE,OAAO;wBACjB,IAAI,EAAE,GAAG,CAAC,OAAO;wBACjB,OAAO,EAAE,mCAAmC,IAAI,CAAC,MAAM,IAAI;qBAC5D,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF,CAAC;AAEF;;;;;GAKG;AACH,SAAS,eAAe,CACtB,SAAiB,EACjB,UAAkB,EAClB,QAAgB;IAEhB,IAAI,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC7B,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACjD,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC;IAC9D,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AACxC,CAAC"}

package/dist/rules/no-absolute-links.d.ts

@@ -0,0 +1,2 @@
+import type { Rule } from "../types.js";
+export declare const noAbsoluteLinksRule: Rule;

package/dist/rules/no-absolute-links.js

@@ -0,0 +1,25 @@
+import { extractMarkdownLinks } from "../links.js";
+const RULE_ID = "no-absolute-links";
+export const noAbsoluteLinksRule = {
+    id: RULE_ID,
+    description: "Link targets should not start with `/`.",
+    run(ctx) {
+        const findings = [];
+        for (const doc of ctx.docs) {
+            for (const link of extractMarkdownLinks(doc.body)) {
+                if (!link.pathPart.startsWith("/"))
+                    continue;
+                findings.push({
+                    ruleId: RULE_ID,
+                    severity: "warning",
+                    file: doc.relPath,
+                    message: `Link target \`${link.target}\` starts with \`/\`: GitHub resolves a leading slash against ` +
+                        "the repository root, not the bundle root, so this link 404s once the bundle is viewed outside " +
+                        "its own repository (agent-tasks#387). Use a same-directory relative link instead.",
+                });
+            }
+        }
+        return findings;
+    },
+};
+//# sourceMappingURL=no-absolute-links.js.map

package/dist/rules/no-absolute-links.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-absolute-links.js","sourceRoot":"","sources":["../../src/rules/no-absolute-links.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAGnD,MAAM,OAAO,GAAG,mBAAmB,CAAC;AAEpC,MAAM,CAAC,MAAM,mBAAmB,GAAS;IACvC,EAAE,EAAE,OAAO;IACX,WAAW,EAAE,yCAAyC;IACtD,GAAG,CAAC,GAAG;QACL,MAAM,QAAQ,GAAc,EAAE,CAAC;QAC/B,KAAK,MAAM,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;YAC3B,KAAK,MAAM,IAAI,IAAI,oBAAoB,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBAClD,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC;oBAAE,SAAS;gBAC7C,QAAQ,CAAC,IAAI,CAAC;oBACZ,MAAM,EAAE,OAAO;oBACf,QAAQ,EAAE,SAAS;oBACnB,IAAI,EAAE,GAAG,CAAC,OAAO;oBACjB,OAAO,EACL,iBAAiB,IAAI,CAAC,MAAM,gEAAgE;wBAC5F,gGAAgG;wBAChG,mFAAmF;iBACtF,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF,CAAC"}

package/dist/rules/reserved-files-bare.d.ts

@@ -0,0 +1,2 @@
+import type { Rule } from "../types.js";
+export declare const reservedFilesBareRule: Rule;

package/dist/rules/reserved-files-bare.js

@@ -0,0 +1,22 @@
+const RULE_ID = "reserved-files-bare";
+export const reservedFilesBareRule = {
+    id: RULE_ID,
+    description: "Reserved files (index.md, log.md, at any depth) must not carry a frontmatter block.",
+    run(ctx) {
+        const findings = [];
+        for (const doc of ctx.docs) {
+            if (!doc.isReserved)
+                continue;
+            if (doc.frontmatter.present) {
+                findings.push({
+                    ruleId: RULE_ID,
+                    severity: "error",
+                    file: doc.relPath,
+                    message: `Reserved file \`${doc.basename}\` must not carry a frontmatter block.`,
+                });
+            }
+        }
+        return findings;
+    },
+};
+//# sourceMappingURL=reserved-files-bare.js.map

package/dist/rules/reserved-files-bare.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reserved-files-bare.js","sourceRoot":"","sources":["../../src/rules/reserved-files-bare.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,GAAG,qBAAqB,CAAC;AAEtC,MAAM,CAAC,MAAM,qBAAqB,GAAS;IACzC,EAAE,EAAE,OAAO;IACX,WAAW,EACT,qFAAqF;IACvF,GAAG,CAAC,GAAG;QACL,MAAM,QAAQ,GAAc,EAAE,CAAC;QAC/B,KAAK,MAAM,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;YAC3B,IAAI,CAAC,GAAG,CAAC,UAAU;gBAAE,SAAS;YAC9B,IAAI,GAAG,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC;gBAC5B,QAAQ,CAAC,IAAI,CAAC;oBACZ,MAAM,EAAE,OAAO;oBACf,QAAQ,EAAE,OAAO;oBACjB,IAAI,EAAE,GAAG,CAAC,OAAO;oBACjB,OAAO,EAAE,mBAAmB,GAAG,CAAC,QAAQ,wCAAwC;iBACjF,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF,CAAC"}

package/dist/rules/sources-fresh.d.ts

@@ -0,0 +1,2 @@
+import type { Rule } from "../types.js";
+export declare const sourcesFreshRule: Rule;

package/dist/rules/sources-fresh.js

@@ -0,0 +1,99 @@
+import fs from "node:fs";
+import path from "node:path";
+import { runGit as defaultRunGit } from "../git.js";
+import { getTimestampEpoch, getValidSources } from "../util.js";
+const RULE_ID = "sources-fresh";
+export const sourcesFreshRule = {
+    id: RULE_ID,
+    description: "Frontmatter `sources` paths must not have a last-commit time newer than the doc's `timestamp`.",
+    run(ctx) {
+        const findings = [];
+        const docsWithSources = ctx.docs
+            .map((doc) => ({ doc, sources: getValidSources(doc.frontmatter.parsed) }))
+            .filter((entry) => entry.sources !== undefined);
+        if (docsWithSources.length === 0)
+            return findings;
+        if (!ctx.repoRoot) {
+            // Never silently skip: an unset repoRoot means no existence check ran
+            // either (sources-shape), so staleness truly was not assessed, not
+            // "everything looked fine". One notice for the whole bundle, not one
+            // per doc: this is a bundle-level condition, not a per-doc finding.
+            findings.push({
+                ruleId: RULE_ID,
+                severity: "notice",
+                file: "",
+                message: "staleness skipped: not inside a git work tree",
+            });
+            return findings;
+        }
+        const repoRoot = ctx.repoRoot;
+        const git = ctx.runGit ?? defaultRunGit;
+        // One git call per unique source path across all docs, even though a
+        // STALE/untracked finding is reported per (doc, path) below.
+        const commitEpochCache = new Map();
+        const commitEpochFor = (source) => {
+            const cached = commitEpochCache.get(source);
+            if (cached !== undefined)
+                return cached;
+            const epoch = getLastCommitEpoch(git, repoRoot, source);
+            commitEpochCache.set(source, epoch);
+            return epoch;
+        };
+        for (const { doc, sources } of docsWithSources) {
+            const timestampEpoch = getTimestampEpoch(doc.frontmatter.parsed);
+            if (timestampEpoch === undefined) {
+                findings.push({
+                    ruleId: RULE_ID,
+                    severity: "notice",
+                    file: doc.relPath,
+                    message: "staleness not assessable: no valid timestamp",
+                });
+                continue;
+            }
+            for (const source of sources) {
+                // A missing path on disk is sources-shape's job to report; avoid a
+                // duplicate/confusing finding here.
+                if (!fs.existsSync(path.join(repoRoot, source)))
+                    continue;
+                const commitEpoch = commitEpochFor(source);
+                if (commitEpoch === null) {
+                    findings.push({
+                        ruleId: RULE_ID,
+                        severity: "notice",
+                        file: doc.relPath,
+                        message: `untracked by git, staleness unknown: \`${source}\``,
+                    });
+                    continue;
+                }
+                if (commitEpoch > timestampEpoch) {
+                    findings.push({
+                        ruleId: RULE_ID,
+                        severity: "warning",
+                        file: doc.relPath,
+                        message: `STALE: \`${source}\` changed ${epochToIso(commitEpoch)} after doc timestamp ${epochToIso(timestampEpoch)}`,
+                    });
+                }
+            }
+        }
+        return findings;
+    },
+};
+/**
+ * Last-commit epoch (seconds) for `source` relative to `repoRoot`, or null
+ * when the path has no git history (untracked) or the git call itself
+ * failed. `git log` with a pathspec that matches no commits exits 0 with
+ * empty stdout, which is exactly the "untracked" case, distinct from a real
+ * git failure (which RunGit also reports as null): both collapse to null
+ * here because sources-fresh treats them the same way, "staleness unknown".
+ */
+function getLastCommitEpoch(git, repoRoot, source) {
+    const out = git(["log", "-1", "--format=%ct", "--", source], repoRoot);
+    if (!out)
+        return null;
+    const epoch = Number.parseInt(out, 10);
+    return Number.isNaN(epoch) ? null : epoch;
+}
+function epochToIso(epochSeconds) {
+    return new Date(epochSeconds * 1000).toISOString();
+}
+//# sourceMappingURL=sources-fresh.js.map

package/dist/rules/sources-fresh.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sources-fresh.js","sourceRoot":"","sources":["../../src/rules/sources-fresh.ts"],"names":[],"mappings":"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"}

package/dist/rules/sources-shape.d.ts

@@ -0,0 +1,2 @@
+import type { Rule } from "../types.js";
+export declare const sourcesShapeRule: Rule;

package/dist/rules/sources-shape.js

@@ -0,0 +1,41 @@
+import fs from "node:fs";
+import path from "node:path";
+import { getValidSources, hasSourcesKey } from "../util.js";
+const RULE_ID = "sources-shape";
+export const sourcesShapeRule = {
+    id: RULE_ID,
+    description: "Frontmatter `sources`, when present, must be a non-empty array of non-empty strings; with a repo root (explicit --repo-root or auto-detected), each path must exist.",
+    run(ctx) {
+        const findings = [];
+        for (const doc of ctx.docs) {
+            const parsed = doc.frontmatter.parsed;
+            if (!hasSourcesKey(parsed))
+                continue;
+            const sources = getValidSources(parsed);
+            if (!sources) {
+                findings.push({
+                    ruleId: RULE_ID,
+                    severity: "error",
+                    file: doc.relPath,
+                    message: "Frontmatter `sources` must be a non-empty array of non-empty strings.",
+                });
+                continue;
+            }
+            if (!ctx.repoRoot)
+                continue;
+            for (const source of sources) {
+                const target = path.join(ctx.repoRoot, source);
+                if (!fs.existsSync(target)) {
+                    findings.push({
+                        ruleId: RULE_ID,
+                        severity: "error",
+                        file: doc.relPath,
+                        message: `Source path does not exist under repo root: \`${source}\``,
+                    });
+                }
+            }
+        }
+        return findings;
+    },
+};
+//# sourceMappingURL=sources-shape.js.map

package/dist/rules/sources-shape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sources-shape.js","sourceRoot":"","sources":["../../src/rules/sources-shape.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAG5D,MAAM,OAAO,GAAG,eAAe,CAAC;AAEhC,MAAM,CAAC,MAAM,gBAAgB,GAAS;IACpC,EAAE,EAAE,OAAO;IACX,WAAW,EACT,sKAAsK;IACxK,GAAG,CAAC,GAAG;QACL,MAAM,QAAQ,GAAc,EAAE,CAAC;QAC/B,KAAK,MAAM,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;YAC3B,MAAM,MAAM,GAAG,GAAG,CAAC,WAAW,CAAC,MAAM,CAAC;YACtC,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC;gBAAE,SAAS;YAErC,MAAM,OAAO,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;YACxC,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,QAAQ,CAAC,IAAI,CAAC;oBACZ,MAAM,EAAE,OAAO;oBACf,QAAQ,EAAE,OAAO;oBACjB,IAAI,EAAE,GAAG,CAAC,OAAO;oBACjB,OAAO,EACL,uEAAuE;iBAC1E,CAAC,CAAC;gBACH,SAAS;YACX,CAAC;YAED,IAAI,CAAC,GAAG,CAAC,QAAQ;gBAAE,SAAS;YAC5B,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;gBAC7B,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;gBAC/C,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;oBAC3B,QAAQ,CAAC,IAAI,CAAC;wBACZ,MAAM,EAAE,OAAO;wBACf,QAAQ,EAAE,OAAO;wBACjB,IAAI,EAAE,GAAG,CAAC,OAAO;wBACjB,OAAO,EAAE,iDAAiD,MAAM,IAAI;qBACrE,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF,CAAC"}

package/dist/templates.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Scaffold content for `okf-kit init`. Everything here is static except the
+ * `timestamp` value, which the caller (src/init.ts) fills in with the real
+ * current instant at generation time: never hardcode an artificial
+ * midnight datetime here, that is exactly the lesson this kit is built to
+ * enforce (see FRONTMATTER_GUIDANCE below).
+ */
+export declare function indexTemplate(): string;
+export declare function logTemplate(timestamp: string): string;
+export declare function overviewTemplate(timestamp: string): string;
+export declare function moduleTemplate(timestamp: string): string;
+export declare function invariantTemplate(timestamp: string): string;
+export declare function runbookTemplate(timestamp: string): string;
+export declare function benchmarkTemplate(timestamp: string): string;