@ybotok/loam 0.1.0-beta.3 → 0.2.0-alpha.2

package/dist/commands/list/campaign/owners.js

@@ -0,0 +1,65 @@
+/**
+ * The `--owners` join behind `loam list`: read the user-named CODEOWNERS
+ * file, bucket the CURRENT listing's rows under the teams it names, and
+ * refuse — `owners-unreadable` — when the file cannot be read or a line in
+ * it cannot be parsed as `pattern owner…`. The parse and the matching are
+ * `core/owners/codeowners.ts`'s (pure; its header records the implemented
+ * subset and the skip-don't-guess rule); this module owns the filesystem
+ * read and the refusal, because core never prints.
+ *
+ * The join runs over the rows the listing is about to show, in the order it
+ * will show them — after `--subsystem`/`--needs-work` filtering and any
+ * `--review-order` ranking — so each team's array IS that team's campaign
+ * worklist, not a second, differently-ordered opinion of the fleet.
+ */
+import { readFile } from "node:fs/promises";
+import { fail } from "../../../core/envelope/json.js";
+import { ownersFor, parseCodeowners } from "../../../core/owners/codeowners.js";
+/**
+ * Read, parse and join, or report the refusal and return null. An empty or
+ * all-skipped file is NOT a refusal: every row lands in `unowned`, honestly —
+ * the file said nothing, and saying so is the answer.
+ */
+export async function ownersJoin(req) {
+    let content;
+    try {
+        content = await readFile(req.path, "utf8");
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        fail(req.json, "owners-unreadable", `Cannot read the CODEOWNERS file at ${req.path}: ${detail}. Nothing was joined; re-run with the path of the file the forge actually uses.`);
+        return null;
+    }
+    const parsed = parseCodeowners(content);
+    if (!parsed.ok) {
+        fail(req.json, "owners-unreadable", `${req.path}:${parsed.line}: ${parsed.problem}. A rule loam cannot read is never guessed at or silently skipped — fix the line, then re-run.`);
+        return null;
+    }
+    const byOwner = new Map();
+    const unowned = [];
+    for (const row of req.rows) {
+        const owners = ownersFor(row.repoDir.split("/"), parsed.rules);
+        if (owners.length === 0) {
+            unowned.push(row);
+            continue;
+        }
+        // A rule may name several owners; the service files under EACH — a shared
+        // directory is two teams' work, not half of either's. The Set: a rule
+        // repeating one owner (`@a @a`) must not list the service twice.
+        for (const owner of new Set(owners)) {
+            byOwner.set(owner, [...(byOwner.get(owner) ?? []), row]);
+        }
+    }
+    return {
+        path: req.path,
+        // Plain lexicographic on the owner string: deterministic across machines,
+        // and owner handles are not ids, so compareIds' numeric tokenizing has
+        // nothing to add.
+        teams: [...byOwner.entries()]
+            .sort(([a], [b]) => (a < b ? -1 : 1))
+            .map(([owner, services]) => ({ owner, services })),
+        unowned,
+        skipped: parsed.skipped,
+    };
+}
+//# sourceMappingURL=owners.js.map

package/dist/commands/list/campaign/owners.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"owners.js","sourceRoot":"","sources":["../../../../src/commands/list/campaign/owners.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,gCAAgC,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,eAAe,EAAoB,MAAM,oCAAoC,CAAC;AA4BlG;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,GAIhC;IACC,IAAI,OAAe,CAAC;IACpB,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC7C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAChE,IAAI,CACF,GAAG,CAAC,IAAI,EACR,mBAAmB,EACnB,sCAAsC,GAAG,CAAC,IAAI,KAAK,MAAM,iFAAiF,CAC3I,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IACxC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,IAAI,CACF,GAAG,CAAC,IAAI,EACR,mBAAmB,EACnB,GAAG,GAAG,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM,CAAC,OAAO,gGAAgG,CAC9I,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,GAAG,EAAsB,CAAC;IAC9C,MAAM,OAAO,GAAe,EAAE,CAAC;IAC/B,KAAK,MAAM,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;QAC/D,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAClB,SAAS;QACX,CAAC;QACD,0EAA0E;QAC1E,sEAAsE;QACtE,iEAAiE;QACjE,KAAK,MAAM,KAAK,IAAI,IAAI,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YACpC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC;IACD,OAAO;QACL,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,0EAA0E;QAC1E,uEAAuE;QACvE,kBAAkB;QAClB,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;aAC1B,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;aACpC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;QACpD,OAAO;QACP,OAAO,EAAE,MAAM,CAAC,OAAO;KACxB,CAAC;AACJ,CAAC","sourcesContent":["/**\n * The `--owners` join behind `loam list`: read the user-named CODEOWNERS\n * file, bucket the CURRENT listing's rows under the teams it names, and\n * refuse — `owners-unreadable` — when the file cannot be read or a line in\n * it cannot be parsed as `pattern owner…`. The parse and the matching are\n * `core/owners/codeowners.ts`'s (pure; its header records the implemented\n * subset and the skip-don't-guess rule); this module owns the filesystem\n * read and the refusal, because core never prints.\n *\n * The join runs over the rows the listing is about to show, in the order it\n * will show them — after `--subsystem`/`--needs-work` filtering and any\n * `--review-order` ranking — so each team's array IS that team's campaign\n * worklist, not a second, differently-ordered opinion of the fleet.\n */\nimport { readFile } from \"node:fs/promises\";\nimport { fail } from \"../../../core/envelope/json.js\";\nimport { ownersFor, parseCodeowners, type SkippedRule } from \"../../../core/owners/codeowners.js\";\n\n/** One row of the listing, reduced to what the join reads. */\nexport interface OwnedRow {\n  readonly id: string;\n  /** The service's docs-repo-relative directory, forward slashes (`repoPath`). */\n  readonly repoDir: string;\n}\n\nexport interface OwnersJoin {\n  /** The path exactly as the user named it — the file is theirs, not loam's. */\n  readonly path: string;\n  /**\n   * One bucket per owning team, sorted by owner; rows in row order. The full\n   * row, not the id: leaf ids can collide across a broken tree, and the\n   * renderers join back to their views by `repoDir` — the row's identity.\n   */\n  readonly teams: { readonly owner: string; readonly services: readonly OwnedRow[] }[];\n  /**\n   * Rows no rule matched, or whose LAST matching rule named no owner —\n   * GitHub's ownership-clearing form. Listed explicitly, because a service\n   * silently absent from every team's queue reads as somebody else's work.\n   */\n  readonly unowned: readonly OwnedRow[];\n  /** Recognised rules outside the implemented subset — reported, never guessed. */\n  readonly skipped: readonly SkippedRule[];\n}\n\n/**\n * Read, parse and join, or report the refusal and return null. An empty or\n * all-skipped file is NOT a refusal: every row lands in `unowned`, honestly —\n * the file said nothing, and saying so is the answer.\n */\nexport async function ownersJoin(req: {\n  path: string;\n  rows: readonly OwnedRow[];\n  json: boolean;\n}): Promise<OwnersJoin | null> {\n  let content: string;\n  try {\n    content = await readFile(req.path, \"utf8\");\n  } catch (err) {\n    const detail = err instanceof Error ? err.message : String(err);\n    fail(\n      req.json,\n      \"owners-unreadable\",\n      `Cannot read the CODEOWNERS file at ${req.path}: ${detail}. Nothing was joined; re-run with the path of the file the forge actually uses.`,\n    );\n    return null;\n  }\n  const parsed = parseCodeowners(content);\n  if (!parsed.ok) {\n    fail(\n      req.json,\n      \"owners-unreadable\",\n      `${req.path}:${parsed.line}: ${parsed.problem}. A rule loam cannot read is never guessed at or silently skipped — fix the line, then re-run.`,\n    );\n    return null;\n  }\n  const byOwner = new Map<string, OwnedRow[]>();\n  const unowned: OwnedRow[] = [];\n  for (const row of req.rows) {\n    const owners = ownersFor(row.repoDir.split(\"/\"), parsed.rules);\n    if (owners.length === 0) {\n      unowned.push(row);\n      continue;\n    }\n    // A rule may name several owners; the service files under EACH — a shared\n    // directory is two teams' work, not half of either's. The Set: a rule\n    // repeating one owner (`@a @a`) must not list the service twice.\n    for (const owner of new Set(owners)) {\n      byOwner.set(owner, [...(byOwner.get(owner) ?? []), row]);\n    }\n  }\n  return {\n    path: req.path,\n    // Plain lexicographic on the owner string: deterministic across machines,\n    // and owner handles are not ids, so compareIds' numeric tokenizing has\n    // nothing to add.\n    teams: [...byOwner.entries()]\n      .sort(([a], [b]) => (a < b ? -1 : 1))\n      .map(([owner, services]) => ({ owner, services })),\n    unowned,\n    skipped: parsed.skipped,\n  };\n}\n"]}

package/dist/commands/list/json.js

@@ -0,0 +1,157 @@
+/**
+ * The `--json` rows. Separate from `./print.ts` because only this side is a
+ * contract: the payload keys are frozen, the columns beside them are not.
+ */
+import { repoPath } from "../../core/envelope/json.js";
+import {} from "../../core/capabilities/rollup.js";
+import {} from "../../core/repo/entries.js";
+import { servicesUnder } from "../../core/repo/tree/find.js";
+import {} from "./views.js";
+/**
+ * The `services[]` rows: ranked and decorated under `--review-order`, plain
+ * otherwise — as a VARIANT, so a call carrying both a plain list and a ranked
+ * queue is unrepresentable rather than resolved by precedence. `fanIn`/
+ * `reviewRank` are ADDITIVE and appear ONLY under the flag — bare
+ * `loam list --json` and `--needs-work --json` stay byte-identical and
+ * cost-identical, the frozen-default doctrine the explicit-only capabilities
+ * section also follows. The spread keeps serviceJson at its two-param
+ * contract; `reviewRank` is 1-based and equals the row's position, so the
+ * array order IS the queue.
+ */
+export function serviceRows(docsDir, rows) {
+    if (Array.isArray(rows))
+        return rows.map((v) => serviceJson(docsDir, v));
+    return rows.queue.map((v, i) => ({
+        ...serviceJson(docsDir, v),
+        fanIn: rows.fanIn.get(v.entry.id) ?? 0,
+        reviewRank: i + 1,
+    }));
+}
+export function serviceJson(docsDir, v) {
+    const s = v.entry;
+    return {
+        id: s.id,
+        path: repoPath(docsDir, s.dir),
+        // Names from services/ down, outermost first; [] = unfiled. `path` above
+        // already truthfully reflects placement — this is the same fact as data
+        // instead of a string to split.
+        subsystem: s.subsystem,
+        has: { ...s.has, archSpec: v.archSpec },
+        adrs: s.adrs,
+        status: s.status,
+        maturity: v.maturity,
+        missing: v.missing,
+        apiExpected: v.apiExpected,
+        // Never omitted when true: a consumer that filters this table into a
+        // worklist has to be able to tell "checked and fine" from "not checkable
+        // from here", and absence reads as the first one.
+        ...(v.unverifiableFromHere ? { provenance: "unverifiable-from-here" } : {}),
+        // Additive, and only when there IS a scope — omission is the fine case
+        // here, exactly as it is for `provenance` above, and `maturity` stays the
+        // frozen `vouched` beside it. A dashboard counting `maturity: "vouched"`
+        // rows keeps counting them; one that cares whether a person read the
+        // document subtracts these.
+        ...(s.vouchScope === "sampled" ? { vouchScope: "sampled" } : {}),
+    };
+}
+/**
+ * The subsystem rows beside the service table, sorted by path. `memberCount`
+ * is TRANSITIVE — every service beneath, at any depth — matching the
+ * generated views file's membership, so the two numbers a consumer can
+ * cross-check never disagree about what "in this group" means.
+ */
+export function subsystemsJson(docsDir, tree) {
+    return [...tree.subsystems]
+        .sort((a, b) => (a.path.join("/") < b.path.join("/") ? -1 : 1))
+        .map((sub) => ({
+        name: sub.name,
+        path: repoPath(docsDir, sub.dir),
+        title: sub.meta.title ?? null,
+        memberCount: servicesUnder(tree, sub).length,
+    }));
+}
+/**
+ * The additive `owners` payload key under `--owners` — the join result as a
+ * contract: `path` (the file exactly as the user named it), `teams[]` (owner
+ * plus that team's services, in the LISTING's own filtered-and-ordered row
+ * order, so each array is that team's campaign worklist), `unowned[]` (rows
+ * no rule matched — explicit, because absence would read as owned-somewhere),
+ * and `skippedRules[]` (recognised rules outside the implemented CODEOWNERS
+ * subset, each with its line — reported, never guessed at). Key spellings
+ * frozen once shipped; the join itself lives in campaign/owners.ts.
+ *
+ * The service arrays carry IDS. On a `subsystem.name-collision` fleet —
+ * already an error finding — two rows can share an id, so a consumer cannot
+ * tell them apart here; if that ever needs disambiguating, the fix is a new
+ * ADDITIVE key carrying paths, never a change to these.
+ */
+export function ownersJson(join) {
+    return {
+        path: join.path,
+        teams: join.teams.map((team) => ({ owner: team.owner, services: team.services.map((row) => row.id) })),
+        unowned: join.unowned.map((row) => row.id),
+        skippedRules: join.skipped.map((rule) => ({ line: rule.line, pattern: rule.pattern })),
+    };
+}
+/**
+ * One `capabilities[]` row — additive payload, explicit `loam list
+ * capabilities` only, and diff-stable: the rollup already sorts rows,
+ * realizedBy and statuses' keys deterministically, and this projection adds
+ * nothing that could vary between machines. Optional keys are omitted rather
+ * than nulled so a declaration that never carried a description does not grow
+ * one in the diff.
+ */
+export function capabilityJson(row) {
+    return {
+        id: row.id,
+        ...(row.description !== undefined ? { description: row.description } : {}),
+        ...(row.owner !== undefined ? { owner: row.owner } : {}),
+        realizedBy: row.realizedBy,
+        services: row.services,
+        statuses: row.statuses,
+        // Present only for a capability that HAS a document, and absent rather than
+        // `[]` for one that does not — the same optional-key rule the two fields
+        // above follow, and here it carries a distinction a reader needs: an empty
+        // array means the document declares no requirements, while no key at all
+        // means there is no document to declare any.
+        //
+        // Each row inside carries `realizedBy` (the service requirements whose
+        // `Realizes:` line names it) and `keptBy` (the flows whose `#cap-`/`#req-`
+        // tags resolve to it) — two independent corpora, NEITHER derived from the
+        // other, because a cross-service promise can only be kept by a flow and a
+        // per-service one is normally kept by a requirement. `keptBy` follows the
+        // same three-state rule one level down and `rollup.ts` states it: absent
+        // means nobody looked, `[]` means loam looked and no flow keeps it. The
+        // payload's own `useCases.unreadable` says which of the two absences it is.
+        ...(row.requirements === undefined ? {} : { requirements: row.requirements }),
+    };
+}
+export function featureJson(docsDir, f, verification) {
+    return {
+        id: f.id,
+        dirName: f.dirName,
+        path: repoPath(docsDir, f.dir),
+        archived: f.archived,
+        services: f.services,
+        has: f.has,
+        verification,
+    };
+}
+/* ------------------------------------------------------------------ */
+/* Verification                                                        */
+/* ------------------------------------------------------------------ */
+/** What the features table says about verification without N `loam verify` runs. */
+/**
+ * One `glossary[]` row — additive payload, explicit `loam list glossary` only.
+ *
+ * `linkedBy` is the whole reason the section exists: "which documents use this
+ * term" is a grep today and a join here, and it is the same answer
+ * `glossary.unlinked` grades. Repo-relative and sorted by the index itself, so
+ * the payload is diff-stable across machines. Empty means loam read every
+ * authored document and none of them cites the term — never "nobody looked",
+ * which is what the sibling `links.unreadable` list is for.
+ */
+export function glossaryJson(term, linkedBy, docsDir) {
+    return { id: term.id, path: repoPath(docsDir, term.path), linkedBy };
+}
+//# sourceMappingURL=json.js.map

package/dist/commands/list/json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.js","sourceRoot":"","sources":["../../../src/commands/list/json.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The `--json` rows. Separate from `./print.ts` because only this side is a\n * contract: the payload keys are frozen, the columns beside them are not.\n */\nimport { repoPath } from \"../../core/envelope/json.js\";\nimport { type CapabilityRow } from \"../../core/capabilities/rollup.js\";\nimport { type FeatureEntry } from \"../../core/repo/entries.js\";\nimport { servicesUnder } from \"../../core/repo/tree/find.js\";\nimport type { FleetTree } from \"../../core/repo/tree/walk.js\";\nimport type { OwnersJoin } from \"./campaign/owners.js\";\nimport { type ServiceView, type VerificationCell } from \"./views.js\";\n\n/**\n * The `services[]` rows: ranked and decorated under `--review-order`, plain\n * otherwise — as a VARIANT, so a call carrying both a plain list and a ranked\n * queue is unrepresentable rather than resolved by precedence. `fanIn`/\n * `reviewRank` are ADDITIVE and appear ONLY under the flag — bare\n * `loam list --json` and `--needs-work --json` stay byte-identical and\n * cost-identical, the frozen-default doctrine the explicit-only capabilities\n * section also follows. The spread keeps serviceJson at its two-param\n * contract; `reviewRank` is 1-based and equals the row's position, so the\n * array order IS the queue.\n */\nexport function serviceRows(\n  docsDir: string,\n  rows: ServiceView[] | { queue: ServiceView[]; fanIn: ReadonlyMap<string, number> },\n): Record<string, unknown>[] {\n  if (Array.isArray(rows)) return rows.map((v) => serviceJson(docsDir, v));\n  return rows.queue.map((v, i) => ({\n    ...serviceJson(docsDir, v),\n    fanIn: rows.fanIn.get(v.entry.id) ?? 0,\n    reviewRank: i + 1,\n  }));\n}\n\nexport function serviceJson(docsDir: string, v: ServiceView): Record<string, unknown> {\n  const s = v.entry;\n  return {\n    id: s.id,\n    path: repoPath(docsDir, s.dir),\n    // Names from services/ down, outermost first; [] = unfiled. `path` above\n    // already truthfully reflects placement — this is the same fact as data\n    // instead of a string to split.\n    subsystem: s.subsystem,\n    has: { ...s.has, archSpec: v.archSpec },\n    adrs: s.adrs,\n    status: s.status,\n    maturity: v.maturity,\n    missing: v.missing,\n    apiExpected: v.apiExpected,\n    // Never omitted when true: a consumer that filters this table into a\n    // worklist has to be able to tell \"checked and fine\" from \"not checkable\n    // from here\", and absence reads as the first one.\n    ...(v.unverifiableFromHere ? { provenance: \"unverifiable-from-here\" } : {}),\n    // Additive, and only when there IS a scope — omission is the fine case\n    // here, exactly as it is for `provenance` above, and `maturity` stays the\n    // frozen `vouched` beside it. A dashboard counting `maturity: \"vouched\"`\n    // rows keeps counting them; one that cares whether a person read the\n    // document subtracts these.\n    ...(s.vouchScope === \"sampled\" ? { vouchScope: \"sampled\" } : {}),\n  };\n}\n\n/**\n * The subsystem rows beside the service table, sorted by path. `memberCount`\n * is TRANSITIVE — every service beneath, at any depth — matching the\n * generated views file's membership, so the two numbers a consumer can\n * cross-check never disagree about what \"in this group\" means.\n */\nexport function subsystemsJson(docsDir: string, tree: FleetTree): Record<string, unknown>[] {\n  return [...tree.subsystems]\n    .sort((a, b) => (a.path.join(\"/\") < b.path.join(\"/\") ? -1 : 1))\n    .map((sub) => ({\n      name: sub.name,\n      path: repoPath(docsDir, sub.dir),\n      title: sub.meta.title ?? null,\n      memberCount: servicesUnder(tree, sub).length,\n    }));\n}\n\n/**\n * The additive `owners` payload key under `--owners` — the join result as a\n * contract: `path` (the file exactly as the user named it), `teams[]` (owner\n * plus that team's services, in the LISTING's own filtered-and-ordered row\n * order, so each array is that team's campaign worklist), `unowned[]` (rows\n * no rule matched — explicit, because absence would read as owned-somewhere),\n * and `skippedRules[]` (recognised rules outside the implemented CODEOWNERS\n * subset, each with its line — reported, never guessed at). Key spellings\n * frozen once shipped; the join itself lives in campaign/owners.ts.\n *\n * The service arrays carry IDS. On a `subsystem.name-collision` fleet —\n * already an error finding — two rows can share an id, so a consumer cannot\n * tell them apart here; if that ever needs disambiguating, the fix is a new\n * ADDITIVE key carrying paths, never a change to these.\n */\nexport function ownersJson(join: OwnersJoin): Record<string, unknown> {\n  return {\n    path: join.path,\n    teams: join.teams.map((team) => ({ owner: team.owner, services: team.services.map((row) => row.id) })),\n    unowned: join.unowned.map((row) => row.id),\n    skippedRules: join.skipped.map((rule) => ({ line: rule.line, pattern: rule.pattern })),\n  };\n}\n\n/**\n * One `capabilities[]` row — additive payload, explicit `loam list\n * capabilities` only, and diff-stable: the rollup already sorts rows,\n * realizedBy and statuses' keys deterministically, and this projection adds\n * nothing that could vary between machines. Optional keys are omitted rather\n * than nulled so a declaration that never carried a description does not grow\n * one in the diff.\n */\nexport function capabilityJson(row: CapabilityRow): Record<string, unknown> {\n  return {\n    id: row.id,\n    ...(row.description !== undefined ? { description: row.description } : {}),\n    ...(row.owner !== undefined ? { owner: row.owner } : {}),\n    realizedBy: row.realizedBy,\n    services: row.services,\n    statuses: row.statuses,\n    // Present only for a capability that HAS a document, and absent rather than\n    // `[]` for one that does not — the same optional-key rule the two fields\n    // above follow, and here it carries a distinction a reader needs: an empty\n    // array means the document declares no requirements, while no key at all\n    // means there is no document to declare any.\n    //\n    // Each row inside carries `realizedBy` (the service requirements whose\n    // `Realizes:` line names it) and `keptBy` (the flows whose `#cap-`/`#req-`\n    // tags resolve to it) — two independent corpora, NEITHER derived from the\n    // other, because a cross-service promise can only be kept by a flow and a\n    // per-service one is normally kept by a requirement. `keptBy` follows the\n    // same three-state rule one level down and `rollup.ts` states it: absent\n    // means nobody looked, `[]` means loam looked and no flow keeps it. The\n    // payload's own `useCases.unreadable` says which of the two absences it is.\n    ...(row.requirements === undefined ? {} : { requirements: row.requirements }),\n  };\n}\n\nexport function featureJson(\n  docsDir: string,\n  f: FeatureEntry,\n  verification: VerificationCell | null,\n): Record<string, unknown> {\n  return {\n    id: f.id,\n    dirName: f.dirName,\n    path: repoPath(docsDir, f.dir),\n    archived: f.archived,\n    services: f.services,\n    has: f.has,\n    verification,\n  };\n}\n\n/* ------------------------------------------------------------------ */\n/* Verification                                                        */\n/* ------------------------------------------------------------------ */\n\n/** What the features table says about verification without N `loam verify` runs. */\n\n/**\n * One `glossary[]` row — additive payload, explicit `loam list glossary` only.\n *\n * `linkedBy` is the whole reason the section exists: \"which documents use this\n * term\" is a grep today and a join here, and it is the same answer\n * `glossary.unlinked` grades. Repo-relative and sorted by the index itself, so\n * the payload is diff-stable across machines. Empty means loam read every\n * authored document and none of them cites the term — never \"nobody looked\",\n * which is what the sibling `links.unreadable` list is for.\n */\nexport function glossaryJson(term: { id: string; path: string }, linkedBy: string[], docsDir: string): Record<string, unknown> {\n  return { id: term.id, path: repoPath(docsDir, term.path), linkedBy };\n}\n"]}

package/dist/commands/list/list.js

@@ -0,0 +1,343 @@
+import { loadConfig } from "../../core/envelope/config.js";
+import { emitJson, fail, repoPath, reportNoConfig } from "../../core/envelope/json.js";
+import { maturityRollup } from "../../core/vocabulary/maturity.js";
+import { FleetContext } from "../../core/fleet-context.js";
+import { DocsRepoUnavailableError } from "../../core/repo/state.js";
+import { capabilityRollup } from "../../core/capabilities/rollup.js";
+import { invalidVocabularyFinding } from "../../core/capabilities/findings.js";
+import { promisesKeptByFlows } from "../../core/usecases/capability.js";
+import { fleetAdrCount, listFeatures, listFleetTree, listServices } from "../../core/repo/repo.js";
+import { readGlossary } from "../../core/glossary/tree.js";
+import { backlinkIndex } from "../../core/links/backlinks.js";
+import { glossaryDir } from "../../core/repo/authored/paths.js";
+import { docsRepoReady, reportDocsRepoError, reportRepositoryUnavailable } from "../policy/gate.js";
+import { featureVerification, serviceViews } from "./views.js";
+import { capabilityJson, featureJson, glossaryJson, ownersJson, serviceRows, subsystemsJson } from "./json.js";
+import { printCapabilities, printFeatures, printGlossary, printOwners, printServices, printWorklist, } from "./print.js";
+import { fanInByService, reviewLandscape, reviewOrder } from "./review.js";
+import { resolveSubsystemSlice } from "./campaign/campaign.js";
+import { ownersJoin } from "./campaign/owners.js";
+const SECTIONS = ["services", "features", "capabilities", "glossary"];
+/**
+ * What a bare `loam list` shows. `capabilities` is explicit-only, NEVER part
+ * of this default: the no-argument output and its `--json` payload are a
+ * frozen contract, byte-identical whether or not a fleet declares capabilities.
+ */
+const DEFAULT_SECTIONS = ["services", "features"];
+export function registerList(program) {
+    program
+        .command("list")
+        .argument("[section]", "services | features | capabilities | glossary (default: services + features)")
+        .description("List the services and features in the docs repo")
+        .option("--json", "emit the machine contract instead of the human view")
+        .option("--archived", "include archived features")
+        .option("--needs-work", "services only: the adoption worklist — every service below `vouched`, with what it is missing")
+        .option("--review-order", "with --needs-work: order the worklist by blast radius — services the most other services depend on first")
+        .option("--subsystem <name>", "services only: limit the listing to services filed under this subsystem, at any depth ('unfiled' selects the ones filed under none, while nothing in the tree claims that name)")
+        .option("--owners <path>", "services only: group the listing by owning team from this CODEOWNERS file, resolved from the current directory (directory-pattern rules only; unsupported rules are listed as skipped, never guessed)")
+        .action(async (section, opts) => {
+        const json = opts.json === true;
+        // The campaign flags grade services, so — exactly like --needs-work —
+        // they narrow a bare `loam list` to the services section instead of
+        // printing a features table the filter silently does not apply to.
+        const campaign = opts.subsystem !== undefined || opts.owners !== undefined;
+        const wanted = opts.needsWork || campaign
+            ? DEFAULT_SECTIONS.filter((s) => s === "services")
+            : section
+                ? SECTIONS.filter((s) => s === section)
+                : DEFAULT_SECTIONS;
+        if (section && !SECTIONS.includes(section)) {
+            // `invalid-option`, same as show's bad --type: one mistake class, one code.
+            fail(json, "invalid-option", `Unknown section '${section}'. Expected: ${SECTIONS.join(" | ")}.`);
+            return;
+        }
+        if (opts.needsWork && section === "features") {
+            fail(json, "invalid-option", "--needs-work is the service adoption worklist; drop the 'features' section.");
+            return;
+        }
+        if (campaign && section !== undefined && section !== "services") {
+            fail(json, "invalid-option", `--subsystem and --owners grade the services section; drop the '${section}' section.`);
+            return;
+        }
+        // The flag ORDERS the worklist, so it requires the worklist explicitly:
+        // silently implying --needs-work would make one flag change which rows
+        // exist, not only their order.
+        if (opts.reviewOrder && !opts.needsWork) {
+            fail(json, "invalid-option", "--review-order sorts the adoption worklist; add --needs-work.");
+            return;
+        }
+        const loaded = await loadConfig();
+        if (loaded.kind !== "loaded") {
+            reportNoConfig(json, loaded);
+            return;
+        }
+        const config = loaded.config;
+        const { docsDir } = config;
+        // A docsDir that is not a docs repo is refused, never rendered as an empty
+        // fleet — the whole point of the gate (see docs-repo-gate.ts).
+        // `list features` alone does not need services/, so it asks for less;
+        // the capability rollup walks every service's spec files, so it asks for them.
+        const needsServices = wanted.includes("services") || wanted.includes("capabilities") || wanted.includes("glossary");
+        if (!docsRepoReady(json, docsDir, needsServices ? "services" : "docs"))
+            return;
+        try {
+            // One context, one walk: the tree memo answers both the service
+            // entries and the subsystem/unfiled counts beside them.
+            const fleet = new FleetContext();
+            const tree = wanted.includes("services") ? await listFleetTree(docsDir, fleet) : undefined;
+            const services = wanted.includes("services") ? await listServices(docsDir, fleet) : undefined;
+            // --review-order parses the landscape ONCE for both of its consumers —
+            // serviceViews' `called` set (handed in as `preloaded`) and the fan-in
+            // joins below. Without the flag, `undefined` keeps serviceViews' own
+            // load-if-exists behaviour and the run byte-identical to today's.
+            const land = opts.reviewOrder === true && services !== undefined
+                ? await reviewLandscape(docsDir, fleet)
+                : undefined;
+            const views = services ? await serviceViews(docsDir, services, config.service, land) : undefined;
+            // The slice is resolved AFTER the full-fleet views, and rows are
+            // filtered rather than re-derived: fan-in, apiExpected and the missing
+            // lists are fleet facts, and a slice-first derivation would recompute
+            // them against a fleet with the callers outside the slice erased. The
+            // composition is pinned as filter-first-then-rank — ranks stay
+            // contiguous within the filtered set (test/list-campaign.test.ts).
+            // `tree !== undefined` is a type NARROWING, not a branch: a campaign
+            // flag forces the services section, so the tree always exists here.
+            const slice = opts.subsystem !== undefined && tree !== undefined
+                ? resolveSubsystemSlice(tree, opts.subsystem, json)
+                : undefined;
+            if (slice === null)
+                return;
+            // Membership is by DIRECTORY: leaf ids can collide across a broken
+            // tree (`subsystem.name-collision`), and the directory is the row's
+            // actual identity — campaign.ts's SubsystemSlice says why.
+            const shown = slice === undefined ? views : views?.filter((v) => slice.members.has(v.entry.dir));
+            // The fleet's own decision records. Read unconditionally — it is one
+            // existsSync over `architecture/adrs/` and it belongs to the docs repo
+            // rather than to any section, so `loam list features --json` reports it
+            // as truthfully as `loam list services --json` does. Nothing grades it:
+            // an absent directory is 0 and 0 is a fine, permanent answer.
+            const fleetAdrs = await fleetAdrCount(docsDir);
+            const features = wanted.includes("features")
+                ? await listFeatures(docsDir, { includeArchived: opts.archived }, fleet)
+                : undefined;
+            const verification = features
+                ? await Promise.all(features.map((f) => featureVerification(docsDir, f)))
+                : undefined;
+            // The capability section: the vocabulary's own verdict decides the shape.
+            // An INVALID file refuses with `repository-unavailable` — an
+            // empty-looking success over a broken file is the silent hole this
+            // command already refuses elsewhere — while an ABSENT one is an honest
+            // empty answer, because the file is the axis's opt-in. The message is
+            // `capability.invalid`'s own sentence, not the fs-error helper's: the
+            // file WAS read, it just is not a vocabulary, and one diagnosis should
+            // have one spelling wherever it surfaces.
+            const capabilityVocab = wanted.includes("capabilities")
+                ? await fleet.capabilities(docsDir)
+                : undefined;
+            const brokenVocab = capabilityVocab === undefined ? null : invalidVocabularyFinding(capabilityVocab);
+            if (brokenVocab !== null) {
+                fail(json, "repository-unavailable", brokenVocab.message);
+                return;
+            }
+            // The SECOND corpus behind a capability's promises: the `#cap-`/`#req-`
+            // tagged flows. Read only under `loam list capabilities`, and
+            // `promisesKeptByFlows` carries `readUseCases`' byte gate, so a fleet
+            // whose architecture/ never mentions the reserved tag prefix pays a
+            // readdir here rather than a LikeC4 workspace.
+            //
+            // AN UNREADABLE architecture/ DEGRADES, it does not refuse — the
+            // opposite of the invalid vocabulary above, and the difference is which
+            // corpus broke. `architecture/capabilities.yaml` is what the ROWS are
+            // built from: unreadable, there is no listing to print, so refusing is
+            // the only honest answer. The flows are a second corpus over rows that
+            // are already true, and refusing the whole listing because a use-case
+            // document has a syntax error would take `loam list capabilities` away
+            // during exactly the minutes somebody is fixing that document, while
+            // `validate` already reports it as `landscape.invalid`. So the join is
+            // withheld instead — every `keptBy` absent rather than `[]` — and the
+            // reason is stated, which is `core/pack/joins.ts`' holes idiom: carry
+            // what is true, name what could not be looked at, never let the two read
+            // the same.
+            const entries = capabilityVocab === undefined ? undefined : await listServices(docsDir, fleet);
+            const promises = capabilityVocab === undefined || entries === undefined
+                ? undefined
+                : await promisesKeptByFlows({
+                    docsDir,
+                    vocab: capabilityVocab,
+                    known: new Set(entries.map((e) => e.id)),
+                    read: (p) => fleet.readRequirements(p),
+                });
+            const capabilities = capabilityVocab === undefined || entries === undefined
+                ? undefined
+                : await capabilityRollup({
+                    services: entries,
+                    vocab: capabilityVocab,
+                    read: (p) => fleet.readRequirements(p),
+                    ...(promises?.kind === "read" ? { keptByFlows: promises.kept } : {}),
+                });
+            // The glossary section: the tree, and who cites each term. The
+            // citation index is the expensive half — it reads every authored
+            // document in the repository — so it is built only when the section is
+            // asked for, and not at all when `glossary/` does not exist. The
+            // directory's existence is the axis's opt-in, exactly as it is for
+            // `capabilities/`, so a fleet without one prints an empty section
+            // rather than paying for a fleet-wide walk to say so.
+            const glossary = wanted.includes("glossary") ? await readGlossary(glossaryDir(docsDir)) : undefined;
+            const citations = glossary !== undefined && glossary.terms.length > 0 ? await backlinkIndex(docsDir, fleet) : undefined;
+            const terms = glossary?.terms.map((term) => ({
+                term,
+                linkedBy: citations === undefined ? [] : citations.linkersOf(term.path),
+            }));
+            const worklist = (shown ?? []).filter((v) => v.maturity !== "vouched");
+            // The ranked review queue, derived never stored: fan-in is computed
+            // FLEET-WIDE (the joins need every service's slice anyway — and a
+            // --subsystem filter must never change a service's count, only which
+            // rows appear) while ranks are assigned over the WORKLIST only — a
+            // vouched service needs no review, and ranking it would put gaps in
+            // the queue. The worklist is already sliced, so under --subsystem the
+            // ranks are contiguous within the filtered set.
+            let ranked;
+            if (opts.reviewOrder === true && services !== undefined) {
+                const fanIn = await fanInByService(services, fleet, land ?? null);
+                ranked = { queue: reviewOrder(worklist, fanIn), fanIn };
+            }
+            // THE row set of this listing, spelled once: the owners join, the
+            // `services[]` payload and the text view must all be about the same
+            // rows — `owners.teams[]` is only "that team's campaign worklist"
+            // while it was computed over the rows `services[]` lists — and three
+            // copies of this expression is how they would drift apart.
+            const rows = shown === undefined ? undefined : (ranked?.queue ?? (opts.needsWork ? worklist : shown));
+            let owned;
+            if (opts.owners !== undefined && rows !== undefined) {
+                const join = await ownersJoin({
+                    path: opts.owners,
+                    rows: rows.map((v) => ({ id: v.entry.id, repoDir: repoPath(docsDir, v.entry.dir) })),
+                    json,
+                });
+                if (join === null)
+                    return;
+                owned = join;
+            }
+            if (json) {
+                emitJson({
+                    command: "list",
+                    docsDir,
+                    // Additive, unconditional and flat, mirroring the per-service
+                    // `adrs` key one row down rather than inventing a second shape for
+                    // the same number. Not nested under the services section: the fleet
+                    // has decision records whether or not this run listed services.
+                    fleetAdrs,
+                    ...(rows && shown
+                        ? {
+                            services: serviceRows(docsDir, ranked ?? rows),
+                            // Under --subsystem the dial is the SLICE's — the filter's
+                            // whole answer — while unfiltered runs keep the full fleet's
+                            // rollup, byte-identical to before the flag existed.
+                            maturity: maturityRollup(shown),
+                            // The tree beside the table — additive keys, wave 3 of the
+                            // subsystem item: the groups, and how many services sit
+                            // unfiled (a permanent, normal state, so a count, never a
+                            // finding). Under --subsystem the rows narrow to the named
+                            // group and its descendants; memberCount stays transitive
+                            // because the full tree's services back the modified copy.
+                            subsystems: subsystemsJson(docsDir, slice === undefined ? tree : { ...tree, subsystems: slice.subsystems }),
+                            // `unfiledServices` is a fleet-root fact: under a filter it
+                            // is omitted rather than reported as 0, which would lie.
+                            ...(slice === undefined
+                                ? { unfiledServices: tree.services.filter((s) => s.subsystem.length === 0).length }
+                                : {}),
+                        }
+                        : {}),
+                    ...(owned !== undefined ? { owners: ownersJson(owned) } : {}),
+                    ...(features
+                        ? { features: features.map((f, i) => featureJson(docsDir, f, verification[i] ?? null)) }
+                        : {}),
+                    ...(capabilities ? { capabilities: capabilities.map(capabilityJson) } : {}),
+                    ...(terms ? { glossary: terms.map((t) => glossaryJson(t.term, t.linkedBy, docsDir)) } : {}),
+                    // What the citation walk could not read, beside the rows it
+                    // decorates — `useCases` below is the same shape for the same
+                    // reason. An empty `linkedBy` means loam read every authored
+                    // document and none cites the term; this key is how a reader tells
+                    // that from "one of them would not decode".
+                    ...(citations ? { links: { unreadable: citations.unreadable } } : {}),
+                    // The use-case corpus's own health, beside the rows it decorates —
+                    // `status --json` and `delta --json` already spell this key this
+                    // way. It is what makes an absent `keptBy` legible: `unreadable:
+                    // false` with no `keptBy` on a row means the document declares that
+                    // promise and no flow keeps it, while `unreadable: true` means
+                    // nobody could look. Emitted only with the capabilities section, so
+                    // bare `loam list --json` is untouched.
+                    ...(promises === undefined
+                        ? {}
+                        : {
+                            useCases: {
+                                unreadable: promises.kind === "unreadable",
+                                ...(promises.kind === "unreadable" && promises.errors[0] !== undefined
+                                    ? { error: promises.errors[0] }
+                                    : {}),
+                            },
+                        }),
+                });
+                return;
+            }
+            if (slice !== undefined && shown !== undefined) {
+                console.log(`filtered to ${slice.label}: ${shown.length} of ${views.length} service(s)`);
+            }
+            if (owned !== undefined && rows !== undefined && shown !== undefined) {
+                if (opts.needsWork && rows.length === 0) {
+                    // printWorklist's own affordance, kept under the grouping flag:
+                    // empty owner groups would answer "who owns the work" without
+                    // saying there is none.
+                    console.log(`nothing to do — all ${shown.length} service(s) are vouched`);
+                    return;
+                }
+                const kind = opts.needsWork
+                    ? `${rows.length} of ${shown.length} service(s) need work`
+                    : `services (${rows.length})`;
+                const ordered = ranked === undefined ? "" : " — review order (fan-in: services depending on each)";
+                console.log(`${kind} — by owner (${owned.path})${ordered}`);
+                printOwners(owned, new Map(rows.map((v) => [repoPath(docsDir, v.entry.dir), v])), ranked?.fanIn);
+                return;
+            }
+            if (opts.needsWork) {
+                printWorklist(ranked === undefined ? worklist : ranked.queue, shown.length, ranked?.fanIn);
+                return;
+            }
+            // Under --subsystem the tree dial (subsystem and unfiled counts) is a
+            // fleet-root fact the filtered table must not claim, so no tree. The
+            // fleet's ADR count is not derived from the rows at all and stays.
+            if (shown)
+                printServices(shown, { tree: slice === undefined ? tree : undefined, adrs: fleetAdrs });
+            if (views && features)
+                console.log("");
+            if (features)
+                printFeatures(features, verification);
+            if (capabilities) {
+                if (capabilityVocab.present)
+                    printCapabilities(capabilities, promises);
+                else
+                    console.log("no architecture/capabilities.yaml — the fleet declares no capabilities");
+            }
+            if (terms && glossary) {
+                if (glossary.present) {
+                    printGlossary(terms.map((t) => ({ id: t.term.id, linkedBy: t.linkedBy })), citations?.unreadable ?? []);
+                }
+                else {
+                    console.log("no glossary/ — the fleet defines no domain terms");
+                }
+            }
+        }
+        catch (err) {
+            if (err instanceof DocsRepoUnavailableError) {
+                reportDocsRepoError(json, err);
+                return;
+            }
+            // One unreadable file used to escape as a stack trace (`internal` in
+            // --json), naming nothing. The enumeration is all-or-nothing — it reads
+            // every service's frontmatter to build one table — so the honest answer
+            // is a refusal that says WHICH path could not be read.
+            reportRepositoryUnavailable(json, err, "the listing would be missing a service", docsDir);
+        }
+    });
+}
+//# sourceMappingURL=list.js.map