@kampus/decisions-index 0.1.0

package/README.md

@@ -0,0 +1,48 @@
+# @kampus/decisions-index
+
+Generate `.decisions/index.md` from the ADR files (ADR
+[0066](../../.decisions/0066-generate-decisions-index.md)).
+
+`.decisions/index.md` is **generated output**, not a hand-maintained file. The
+source of truth is each `.decisions/NNNN-*.md` file's YAML front-matter (`id`,
+`title`, `status`, `date`); the index table is derived from it, ordered ascending
+by `id`. Two doc PRs that add two different ADR files no longer share a textual
+anchor (the tail of the table), so they can't collide on `index.md` — the
+concurrent-merge friction ADR 0066 removes. The same gate folds in the sibling
+problem: a **duplicate ADR `id`** across files fails the check.
+
+## Shape
+
+Per the repo's mechanical-tooling idiom (`leak-guard` / `epic-ledger` /
+`crabbox-manifest`): a pure, unit-tested core + a thin Effect CLI bin.
+
+- `src/decisions-index.ts` — the pure core. `buildIndex(files)` parses every
+  file's front-matter, fails on a duplicate id (`DuplicateIdError`) or a
+  malformed file (`FrontmatterError`), and renders the deterministic table.
+  Status/title render **verbatim** (they may carry inline markdown, e.g. a linked
+  `superseded by [0009](0009-slug.md)`).
+- `src/bin.ts` — the `effect/unstable/cli` bin (`generate` + `check`).
+
+## Usage
+
+```bash
+# Rewrite .decisions/index.md from the ADR files (authors / the /adr skill):
+pnpm --filter @kampus/decisions-index generate
+
+# CI gate — exit 1 on a stale index OR a duplicate ADR id:
+pnpm --filter @kampus/decisions-index check
+
+# Point at a different directory:
+node packages/decisions-index/src/bin.ts check --dir path/to/.decisions
+```
+
+Exit codes: `0` clean, `1` gate failure (stale index or duplicate id; reason on
+stderr), any other non-zero = the run could not complete (e.g. unreadable dir).
+
+CI runs `check` on every PR via
+[`.github/workflows/decisions-index.yml`](../../.github/workflows/decisions-index.yml).
+
+## Do not hand-edit `index.md`
+
+Edit the ADR file's front-matter and regenerate. A hand-appended row is exactly
+the collision this package removes.

package/dist/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":""}

package/dist/bin.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/**
+ * `decisions-index` CLI — the author + CI surface for ADR 0066.
+ *
+ *   node src/bin.ts generate          # rewrite .decisions/index.md from the ADR files
+ *   node src/bin.ts check             # CI gate: exit non-zero on a stale index or a dup id
+ *   node src/bin.ts <mode> --dir <d>  # point at a different .decisions dir (default: ./.decisions)
+ *
+ * `generate` is what the `/adr` skill (and an author) runs instead of hand-editing
+ * the table; `check` is the CI gate that fails on (a) a committed `index.md` that
+ * differs from the generated one (stale) and (b) a duplicate ADR `id` — closing the
+ * number-collision class in the same step (ADR 0066).
+ *
+ * Exit-code contract: 0 = clean (check passed / generate wrote), 1 = the gate
+ * failed (stale index or duplicate id; report on stderr); any OTHER non-zero means
+ * the run could not complete (e.g. the dir is unreadable). Wired per effect-smol's
+ * CLI guidance (mirrors `@kampus/epic-ledger` / `@kampus/leak-guard` /
+ * `changelog-derive`): `effect/unstable/cli`, the Node platform over
+ * `NodeServices.layer`, run via `NodeRuntime.runMain`.
+ */
+import { readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { NodeRuntime, NodeServices } from "@effect/platform-node";
+import { Console, Data, Effect } from "effect";
+import { Command, Flag } from "effect/unstable/cli";
+import { buildIndex, DuplicateIdError } from "./decisions-index.js";
+const INDEX_FILE = "index.md";
+const ADR_FILE = /^\d+[A-Za-z]*-.+\.md$/;
+const GATE_FAIL_EXIT_CODE = 1;
+// A directory/file IO failure that should crash (non-1 exit): the run couldn't complete.
+class IoError extends Data.TaggedError("IoError") {
+}
+// Carries the non-zero gate-fail exit (the report is already on stderr). Distinct from
+// IoError so a stale index / dup id exits 1 while an unreadable dir exits differently.
+class CheckFailed extends Data.TaggedError("CheckFailed") {
+}
+/** Read every ADR file (NNNN[a]-slug.md) in `dir`, excluding the generated index. */
+const readAdrFiles = (dir) => Effect.try({
+    try: () => readdirSync(dir)
+        .filter((f) => f !== INDEX_FILE && ADR_FILE.test(f))
+        .sort()
+        .map((file) => ({ file, text: readFileSync(join(dir, file), "utf8") })),
+    catch: (cause) => new IoError({ path: dir, cause }),
+});
+/** Build the index, folding a duplicate id into a CheckFailed gate failure. */
+const build = (files) => Effect.try({
+    try: () => buildIndex(files),
+    catch: (cause) => cause instanceof DuplicateIdError
+        ? new CheckFailed({ reason: cause.message })
+        : new CheckFailed({ reason: String(cause?.message ?? cause) }),
+});
+const dirFlag = Flag.string("dir").pipe(Flag.withDefault(".decisions"), Flag.withDescription("the .decisions directory to read ADR files from (default: .decisions)"));
+const generate = Command.make("generate", { dir: dirFlag }, Effect.fn(function* ({ dir }) {
+    const markdown = yield* readAdrFiles(dir).pipe(Effect.flatMap(build));
+    const target = join(dir, INDEX_FILE);
+    yield* Effect.try({
+        try: () => writeFileSync(target, markdown),
+        catch: (cause) => new IoError({ path: target, cause }),
+    });
+    yield* Console.log(`decisions-index: wrote ${target}`);
+})).pipe(Command.withDescription("Regenerate .decisions/index.md from the ADR files"));
+const check = Command.make("check", { dir: dirFlag }, Effect.fn(function* ({ dir }) {
+    const expected = yield* readAdrFiles(dir).pipe(Effect.flatMap(build));
+    const target = join(dir, INDEX_FILE);
+    const committed = yield* Effect.try({
+        try: () => readFileSync(target, "utf8"),
+        catch: () => "",
+    }).pipe(Effect.orElseSucceed(() => ""));
+    if (committed === expected) {
+        yield* Console.log("decisions-index: index.md is up to date");
+        return;
+    }
+    return yield* Effect.fail(new CheckFailed({
+        reason: `${target} is stale — it does not match the generated index.\n` +
+            "Run `pnpm --filter @kampus/decisions-index generate` and commit the result\n" +
+            "(edit the ADR file's front-matter, never index.md by hand — ADR 0066).",
+    }));
+})).pipe(Command.withDescription("Verify the committed index.md is fresh and has no duplicate ADR id"));
+const cli = Command.make("decisions-index").pipe(Command.withSubcommands([generate, check]), Command.withDescription("Generate .decisions/index.md from the ADR files (ADR 0066)"));
+cli.pipe(Command.run({ version: "0.1.0" }), 
+// CheckFailed is the expected gate-fail signal — print its reason on stderr and exit
+// non-zero WITHOUT a stack trace; genuine crashes (IoError, etc.) still get the
+// default error report (a different non-zero exit, per the exit-code contract).
+Effect.catchTag("CheckFailed", (e) => Effect.sync(() => {
+    process.stderr.write(`decisions-index: ${e.reason}\n`);
+    process.exit(GATE_FAIL_EXIT_CODE);
+})), Effect.provide(NodeServices.layer), NodeRuntime.runMain);
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

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

package/dist/decisions-index.d.ts

@@ -0,0 +1,78 @@
+/**
+ * `@kampus/decisions-index` core — the pure, IO-free derivation of
+ * `.decisions/index.md` from the ADR files (ADR 0066).
+ *
+ * The single source of truth is each `.decisions/NNNN-*.md` file's YAML
+ * front-matter (`id`, `title`, `status`, `date`); the index table is *derived*
+ * output, deterministically ordered by `id` ascending. Two doc PRs that add two
+ * different ADR files no longer share a textual anchor (the tail of the table),
+ * so they cannot collide on `index.md` — the friction ADR 0066 removes.
+ *
+ * `buildIndex` folds the sibling problem in: a **duplicate `id`** across files is
+ * a `DuplicateIdError`, so the same gate that catches a stale index catches two
+ * PRs racing the same ADR number.
+ *
+ * Two non-obvious points, both load-bearing and pinned by the unit tests:
+ *  - `title`/`status` render **verbatim** from front-matter — they may carry
+ *    inline markdown (a linked `superseded by [0009](…)`), so the front-matter is
+ *    the curated display text, not just a bare keyword. Make the file right; the
+ *    table mirrors it.
+ *  - ordering is numeric-then-suffix so a lettered id like `0034a` sorts between
+ *    `0034` and `0035` (a plain string sort would too here, but the explicit
+ *    numeric compare keeps it correct if ids ever stop being zero-padded).
+ */
+export interface AdrEntry {
+    /** The ADR id from front-matter, e.g. `0034` or `0034a`. */
+    readonly id: string;
+    /** Display title, rendered verbatim (may contain inline markdown). */
+    readonly title: string;
+    /** Display status, rendered verbatim (may contain inline markdown links). */
+    readonly status: string;
+    /** ISO date string, rendered verbatim. */
+    readonly date: string;
+    /** The file the index row links to, e.g. `0034-fate-native-sse-protocol.md`. */
+    readonly file: string;
+}
+/** A `.decisions/` file handed to the core: its base name + full text. */
+export interface AdrFile {
+    /** Base name only, e.g. `0034-fate-native-sse-protocol.md` (no directory). */
+    readonly file: string;
+    /** The file's full UTF-8 contents. */
+    readonly text: string;
+}
+export declare class DuplicateIdError extends Error {
+    readonly id: string;
+    readonly files: ReadonlyArray<string>;
+    constructor(id: string, files: ReadonlyArray<string>);
+}
+export declare class FrontmatterError extends Error {
+    readonly file: string;
+    constructor(file: string, reason: string);
+}
+declare const FRONTMATTER_FIELDS: readonly ["id", "title", "status", "date"];
+/**
+ * Parse the four index-relevant fields out of a `---`-delimited YAML block.
+ * Only the top-level `id`/`title`/`status`/`date` scalars are read; everything
+ * else (tags, body) is ignored. Returns the fields present; the caller validates.
+ */
+export declare const parseFrontmatter: (text: string) => Partial<Record<(typeof FRONTMATTER_FIELDS)[number], string>>;
+/** Parse one ADR file into an entry, or throw `FrontmatterError` if a field is missing. */
+export declare const parseAdrFile: ({ file, text }: AdrFile) => AdrEntry;
+/** Entries sorted ascending by id (numeric part, then letter suffix). */
+export declare const sortEntries: (entries: ReadonlyArray<AdrEntry>) => ReadonlyArray<AdrEntry>;
+/** First duplicated id across the entries (lowest by sort order), or null if all unique. */
+export declare const findDuplicateId: (entries: ReadonlyArray<AdrEntry>) => DuplicateIdError | null;
+/**
+ * Render the canonical `.decisions/index.md` from sorted entries. The preamble +
+ * table header are fixed; rows are one per ADR. The trailing newline matches a
+ * POSIX text file (the committed index ends in a single `\n`).
+ */
+export declare const renderIndex: (entries: ReadonlyArray<AdrEntry>) => string;
+/**
+ * Build the index markdown from the raw `.decisions/` files. Parses every file,
+ * fails on a duplicate id (`DuplicateIdError`) or a malformed file
+ * (`FrontmatterError`), and otherwise returns the deterministically-ordered table.
+ */
+export declare const buildIndex: (files: ReadonlyArray<AdrFile>) => string;
+export {};
+//# sourceMappingURL=decisions-index.d.ts.map

package/dist/decisions-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decisions-index.d.ts","sourceRoot":"","sources":["../src/decisions-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,WAAW,QAAQ;IACxB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAED,0EAA0E;AAC1E,MAAM,WAAW,OAAO;IACvB,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,gBAAiB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;gBAC1B,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC;CAMpD;AAED,qBAAa,gBAAiB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBACV,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAKxC;AAED,QAAA,MAAM,kBAAkB,4CAA6C,CAAC;AAuBtE;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAC5B,MAAM,MAAM,KACV,OAAO,CAAC,MAAM,CAAC,CAAC,OAAO,kBAAkB,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,CAc7D,CAAC;AAEF,2FAA2F;AAC3F,eAAO,MAAM,YAAY,GAAI,gBAAc,OAAO,KAAG,QAcpD,CAAC;AASF,yEAAyE;AACzE,eAAO,MAAM,WAAW,GAAI,SAAS,aAAa,CAAC,QAAQ,CAAC,KAAG,aAAa,CAAC,QAAQ,CAMlF,CAAC;AAEJ,4FAA4F;AAC5F,eAAO,MAAM,eAAe,GAAI,SAAS,aAAa,CAAC,QAAQ,CAAC,KAAG,gBAAgB,GAAG,IAgBrF,CAAC;AAKF;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,SAAS,aAAa,CAAC,QAAQ,CAAC,KAAG,MAY9D,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,UAAU,GAAI,OAAO,aAAa,CAAC,OAAO,CAAC,KAAG,MAK1D,CAAC"}

package/dist/decisions-index.js

@@ -0,0 +1,166 @@
+/**
+ * `@kampus/decisions-index` core — the pure, IO-free derivation of
+ * `.decisions/index.md` from the ADR files (ADR 0066).
+ *
+ * The single source of truth is each `.decisions/NNNN-*.md` file's YAML
+ * front-matter (`id`, `title`, `status`, `date`); the index table is *derived*
+ * output, deterministically ordered by `id` ascending. Two doc PRs that add two
+ * different ADR files no longer share a textual anchor (the tail of the table),
+ * so they cannot collide on `index.md` — the friction ADR 0066 removes.
+ *
+ * `buildIndex` folds the sibling problem in: a **duplicate `id`** across files is
+ * a `DuplicateIdError`, so the same gate that catches a stale index catches two
+ * PRs racing the same ADR number.
+ *
+ * Two non-obvious points, both load-bearing and pinned by the unit tests:
+ *  - `title`/`status` render **verbatim** from front-matter — they may carry
+ *    inline markdown (a linked `superseded by [0009](…)`), so the front-matter is
+ *    the curated display text, not just a bare keyword. Make the file right; the
+ *    table mirrors it.
+ *  - ordering is numeric-then-suffix so a lettered id like `0034a` sorts between
+ *    `0034` and `0035` (a plain string sort would too here, but the explicit
+ *    numeric compare keeps it correct if ids ever stop being zero-padded).
+ */
+export class DuplicateIdError extends Error {
+    id;
+    files;
+    constructor(id, files) {
+        super(`duplicate ADR id ${id} in: ${files.join(", ")}`);
+        this.name = "DuplicateIdError";
+        this.id = id;
+        this.files = files;
+    }
+}
+export class FrontmatterError extends Error {
+    file;
+    constructor(file, reason) {
+        super(`${file}: ${reason}`);
+        this.name = "FrontmatterError";
+        this.file = file;
+    }
+}
+const FRONTMATTER_FIELDS = ["id", "title", "status", "date"];
+/**
+ * Strip one layer of surrounding quotes from a YAML scalar. A double-quoted value
+ * also has its `\"` / `\\` escapes resolved (YAML double-quote semantics), so a
+ * title quoted to protect an inner `"by path"` round-trips back to the literal text.
+ * A single-quoted value is taken verbatim (we never emit `''` escapes).
+ */
+const unquote = (value) => {
+    const v = value.trim();
+    if (v.length >= 2) {
+        const first = v[0];
+        const last = v[v.length - 1];
+        if (first === '"' && last === '"') {
+            return v.slice(1, -1).replace(/\\(["\\])/g, "$1");
+        }
+        if (first === "'" && last === "'") {
+            return v.slice(1, -1);
+        }
+    }
+    return v;
+};
+/**
+ * Parse the four index-relevant fields out of a `---`-delimited YAML block.
+ * Only the top-level `id`/`title`/`status`/`date` scalars are read; everything
+ * else (tags, body) is ignored. Returns the fields present; the caller validates.
+ */
+export const parseFrontmatter = (text) => {
+    const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!match || match[1] === undefined)
+        return {};
+    const block = match[1];
+    const out = {};
+    for (const line of block.split(/\r?\n/)) {
+        const kv = line.match(/^([A-Za-z][A-Za-z0-9_-]*):\s?(.*)$/);
+        if (!kv || kv[1] === undefined || kv[2] === undefined)
+            continue;
+        const key = kv[1];
+        if (FRONTMATTER_FIELDS.includes(key)) {
+            out[key] = unquote(kv[2]);
+        }
+    }
+    return out;
+};
+/** Parse one ADR file into an entry, or throw `FrontmatterError` if a field is missing. */
+export const parseAdrFile = ({ file, text }) => {
+    const fm = parseFrontmatter(text);
+    for (const field of FRONTMATTER_FIELDS) {
+        if (fm[field] === undefined || fm[field] === "") {
+            throw new FrontmatterError(file, `missing front-matter field \`${field}\``);
+        }
+    }
+    return {
+        id: fm.id,
+        title: fm.title,
+        status: fm.status,
+        date: fm.date,
+        file,
+    };
+};
+/** Split an id into [numeric, letterSuffix] for ordering, e.g. `0034a` → [34, "a"]. */
+const idSortKey = (id) => {
+    const m = id.match(/^(\d+)([A-Za-z]*)$/);
+    if (!m || m[1] === undefined)
+        return [Number.POSITIVE_INFINITY, id];
+    return [Number.parseInt(m[1], 10), m[2] ?? ""];
+};
+/** Entries sorted ascending by id (numeric part, then letter suffix). */
+export const sortEntries = (entries) => [...entries].sort((a, b) => {
+    const [an, as] = idSortKey(a.id);
+    const [bn, bs] = idSortKey(b.id);
+    if (an !== bn)
+        return an - bn;
+    return as < bs ? -1 : as > bs ? 1 : 0;
+});
+/** First duplicated id across the entries (lowest by sort order), or null if all unique. */
+export const findDuplicateId = (entries) => {
+    const byId = new Map();
+    for (const e of entries) {
+        const files = byId.get(e.id) ?? [];
+        files.push(e.file);
+        byId.set(e.id, files);
+    }
+    const dups = [...byId.entries()].filter(([, files]) => files.length > 1);
+    if (dups.length === 0)
+        return null;
+    dups.sort((a, b) => {
+        const [an] = idSortKey(a[0]);
+        const [bn] = idSortKey(b[0]);
+        return an - bn;
+    });
+    const [id, files] = dups[0];
+    return new DuplicateIdError(id, files);
+};
+const renderRow = (e) => `| [${e.id}](${e.file}) | ${e.title} | ${e.status} | ${e.date} |`;
+/**
+ * Render the canonical `.decisions/index.md` from sorted entries. The preamble +
+ * table header are fixed; rows are one per ADR. The trailing newline matches a
+ * POSIX text file (the committed index ends in a single `\n`).
+ */
+export const renderIndex = (entries) => {
+    const sorted = sortEntries(entries);
+    const lines = [
+        "# Decisions",
+        "",
+        "One row per ADR. Read the file for the why.",
+        "",
+        "| # | Title | Status | Date |",
+        "|---|-------|--------|------|",
+        ...sorted.map(renderRow),
+    ];
+    return `${lines.join("\n")}\n`;
+};
+/**
+ * Build the index markdown from the raw `.decisions/` files. Parses every file,
+ * fails on a duplicate id (`DuplicateIdError`) or a malformed file
+ * (`FrontmatterError`), and otherwise returns the deterministically-ordered table.
+ */
+export const buildIndex = (files) => {
+    const entries = files.map(parseAdrFile);
+    const dup = findDuplicateId(entries);
+    if (dup)
+        throw dup;
+    return renderIndex(entries);
+};
+//# sourceMappingURL=decisions-index.js.map

package/dist/decisions-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decisions-index.js","sourceRoot":"","sources":["../src/decisions-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAuBH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IACjC,EAAE,CAAS;IACX,KAAK,CAAwB;IACtC,YAAY,EAAU,EAAE,KAA4B;QACnD,KAAK,CAAC,oBAAoB,EAAE,QAAQ,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACxD,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACpB,CAAC;CACD;AAED,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IACjC,IAAI,CAAS;IACtB,YAAY,IAAY,EAAE,MAAc;QACvC,KAAK,CAAC,GAAG,IAAI,KAAK,MAAM,EAAE,CAAC,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IAClB,CAAC;CACD;AAED,MAAM,kBAAkB,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAU,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,OAAO,GAAG,CAAC,KAAa,EAAU,EAAE;IACzC,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IACvB,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;QACnB,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACnB,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAC7B,IAAI,KAAK,KAAK,GAAG,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;YACnC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;QACnD,CAAC;QACD,IAAI,KAAK,KAAK,GAAG,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;YACnC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QACvB,CAAC;IACF,CAAC;IACD,OAAO,CAAC,CAAC;AACV,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAC/B,IAAY,EACmD,EAAE;IACjE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC;IACxD,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IAChD,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACvB,MAAM,GAAG,GAAiE,EAAE,CAAC;IAC7E,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QACzC,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,oCAAoC,CAAC,CAAC;QAC5D,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,SAAS,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,SAAS;YAAE,SAAS;QAChE,MAAM,GAAG,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;QAClB,IAAK,kBAA4C,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACjE,GAAG,CAAC,GAA0C,CAAC,GAAG,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QAClE,CAAC;IACF,CAAC;IACD,OAAO,GAAG,CAAC;AACZ,CAAC,CAAC;AAEF,2FAA2F;AAC3F,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,EAAC,IAAI,EAAE,IAAI,EAAU,EAAY,EAAE;IAC/D,MAAM,EAAE,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAClC,KAAK,MAAM,KAAK,IAAI,kBAAkB,EAAE,CAAC;QACxC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,SAAS,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;YACjD,MAAM,IAAI,gBAAgB,CAAC,IAAI,EAAE,gCAAgC,KAAK,IAAI,CAAC,CAAC;QAC7E,CAAC;IACF,CAAC;IACD,OAAO;QACN,EAAE,EAAE,EAAE,CAAC,EAAY;QACnB,KAAK,EAAE,EAAE,CAAC,KAAe;QACzB,MAAM,EAAE,EAAE,CAAC,MAAgB;QAC3B,IAAI,EAAE,EAAE,CAAC,IAAc;QACvB,IAAI;KACJ,CAAC;AACH,CAAC,CAAC;AAEF,uFAAuF;AACvF,MAAM,SAAS,GAAG,CAAC,EAAU,EAAoB,EAAE;IAClD,MAAM,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC;IACzC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,SAAS;QAAE,OAAO,CAAC,MAAM,CAAC,iBAAiB,EAAE,EAAE,CAAC,CAAC;IACpE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;AAChD,CAAC,CAAC;AAEF,yEAAyE;AACzE,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,OAAgC,EAA2B,EAAE,CACxF,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;IAC1B,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACjC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,EAAE,GAAG,EAAE,CAAC;IAC9B,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACvC,CAAC,CAAC,CAAC;AAEJ,4FAA4F;AAC5F,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,OAAgC,EAA2B,EAAE;IAC5F,MAAM,IAAI,GAAG,IAAI,GAAG,EAAoB,CAAC;IACzC,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC;QACnC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACnB,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IACvB,CAAC;IACD,MAAM,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACzE,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QAClB,MAAM,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7B,MAAM,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7B,OAAO,EAAE,GAAG,EAAE,CAAC;IAChB,CAAC,CAAC,CAAC;IACH,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC,CAAuB,CAAC;IAClD,OAAO,IAAI,gBAAgB,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;AACxC,CAAC,CAAC;AAEF,MAAM,SAAS,GAAG,CAAC,CAAW,EAAU,EAAE,CACzC,MAAM,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,MAAM,MAAM,CAAC,CAAC,IAAI,IAAI,CAAC;AAEnE;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,OAAgC,EAAU,EAAE;IACvE,MAAM,MAAM,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;IACpC,MAAM,KAAK,GAAG;QACb,aAAa;QACb,EAAE;QACF,6CAA6C;QAC7C,EAAE;QACF,+BAA+B;QAC/B,+BAA+B;QAC/B,GAAG,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC;KACxB,CAAC;IACF,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;AAChC,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,KAA6B,EAAU,EAAE;IACnE,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IACxC,MAAM,GAAG,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IACrC,IAAI,GAAG;QAAE,MAAM,GAAG,CAAC;IACnB,OAAO,WAAW,CAAC,OAAO,CAAC,CAAC;AAC7B,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `@kampus/decisions-index` — derive `.decisions/index.md` from the ADR files
+ * (ADR 0066). The core (`buildIndex` + its parse/sort/dup helpers) is a pure,
+ * IO-free derivation; `bin.ts` wires it to the filesystem as an Effect CLI with
+ * `generate` (write the index) and `check` (CI gate: fail on a stale index or a
+ * duplicate ADR id) modes.
+ */
+export { type AdrEntry, type AdrFile, buildIndex, DuplicateIdError, FrontmatterError, findDuplicateId, parseAdrFile, parseFrontmatter, renderIndex, sortEntries, } from "./decisions-index.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACN,KAAK,QAAQ,EACb,KAAK,OAAO,EACZ,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACX,WAAW,GACX,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * `@kampus/decisions-index` — derive `.decisions/index.md` from the ADR files
+ * (ADR 0066). The core (`buildIndex` + its parse/sort/dup helpers) is a pure,
+ * IO-free derivation; `bin.ts` wires it to the filesystem as an Effect CLI with
+ * `generate` (write the index) and `check` (CI gate: fail on a stale index or a
+ * duplicate ADR id) modes.
+ */
+export { buildIndex, DuplicateIdError, FrontmatterError, findDuplicateId, parseAdrFile, parseFrontmatter, renderIndex, sortEntries, } from "./decisions-index.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAGN,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACX,WAAW,GACX,MAAM,sBAAsB,CAAC"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@kampus/decisions-index",
+  "version": "0.1.0",
+  "description": "decisions-index — generate .decisions/index.md from the ADR files; CI --check fails on a stale index or a duplicate ADR id (ADR 0066)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kamp-us/phoenix.git",
+    "directory": "packages/decisions-index"
+  },
+  "type": "module",
+  "bin": {
+    "decisions-index": "./dist/bin.js"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@effect/platform-node": "4.0.0-beta.78",
+    "effect": "4.0.0-beta.78"
+  },
+  "devDependencies": {
+    "@effect/tsgo": "^0.5.2",
+    "@effect/vitest": "4.0.0-beta.78",
+    "@types/node": "^25.6.2",
+    "@typescript/native-preview": "^7.0.0-dev.20260509.2",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
+  },
+  "volta": {
+    "node": "26.2.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsgo -p tsconfig.json",
+    "test": "vitest run",
+    "generate": "node src/bin.ts generate",
+    "check": "node src/bin.ts check"
+  }
+}