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

package/dist/core/repo/paths.js

@@ -0,0 +1,277 @@
+/**
+ * Where every artifact lives. Artifact filenames are spelled here and nowhere
+ * else, so a rename is one edit rather than a grep.
+ *
+ * This is also the module that carries loam's one path guarantee.
+ * `unfiledServicePaths(docsDir, service)` spells `<docsDir>/services/<service>/`,
+ * so both parts are caller-controlled path input, and `node:path` cannot help:
+ * `join(...paths: string[])` accepts every string there is. The guarantee IS
+ * the parameter brands and nothing else — `PathableService` for the id (a name
+ * whose provenance is the repository, unconstructible from document text),
+ * `DocsDir`/`FeatureDir` for the roots (a resolved config or validated
+ * `--docs`; a directory an enumeration read), and `ServiceDir` for
+ * `servicePathsAt` (the enumeration's own resolved directory, narrower still)
+ * — the `kernel/ids/` package holds the only casts, so an unchecked value at
+ * these call sites does not compile.
+ * Code that spells `services/<id>/` or a feature layout with a bare join is
+ * outside the guarantee — `commands/new.ts` and the openspec migrator both do,
+ * held instead by `resolveInside` at the write.
+ */
+import { join } from "node:path";
+import { serviceDirOf } from "../kernel/ids/dirs.js";
+/** Directory under features/ holding shipped features. Never a feature itself. */
+export const ARCHIVE_DIR = "archive";
+/* ------------------------------------------------------------------ */
+/* Paths — artifact filenames are spelled here and nowhere else        */
+/* ------------------------------------------------------------------ */
+/**
+ * The living artifact filenames, as one table, because three questions read
+ * them: `servicePathsAt` below spells the paths, the tree walk classifies
+ * a directory as a service by whether any of these names sit in it, and
+ * `core/diff/base-state.ts` classifies the SAME way over a base git ref's
+ * tree listing (exported for that reader — a filename respelled there would
+ * be the drift this table exists to prevent). The walk cannot import this
+ * module — `repo → repo/tree` is the package direction, and an edge back
+ * would be the cycle `scripts/package-graph.mjs` refuses — so `repo.ts`
+ * injects `isServiceArtifactName` into the walk request instead.
+ */
+export const ARTIFACT_FILES = {
+    model: "model.likec4",
+    spec: "spec.md",
+    archSpec: "arch.spec.md",
+    openapi: "openapi.yaml",
+    asyncapi: "asyncapi.yaml",
+    runbook: "runbook.md",
+    health: "health.yaml",
+    steps: "steps.yaml",
+};
+const ADRS_DIR = "adrs";
+/** Does a directory entry name a living service artifact? The classification half of the table above. */
+export function isServiceArtifactName(name, kind) {
+    if (kind === "dir")
+        return name === ADRS_DIR;
+    return Object.values(ARTIFACT_FILES).some((file) => file === name);
+}
+/**
+ * The artifact paths of a service whose directory is already KNOWN — the
+ * enumeration's `dir`, at whatever depth the tree walk found it. This is the
+ * spelling every reader of an existing service must use: joining
+ * `services/<id>/` at the root is only true for a fleet nobody has filed, and
+ * a moved service would silently grade as absent through it.
+ */
+export function servicePathsAt(dir) {
+    return {
+        dir,
+        model: join(dir, ARTIFACT_FILES.model),
+        spec: join(dir, ARTIFACT_FILES.spec),
+        archSpec: join(dir, ARTIFACT_FILES.archSpec),
+        openapi: join(dir, ARTIFACT_FILES.openapi),
+        asyncapi: join(dir, ARTIFACT_FILES.asyncapi),
+        runbook: join(dir, ARTIFACT_FILES.runbook),
+        health: join(dir, ARTIFACT_FILES.health),
+        steps: join(dir, ARTIFACT_FILES.steps),
+        adrsDir: join(dir, ADRS_DIR),
+    };
+}
+/**
+ * The UNFILED spelling — `<docsDir>/services/<id>/`, the tree's root level.
+ * This is where creation lands (`adopt`'s brief, a new service materialised by
+ * `archive`, the OpenSpec migration) and the honest fallback for a service the
+ * enumeration does not answer; for a service that EXISTS, resolve through the
+ * enumeration instead (`servicePathsAt(entry.dir)`, or
+ * `locateServicePaths` in `service-target.ts`, which chooses between the two).
+ * Renamed from `servicePaths` when the tree landed, precisely so the compiler
+ * would put every remaining caller in front of a reviewer: a root join that
+ * survives unreviewed is a moved service silently grading as absent.
+ */
+export function unfiledServicePaths(docsDir, service) {
+    return servicePathsAt(serviceDirOf(join(docsDir, "services", service)));
+}
+/**
+ * The creation spelling INSIDE a subsystem — `<subsystemDir>/<id>/`, the
+ * target `adopt --subsystem` briefs so an adoption need not land unfiled and
+ * cost a second command. The same two provenances the unfiled spelling
+ * combines, one level down: the subsystem directory came off the tree walk's
+ * readdir, and the id passed the service grammar before it reached here.
+ */
+export function servicePathsUnder(subsystemDir, service) {
+    return servicePathsAt(serviceDirOf(join(subsystemDir, service)));
+}
+/**
+ * The directory a SUBSYSTEM occupies (or will occupy) under a parent — the
+ * spelling `subsystem new` creates and `subsystem rename` renames into. The
+ * same guarantee-by-brand as the service spellings above: the parent came off
+ * the tree walk's readdir (or is `servicesDir` itself), and demanding
+ * `SubsystemName` here is what makes the validator unskippable — a raw argv
+ * string at this call site does not compile, so no future verb can hoist the
+ * join above the check that earns it.
+ */
+export function subsystemPathUnder(parentDir, name) {
+    return join(parentDir, name);
+}
+/**
+ * The pair of requirement-carrying spec files, living and delta alike: the
+ * business spec and the architecture spec. Same grammar, same delta algebra,
+ * same merge — everything that walks "the spec files" of a service walks this
+ * list, so the two axes cannot drift apart in what handles them. `key` indexes
+ * ServicePaths/FeatureSpecPaths; `label` is how the axis names itself in prose.
+ */
+export const SPEC_AXES = [
+    { key: "spec", file: "spec.md", label: "requirements" },
+    { key: "archSpec", file: "arch.spec.md", label: "arch requirements" },
+];
+export function featurePaths(featureDir) {
+    return {
+        dir: featureDir,
+        intent: join(featureDir, "intent.md"),
+        delta: join(featureDir, "delta.likec4"),
+        specsDir: join(featureDir, "specs"),
+        adrsDir: join(featureDir, "adrs"),
+    };
+}
+export function featureSpecPaths(featureDir, service) {
+    const dir = join(featureDir, "specs", service);
+    return {
+        dir,
+        spec: join(dir, "spec.md"),
+        archSpec: join(dir, "arch.spec.md"),
+        openapi: join(dir, "openapi.yaml"),
+        asyncapi: join(dir, "asyncapi.yaml"),
+    };
+}
+export function landscapePath(docsDir) {
+    return join(docsDir, "architecture", LANDSCAPE_FILE);
+}
+/** The fleet's authorization vocabulary — beside the fleet map, for the same reason. */
+export function permissionsPath(docsDir) {
+    return join(docsDir, "architecture", "permissions.yaml");
+}
+/** The fleet's capability vocabulary — beside the other two fleet documents, for the same reason. */
+export function capabilitiesPath(docsDir) {
+    return join(docsDir, "architecture", "capabilities.yaml");
+}
+/**
+ * The fleet's ARCHITECTURAL OBLIGATION vocabulary — beside the landscape it tags
+ * and the two vocabularies it sits with, for their reason: it is a fact about
+ * the fleet that no single service owns.
+ */
+export function obligationsPath(docsDir) {
+    return join(docsDir, "architecture", "obligations.yaml");
+}
+/**
+ * The FLEET's decision records — `architecture/adrs/`, beside the landscape and
+ * the two vocabularies.
+ *
+ * ADRs used to exist at two altitudes only, `services/<id>/adrs/` and
+ * `features/<FEAT>/adrs/`, so a decision about the fleet itself — "event
+ * publishers use a transactional outbox", "cross-service calls carry a circuit
+ * breaker" — had no home but one arbitrary service's directory, where the next
+ * reader of the other fifty services never finds it. This is not a new axis: it
+ * is the same `ADRS_DIR` name one level up, spelled through the same constant so
+ * the two altitudes cannot drift into `adrs/` and `decisions/`.
+ *
+ * PRESENCE-TRACKED AND NOTHING MORE, exactly like the service directory it
+ * mirrors: `loam list` counts the files (`repo.ts`'s `fleetAdrCount`) and no
+ * check anywhere reads one. A fleet with no fleet-level ADRs owes nothing and
+ * must produce no finding — which is also why `loam init` does NOT scaffold the
+ * directory. git does not carry an empty one, so it would vanish on the first
+ * clone and come back as a diff on the next `init`; and an empty `adrs/` in a
+ * fresh repo reads as an obligation nobody has met, when there is no obligation
+ * at all.
+ */
+export function fleetAdrsDir(docsDir) {
+    return join(docsDir, "architecture", ADRS_DIR);
+}
+/**
+ * The GENERATED subsystem views — beside the fleet map because the LikeC4
+ * renderer merges the whole `architecture/` project, and a view can only
+ * `include` elements the landscape beside it defines. `loam subsystem sync`
+ * owns the bytes (`core/repo/tree/views.ts` renders them); nothing in loam
+ * ever parses the file, and staleness against the tree is a byte compare.
+ */
+export function subsystemViewsPath(docsDir) {
+    return join(docsDir, "architecture", SUBSYSTEM_VIEWS_FILE);
+}
+/** The generated views' file name, spelled once because the reservation below reads it too. */
+const SUBSYSTEM_VIEWS_FILE = "subsystems.likec4";
+/**
+ * Names inside `architecture/` that LOAM owns, and what goes wrong if a
+ * feature's own document claims one.
+ *
+ * `features/<FEAT>/deployment/<name>.likec4` merges as a whole-file copy
+ * straight into `architecture/` — unlike a flow, which lands under
+ * `usecases/` — so its `<name>` is free to be any of these, and two of them
+ * fail in ways nothing downstream would report:
+ *
+ *  - `subsystems.likec4` is GENERATED and is EXCLUDED from every project load
+ *    (docs/DESIGN.md rule 26 keeps it a byte compare), so topology landing
+ *    there is invisible to loam from the moment it archives — and the next
+ *    `loam subsystem sync` overwrites the file wholesale. Silent both ways,
+ *    which is the worst shape a failure can have;
+ *  - `landscape.likec4` is the living map the archive SPLICES; a whole-file
+ *    copy over it would discard the fleet;
+ *  - `usecases/` is the flow tree, walked by the use-case scan. A deployment
+ *    document filed there parses (one project) and is then looked for by a
+ *    reader asking a different question.
+ *
+ * Returns the reason, or null when the name is the author's to choose. Takes
+ * the `/`-separated rel a directory walk produced, never a string from argv.
+ */
+export function reservedArchitectureName(rel) {
+    const parts = rel.split("/");
+    if (parts[0] === USECASE_DIR) {
+        return `\`${USECASE_DIR}/\` is the use-case tree — a flow belongs in \`features/<FEAT>/usecases/\`, which merges there`;
+    }
+    if (rel === SUBSYSTEM_VIEWS_FILE) {
+        return "`subsystems.likec4` is generated by `loam subsystem sync`, which overwrites it wholesale — and nothing in loam ever parses it, so anything landing there is invisible from the moment it archives";
+    }
+    if (rel === LANDSCAPE_FILE) {
+        return "`landscape.likec4` is the living fleet map, which the archive SPLICES into rather than replaces";
+    }
+    return null;
+}
+/** The living map's file name, and the flow tree's directory — spelled once, read by the reservation. */
+const LANDSCAPE_FILE = "landscape.likec4";
+const USECASE_DIR = "usecases";
+export function featuresDir(docsDir) {
+    return join(docsDir, "features");
+}
+/**
+ * The root of the tree that IS the fleet — where an unfiled service and a
+ * root-level subsystem both sit. The `subsystem` verbs join validated names
+ * under it; the enumerating walk spells the same join for itself
+ * (`repo/tree/walk.ts`), because it cannot import this module.
+ */
+export function servicesDir(docsDir) {
+    return join(docsDir, "services");
+}
+/**
+ * The agent contract's filename, and where it sits in a docs repo.
+ *
+ * Both spellings are exported because the two questions are different: `init`,
+ * `doctor` and `validate` want a path under a docsDir they already hold, while
+ * `docs.ts` builds the scaffold as `[relative path, bytes]` pairs and needs the
+ * bare name. Four modules spelled the literal out for themselves, and one of
+ * them — `init` — uses it to decide whether a directory IS a docs repo at all,
+ * so a rename that reached three of the four would leave `init` recognising a
+ * file nothing else writes any more.
+ *
+ * `openspec-inventory.ts`'s "AGENTS.md" is deliberately NOT this constant: it
+ * names a file in a foreign OpenSpec tree that happens to share the name.
+ */
+export const AGENTS_FILENAME = "AGENTS.md";
+export function agentsPath(docsDir) {
+    return join(docsDir, AGENTS_FILENAME);
+}
+/**
+ * Where shipped features live. `features/archive/` is spelled here and nowhere
+ * else for the same reason every other artifact path is: `archive` and
+ * `unarchive` move directories in and out of it, and a layout string that two
+ * commands re-derive is a layout two commands can disagree about. The
+ * `features/archive/…` strings in refusal PROSE are not this path — they are
+ * what a reader types into `ls`, and they stay spelled out.
+ */
+export function archiveDir(docsDir) {
+    return join(featuresDir(docsDir), ARCHIVE_DIR);
+}
+//# sourceMappingURL=paths.js.map

package/dist/core/repo/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../../src/core/repo/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,YAAY,EAAkD,MAAM,uBAAuB,CAAC;AAIrG,kFAAkF;AAClF,MAAM,CAAC,MAAM,WAAW,GAAG,SAAS,CAAC;AAErC,wEAAwE;AACxE,yEAAyE;AACzE,wEAAwE;AAExE;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,KAAK,EAAE,cAAc;IACrB,IAAI,EAAE,SAAS;IACf,QAAQ,EAAE,cAAc;IACxB,OAAO,EAAE,cAAc;IACvB,QAAQ,EAAE,eAAe;IACzB,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE,aAAa;IACrB,KAAK,EAAE,YAAY;CACX,CAAC;AACX,MAAM,QAAQ,GAAG,MAAM,CAAC;AAExB,yGAAyG;AACzG,MAAM,UAAU,qBAAqB,CAAC,IAAY,EAAE,IAAoB;IACtE,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO,IAAI,KAAK,QAAQ,CAAC;IAC7C,OAAO,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;AACrE,CAAC;AA4BD;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,GAAe;IAC5C,OAAO;QACL,GAAG;QACH,KAAK,EAAE,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,KAAK,CAAC;QACtC,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,IAAI,CAAC;QACpC,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,QAAQ,CAAC;QAC5C,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,OAAO,CAAC;QAC1C,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,QAAQ,CAAC;QAC5C,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,OAAO,CAAC;QAC1C,MAAM,EAAE,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,MAAM,CAAC;QACxC,KAAK,EAAE,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,KAAK,CAAC;QACtC,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC;KAC7B,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAgB,EAAE,OAAwB;IAC5E,OAAO,cAAc,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;AAC1E,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,YAAoB,EAAE,OAAwB;IAC9E,OAAO,cAAc,CAAC,YAAY,CAAC,IAAI,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;AACnE,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,SAAiB,EAAE,IAAmB;IACvE,OAAO,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;AAC/B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,cAAc,EAAE;IACvD,EAAE,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,mBAAmB,EAAE;CAC7D,CAAC;AAWX,MAAM,UAAU,YAAY,CAAC,UAAsB;IACjD,OAAO;QACL,GAAG,EAAE,UAAU;QACf,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,WAAW,CAAC;QACrC,KAAK,EAAE,IAAI,CAAC,UAAU,EAAE,cAAc,CAAC;QACvC,QAAQ,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC;QACnC,OAAO,EAAE,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC;KAClC,CAAC;AACJ,CAAC;AAWD,MAAM,UAAU,gBAAgB,CAAC,UAAsB,EAAE,OAAwB;IAC/E,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAC/C,OAAO;QACL,GAAG;QACH,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC;QAC1B,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC;QACnC,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC;QAClC,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,eAAe,CAAC;KACrC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,OAAgB;IAC5C,OAAO,IAAI,CAAC,OAAO,EAAE,cAAc,EAAE,cAAc,CAAC,CAAC;AACvD,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,OAAO,IAAI,CAAC,OAAO,EAAE,cAAc,EAAE,kBAAkB,CAAC,CAAC;AAC3D,CAAC;AAED,qGAAqG;AACrG,MAAM,UAAU,gBAAgB,CAAC,OAAgB;IAC/C,OAAO,IAAI,CAAC,OAAO,EAAE,cAAc,EAAE,mBAAmB,CAAC,CAAC;AAC5D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,OAAO,IAAI,CAAC,OAAO,EAAE,cAAc,EAAE,kBAAkB,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,YAAY,CAAC,OAAgB;IAC3C,OAAO,IAAI,CAAC,OAAO,EAAE,cAAc,EAAE,QAAQ,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAgB;IACjD,OAAO,IAAI,CAAC,OAAO,EAAE,cAAc,EAAE,oBAAoB,CAAC,CAAC;AAC7D,CAAC;AAED,+FAA+F;AAC/F,MAAM,oBAAoB,GAAG,mBAAmB,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,wBAAwB,CAAC,GAAW;IAClD,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC7B,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,WAAW,EAAE,CAAC;QAC7B,OAAO,KAAK,WAAW,gGAAgG,CAAC;IAC1H,CAAC;IACD,IAAI,GAAG,KAAK,oBAAoB,EAAE,CAAC;QACjC,OAAO,mMAAmM,CAAC;IAC7M,CAAC;IACD,IAAI,GAAG,KAAK,cAAc,EAAE,CAAC;QAC3B,OAAO,iGAAiG,CAAC;IAC3G,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,yGAAyG;AACzG,MAAM,cAAc,GAAG,kBAAkB,CAAC;AAC1C,MAAM,WAAW,GAAG,UAAU,CAAC;AAE/B,MAAM,UAAU,WAAW,CAAC,OAAgB;IAC1C,OAAO,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;AACnC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,OAAgB;IAC1C,OAAO,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;AACnC,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,WAAW,CAAC;AAE3C,MAAM,UAAU,UAAU,CAAC,OAAgB;IACzC,OAAO,IAAI,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,OAAgB;IACzC,OAAO,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC,CAAC;AACjD,CAAC","sourcesContent":["/**\n * Where every artifact lives. Artifact filenames are spelled here and nowhere\n * else, so a rename is one edit rather than a grep.\n *\n * This is also the module that carries loam's one path guarantee.\n * `unfiledServicePaths(docsDir, service)` spells `<docsDir>/services/<service>/`,\n * so both parts are caller-controlled path input, and `node:path` cannot help:\n * `join(...paths: string[])` accepts every string there is. The guarantee IS\n * the parameter brands and nothing else — `PathableService` for the id (a name\n * whose provenance is the repository, unconstructible from document text),\n * `DocsDir`/`FeatureDir` for the roots (a resolved config or validated\n * `--docs`; a directory an enumeration read), and `ServiceDir` for\n * `servicePathsAt` (the enumeration's own resolved directory, narrower still)\n * — the `kernel/ids/` package holds the only casts, so an unchecked value at\n * these call sites does not compile.\n * Code that spells `services/<id>/` or a feature layout with a bare join is\n * outside the guarantee — `commands/new.ts` and the openspec migrator both do,\n * held instead by `resolveInside` at the write.\n */\nimport { join } from \"node:path\";\nimport { serviceDirOf, type DocsDir, type FeatureDir, type ServiceDir } from \"../kernel/ids/dirs.js\";\nimport type { PathableService } from \"../kernel/ids/service.js\";\nimport type { SubsystemName } from \"../kernel/ids/subsystem.js\";\n\n/** Directory under features/ holding shipped features. Never a feature itself. */\nexport const ARCHIVE_DIR = \"archive\";\n\n/* ------------------------------------------------------------------ */\n/* Paths — artifact filenames are spelled here and nowhere else        */\n/* ------------------------------------------------------------------ */\n\n/**\n * The living artifact filenames, as one table, because three questions read\n * them: `servicePathsAt` below spells the paths, the tree walk classifies\n * a directory as a service by whether any of these names sit in it, and\n * `core/diff/base-state.ts` classifies the SAME way over a base git ref's\n * tree listing (exported for that reader — a filename respelled there would\n * be the drift this table exists to prevent). The walk cannot import this\n * module — `repo → repo/tree` is the package direction, and an edge back\n * would be the cycle `scripts/package-graph.mjs` refuses — so `repo.ts`\n * injects `isServiceArtifactName` into the walk request instead.\n */\nexport const ARTIFACT_FILES = {\n  model: \"model.likec4\",\n  spec: \"spec.md\",\n  archSpec: \"arch.spec.md\",\n  openapi: \"openapi.yaml\",\n  asyncapi: \"asyncapi.yaml\",\n  runbook: \"runbook.md\",\n  health: \"health.yaml\",\n  steps: \"steps.yaml\",\n} as const;\nconst ADRS_DIR = \"adrs\";\n\n/** Does a directory entry name a living service artifact? The classification half of the table above. */\nexport function isServiceArtifactName(name: string, kind: \"file\" | \"dir\"): boolean {\n  if (kind === \"dir\") return name === ADRS_DIR;\n  return Object.values(ARTIFACT_FILES).some((file) => file === name);\n}\n\nexport interface ServicePaths {\n  dir: ServiceDir;\n  model: string;\n  spec: string;\n  archSpec: string;\n  openapi: string;\n  /** The async contract — the event axis's sibling of `openapi`. */\n  asyncapi: string;\n  runbook: string;\n  health: string;\n  /**\n   * The step catalogue — which phrases this service's suite has DECIDED to\n   * define. Authored and opt-in; its CONTENTS are read by `loam steps` alone and\n   * nothing in `validate` consults them\n   * (`core/gherkin/steps/catalogue.ts` records why).\n   *\n   * Its EXISTENCE is read more widely, and that is not the same statement: the\n   * filename is in `ARTIFACT_FILES`, so `isServiceArtifactName` classifies it\n   * and the tree walk treats a directory holding one as a service. That is\n   * correct — it is a service artifact — and it is worth writing down, because\n   * it means a `steps.yaml` written at the wrong path mints a service.\n   */\n  steps: string;\n  adrsDir: string;\n}\n\n/**\n * The artifact paths of a service whose directory is already KNOWN — the\n * enumeration's `dir`, at whatever depth the tree walk found it. This is the\n * spelling every reader of an existing service must use: joining\n * `services/<id>/` at the root is only true for a fleet nobody has filed, and\n * a moved service would silently grade as absent through it.\n */\nexport function servicePathsAt(dir: ServiceDir): ServicePaths {\n  return {\n    dir,\n    model: join(dir, ARTIFACT_FILES.model),\n    spec: join(dir, ARTIFACT_FILES.spec),\n    archSpec: join(dir, ARTIFACT_FILES.archSpec),\n    openapi: join(dir, ARTIFACT_FILES.openapi),\n    asyncapi: join(dir, ARTIFACT_FILES.asyncapi),\n    runbook: join(dir, ARTIFACT_FILES.runbook),\n    health: join(dir, ARTIFACT_FILES.health),\n    steps: join(dir, ARTIFACT_FILES.steps),\n    adrsDir: join(dir, ADRS_DIR),\n  };\n}\n\n/**\n * The UNFILED spelling — `<docsDir>/services/<id>/`, the tree's root level.\n * This is where creation lands (`adopt`'s brief, a new service materialised by\n * `archive`, the OpenSpec migration) and the honest fallback for a service the\n * enumeration does not answer; for a service that EXISTS, resolve through the\n * enumeration instead (`servicePathsAt(entry.dir)`, or\n * `locateServicePaths` in `service-target.ts`, which chooses between the two).\n * Renamed from `servicePaths` when the tree landed, precisely so the compiler\n * would put every remaining caller in front of a reviewer: a root join that\n * survives unreviewed is a moved service silently grading as absent.\n */\nexport function unfiledServicePaths(docsDir: DocsDir, service: PathableService): ServicePaths {\n  return servicePathsAt(serviceDirOf(join(docsDir, \"services\", service)));\n}\n\n/**\n * The creation spelling INSIDE a subsystem — `<subsystemDir>/<id>/`, the\n * target `adopt --subsystem` briefs so an adoption need not land unfiled and\n * cost a second command. The same two provenances the unfiled spelling\n * combines, one level down: the subsystem directory came off the tree walk's\n * readdir, and the id passed the service grammar before it reached here.\n */\nexport function servicePathsUnder(subsystemDir: string, service: PathableService): ServicePaths {\n  return servicePathsAt(serviceDirOf(join(subsystemDir, service)));\n}\n\n/**\n * The directory a SUBSYSTEM occupies (or will occupy) under a parent — the\n * spelling `subsystem new` creates and `subsystem rename` renames into. The\n * same guarantee-by-brand as the service spellings above: the parent came off\n * the tree walk's readdir (or is `servicesDir` itself), and demanding\n * `SubsystemName` here is what makes the validator unskippable — a raw argv\n * string at this call site does not compile, so no future verb can hoist the\n * join above the check that earns it.\n */\nexport function subsystemPathUnder(parentDir: string, name: SubsystemName): string {\n  return join(parentDir, name);\n}\n\n/**\n * The pair of requirement-carrying spec files, living and delta alike: the\n * business spec and the architecture spec. Same grammar, same delta algebra,\n * same merge — everything that walks \"the spec files\" of a service walks this\n * list, so the two axes cannot drift apart in what handles them. `key` indexes\n * ServicePaths/FeatureSpecPaths; `label` is how the axis names itself in prose.\n */\nexport const SPEC_AXES = [\n  { key: \"spec\", file: \"spec.md\", label: \"requirements\" },\n  { key: \"archSpec\", file: \"arch.spec.md\", label: \"arch requirements\" },\n] as const;\nexport type SpecAxis = (typeof SPEC_AXES)[number];\n\nexport interface FeaturePaths {\n  dir: string;\n  intent: string;\n  delta: string;\n  specsDir: string;\n  adrsDir: string;\n}\n\nexport function featurePaths(featureDir: FeatureDir): FeaturePaths {\n  return {\n    dir: featureDir,\n    intent: join(featureDir, \"intent.md\"),\n    delta: join(featureDir, \"delta.likec4\"),\n    specsDir: join(featureDir, \"specs\"),\n    adrsDir: join(featureDir, \"adrs\"),\n  };\n}\n\nexport interface FeatureSpecPaths {\n  dir: string;\n  spec: string;\n  archSpec: string;\n  openapi: string;\n  /** The async contract delta — the event axis's sibling of `openapi`. */\n  asyncapi: string;\n}\n\nexport function featureSpecPaths(featureDir: FeatureDir, service: PathableService): FeatureSpecPaths {\n  const dir = join(featureDir, \"specs\", service);\n  return {\n    dir,\n    spec: join(dir, \"spec.md\"),\n    archSpec: join(dir, \"arch.spec.md\"),\n    openapi: join(dir, \"openapi.yaml\"),\n    asyncapi: join(dir, \"asyncapi.yaml\"),\n  };\n}\n\nexport function landscapePath(docsDir: DocsDir): string {\n  return join(docsDir, \"architecture\", LANDSCAPE_FILE);\n}\n\n/** The fleet's authorization vocabulary — beside the fleet map, for the same reason. */\nexport function permissionsPath(docsDir: DocsDir): string {\n  return join(docsDir, \"architecture\", \"permissions.yaml\");\n}\n\n/** The fleet's capability vocabulary — beside the other two fleet documents, for the same reason. */\nexport function capabilitiesPath(docsDir: DocsDir): string {\n  return join(docsDir, \"architecture\", \"capabilities.yaml\");\n}\n\n/**\n * The fleet's ARCHITECTURAL OBLIGATION vocabulary — beside the landscape it tags\n * and the two vocabularies it sits with, for their reason: it is a fact about\n * the fleet that no single service owns.\n */\nexport function obligationsPath(docsDir: DocsDir): string {\n  return join(docsDir, \"architecture\", \"obligations.yaml\");\n}\n\n/**\n * The FLEET's decision records — `architecture/adrs/`, beside the landscape and\n * the two vocabularies.\n *\n * ADRs used to exist at two altitudes only, `services/<id>/adrs/` and\n * `features/<FEAT>/adrs/`, so a decision about the fleet itself — \"event\n * publishers use a transactional outbox\", \"cross-service calls carry a circuit\n * breaker\" — had no home but one arbitrary service's directory, where the next\n * reader of the other fifty services never finds it. This is not a new axis: it\n * is the same `ADRS_DIR` name one level up, spelled through the same constant so\n * the two altitudes cannot drift into `adrs/` and `decisions/`.\n *\n * PRESENCE-TRACKED AND NOTHING MORE, exactly like the service directory it\n * mirrors: `loam list` counts the files (`repo.ts`'s `fleetAdrCount`) and no\n * check anywhere reads one. A fleet with no fleet-level ADRs owes nothing and\n * must produce no finding — which is also why `loam init` does NOT scaffold the\n * directory. git does not carry an empty one, so it would vanish on the first\n * clone and come back as a diff on the next `init`; and an empty `adrs/` in a\n * fresh repo reads as an obligation nobody has met, when there is no obligation\n * at all.\n */\nexport function fleetAdrsDir(docsDir: DocsDir): string {\n  return join(docsDir, \"architecture\", ADRS_DIR);\n}\n\n/**\n * The GENERATED subsystem views — beside the fleet map because the LikeC4\n * renderer merges the whole `architecture/` project, and a view can only\n * `include` elements the landscape beside it defines. `loam subsystem sync`\n * owns the bytes (`core/repo/tree/views.ts` renders them); nothing in loam\n * ever parses the file, and staleness against the tree is a byte compare.\n */\nexport function subsystemViewsPath(docsDir: DocsDir): string {\n  return join(docsDir, \"architecture\", SUBSYSTEM_VIEWS_FILE);\n}\n\n/** The generated views' file name, spelled once because the reservation below reads it too. */\nconst SUBSYSTEM_VIEWS_FILE = \"subsystems.likec4\";\n\n/**\n * Names inside `architecture/` that LOAM owns, and what goes wrong if a\n * feature's own document claims one.\n *\n * `features/<FEAT>/deployment/<name>.likec4` merges as a whole-file copy\n * straight into `architecture/` — unlike a flow, which lands under\n * `usecases/` — so its `<name>` is free to be any of these, and two of them\n * fail in ways nothing downstream would report:\n *\n *  - `subsystems.likec4` is GENERATED and is EXCLUDED from every project load\n *    (docs/DESIGN.md rule 26 keeps it a byte compare), so topology landing\n *    there is invisible to loam from the moment it archives — and the next\n *    `loam subsystem sync` overwrites the file wholesale. Silent both ways,\n *    which is the worst shape a failure can have;\n *  - `landscape.likec4` is the living map the archive SPLICES; a whole-file\n *    copy over it would discard the fleet;\n *  - `usecases/` is the flow tree, walked by the use-case scan. A deployment\n *    document filed there parses (one project) and is then looked for by a\n *    reader asking a different question.\n *\n * Returns the reason, or null when the name is the author's to choose. Takes\n * the `/`-separated rel a directory walk produced, never a string from argv.\n */\nexport function reservedArchitectureName(rel: string): string | null {\n  const parts = rel.split(\"/\");\n  if (parts[0] === USECASE_DIR) {\n    return `\\`${USECASE_DIR}/\\` is the use-case tree — a flow belongs in \\`features/<FEAT>/usecases/\\`, which merges there`;\n  }\n  if (rel === SUBSYSTEM_VIEWS_FILE) {\n    return \"`subsystems.likec4` is generated by `loam subsystem sync`, which overwrites it wholesale — and nothing in loam ever parses it, so anything landing there is invisible from the moment it archives\";\n  }\n  if (rel === LANDSCAPE_FILE) {\n    return \"`landscape.likec4` is the living fleet map, which the archive SPLICES into rather than replaces\";\n  }\n  return null;\n}\n\n/** The living map's file name, and the flow tree's directory — spelled once, read by the reservation. */\nconst LANDSCAPE_FILE = \"landscape.likec4\";\nconst USECASE_DIR = \"usecases\";\n\nexport function featuresDir(docsDir: DocsDir): string {\n  return join(docsDir, \"features\");\n}\n\n/**\n * The root of the tree that IS the fleet — where an unfiled service and a\n * root-level subsystem both sit. The `subsystem` verbs join validated names\n * under it; the enumerating walk spells the same join for itself\n * (`repo/tree/walk.ts`), because it cannot import this module.\n */\nexport function servicesDir(docsDir: DocsDir): string {\n  return join(docsDir, \"services\");\n}\n\n/**\n * The agent contract's filename, and where it sits in a docs repo.\n *\n * Both spellings are exported because the two questions are different: `init`,\n * `doctor` and `validate` want a path under a docsDir they already hold, while\n * `docs.ts` builds the scaffold as `[relative path, bytes]` pairs and needs the\n * bare name. Four modules spelled the literal out for themselves, and one of\n * them — `init` — uses it to decide whether a directory IS a docs repo at all,\n * so a rename that reached three of the four would leave `init` recognising a\n * file nothing else writes any more.\n *\n * `openspec-inventory.ts`'s \"AGENTS.md\" is deliberately NOT this constant: it\n * names a file in a foreign OpenSpec tree that happens to share the name.\n */\nexport const AGENTS_FILENAME = \"AGENTS.md\";\n\nexport function agentsPath(docsDir: DocsDir): string {\n  return join(docsDir, AGENTS_FILENAME);\n}\n\n/**\n * Where shipped features live. `features/archive/` is spelled here and nowhere\n * else for the same reason every other artifact path is: `archive` and\n * `unarchive` move directories in and out of it, and a layout string that two\n * commands re-derive is a layout two commands can disagree about. The\n * `features/archive/…` strings in refusal PROSE are not this path — they are\n * what a reader types into `ls`, and they stay spelled out.\n */\nexport function archiveDir(docsDir: DocsDir): string {\n  return join(featuresDir(docsDir), ARCHIVE_DIR);\n}\n"]}

package/dist/core/repo/repo.js

@@ -0,0 +1,248 @@
+/**
+ * Read model of the docs repo — enumeration, and only by the filesystem.
+ *
+ * Files are the source of truth, so `services/` IS the list of services and
+ * there is no manifest that can disagree with it. The shapes this hands back
+ * live in `entries.ts`, the layout it walks in `paths.ts`, and whether there is
+ * a repo to walk at all in `state.ts`.
+ */
+import { existsSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { listField, readFrontmatter, stringField } from "../document/frontmatter.js";
+import { featureDirOf } from "../kernel/ids/dirs.js";
+import { rawServiceId, serviceIdProblem } from "../kernel/ids/service.js";
+import { readVouchScope } from "../provenance/sample/scope.js";
+import { compareIds, featureIdFromDirName } from "./entries.js";
+import { ARCHIVE_DIR, featurePaths, featuresDir, fleetAdrsDir, isServiceArtifactName, servicePathsAt } from "./paths.js";
+import { requireDocsRepo } from "./state.js";
+import { countMarkdown, entryIs } from "./tree/fs.js";
+import { walkServicesTree } from "./tree/walk.js";
+/* ------------------------------------------------------------------ */
+/* Enumeration                                                         */
+/* ------------------------------------------------------------------ */
+/**
+ * Sorted names of the real subdirectories of `dir` (dot-dirs and files skipped).
+ * A missing `dir` is an empty list — the swallow is deliberate but narrow: it
+ * only ever runs INSIDE a docs repo that `requireDocsRepo` has already
+ * confirmed, where an absent `features/` or `specs/` means "none yet" and
+ * nothing else.
+ */
+async function subdirs(dir) {
+    if (!existsSync(dir))
+        return [];
+    const entries = await readdir(dir, { withFileTypes: true });
+    return entries
+        .filter((e) => !e.name.startsWith(".") && entryIs(dir, e, "dir"))
+        .map((e) => e.name)
+        .sort(compareIds);
+}
+/** Services a feature carries a delta for, ordered — the subdirs of its specs/. */
+export async function featureSpecServices(featureDir, context) {
+    if (context !== undefined)
+        return context.featureSpecServices(featureDir);
+    return (await subdirs(featurePaths(featureDir).specsDir)).map(rawServiceId);
+}
+/**
+ * The classified `services/` tree — services at any depth, the subsystems
+ * grouping them, and the walk's own findings (`subsystem.*`). The walk itself
+ * lives in `./tree/walk.ts` and never imports back into this package; this
+ * function is where its two injected dependencies are built — the docs-repo
+ * precondition and the artifact-name table `paths.ts` owns.
+ */
+export async function listFleetTree(docsDir, context) {
+    if (context !== undefined)
+        return context.fleetTree(docsDir);
+    requireDocsRepo(docsDir, ["ok"]);
+    return walkServicesTree({ docsDir, isServiceArtifact: isServiceArtifactName });
+}
+/** Every service in the docs repo, at any depth of the tree, ordered by id. */
+export async function listServices(docsDir, context) {
+    if (context !== undefined)
+        return context.listServices(docsDir);
+    return serviceEntries(await listFleetTree(docsDir));
+}
+/**
+ * The full entries for a walked tree — frontmatter, artifact presence, ADR
+ * count. Split from `listServices` so `FleetContext` can derive its services
+ * memo from its tree memo: one walk per invocation answers both questions.
+ * Ordering is `compareIds` over the id wherever the service sits — placement
+ * is never part of any identity, and `--json` consumers diff this order — with
+ * the directory as the tiebreak so a duplicated id (its own error finding)
+ * still lists deterministically.
+ */
+/**
+ * The second spec axis's header, or an empty one when nobody could read it.
+ *
+ * `readFrontmatter` folds a decode failure into a flag but still THROWS when
+ * the path exists and cannot be read as a file at all — a directory named
+ * `arch.spec.md`, which test/gate-command.test.ts builds on purpose. This is
+ * the fleet ENUMERATION, where one service's bad byte must cost one subject
+ * and not the listing of the other 119, so the throw stops here.
+ *
+ * The distinction between "no scope" and "nobody could look" is not lost by
+ * swallowing it: a path that exists and cannot be read is `service.unreadable`
+ * — an ERROR that fails `loam validate` and `loam gate` — which is a louder
+ * signal than any row of a listing, and it names the file this cannot.
+ */
+async function archHeader(path) {
+    try {
+        return await readFrontmatter(path);
+    }
+    catch {
+        return { present: false, malformed: false, data: {}, body: "" };
+    }
+}
+export async function serviceEntries(tree) {
+    const entries = await Promise.all(tree.services.map(async (svc) => {
+        const p = servicePathsAt(svc.dir);
+        // Both spec axes, because a sample is per FILE: one `--sample 3` run can
+        // read a short spec.md in full and stamp a scope on a long arch.spec.md
+        // beside it, and a fleet row that reported only spec.md's header would
+        // print that service as fully vouched while `loam validate` reported it
+        // sampled. `readFrontmatter` answers "absent" for a file that is not
+        // there, so a service without the second axis pays one existsSync.
+        const [fm, archFm] = await Promise.all([readFrontmatter(p.spec), archHeader(p.archSpec)]);
+        const idProblem = serviceIdProblem(svc.id, "directory name");
+        return {
+            id: svc.id,
+            dir: svc.dir,
+            subsystem: svc.subsystem,
+            ...(idProblem === null ? {} : { idProblem }),
+            has: {
+                model: existsSync(p.model),
+                spec: existsSync(p.spec),
+                openapi: existsSync(p.openapi),
+                asyncapi: existsSync(p.asyncapi),
+                runbook: existsSync(p.runbook),
+                health: existsSync(p.health),
+            },
+            adrs: await countMarkdown(p.adrsDir),
+            status: stringField(fm, "status") ?? null,
+            sources: {
+                declared: listField(fm, "sources").length > 0,
+                stamped: stringField(fm, "sources_digest") !== undefined,
+            },
+            // Either axis makes the SERVICE sampled, and presence is the test, not
+            // decodability: an unreadable scope is still a stamped partial read
+            // (core/provenance/sample/scope.ts's `readVouchScope`), and the fleet
+            // listing is the last place a mangled field should be able to buy
+            // itself a full-trust row.
+            vouchScope: [fm, archFm].some((header) => readVouchScope(header).kind !== "none") ? "sampled" : null,
+        };
+    }));
+    return entries.sort((a, b) => compareIds(a.id, b.id) || compareIds(a.dir, b.dir));
+}
+/**
+ * How many fleet-level ADRs `architecture/adrs/` holds — the same number, by the
+ * same rule (`countMarkdown`), that `ServiceEntry.adrs` carries one altitude
+ * down. One shape for one question: a second spelling of "count the decisions"
+ * is how `list` and `show` once reported different ADR counts for one service.
+ *
+ * A count and never a finding. The directory is optional, an absent one is 0,
+ * and nothing in loam grades either — see `fleetAdrsDir` for why that is the
+ * whole design rather than an unfinished half of it. No `FleetContext` overload:
+ * one caller asks this once per invocation, and a memo whose key is the docsDir
+ * would be a cache nobody reads twice.
+ */
+export async function fleetAdrCount(docsDir) {
+    return countMarkdown(fleetAdrsDir(docsDir));
+}
+async function readFeature(dir, dirName, archived) {
+    const p = featurePaths(dir);
+    return {
+        id: featureIdFromDirName(dirName),
+        dirName,
+        dir,
+        archived,
+        services: (await subdirs(p.specsDir)).map(rawServiceId),
+        has: { intent: existsSync(p.intent), delta: existsSync(p.delta) },
+    };
+}
+/**
+ * Features in the docs repo, ordered by id (active and archived interleaved when
+ * both are asked for). `features/archive/` is the archive, never a feature.
+ */
+export async function listFeatures(docsDir, opts = {}, context) {
+    if (context !== undefined)
+        return context.listFeatures(docsDir, opts);
+    // "no-services" is tolerated here on purpose: a docs repo whose services/ is
+    // gone is broken, but it is `listServices` (and `loam doctor`) that says so.
+    // Refusing here too would turn one diagnosis into two contradictory ones.
+    requireDocsRepo(docsDir, ["ok", "no-services"]);
+    const root = featuresDir(docsDir);
+    const active = (await subdirs(root)).filter((n) => n !== ARCHIVE_DIR);
+    // Branded at the join: the name came off this readdir, onto the features
+    // root it was listed under — the provenance `FeatureDir` records.
+    const out = await Promise.all(active.map((n) => readFeature(featureDirOf(join(root, n)), n, false)));
+    if (opts.includeArchived) {
+        const archiveRoot = join(root, ARCHIVE_DIR);
+        const archived = await subdirs(archiveRoot);
+        out.push(...(await Promise.all(archived.map((n) => readFeature(featureDirOf(join(archiveRoot, n)), n, true)))));
+    }
+    return out.sort((a, b) => compareIds(a.id, b.id) || compareIds(a.dirName, b.dirName));
+}
+/**
+ * Resolve a feature argument — a canonical id (`FEAT-5`) or an exact directory
+ * name (`FEAT-5-slug`) — to its entry. The entry's `id` is the canonical
+ * spelling, and it is the only name a caller may use from here on: tag filters,
+ * coherence, and the cross-feature self-exclusion scans all compare against
+ * `feature.id`, never against the raw argument.
+ *
+ * Matching is EXACT, on one of two spellings: the directory name as it is on
+ * disk, or the canonical id derived from it. It used to also match any dirName
+ * starting with `arg + "-"`, which made the argument a prefix query in
+ * disguise: with FEAT-401 and FEAT-402 in flight, `loam archive FEAT` archived
+ * whichever sorted first, and `loam delta billing` reached into
+ * `billing-7-rewrite`. A destructive command must never pick a target the
+ * caller did not name, so a prefix now resolves to nothing at all.
+ *
+ * An exact directory name still wins over the id spelling (`FEAT-5` the
+ * directory over `FEAT-5-slug`, whose id is also `FEAT-5`), and under "include"
+ * an active feature wins over an archived one. Ties among equally-exact
+ * candidates go to the first by name — deterministic, unlike the raw readdir
+ * order this replaces; `ambiguousFeatureMessage` lists them for the caller.
+ */
+export async function resolveFeature(docsDir, arg, archived, context) {
+    return (await featureCandidates(docsDir, arg, archived, context))[0] ?? null;
+}
+/**
+ * Every feature the argument names exactly, best first. Split out of
+ * `resolveFeature` so a caller that wants to REFUSE an ambiguous argument can
+ * see the tie instead of inheriting the winner.
+ */
+export async function featureCandidates(docsDir, arg, archived, context) {
+    const all = await listFeatures(docsDir, { includeArchived: archived !== "exclude" }, context);
+    return all
+        .filter((f) => archived === "include" || f.archived === (archived === "only"))
+        .filter((f) => f.dirName === arg || f.id === arg)
+        .sort((a, b) => Number(b.dirName === arg) - Number(a.dirName === arg) ||
+        Number(a.archived) - Number(b.archived) ||
+        compareIds(a.dirName, b.dirName));
+}
+/**
+ * The message for an argument that names more than one feature — two directories
+ * carrying the same id (`FEAT-6-aaa` and `FEAT-6-zzz`). `resolveFeature` still
+ * picks one deterministically, but a command that is about to WRITE should say
+ * which directories collided and make the caller spell one out.
+ */
+export function ambiguousFeatureMessage(arg, candidates) {
+    return (`'${arg}' names ${candidates.length} features: ${candidates.map((c) => c.dirName).join(", ")}. ` +
+        "Pass the directory name you mean.");
+}
+/**
+ * The message for an exclude-mode miss. When the feature exists under
+ * `features/archive/`, "no feature" is a lie the caller would have to debug —
+ * the honest answer is "already archived", plus how to look at it. The `--json`
+ * code stays `unknown-target` either way: the target is unknown to the command
+ * that asked, and the prose carries the diagnosis.
+ */
+export async function missingFeatureMessage(docsDir, arg, context) {
+    const shipped = await resolveFeature(docsDir, arg, "only", context);
+    if (shipped !== null) {
+        return (`Feature '${shipped.id}' is already archived (features/archive/${shipped.dirName}) — ` +
+            `\`loam show ${shipped.id}\` reads it, \`loam unarchive ${shipped.id}\` re-opens it.`);
+    }
+    return `No feature '${arg}' under ${featuresDir(docsDir)}.`;
+}
+//# sourceMappingURL=repo.js.map

package/dist/core/repo/repo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo.js","sourceRoot":"","sources":["../../../src/core/repo/repo.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Read model of the docs repo — enumeration, and only by the filesystem.\n *\n * Files are the source of truth, so `services/` IS the list of services and\n * there is no manifest that can disagree with it. The shapes this hands back\n * live in `entries.ts`, the layout it walks in `paths.ts`, and whether there is\n * a repo to walk at all in `state.ts`.\n */\nimport { existsSync } from \"node:fs\";\nimport { readdir } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { listField, readFrontmatter, stringField, type Frontmatter } from \"../document/frontmatter.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\nimport { featureDirOf, type DocsDir, type FeatureDir } from \"../kernel/ids/dirs.js\";\nimport { rawServiceId, serviceIdProblem, type RawServiceId } from \"../kernel/ids/service.js\";\nimport { readVouchScope } from \"../provenance/sample/scope.js\";\nimport { compareIds, featureIdFromDirName, type FeatureEntry, type ServiceEntry } from \"./entries.js\";\nimport { ARCHIVE_DIR, featurePaths, featuresDir, fleetAdrsDir, isServiceArtifactName, servicePathsAt } from \"./paths.js\";\nimport { requireDocsRepo } from \"./state.js\";\nimport { countMarkdown, entryIs } from \"./tree/fs.js\";\nimport { walkServicesTree, type FleetTree } from \"./tree/walk.js\";\n\n/* ------------------------------------------------------------------ */\n/* Enumeration                                                         */\n/* ------------------------------------------------------------------ */\n\n/**\n * Sorted names of the real subdirectories of `dir` (dot-dirs and files skipped).\n * A missing `dir` is an empty list — the swallow is deliberate but narrow: it\n * only ever runs INSIDE a docs repo that `requireDocsRepo` has already\n * confirmed, where an absent `features/` or `specs/` means \"none yet\" and\n * nothing else.\n */\nasync function subdirs(dir: string): Promise<string[]> {\n  if (!existsSync(dir)) return [];\n  const entries = await readdir(dir, { withFileTypes: true });\n  return entries\n    .filter((e) => !e.name.startsWith(\".\") && entryIs(dir, e, \"dir\"))\n    .map((e) => e.name)\n    .sort(compareIds);\n}\n\n/** Services a feature carries a delta for, ordered — the subdirs of its specs/. */\nexport async function featureSpecServices(\n  featureDir: FeatureDir,\n  context?: FleetContext,\n): Promise<RawServiceId[]> {\n  if (context !== undefined) return context.featureSpecServices(featureDir);\n  return (await subdirs(featurePaths(featureDir).specsDir)).map(rawServiceId);\n}\n\n/**\n * The classified `services/` tree — services at any depth, the subsystems\n * grouping them, and the walk's own findings (`subsystem.*`). The walk itself\n * lives in `./tree/walk.ts` and never imports back into this package; this\n * function is where its two injected dependencies are built — the docs-repo\n * precondition and the artifact-name table `paths.ts` owns.\n */\nexport async function listFleetTree(docsDir: DocsDir, context?: FleetContext): Promise<FleetTree> {\n  if (context !== undefined) return context.fleetTree(docsDir);\n  requireDocsRepo(docsDir, [\"ok\"]);\n  return walkServicesTree({ docsDir, isServiceArtifact: isServiceArtifactName });\n}\n\n/** Every service in the docs repo, at any depth of the tree, ordered by id. */\nexport async function listServices(docsDir: DocsDir, context?: FleetContext): Promise<ServiceEntry[]> {\n  if (context !== undefined) return context.listServices(docsDir);\n  return serviceEntries(await listFleetTree(docsDir));\n}\n\n/**\n * The full entries for a walked tree — frontmatter, artifact presence, ADR\n * count. Split from `listServices` so `FleetContext` can derive its services\n * memo from its tree memo: one walk per invocation answers both questions.\n * Ordering is `compareIds` over the id wherever the service sits — placement\n * is never part of any identity, and `--json` consumers diff this order — with\n * the directory as the tiebreak so a duplicated id (its own error finding)\n * still lists deterministically.\n */\n/**\n * The second spec axis's header, or an empty one when nobody could read it.\n *\n * `readFrontmatter` folds a decode failure into a flag but still THROWS when\n * the path exists and cannot be read as a file at all — a directory named\n * `arch.spec.md`, which test/gate-command.test.ts builds on purpose. This is\n * the fleet ENUMERATION, where one service's bad byte must cost one subject\n * and not the listing of the other 119, so the throw stops here.\n *\n * The distinction between \"no scope\" and \"nobody could look\" is not lost by\n * swallowing it: a path that exists and cannot be read is `service.unreadable`\n * — an ERROR that fails `loam validate` and `loam gate` — which is a louder\n * signal than any row of a listing, and it names the file this cannot.\n */\nasync function archHeader(path: string): Promise<Frontmatter> {\n  try {\n    return await readFrontmatter(path);\n  } catch {\n    return { present: false, malformed: false, data: {}, body: \"\" };\n  }\n}\n\nexport async function serviceEntries(tree: FleetTree): Promise<ServiceEntry[]> {\n  const entries = await Promise.all(\n    tree.services.map(async (svc): Promise<ServiceEntry> => {\n      const p = servicePathsAt(svc.dir);\n      // Both spec axes, because a sample is per FILE: one `--sample 3` run can\n      // read a short spec.md in full and stamp a scope on a long arch.spec.md\n      // beside it, and a fleet row that reported only spec.md's header would\n      // print that service as fully vouched while `loam validate` reported it\n      // sampled. `readFrontmatter` answers \"absent\" for a file that is not\n      // there, so a service without the second axis pays one existsSync.\n      const [fm, archFm] = await Promise.all([readFrontmatter(p.spec), archHeader(p.archSpec)]);\n      const idProblem = serviceIdProblem(svc.id, \"directory name\");\n      return {\n        id: svc.id,\n        dir: svc.dir,\n        subsystem: svc.subsystem,\n        ...(idProblem === null ? {} : { idProblem }),\n        has: {\n          model: existsSync(p.model),\n          spec: existsSync(p.spec),\n          openapi: existsSync(p.openapi),\n          asyncapi: existsSync(p.asyncapi),\n          runbook: existsSync(p.runbook),\n          health: existsSync(p.health),\n        },\n        adrs: await countMarkdown(p.adrsDir),\n        status: stringField(fm, \"status\") ?? null,\n        sources: {\n          declared: listField(fm, \"sources\").length > 0,\n          stamped: stringField(fm, \"sources_digest\") !== undefined,\n        },\n        // Either axis makes the SERVICE sampled, and presence is the test, not\n        // decodability: an unreadable scope is still a stamped partial read\n        // (core/provenance/sample/scope.ts's `readVouchScope`), and the fleet\n        // listing is the last place a mangled field should be able to buy\n        // itself a full-trust row.\n        vouchScope: [fm, archFm].some((header) => readVouchScope(header).kind !== \"none\") ? \"sampled\" : null,\n      };\n    }),\n  );\n  return entries.sort((a, b) => compareIds(a.id, b.id) || compareIds(a.dir, b.dir));\n}\n\n/**\n * How many fleet-level ADRs `architecture/adrs/` holds — the same number, by the\n * same rule (`countMarkdown`), that `ServiceEntry.adrs` carries one altitude\n * down. One shape for one question: a second spelling of \"count the decisions\"\n * is how `list` and `show` once reported different ADR counts for one service.\n *\n * A count and never a finding. The directory is optional, an absent one is 0,\n * and nothing in loam grades either — see `fleetAdrsDir` for why that is the\n * whole design rather than an unfinished half of it. No `FleetContext` overload:\n * one caller asks this once per invocation, and a memo whose key is the docsDir\n * would be a cache nobody reads twice.\n */\nexport async function fleetAdrCount(docsDir: DocsDir): Promise<number> {\n  return countMarkdown(fleetAdrsDir(docsDir));\n}\n\nasync function readFeature(dir: FeatureDir, dirName: string, archived: boolean): Promise<FeatureEntry> {\n  const p = featurePaths(dir);\n  return {\n    id: featureIdFromDirName(dirName),\n    dirName,\n    dir,\n    archived,\n    services: (await subdirs(p.specsDir)).map(rawServiceId),\n    has: { intent: existsSync(p.intent), delta: existsSync(p.delta) },\n  };\n}\n\n/**\n * Features in the docs repo, ordered by id (active and archived interleaved when\n * both are asked for). `features/archive/` is the archive, never a feature.\n */\nexport async function listFeatures(\n  docsDir: DocsDir,\n  opts: { includeArchived?: boolean } = {},\n  context?: FleetContext,\n): Promise<FeatureEntry[]> {\n  if (context !== undefined) return context.listFeatures(docsDir, opts);\n  // \"no-services\" is tolerated here on purpose: a docs repo whose services/ is\n  // gone is broken, but it is `listServices` (and `loam doctor`) that says so.\n  // Refusing here too would turn one diagnosis into two contradictory ones.\n  requireDocsRepo(docsDir, [\"ok\", \"no-services\"]);\n  const root = featuresDir(docsDir);\n  const active = (await subdirs(root)).filter((n) => n !== ARCHIVE_DIR);\n  // Branded at the join: the name came off this readdir, onto the features\n  // root it was listed under — the provenance `FeatureDir` records.\n  const out = await Promise.all(active.map((n) => readFeature(featureDirOf(join(root, n)), n, false)));\n\n  if (opts.includeArchived) {\n    const archiveRoot = join(root, ARCHIVE_DIR);\n    const archived = await subdirs(archiveRoot);\n    out.push(...(await Promise.all(archived.map((n) => readFeature(featureDirOf(join(archiveRoot, n)), n, true)))));\n  }\n\n  return out.sort((a, b) => compareIds(a.id, b.id) || compareIds(a.dirName, b.dirName));\n}\n\n/**\n * Which side of `features/archive/` a lookup may land on. The policy is an\n * argument, not a default, so every command's stance on shipped features is\n * visible at its call site: delta/validate/archive work on in-flight features\n * (\"exclude\"), show/verify/new read shipped ones too (\"include\"), unarchive\n * takes back nothing else (\"only\").\n */\nexport type ArchivedPolicy = \"exclude\" | \"include\" | \"only\";\n\n/**\n * Resolve a feature argument — a canonical id (`FEAT-5`) or an exact directory\n * name (`FEAT-5-slug`) — to its entry. The entry's `id` is the canonical\n * spelling, and it is the only name a caller may use from here on: tag filters,\n * coherence, and the cross-feature self-exclusion scans all compare against\n * `feature.id`, never against the raw argument.\n *\n * Matching is EXACT, on one of two spellings: the directory name as it is on\n * disk, or the canonical id derived from it. It used to also match any dirName\n * starting with `arg + \"-\"`, which made the argument a prefix query in\n * disguise: with FEAT-401 and FEAT-402 in flight, `loam archive FEAT` archived\n * whichever sorted first, and `loam delta billing` reached into\n * `billing-7-rewrite`. A destructive command must never pick a target the\n * caller did not name, so a prefix now resolves to nothing at all.\n *\n * An exact directory name still wins over the id spelling (`FEAT-5` the\n * directory over `FEAT-5-slug`, whose id is also `FEAT-5`), and under \"include\"\n * an active feature wins over an archived one. Ties among equally-exact\n * candidates go to the first by name — deterministic, unlike the raw readdir\n * order this replaces; `ambiguousFeatureMessage` lists them for the caller.\n */\nexport async function resolveFeature(\n  docsDir: DocsDir,\n  arg: string,\n  archived: ArchivedPolicy,\n  context?: FleetContext,\n): Promise<FeatureEntry | null> {\n  return (await featureCandidates(docsDir, arg, archived, context))[0] ?? null;\n}\n\n/**\n * Every feature the argument names exactly, best first. Split out of\n * `resolveFeature` so a caller that wants to REFUSE an ambiguous argument can\n * see the tie instead of inheriting the winner.\n */\nexport async function featureCandidates(\n  docsDir: DocsDir,\n  arg: string,\n  archived: ArchivedPolicy,\n  context?: FleetContext,\n): Promise<FeatureEntry[]> {\n  const all = await listFeatures(docsDir, { includeArchived: archived !== \"exclude\" }, context);\n  return all\n    .filter((f) => archived === \"include\" || f.archived === (archived === \"only\"))\n    .filter((f) => f.dirName === arg || f.id === arg)\n    .sort(\n      (a, b) =>\n        Number(b.dirName === arg) - Number(a.dirName === arg) ||\n        Number(a.archived) - Number(b.archived) ||\n        compareIds(a.dirName, b.dirName),\n    );\n}\n\n/**\n * The message for an argument that names more than one feature — two directories\n * carrying the same id (`FEAT-6-aaa` and `FEAT-6-zzz`). `resolveFeature` still\n * picks one deterministically, but a command that is about to WRITE should say\n * which directories collided and make the caller spell one out.\n */\nexport function ambiguousFeatureMessage(arg: string, candidates: FeatureEntry[]): string {\n  return (\n    `'${arg}' names ${candidates.length} features: ${candidates.map((c) => c.dirName).join(\", \")}. ` +\n    \"Pass the directory name you mean.\"\n  );\n}\n\n/**\n * The message for an exclude-mode miss. When the feature exists under\n * `features/archive/`, \"no feature\" is a lie the caller would have to debug —\n * the honest answer is \"already archived\", plus how to look at it. The `--json`\n * code stays `unknown-target` either way: the target is unknown to the command\n * that asked, and the prose carries the diagnosis.\n */\nexport async function missingFeatureMessage(\n  docsDir: DocsDir,\n  arg: string,\n  context?: FleetContext,\n): Promise<string> {\n  const shipped = await resolveFeature(docsDir, arg, \"only\", context);\n  if (shipped !== null) {\n    return (\n      `Feature '${shipped.id}' is already archived (features/archive/${shipped.dirName}) — ` +\n      `\\`loam show ${shipped.id}\\` reads it, \\`loam unarchive ${shipped.id}\\` re-opens it.`\n    );\n  }\n  return `No feature '${arg}' under ${featuresDir(docsDir)}.`;\n}\n"]}