okf-kit 0.3.0

package/README.md

@@ -0,0 +1,124 @@
+# okf-kit
+
+`okf-kit` validates knowledge bundles against the [Open Knowledge Format (OKF) v0.1 spec](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md), a shape for markdown-plus-frontmatter knowledge bundles meant to be readable by both humans and agents. The check catalog here was shaped by the Phase-0 OKF pilot in agent-tasks ([PR #385](https://github.com/LanNguyenSi/agent-tasks/pull/385)), where a few structural mistakes (bad links, absolute paths) turned out to be easy to make and easy to catch mechanically.
+
+Part of [agent-dx](https://github.com/LanNguyenSi/agent-dx), playbooks and tooling for teams shipping with AI agents.
+
+## Install
+
+```bash
+# one-off, no install
+npx okf-kit check path/to/bundle
+
+# or install it
+npm install -g okf-kit
+```
+
+Requires Node >= 20.
+
+## Quick start
+
+```bash
+okf-kit check path/to/bundle
+
+# explicit repo root, used for both sources-shape existence checks and
+# sources-fresh staleness checks (see "repo-root auto-detection" below for
+# what happens when you omit this)
+okf-kit check path/to/bundle --repo-root /path/to/repo
+
+# JSON output for tooling
+okf-kit check path/to/bundle --json
+
+# fail on warnings too, not just errors (STALE findings are warnings)
+okf-kit check path/to/bundle --strict
+```
+
+## Scaffold a bundle (`init`)
+
+```bash
+# scaffold docs/okf (the default target, relative to the current directory)
+okf-kit init
+
+# scaffold a specific directory instead
+okf-kit init path/to/bundle
+
+# an existing, non-empty target directory is refused (exit 2) unless forced;
+# --force overwrites only the files init owns, nothing else in the directory
+okf-kit init path/to/bundle --force
+```
+
+`init` writes `index.md`, `log.md`, and one template doc per concept type: `overview-template.md`, `module-template.md`, `invariant-template.md`, `runbook-template.md`, plus `benchmark-template.md` for measuring whether the bundle helps. `index.md` and `log.md` carry no frontmatter (`reserved-files-bare`); every template doc carries full frontmatter (`type`, `title`, `description`, `tags`, `timestamp`, and, except for the benchmark template, `sources`) plus inline HTML-comment guidance on writing dense, source-verified, pointer-carrying docs instead of filler. All generated links are same-directory relative (`name.md`), never a leading-slash form.
+
+### Placeholder sources are intentional
+
+Every template doc except `benchmark-template.md` ships with `sources: [path/to/covered/source]`, a placeholder, not a real path. Running `okf-kit check` against the freshly scaffolded bundle (with a repo root available, explicit or auto-detected) will report that placeholder as a `sources-shape` "does not exist" error on every template doc. That is intentional: it is the tool telling you which docs still need a real source path, not a bug in the scaffold. The `init` completion message repeats this so it isn't missed. Replace each placeholder with the real repo-root-relative path(s) the doc describes as you write it, and the error clears doc by doc.
+
+### Authoring guidance baked into the templates
+
+- **`timestamp` means "last verified against sources," not "created on."** Bump it, and add a line to `log.md`, every time you re-verify a doc against its sources. Always use the real instant of verification (`new Date().toISOString()` or equivalent); never hand-write an artificial midnight datetime, `sources-fresh` staleness comparisons depend on it being real.
+- **Never list the bundle's own directory in `sources`.** A bundle directory changes on every doc edit inside it, so a self-referential `sources` entry goes permanently stale. This happened to the OKF pilot's own `BENCHMARK.md` (`agent-tasks` `docs/okf/BENCHMARK.md`, `sources: [docs/okf/]`); `benchmark-template.md` here omits `sources` entirely for the same reason, since a benchmark record measures the bundle rather than describing a piece of the codebase.
+- **Keep all links same-directory relative.** Use `name.md`, not `/name.md`; see `no-absolute-links` above for why a leading slash breaks once the bundle is viewed outside its own repository.
+
+## Check catalog
+
+| Rule | Severity | What it enforces |
+|------|----------|-------------------|
+| `frontmatter-required` | error | Every non-reserved `.md` file has a frontmatter block that parses as YAML and carries a non-empty string `type`. |
+| `reserved-files-bare` | error | Reserved files (`index.md`, `log.md`, at any depth) must not carry a frontmatter block. |
+| `links-resolve` | error | Markdown links to other `.md` files in the bundle must resolve to a real file. Relative targets resolve against the containing file's directory; targets starting with `/` resolve against the bundle root. A relative target that climbs out of the bundle directory (`../outside.md`) and still resolves on disk is accepted; the rule checks resolution, not containment. |
+| `no-absolute-links` | warning | Link targets should not start with `/`. GitHub resolves a leading slash against the repository root, not the bundle root, so an absolute link 404s once the bundle is viewed outside its own repository. Use a same-directory relative link instead. |
+| `sources-shape` | error | Frontmatter `sources`, when present, must be a non-empty array of non-empty strings. With a repo root (explicit or auto-detected), each listed path (file or directory) must also exist under it. |
+| `sources-fresh` | warning / notice | For docs with a `sources` list and a repo root, flags a source path whose last git commit is newer than the doc's `timestamp`. See "Staleness (sources-fresh)" below. |
+
+## repo-root auto-detection
+
+**Behavior change:** when `--repo-root` is omitted, okf-kit runs `git rev-parse --show-toplevel` from the bundle directory and uses the result if it succeeds. A bundle that lives inside a git work tree therefore gets `sources-shape` existence checks and `sources-fresh` staleness checks by default now, not just when you pass `--repo-root` explicitly.
+
+If the bundle is not inside a git work tree (or `git` is unavailable), repo-root stays unset: `sources-shape` skips existence checks exactly as before, and `sources-fresh` emits a single notice (`staleness skipped: not inside a git work tree`) rather than silently reporting nothing, so a "clean" run is never a fake pass.
+
+Pass `--repo-root` explicitly to pin a specific root (useful in CI when the bundle and the code it documents live in different checkouts) or to opt out of the ambient repo (point it at the bundle directory itself to disable both checks' access to the rest of the repo).
+
+## Staleness (sources-fresh)
+
+`sources-fresh` compares each frontmatter `sources` entry's last git commit time against the doc's `timestamp`. It never blocks a doc that has no `sources`, and it never invents an error where git can't give a real answer:
+
+| Situation | Severity | Message |
+|-----------|----------|---------|
+| A source path's last commit is newer than the doc's `timestamp` | warning | `STALE: <path> changed <iso> after doc timestamp <iso>` |
+| A source path exists but has no git history (untracked) | notice | `untracked by git, staleness unknown: <path>` |
+| The doc's `timestamp` is missing or not a parseable date, while `sources` is present | notice | `staleness not assessable: no valid timestamp` |
+| No repo root available (see auto-detection above) | notice | `staleness skipped: not inside a git work tree` |
+| A source path does not exist on disk | (nothing) | left to `sources-shape`, not duplicated here |
+
+STALE findings are warnings, so they are advisory by default; run with `--strict` to fail the build on them.
+
+Known limitation: a `git log` call that fails for a reason other than "no history for this path" (for example a corrupt object or a transient git error) is reported the same way as a genuinely untracked path, the `untracked by git, staleness unknown` notice; okf-kit does not currently distinguish a real git failure from "no commits touch this path".
+
+**Authoring guidance:** when you re-verify a doc against its sources, bump its frontmatter `timestamp` (and add a line to the bundle's `log.md`) so `sources-fresh` reflects that the doc is current again.
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | No errors (and, under `--strict`, no warnings either). |
+| 1 | At least one error (or, under `--strict`, at least one warning). |
+| 2 | CLI invocation error: bundle directory does not exist, `init`'s target directory is non-empty without `--force`, or a commander usage error (unknown option, missing argument, missing/unknown command). `--help` and `--version` still exit 0. |
+
+## CI usage
+
+This is advisory: don't fail the build on warnings unless you pass `--strict`. Use a normal (non-shallow) checkout of the repo that owns the bundle: repo-root detection runs `git rev-parse --show-toplevel` from the `path/to/bundle` argument itself, not from the shell's working directory, and `sources-fresh` reads `git log`, so a shallow clone reports paths as untracked.
+
+```yaml
+- name: OKF bundle check
+  run: npx okf-kit@0.3.0 check path/to/bundle
+```
+
+Pin the version: an unpinned `npx okf-kit` picks up new rules on their release day, which turns an unrelated PR red.
+
+## Where this fits
+
+okf-kit is the producer-side check: it validates a bundle you are authoring or maintaining. Consuming an OKF bundle at query time (loading, indexing, ranking passages for an agent) lives in [codebase-oracle](https://github.com/LanNguyenSi/codebase-oracle), a separate tool.
+
+## License
+
+MIT, see [LICENSE](../../LICENSE) at repo root.

package/dist/bundle.d.ts

@@ -0,0 +1,2 @@
+import type { BundleContext, RunGit } from "./types.js";
+export declare function loadBundle(bundleDir: string, repoRoot?: string, runGit?: RunGit): BundleContext;

package/dist/bundle.js

@@ -0,0 +1,69 @@
+import fs from "node:fs";
+import path from "node:path";
+import YAML from "yaml";
+const RESERVED_BASENAMES = new Set(["index.md", "log.md"]);
+export function loadBundle(bundleDir, repoRoot, runGit) {
+    const files = walkMarkdownFiles(bundleDir);
+    const docs = files.map((absPath) => {
+        const relPath = path.relative(bundleDir, absPath).split(path.sep).join("/");
+        const basename = path.basename(absPath);
+        const raw = fs.readFileSync(absPath, "utf8");
+        const { frontmatter, body } = parseFrontmatter(raw);
+        return {
+            relPath,
+            basename,
+            isReserved: RESERVED_BASENAMES.has(basename),
+            raw,
+            frontmatter,
+            body,
+        };
+    });
+    docs.sort((a, b) => a.relPath.localeCompare(b.relPath));
+    return { bundleDir, repoRoot, docs, runGit };
+}
+function walkMarkdownFiles(dir) {
+    const out = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            out.push(...walkMarkdownFiles(full));
+        }
+        else if (entry.isFile() && entry.name.endsWith(".md")) {
+            out.push(full);
+        }
+    }
+    return out;
+}
+/**
+ * A frontmatter block is the first line being exactly `---` up to the next
+ * line that is exactly `---`. Anything else (no opening delimiter, or an
+ * opening delimiter with no matching close) counts as no frontmatter block
+ * at all, per the OKF v0.1 shape rule.
+ */
+function parseFrontmatter(raw) {
+    const lines = raw.split(/\r?\n/);
+    if (lines[0] !== "---") {
+        return { frontmatter: { present: false }, body: raw };
+    }
+    let closingIndex = -1;
+    for (let i = 1; i < lines.length; i++) {
+        if (lines[i] === "---") {
+            closingIndex = i;
+            break;
+        }
+    }
+    if (closingIndex === -1) {
+        return { frontmatter: { present: false }, body: raw };
+    }
+    const yamlText = lines.slice(1, closingIndex).join("\n");
+    const body = lines.slice(closingIndex + 1).join("\n");
+    try {
+        const parsed = YAML.parse(yamlText);
+        return { frontmatter: { present: true, parsed }, body };
+    }
+    catch (err) {
+        const parseError = err instanceof Error ? err.message : String(err);
+        return { frontmatter: { present: true, parseError }, body };
+    }
+}
+//# sourceMappingURL=bundle.js.map

package/dist/bundle.js.map

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

package/dist/cli.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { UsageError } from "./errors.js";
+import type { Finding, RunGit } from "./types.js";
+export { UsageError };
+export interface CheckOptions {
+    repoRoot?: string;
+    strict?: boolean;
+    /** Test-only override for git access; production code shells out to the real `git` binary. */
+    runGit?: RunGit;
+}
+export interface CheckResult {
+    bundleDir: string;
+    findings: Finding[];
+    exitCode: number;
+}
+export declare function runCheck(bundleDir: string, options?: CheckOptions): CheckResult;

package/dist/cli.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { pathToFileURL } from "node:url";
+import { Command, CommanderError } from "commander";
+import { loadBundle } from "./bundle.js";
+import { UsageError } from "./errors.js";
+import { detectRepoRoot } from "./git.js";
+import { formatInitSummary, runInit } from "./init.js";
+import { allRules } from "./rules/index.js";
+import { renderJson, renderText, summarize } from "./report.js";
+export { UsageError };
+export function runCheck(bundleDir, options = {}) {
+    if (!fs.existsSync(bundleDir) || !fs.statSync(bundleDir).isDirectory()) {
+        throw new UsageError(`Bundle directory does not exist: ${bundleDir}`);
+    }
+    const resolvedBundleDir = path.resolve(bundleDir);
+    // When --repo-root is omitted, try to find the enclosing git work tree so
+    // sources-shape's existence check and sources-fresh's staleness check are
+    // active by default for any bundle that lives inside a git repo. A bundle
+    // outside any git work tree falls back to the pre-detection behavior
+    // (existence check skipped; sources-fresh reports one skip notice).
+    const repoRoot = options.repoRoot
+        ? path.resolve(options.repoRoot)
+        : detectRepoRoot(resolvedBundleDir, options.runGit);
+    const ctx = loadBundle(resolvedBundleDir, repoRoot, options.runGit);
+    const findings = allRules.flatMap((rule) => rule.run(ctx));
+    const summary = summarize(findings);
+    const exitCode = summary.errors > 0 || (Boolean(options.strict) && summary.warnings > 0)
+        ? 1
+        : 0;
+    return { bundleDir: resolvedBundleDir, findings, exitCode };
+}
+const program = new Command();
+// Route commander's own usage errors (unknown option, missing argument, no
+// matching command, ...) through a thrown CommanderError instead of an
+// implicit process.exit(1), so they can be told apart from "the bundle has
+// findings" (also 1) below. Must be called before `.command()` so the
+// subcommand inherits it via copyInheritedSettings; also set explicitly on
+// the subcommand for clarity.
+program.exitOverride();
+program
+    .name("okf-kit")
+    .description("Validate OKF v0.1 knowledge bundles")
+    .version(readVersion());
+program
+    .command("check <bundleDir>")
+    .description("Check a knowledge bundle for OKF structural violations")
+    .option("-r, --repo-root <path>", "Repo root to verify frontmatter `sources` paths exist under and assess staleness against " +
+    "(auto-detected via `git rev-parse --show-toplevel` from the bundle dir when omitted)")
+    .option("-j, --json", "Output findings as JSON")
+    .option("-s, --strict", "Also fail (exit 1) when warnings are present")
+    .exitOverride()
+    .action((bundleDir, opts) => {
+    try {
+        const result = runCheck(bundleDir, {
+            repoRoot: opts.repoRoot,
+            strict: opts.strict,
+        });
+        const output = opts.json
+            ? renderJson(result.bundleDir, result.findings)
+            : renderText(result.bundleDir, result.findings);
+        process.stdout.write(output);
+        process.exit(result.exitCode);
+    }
+    catch (err) {
+        if (err instanceof UsageError) {
+            process.stderr.write(`okf-kit: ${err.message}\n`);
+            process.exit(2);
+        }
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`okf-kit: ${msg}\n`);
+        process.exit(2);
+    }
+});
+program
+    .command("init [dir]")
+    .description("Scaffold a starter OKF v0.1 knowledge bundle (default target: docs/okf)")
+    .option("-f, --force", "Overwrite the scaffold files in a non-empty target directory (other existing files are left alone)")
+    .exitOverride()
+    .action((dir, opts) => {
+    try {
+        const result = runInit(dir ?? "docs/okf", { force: opts.force });
+        process.stdout.write(formatInitSummary(result));
+        process.exit(0);
+    }
+    catch (err) {
+        if (err instanceof UsageError) {
+            process.stderr.write(`okf-kit: ${err.message}\n`);
+            process.exit(2);
+        }
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`okf-kit: ${msg}\n`);
+        process.exit(2);
+    }
+});
+// Commander codes for an explicit `-h`/`--help` or `-V`/`--version` flag:
+// keep commander's own exit code (0) for these. Note `commander.help` is
+// deliberately NOT in this set: in this commander version that code only
+// fires for the "subcommands exist, none given, no action handler" path
+// (Command.prototype._parseCommand calling `this.help({ error: true })`),
+// which is itself a usage error and must fall through to exit 2 below, not
+// be passed through as 0 or 1.
+const PASSTHROUGH_EXIT_CODES = new Set([
+    "commander.helpDisplayed",
+    "commander.version",
+]);
+// Only run the CLI (and its process.exit calls) when this file is executed
+// directly (`node dist/cli.js ...`), not when it is merely imported for its
+// exported runCheck/UsageError (as tests do): otherwise importing this
+// module would parse the importer's own process.argv and could exit the
+// importing process.
+const isMainModule = process.argv[1] !== undefined &&
+    import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isMainModule) {
+    program.parseAsync().catch((err) => {
+        if (err instanceof CommanderError) {
+            if (PASSTHROUGH_EXIT_CODES.has(err.code)) {
+                process.exit(err.exitCode);
+            }
+            // Commander already wrote its own error message to stderr before
+            // throwing; a usage error (unknown option, missing argument, missing
+            // command, ...) is exit 2, distinct from exit 1 (bundle has findings).
+            process.exit(2);
+        }
+        process.stderr.write(`okf-kit: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(2);
+    });
+}
+function readVersion() {
+    try {
+        const url = new URL("../package.json", import.meta.url);
+        const text = fs.readFileSync(url, "utf8");
+        const pkg = JSON.parse(text);
+        return pkg.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,OAAO,MAAM,cAAc,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGhE,OAAO,EAAE,UAAU,EAAE,CAAC;AAetB,MAAM,UAAU,QAAQ,CACtB,SAAiB,EACjB,UAAwB,EAAE;IAE1B,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;QACvE,MAAM,IAAI,UAAU,CAAC,oCAAoC,SAAS,EAAE,CAAC,CAAC;IACxE,CAAC;IACD,MAAM,iBAAiB,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAClD,0EAA0E;IAC1E,0EAA0E;IAC1E,0EAA0E;IAC1E,qEAAqE;IACrE,oEAAoE;IACpE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ;QAC/B,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC;QAChC,CAAC,CAAC,cAAc,CAAC,iBAAiB,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACtD,MAAM,GAAG,GAAG,UAAU,CAAC,iBAAiB,EAAE,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAEpE,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3D,MAAM,OAAO,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;IACpC,MAAM,QAAQ,GACZ,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrE,CAAC,CAAC,CAAC;QACH,CAAC,CAAC,CAAC,CAAC;IACR,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;AAC9D,CAAC;AAED,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,2EAA2E;AAC3E,uEAAuE;AACvE,2EAA2E;AAC3E,sEAAsE;AACtE,2EAA2E;AAC3E,8BAA8B;AAC9B,OAAO,CAAC,YAAY,EAAE,CAAC;AAEvB,OAAO;KACJ,IAAI,CAAC,SAAS,CAAC;KACf,WAAW,CAAC,qCAAqC,CAAC;KAClD,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;AAE1B,OAAO;KACJ,OAAO,CAAC,mBAAmB,CAAC;KAC5B,WAAW,CAAC,wDAAwD,CAAC;KACrE,MAAM,CACL,wBAAwB,EACxB,2FAA2F;IACzF,sFAAsF,CACzF;KACA,MAAM,CAAC,YAAY,EAAE,yBAAyB,CAAC;KAC/C,MAAM,CAAC,cAAc,EAAE,8CAA8C,CAAC;KACtE,YAAY,EAAE;KACd,MAAM,CACL,CACE,SAAiB,EACjB,IAA6D,EAC7D,EAAE;IACF,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,QAAQ,CAAC,SAAS,EAAE;YACjC,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,MAAM,EAAE,IAAI,CAAC,MAAM;SACpB,CAAC,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI;YACtB,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,QAAQ,CAAC;YAC/C,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;QAClD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAC7B,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAChC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,UAAU,EAAE,CAAC;YAC9B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,YAAY,GAAG,CAAC,OAAO,IAAI,CAAC,CAAC;YAClD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QACD,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7D,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;QAC1C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC,CACF,CAAC;AAEJ,OAAO;KACJ,OAAO,CAAC,YAAY,CAAC;KACrB,WAAW,CACV,yEAAyE,CAC1E;KACA,MAAM,CACL,aAAa,EACb,oGAAoG,CACrG;KACA,YAAY,EAAE;KACd,MAAM,CAAC,CAAC,GAAuB,EAAE,IAAyB,EAAE,EAAE;IAC7D,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,IAAI,UAAU,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;QACjE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC;QAChD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,UAAU,EAAE,CAAC;YAC9B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,YAAY,GAAG,CAAC,OAAO,IAAI,CAAC,CAAC;YAClD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QACD,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7D,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;QAC1C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC,CAAC,CAAC;AAEL,0EAA0E;AAC1E,yEAAyE;AACzE,yEAAyE;AACzE,wEAAwE;AACxE,0EAA0E;AAC1E,2EAA2E;AAC3E,+BAA+B;AAC/B,MAAM,sBAAsB,GAAG,IAAI,GAAG,CAAC;IACrC,yBAAyB;IACzB,mBAAmB;CACpB,CAAC,CAAC;AAEH,2EAA2E;AAC3E,4EAA4E;AAC5E,uEAAuE;AACvE,wEAAwE;AACxE,qBAAqB;AACrB,MAAM,YAAY,GAChB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,SAAS;IAC7B,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAE1D,IAAI,YAAY,EAAE,CAAC;IACjB,OAAO,CAAC,UAAU,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;QACjC,IAAI,GAAG,YAAY,cAAc,EAAE,CAAC;YAClC,IAAI,sBAAsB,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBACzC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YAC7B,CAAC;YACD,iEAAiE;YACjE,qEAAqE;YACrE,uEAAuE;YACvE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,YAAY,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CACjE,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,WAAW;IAClB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACxD,MAAM,IAAI,GAAG,EAAE,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAC1C,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAyB,CAAC;QACrD,OAAO,GAAG,CAAC,OAAO,IAAI,OAAO,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,OAAO,CAAC;IACjB,CAAC;AACH,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,3 @@
+/** Thrown for CLI usage problems (bad arguments, bad target state); the CLI wiring maps this to exit code 2. */
+export declare class UsageError extends Error {
+}

package/dist/errors.js

@@ -0,0 +1,4 @@
+/** Thrown for CLI usage problems (bad arguments, bad target state); the CLI wiring maps this to exit code 2. */
+export class UsageError extends Error {
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,gHAAgH;AAChH,MAAM,OAAO,UAAW,SAAQ,KAAK;CAAG"}

package/dist/git.d.ts

@@ -0,0 +1,15 @@
+import type { RunGit } from "./types.js";
+/**
+ * Default RunGit implementation: shells out to the real `git` binary.
+ * stderr is discarded (git's own "fatal: not a git repository" etc. text is
+ * an expected, silent signal here, not something to surface), and any
+ * failure (non-zero exit, git missing) resolves to null instead of
+ * throwing.
+ */
+export declare const runGit: RunGit;
+/**
+ * Resolves the git work tree root containing `startDir`, or undefined when
+ * `startDir` is not inside a git work tree (or git is unavailable). Used to
+ * auto-fill --repo-root when the CLI flag is omitted.
+ */
+export declare function detectRepoRoot(startDir: string, git?: RunGit): string | undefined;

package/dist/git.js

@@ -0,0 +1,30 @@
+import { execFileSync } from "node:child_process";
+/**
+ * Default RunGit implementation: shells out to the real `git` binary.
+ * stderr is discarded (git's own "fatal: not a git repository" etc. text is
+ * an expected, silent signal here, not something to surface), and any
+ * failure (non-zero exit, git missing) resolves to null instead of
+ * throwing.
+ */
+export const runGit = (args, cwd) => {
+    try {
+        return execFileSync("git", args, {
+            cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Resolves the git work tree root containing `startDir`, or undefined when
+ * `startDir` is not inside a git work tree (or git is unavailable). Used to
+ * auto-fill --repo-root when the CLI flag is omitted.
+ */
+export function detectRepoRoot(startDir, git = runGit) {
+    const result = git(["rev-parse", "--show-toplevel"], startDir);
+    return result ? result : undefined;
+}
+//# sourceMappingURL=git.js.map

package/dist/git.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.js","sourceRoot":"","sources":["../src/git.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGlD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,MAAM,GAAW,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE;IAC1C,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,KAAK,EAAE,IAAI,EAAE;YAC/B,GAAG;YACH,QAAQ,EAAE,MAAM;YAChB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC;SACpC,CAAC,CAAC,IAAI,EAAE,CAAC;IACZ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAC5B,QAAgB,EAChB,MAAc,MAAM;IAEpB,MAAM,MAAM,GAAG,GAAG,CAAC,CAAC,WAAW,EAAE,iBAAiB,CAAC,EAAE,QAAQ,CAAC,CAAC;IAC/D,OAAO,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;AACrC,CAAC"}

package/dist/init.d.ts

@@ -0,0 +1,11 @@
+export interface InitOptions {
+    force?: boolean;
+    /** Test-only override for "now"; production code uses the real clock. */
+    now?: () => Date;
+}
+export interface InitResult {
+    targetDir: string;
+    filesWritten: string[];
+}
+export declare function runInit(targetDir: string, options?: InitOptions): InitResult;
+export declare function formatInitSummary(result: InitResult): string;

package/dist/init.js

@@ -0,0 +1,63 @@
+import fs from "node:fs";
+import path from "node:path";
+import { UsageError } from "./errors.js";
+import { benchmarkTemplate, indexTemplate, invariantTemplate, logTemplate, moduleTemplate, overviewTemplate, runbookTemplate, } from "./templates.js";
+/** The exact set of filenames `init` owns: with --force, only these are overwritten, nothing else in the directory is touched. */
+const SCAFFOLD_FILENAMES = [
+    "index.md",
+    "log.md",
+    "overview-template.md",
+    "module-template.md",
+    "invariant-template.md",
+    "runbook-template.md",
+    "benchmark-template.md",
+];
+export function runInit(targetDir, options = {}) {
+    const resolvedDir = path.resolve(targetDir);
+    const now = options.now ?? (() => new Date());
+    const timestamp = now().toISOString();
+    if (fs.existsSync(resolvedDir)) {
+        if (!fs.statSync(resolvedDir).isDirectory()) {
+            throw new UsageError(`Target path exists and is not a directory: ${resolvedDir}`);
+        }
+        const isNonEmpty = fs.readdirSync(resolvedDir).length > 0;
+        if (isNonEmpty && !options.force) {
+            throw new UsageError(`Target directory is not empty: ${resolvedDir}. Re-run with --force to overwrite the scaffold ` +
+                "files okf-kit owns (index.md, log.md, and the *-template.md docs); any other existing files " +
+                "are left alone.");
+        }
+    }
+    fs.mkdirSync(resolvedDir, { recursive: true });
+    const contentByFilename = {
+        "index.md": indexTemplate(),
+        "log.md": logTemplate(timestamp),
+        "overview-template.md": overviewTemplate(timestamp),
+        "module-template.md": moduleTemplate(timestamp),
+        "invariant-template.md": invariantTemplate(timestamp),
+        "runbook-template.md": runbookTemplate(timestamp),
+        "benchmark-template.md": benchmarkTemplate(timestamp),
+    };
+    const filesWritten = [];
+    for (const filename of SCAFFOLD_FILENAMES) {
+        fs.writeFileSync(path.join(resolvedDir, filename), contentByFilename[filename]);
+        filesWritten.push(filename);
+    }
+    return { targetDir: resolvedDir, filesWritten };
+}
+export function formatInitSummary(result) {
+    const lines = [
+        `Scaffolded OKF bundle at ${result.targetDir}:`,
+        ...result.filesWritten.map((f) => `  ${f}`),
+        "",
+        "Next steps:",
+        "  - Fill in each *-template.md placeholder and rename it to a real doc name.",
+        "  - Replace the `path/to/covered/source` placeholder in each doc's `sources:` list with the",
+        "    real repo-root-relative path(s) it describes.",
+        "  - Until you do, `okf-kit check` will report those placeholders as missing source paths",
+        "    (`sources-shape` errors) whenever it has a repo root to check against (inside a git repo, or",
+        "    with --repo-root); that is intentional, not a bug, it flags unwritten sources so you don't",
+        "    forget them.",
+    ];
+    return lines.join("\n") + "\n";
+}
+//# sourceMappingURL=init.js.map

package/dist/init.js.map

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

package/dist/links.d.ts

@@ -0,0 +1,15 @@
+export interface LinkRef {
+    /** The link destination after normalization, including any `#anchor`. */
+    target: string;
+    /** `target` with an optional trailing `#anchor` stripped. */
+    pathPart: string;
+}
+/**
+ * Extracts markdown link targets from body text, restricted to the targets
+ * the OKF checks care about: relative or bundle-root-relative `.md` links.
+ * Fenced code blocks are stripped first so example markdown inside a code
+ * fence is never mistaken for a real link. http(s):// and mailto: links and
+ * any target not ending in `.md` (after stripping an optional `#anchor`)
+ * are excluded.
+ */
+export declare function extractMarkdownLinks(body: string): LinkRef[];

package/dist/links.js

@@ -0,0 +1,82 @@
+const LINK_PATTERN = /\[[^\]]*\]\(([^)]+)\)/g;
+/**
+ * Extracts markdown link targets from body text, restricted to the targets
+ * the OKF checks care about: relative or bundle-root-relative `.md` links.
+ * Fenced code blocks are stripped first so example markdown inside a code
+ * fence is never mistaken for a real link. http(s):// and mailto: links and
+ * any target not ending in `.md` (after stripping an optional `#anchor`)
+ * are excluded.
+ */
+export function extractMarkdownLinks(body) {
+    const stripped = stripFencedCode(body);
+    const refs = [];
+    LINK_PATTERN.lastIndex = 0;
+    let match;
+    while ((match = LINK_PATTERN.exec(stripped)) !== null) {
+        const target = normalizeDestination(match[1]);
+        if (target.startsWith("http://") ||
+            target.startsWith("https://") ||
+            target.startsWith("mailto:")) {
+            continue;
+        }
+        const pathPart = target.split("#")[0];
+        if (!pathPart.endsWith(".md"))
+            continue;
+        refs.push({ target, pathPart });
+    }
+    return refs;
+}
+/**
+ * Normalizes a raw CommonMark link destination capture (the text between the
+ * link's parens) down to a bare path:
+ *  - `<x.md>` form: unwrap the angle brackets (the destination can contain
+ *    whitespace inside them; anything after the closing `>` is a title).
+ *  - bare form: a link title, if present, is separated from the destination
+ *    by whitespace and written as "t", 't', or (t); take the first
+ *    whitespace-delimited token as the destination and drop the rest.
+ *  - percent-decode the result (falling back to the raw string if it is not
+ *    valid percent-encoding) so an encoded path compares equal to the real
+ *    filename on disk.
+ */
+function normalizeDestination(raw) {
+    let dest = raw.trim();
+    if (dest.startsWith("<")) {
+        const closeIdx = dest.indexOf(">", 1);
+        dest = closeIdx === -1 ? dest.slice(1) : dest.slice(1, closeIdx);
+    }
+    else {
+        const spaceIdx = dest.search(/\s/);
+        if (spaceIdx !== -1)
+            dest = dest.slice(0, spaceIdx);
+    }
+    try {
+        return decodeURIComponent(dest);
+    }
+    catch {
+        return dest;
+    }
+}
+function stripFencedCode(text) {
+    const lines = text.split(/\r?\n/);
+    const out = [];
+    let fenceMarker;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!fenceMarker &&
+            (trimmed.startsWith("```") || trimmed.startsWith("~~~"))) {
+            fenceMarker = trimmed.slice(0, 3);
+            out.push("");
+            continue;
+        }
+        if (fenceMarker) {
+            if (trimmed.startsWith(fenceMarker)) {
+                fenceMarker = undefined;
+            }
+            out.push("");
+            continue;
+        }
+        out.push(line);
+    }
+    return out.join("\n");
+}
+//# sourceMappingURL=links.js.map

package/dist/links.js.map

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

package/dist/report.d.ts

@@ -0,0 +1,9 @@
+import type { Finding } from "./types.js";
+export interface Summary {
+    errors: number;
+    warnings: number;
+    notices: number;
+}
+export declare function summarize(findings: Finding[]): Summary;
+export declare function renderText(bundleDir: string, findings: Finding[]): string;
+export declare function renderJson(bundleDir: string, findings: Finding[]): string;