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

package/dist/commands/steps/steps.js

@@ -0,0 +1,269 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { relative } from "node:path";
+import { decodeDocument, NotUtf8DocumentError } from "../../core/kernel/document-bytes.js";
+import { configOrRefuse, emitJson, fail, NO_SERVICE_MESSAGE } from "../../core/envelope/json.js";
+import { featureSpecPaths, SPEC_AXES, unfiledServicePaths } from "../../core/repo/paths.js";
+import { locateServicePaths, resolveServiceTarget } from "../../core/repo/service-target.js";
+import {} from "../../core/repo/entries.js";
+import { introducingFeatures } from "../../core/projection/introduced.js";
+import { parseRequirements } from "../../core/document/parse.js";
+import { axisLabel } from "../../core/gherkin/emit.js";
+import { coveringPhrases, stepInventory, } from "../../core/gherkin/steps/inventory.js";
+import { compareToCatalogue, readStepCatalogue, } from "../../core/gherkin/steps/catalogue.js";
+export function registerSteps(program) {
+    program
+        .command("steps")
+        .description("Inventory the step phrases of a service's scenarios — how many step definitions its suite needs")
+        .option("--service <id>", "service to inventory (defaults to the configured service)")
+        .option("--duplicates", "list only the near-duplicate groups — phrases that differ by an article or a trailing clause")
+        .option("--json", "emit the machine contract instead of the human view")
+        .action(async (opts) => {
+        const json = opts.json === true;
+        const config = await configOrRefuse(json);
+        if (config === null)
+            return;
+        const named = opts.service ?? config.service;
+        if (named === undefined)
+            return fail(json, "invalid-option", NO_SERVICE_MESSAGE);
+        // The enumeration's own id, not the string the caller typed: only one of
+        // them carries the fact that a `readdir` produced it, and it is what makes
+        // the name pathable. Same resolution `validate --service` performs, so the
+        // two commands cannot disagree about which directory a name means.
+        const resolved = await resolveServiceTarget(config.docsDir, named, "--service");
+        // A name `services/` does not hold may still be a service an active
+        // feature INTRODUCES — the second enumeration, a readdir of the feature's
+        // own specs/, so it is asked before the grammar refusal too. Its phrases
+        // are the delta's: the implement protocol tells whoever builds a NEW
+        // service to run this before writing a single step definition, and the
+        // answer was "No living spec … run `loam adopt`" for code that does not
+        // exist yet. The bound service (`config.service`) takes the same road.
+        const introducing = resolved.ok && resolved.dir !== undefined ? [] : await introducingFeatures(config.docsDir, named);
+        const introducedId = introducing[0]?.services.find((s) => s === named);
+        let source;
+        if (introducedId !== undefined) {
+            source = introducedSource(config.docsDir, introducedId, introducing);
+        }
+        else {
+            if (!resolved.ok)
+                return fail(json, "invalid-option", resolved.problem);
+            const paths = await locateServicePaths(config.docsDir, resolved.id);
+            if (!existsSync(paths.spec)) {
+                return fail(json, "unknown-target", `No living spec at ${paths.spec}. Run \`loam adopt\` for '${resolved.id}' first.`);
+            }
+            source = {
+                service: resolved.id,
+                files: SPEC_AXES.map((axis) => ({ axis, path: paths[axis.key] })),
+                steps: paths.steps,
+                introducedBy: [],
+            };
+        }
+        const { service } = source;
+        const axes = [];
+        try {
+            for (const { axis, path } of source.files) {
+                // An absent arch.spec.md is not a finding anywhere else and is not one
+                // here: partial adoption is supported, and an empty axis contributes
+                // no phrases rather than an empty section nobody asked for.
+                const reqs = existsSync(path)
+                    ? parseRequirements(decodeDocument(await readFile(path), path))
+                    : [];
+                axes.push({ axis: axisLabel(axis), reqs });
+            }
+        }
+        catch (err) {
+            if (!(err instanceof NotUtf8DocumentError))
+                throw err;
+            return fail(json, "repository-unavailable", `Cannot inventory steps: ${err.message}`);
+        }
+        const inv = stepInventory(axes);
+        // The catalogue is what makes the report a DIFF rather than a
+        // recomputation: without it every run says the same thing about a suite
+        // whose glue somebody has already written. Absent is the ordinary state
+        // and costs one `existsSync` (`core/gherkin/steps/catalogue.ts`).
+        const catalogue = await readStepCatalogue(source.steps);
+        const against = catalogue.present && catalogue.unreadable === undefined
+            ? compareToCatalogue(inv, catalogue)
+            : null;
+        // Computed ONCE, above the branch, and derived from the path
+        // `locateServicePaths` resolved rather than joined from the id. A filed
+        // service lives wherever the tree walk found it — `services/commerce/
+        // checkout/`, not `services/checkout/` — and `core/repo/service-target.ts`
+        // says so at length. Two outputs of one command spelling the path two
+        // ways is how the human view came to name a directory that does not
+        // exist, and here that would be worse than cosmetic: `steps.yaml` is a
+        // service artifact now, so an author who created the file where this told
+        // them to would mint a second, empty service in the enumeration.
+        const where = docsRelative(config.docsDir, source.steps);
+        const introducedBy = source.introducedBy.map((f) => f.id);
+        if (json) {
+            emitJson({
+                command: "steps",
+                docsDir: config.docsDir,
+                service,
+                // Present only for a service a feature introduces, so a living
+                // service's payload stays byte-identical: `living: false` is the
+                // marker, and `specs` names the delta files the phrases came from.
+                ...(introducedBy.length === 0
+                    ? {}
+                    : {
+                        living: false,
+                        introducedBy,
+                        specs: source.files.filter((f) => existsSync(f.path)).map((f) => docsRelative(config.docsDir, f.path)),
+                    }),
+                steps: inv.steps,
+                phrases: inv.phrases.length,
+                covering80: coveringPhrases(inv),
+                rows: inv.phrases.map((p) => ({
+                    key: p.key,
+                    count: p.count,
+                    keywords: p.keywords,
+                    uses: p.uses,
+                })),
+                nearDuplicates: inv.nearDuplicates,
+                // Additive, and one key rather than columns spread through `rows`: a
+                // consumer that has not adopted the catalogue reads exactly what it
+                // read before. `present: false` and `unreadable` are different
+                // answers and both are real — "nobody has catalogued anything" is not
+                // "loam could not look".
+                catalogue: {
+                    present: catalogue.present,
+                    path: where,
+                    entries: catalogue.entries.length,
+                    ...(catalogue.unreadable === undefined ? {} : { unreadable: catalogue.unreadable }),
+                    ...(against === null ? {} : against),
+                },
+            });
+            return;
+        }
+        const origin = introducedBy.length === 0
+            ? null
+            : {
+                by: introducedBy.join(", "),
+                dirs: source.introducedBy.map((f) => `${docsRelative(config.docsDir, featureSpecPaths(f.dir, service).dir)}/`),
+            };
+        print(inv, { service, origin, duplicatesOnly: opts.duplicates === true });
+        printCatalogue({ catalogue, against, where, introducedBy });
+    });
+}
+/**
+ * Every introducing feature's spec pair, not just the first: with two features
+ * each introducing the service, the suite that exists once both merge needs the
+ * glue for both, and this command has no flag to choose one. The catalogue path
+ * is the unfiled spelling — where archive materialises a new service — and is
+ * reported, never written: `printCatalogue` says why nobody should create it
+ * yet.
+ */
+function introducedSource(docsDir, service, introducedBy) {
+    return {
+        service,
+        files: introducedBy.flatMap((f) => {
+            const paths = featureSpecPaths(f.dir, service);
+            return SPEC_AXES.map((axis) => ({ axis, path: paths[axis.key] }));
+        }),
+        steps: unfiledServicePaths(docsDir, service).steps,
+        introducedBy,
+    };
+}
+/** A docs-relative POSIX path, the spelling every path in this command's output uses. */
+function docsRelative(docsDir, path) {
+    return relative(docsDir, path).split(/[\\/]/).join("/");
+}
+/**
+ * The human view leads with the two numbers a team plans from — how many steps
+ * are written, and how few definitions cover most of them — because the list
+ * underneath is long by construction and the headline is what decides whether
+ * anybody reads it.
+ *
+ * For an introduced service the source is said straight under the headline:
+ * the same numbers read off a delta are a proposal, and a reader who takes them
+ * for a living spec's would plan glue for scenarios review may still change.
+ */
+function print(inv, view) {
+    const { service, origin, duplicatesOnly } = view;
+    const from = origin === null
+        ? null
+        : `  read from the feature delta, not a living spec: ${origin.dirs.join(", ")} — ` +
+            `${service} is introduced by ${origin.by} and is not in the living docs until it archives`;
+    if (inv.steps === 0) {
+        console.log(origin === null
+            ? `steps ${service} — the living specs hold no scenario steps yet.\n`
+            : `steps ${service} — the delta introducing it holds no scenario steps yet.\n${from}\n`);
+        return;
+    }
+    const covering = coveringPhrases(inv);
+    const share = Math.round((100 * inv.phrases.reduce((a, p, i) => (i < covering ? a + p.count : a), 0)) / inv.steps);
+    console.log(`steps ${service} — ${inv.steps} written step(s), ${inv.phrases.length} distinct phrase(s)`);
+    if (from !== null)
+        console.log(from);
+    console.log(`  ${covering} phrase(s) cover ${share}% of them — that is the size of the step-definition registry\n`);
+    if (!duplicatesOnly) {
+        for (const p of inv.phrases) {
+            console.log(`  ${String(p.count).padStart(4)}  ${p.key}`);
+            console.log(`        ${p.keywords.join("/")} · ${[...new Set(p.uses.map((u) => u.requirement))].join(", ")}`);
+        }
+        console.log();
+    }
+    if (inv.nearDuplicates.length === 0) {
+        console.log("  no near-duplicate phrases.");
+        return;
+    }
+    console.log(`  ${inv.nearDuplicates.length} near-duplicate group(s) — one definition was probably meant:`);
+    for (const g of inv.nearDuplicates) {
+        console.log(`    ${g.family}`);
+        for (const k of g.keys)
+            console.log(`      · ${k}`);
+    }
+}
+/**
+ * The catalogue columns, printed after the inventory rather than woven into
+ * them.
+ *
+ * Separate because the two answers have different lifetimes: the inventory is a
+ * fact about the specs and is always true, while this is a diff against a
+ * decision that may not have been made yet. Weaving a "not catalogued" marker
+ * through every phrase row of a service with no `steps.yaml` would mark the
+ * whole report as work owed, which is the opposite of what an absent catalogue
+ * means.
+ *
+ * Nothing here is a finding and nothing changes the exit code. `loam steps` is a
+ * read, and a phrase written before its glue is the normal order of work.
+ */
+function printCatalogue({ catalogue, against, where, introducedBy }) {
+    // A service still in flight gets the opposite advice. `steps.yaml` is a
+    // service artifact (repo/paths.ts), so writing one where it belongs mints the
+    // service's directory — and the service with it — before its feature merges,
+    // after which nothing reads the feature's specs/ as introducing it any more.
+    if (!catalogue.present && introducedBy.length > 0) {
+        console.log(`\n  no catalogue yet — ${where} lands with the service when ${introducedBy.join(", ")} archives.`);
+        console.log("  Write it after the archive: a steps.yaml there now would put the service in the living docs before its feature merges.");
+        return;
+    }
+    if (!catalogue.present) {
+        console.log(`\n  no ${where} — nothing records which phrases this suite has decided to define.`);
+        console.log("  Write one (a `steps:` list of step texts) and this report becomes a diff instead of a recount.");
+        return;
+    }
+    if (catalogue.unreadable !== undefined) {
+        console.log(`\n  ${where} could not be read — ${catalogue.unreadable}.`);
+        console.log("  The catalogue columns are blank: loam did not look, which is not the same as nothing being catalogued.");
+        return;
+    }
+    if (against === null)
+        return;
+    console.log(`\n  ${catalogue.entries.length} phrase(s) catalogued in ${where}`);
+    console.log(`  ${against.uncatalogued.length} written but not catalogued · ${against.unwritten.length} catalogued but not written`);
+    for (const key of against.uncatalogued)
+        console.log(`    + ${key}`);
+    for (const key of against.unwritten)
+        console.log(`    - ${key}`);
+    if (against.duplicated.length === 0)
+        return;
+    console.log(`  ${against.duplicated.length} catalogue entr(ies) collapse onto a phrase already listed:`);
+    for (const dup of against.duplicated) {
+        console.log(`    ${dup.key}`);
+        for (const text of dup.texts)
+            console.log(`      · ${text}`);
+    }
+}
+//# sourceMappingURL=steps.js.map

package/dist/commands/steps/steps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"steps.js","sourceRoot":"","sources":["../../../src/commands/steps/steps.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `loam steps` — the step-phrase inventory of one service's living specs, or,\n * for a service an active feature introduces and `services/` does not hold\n * yet, of that feature's spec delta (the payload then says `living: false`).\n *\n * A READ, and that is the whole design. It emits no finding, sets no exit code\n * beyond a refusal, writes nothing, and needs no service repo to stand in: it\n * parses `spec.md` and `arch.spec.md` from the docs repo exactly as `validate\n * --service` does. `loam gherkin` refuses outside the service's own repository\n * because it WRITES there; this answers a question about documents, so the\n * restriction would buy nothing and cost the analyst who wants the number\n * before anybody has scaffolded a repo.\n *\n * What it is for is in `core/gherkin/steps/inventory.ts`. In one line: the glue\n * layer is where a generated suite dies, and until this existed nobody could\n * tell a suite needing forty step definitions from one needing four hundred.\n */\nimport type { Command } from \"commander\";\nimport { existsSync } from \"node:fs\";\nimport { readFile } from \"node:fs/promises\";\nimport { relative } from \"node:path\";\nimport { decodeDocument, NotUtf8DocumentError } from \"../../core/kernel/document-bytes.js\";\nimport { configOrRefuse, emitJson, fail, NO_SERVICE_MESSAGE } from \"../../core/envelope/json.js\";\nimport { featureSpecPaths, SPEC_AXES, unfiledServicePaths, type SpecAxis } from \"../../core/repo/paths.js\";\nimport { locateServicePaths, resolveServiceTarget } from \"../../core/repo/service-target.js\";\nimport { type FeatureEntry } from \"../../core/repo/entries.js\";\nimport { introducingFeatures } from \"../../core/projection/introduced.js\";\nimport type { DocsDir } from \"../../core/kernel/ids/dirs.js\";\nimport type { RawServiceId } from \"../../core/kernel/ids/service.js\";\nimport { parseRequirements } from \"../../core/document/parse.js\";\nimport { axisLabel } from \"../../core/gherkin/emit.js\";\nimport {\n  coveringPhrases,\n  stepInventory,\n  type InventoryAxis,\n  type StepInventory,\n} from \"../../core/gherkin/steps/inventory.js\";\nimport {\n  compareToCatalogue,\n  readStepCatalogue,\n  type CatalogueComparison,\n  type StepCatalogue,\n} from \"../../core/gherkin/steps/catalogue.js\";\n\ninterface StepsOptions {\n  service?: string;\n  duplicates?: boolean;\n  json?: boolean;\n}\n\nexport function registerSteps(program: Command): void {\n  program\n    .command(\"steps\")\n    .description(\"Inventory the step phrases of a service's scenarios — how many step definitions its suite needs\")\n    .option(\"--service <id>\", \"service to inventory (defaults to the configured service)\")\n    .option(\"--duplicates\", \"list only the near-duplicate groups — phrases that differ by an article or a trailing clause\")\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (opts: StepsOptions) => {\n      const json = opts.json === true;\n      const config = await configOrRefuse(json);\n      if (config === null) return;\n      const named = opts.service ?? config.service;\n      if (named === undefined) return fail(json, \"invalid-option\", NO_SERVICE_MESSAGE);\n      // The enumeration's own id, not the string the caller typed: only one of\n      // them carries the fact that a `readdir` produced it, and it is what makes\n      // the name pathable. Same resolution `validate --service` performs, so the\n      // two commands cannot disagree about which directory a name means.\n      const resolved = await resolveServiceTarget(config.docsDir, named, \"--service\");\n      // A name `services/` does not hold may still be a service an active\n      // feature INTRODUCES — the second enumeration, a readdir of the feature's\n      // own specs/, so it is asked before the grammar refusal too. Its phrases\n      // are the delta's: the implement protocol tells whoever builds a NEW\n      // service to run this before writing a single step definition, and the\n      // answer was \"No living spec … run `loam adopt`\" for code that does not\n      // exist yet. The bound service (`config.service`) takes the same road.\n      const introducing =\n        resolved.ok && resolved.dir !== undefined ? [] : await introducingFeatures(config.docsDir, named);\n      const introducedId = introducing[0]?.services.find((s) => s === named);\n      let source: Source;\n      if (introducedId !== undefined) {\n        source = introducedSource(config.docsDir, introducedId, introducing);\n      } else {\n        if (!resolved.ok) return fail(json, \"invalid-option\", resolved.problem);\n        const paths = await locateServicePaths(config.docsDir, resolved.id);\n        if (!existsSync(paths.spec)) {\n          return fail(\n            json,\n            \"unknown-target\",\n            `No living spec at ${paths.spec}. Run \\`loam adopt\\` for '${resolved.id}' first.`,\n          );\n        }\n        source = {\n          service: resolved.id,\n          files: SPEC_AXES.map((axis) => ({ axis, path: paths[axis.key] })),\n          steps: paths.steps,\n          introducedBy: [],\n        };\n      }\n      const { service } = source;\n      const axes: InventoryAxis[] = [];\n      try {\n        for (const { axis, path } of source.files) {\n          // An absent arch.spec.md is not a finding anywhere else and is not one\n          // here: partial adoption is supported, and an empty axis contributes\n          // no phrases rather than an empty section nobody asked for.\n          const reqs = existsSync(path)\n            ? parseRequirements(decodeDocument(await readFile(path), path))\n            : [];\n          axes.push({ axis: axisLabel(axis), reqs });\n        }\n      } catch (err) {\n        if (!(err instanceof NotUtf8DocumentError)) throw err;\n        return fail(json, \"repository-unavailable\", `Cannot inventory steps: ${err.message}`);\n      }\n\n      const inv = stepInventory(axes);\n      // The catalogue is what makes the report a DIFF rather than a\n      // recomputation: without it every run says the same thing about a suite\n      // whose glue somebody has already written. Absent is the ordinary state\n      // and costs one `existsSync` (`core/gherkin/steps/catalogue.ts`).\n      const catalogue = await readStepCatalogue(source.steps);\n      const against = catalogue.present && catalogue.unreadable === undefined\n        ? compareToCatalogue(inv, catalogue)\n        : null;\n      // Computed ONCE, above the branch, and derived from the path\n      // `locateServicePaths` resolved rather than joined from the id. A filed\n      // service lives wherever the tree walk found it — `services/commerce/\n      // checkout/`, not `services/checkout/` — and `core/repo/service-target.ts`\n      // says so at length. Two outputs of one command spelling the path two\n      // ways is how the human view came to name a directory that does not\n      // exist, and here that would be worse than cosmetic: `steps.yaml` is a\n      // service artifact now, so an author who created the file where this told\n      // them to would mint a second, empty service in the enumeration.\n      const where = docsRelative(config.docsDir, source.steps);\n      const introducedBy = source.introducedBy.map((f) => f.id);\n      if (json) {\n        emitJson({\n          command: \"steps\",\n          docsDir: config.docsDir,\n          service,\n          // Present only for a service a feature introduces, so a living\n          // service's payload stays byte-identical: `living: false` is the\n          // marker, and `specs` names the delta files the phrases came from.\n          ...(introducedBy.length === 0\n            ? {}\n            : {\n                living: false,\n                introducedBy,\n                specs: source.files.filter((f) => existsSync(f.path)).map((f) => docsRelative(config.docsDir, f.path)),\n              }),\n          steps: inv.steps,\n          phrases: inv.phrases.length,\n          covering80: coveringPhrases(inv),\n          rows: inv.phrases.map((p) => ({\n            key: p.key,\n            count: p.count,\n            keywords: p.keywords,\n            uses: p.uses,\n          })),\n          nearDuplicates: inv.nearDuplicates,\n          // Additive, and one key rather than columns spread through `rows`: a\n          // consumer that has not adopted the catalogue reads exactly what it\n          // read before. `present: false` and `unreadable` are different\n          // answers and both are real — \"nobody has catalogued anything\" is not\n          // \"loam could not look\".\n          catalogue: {\n            present: catalogue.present,\n            path: where,\n            entries: catalogue.entries.length,\n            ...(catalogue.unreadable === undefined ? {} : { unreadable: catalogue.unreadable }),\n            ...(against === null ? {} : against),\n          },\n        });\n        return;\n      }\n      const origin = introducedBy.length === 0\n        ? null\n        : {\n            by: introducedBy.join(\", \"),\n            dirs: source.introducedBy.map((f) => `${docsRelative(config.docsDir, featureSpecPaths(f.dir, service).dir)}/`),\n          };\n      print(inv, { service, origin, duplicatesOnly: opts.duplicates === true });\n      printCatalogue({ catalogue, against, where, introducedBy });\n    });\n}\n\n/**\n * Where the phrases are read from. A living service reads its own spec pair; a\n * service an active feature introduces reads each introducing feature's delta\n * pair, because that is the only place its scenarios are written yet.\n */\ninterface Source {\n  service: RawServiceId;\n  files: Array<{ axis: SpecAxis; path: string }>;\n  /** The catalogue's path — the service's own, or, for an introduced one, where its directory will land. */\n  steps: string;\n  /** The introducing features; empty for a living service. */\n  introducedBy: FeatureEntry[];\n}\n\n/**\n * Every introducing feature's spec pair, not just the first: with two features\n * each introducing the service, the suite that exists once both merge needs the\n * glue for both, and this command has no flag to choose one. The catalogue path\n * is the unfiled spelling — where archive materialises a new service — and is\n * reported, never written: `printCatalogue` says why nobody should create it\n * yet.\n */\nfunction introducedSource(docsDir: DocsDir, service: RawServiceId, introducedBy: FeatureEntry[]): Source {\n  return {\n    service,\n    files: introducedBy.flatMap((f) => {\n      const paths = featureSpecPaths(f.dir, service);\n      return SPEC_AXES.map((axis) => ({ axis, path: paths[axis.key] }));\n    }),\n    steps: unfiledServicePaths(docsDir, service).steps,\n    introducedBy,\n  };\n}\n\n/** A docs-relative POSIX path, the spelling every path in this command's output uses. */\nfunction docsRelative(docsDir: DocsDir, path: string): string {\n  return relative(docsDir, path).split(/[\\\\/]/).join(\"/\");\n}\n\n/** What the human headline prints from. */\ninterface PrintView {\n  service: string;\n  /** For a service a feature introduces: which features, and the delta directories read. Null when living. */\n  origin: { by: string; dirs: string[] } | null;\n  duplicatesOnly: boolean;\n}\n\n/**\n * The human view leads with the two numbers a team plans from — how many steps\n * are written, and how few definitions cover most of them — because the list\n * underneath is long by construction and the headline is what decides whether\n * anybody reads it.\n *\n * For an introduced service the source is said straight under the headline:\n * the same numbers read off a delta are a proposal, and a reader who takes them\n * for a living spec's would plan glue for scenarios review may still change.\n */\nfunction print(inv: StepInventory, view: PrintView): void {\n  const { service, origin, duplicatesOnly } = view;\n  const from = origin === null\n    ? null\n    : `  read from the feature delta, not a living spec: ${origin.dirs.join(\", \")} — ` +\n      `${service} is introduced by ${origin.by} and is not in the living docs until it archives`;\n  if (inv.steps === 0) {\n    console.log(\n      origin === null\n        ? `steps ${service} — the living specs hold no scenario steps yet.\\n`\n        : `steps ${service} — the delta introducing it holds no scenario steps yet.\\n${from}\\n`,\n    );\n    return;\n  }\n  const covering = coveringPhrases(inv);\n  const share = Math.round((100 * inv.phrases.reduce((a, p, i) => (i < covering ? a + p.count : a), 0)) / inv.steps);\n  console.log(`steps ${service} — ${inv.steps} written step(s), ${inv.phrases.length} distinct phrase(s)`);\n  if (from !== null) console.log(from);\n  console.log(`  ${covering} phrase(s) cover ${share}% of them — that is the size of the step-definition registry\\n`);\n\n  if (!duplicatesOnly) {\n    for (const p of inv.phrases) {\n      console.log(`  ${String(p.count).padStart(4)}  ${p.key}`);\n      console.log(`        ${p.keywords.join(\"/\")} · ${[...new Set(p.uses.map((u) => u.requirement))].join(\", \")}`);\n    }\n    console.log();\n  }\n\n  if (inv.nearDuplicates.length === 0) {\n    console.log(\"  no near-duplicate phrases.\");\n    return;\n  }\n  console.log(`  ${inv.nearDuplicates.length} near-duplicate group(s) — one definition was probably meant:`);\n  for (const g of inv.nearDuplicates) {\n    console.log(`    ${g.family}`);\n    for (const k of g.keys) console.log(`      · ${k}`);\n  }\n}\n\n/** What the catalogue columns print from — the read and, when it was worth making, the comparison. */\ninterface CatalogueView {\n  catalogue: StepCatalogue;\n  /** Null when there was nothing readable to compare against. */\n  against: CatalogueComparison | null;\n  /**\n   * The catalogue's docs-relative path, RESOLVED — never `services/<id>/…`\n   * rejoined from the service name, which is right for an unfiled service and\n   * wrong for every filed one. The same string `--json` reports.\n   */\n  where: string;\n  /** The features introducing the service, by id; empty for a living one. */\n  introducedBy: string[];\n}\n\n/**\n * The catalogue columns, printed after the inventory rather than woven into\n * them.\n *\n * Separate because the two answers have different lifetimes: the inventory is a\n * fact about the specs and is always true, while this is a diff against a\n * decision that may not have been made yet. Weaving a \"not catalogued\" marker\n * through every phrase row of a service with no `steps.yaml` would mark the\n * whole report as work owed, which is the opposite of what an absent catalogue\n * means.\n *\n * Nothing here is a finding and nothing changes the exit code. `loam steps` is a\n * read, and a phrase written before its glue is the normal order of work.\n */\nfunction printCatalogue({ catalogue, against, where, introducedBy }: CatalogueView): void {\n  // A service still in flight gets the opposite advice. `steps.yaml` is a\n  // service artifact (repo/paths.ts), so writing one where it belongs mints the\n  // service's directory — and the service with it — before its feature merges,\n  // after which nothing reads the feature's specs/ as introducing it any more.\n  if (!catalogue.present && introducedBy.length > 0) {\n    console.log(`\\n  no catalogue yet — ${where} lands with the service when ${introducedBy.join(\", \")} archives.`);\n    console.log(\"  Write it after the archive: a steps.yaml there now would put the service in the living docs before its feature merges.\");\n    return;\n  }\n  if (!catalogue.present) {\n    console.log(`\\n  no ${where} — nothing records which phrases this suite has decided to define.`);\n    console.log(\"  Write one (a `steps:` list of step texts) and this report becomes a diff instead of a recount.\");\n    return;\n  }\n  if (catalogue.unreadable !== undefined) {\n    console.log(`\\n  ${where} could not be read — ${catalogue.unreadable}.`);\n    console.log(\"  The catalogue columns are blank: loam did not look, which is not the same as nothing being catalogued.\");\n    return;\n  }\n  if (against === null) return;\n  console.log(`\\n  ${catalogue.entries.length} phrase(s) catalogued in ${where}`);\n  console.log(\n    `  ${against.uncatalogued.length} written but not catalogued · ${against.unwritten.length} catalogued but not written`,\n  );\n  for (const key of against.uncatalogued) console.log(`    + ${key}`);\n  for (const key of against.unwritten) console.log(`    - ${key}`);\n  if (against.duplicated.length === 0) return;\n  console.log(`  ${against.duplicated.length} catalogue entr(ies) collapse onto a phrase already listed:`);\n  for (const dup of against.duplicated) {\n    console.log(`    ${dup.key}`);\n    for (const text of dup.texts) console.log(`      · ${text}`);\n  }\n}\n"]}

package/dist/commands/subsystem/edit.js

@@ -0,0 +1,192 @@
+/**
+ * The two verbs that create and remove GROUPS: `subsystem new` and
+ * `subsystem rm`. Both commit the marker AND the regenerated views file in
+ * one journaled transaction, because a marker without its view (or a view
+ * outliving its marker) is exactly the `subsystem.views-stale` state the
+ * generated file's contract refuses to leave behind.
+ *
+ * `rm` refuses a subsystem with members — services, child subsystems, or any
+ * stray non-dot entry beside the marker the tree does not already count —
+ * naming each once, as what it is (`subsystem-not-empty`):
+ * a destructive command never picks targets the caller did not name, and a
+ * directory emptied of its marker but not of its contents would re-enter the
+ * walk as a phantom service.
+ */
+import { existsSync } from "node:fs";
+import { readdir, rmdir } from "node:fs/promises";
+import { join } from "node:path";
+import { stringify } from "yaml";
+import { parseSubsystemName } from "../../core/kernel/ids/subsystem.js";
+import { emitJson, fail, repoPath } from "../../core/envelope/json.js";
+import { servicesDir, subsystemPathUnder } from "../../core/repo/paths.js";
+import { closeNamesHint, findInTree, servicesUnder, subsystemsUnder } from "../../core/repo/tree/find.js";
+import { entryIs } from "../../core/repo/tree/fs.js";
+import { SUBSYSTEM_MARKER } from "../../core/repo/tree/marker.js";
+import { planWrite } from "../../core/staging/writes.js";
+import { commitWindow, reportViews } from "./txn/txn.js";
+/** `subsystem new <name> [--under <parent>] [--title …] [--description …] [--owner …]` */
+export async function runNew(docsDir, name, opts, json) {
+    const parsed = parseSubsystemName(name, "subsystem name");
+    if (!parsed.ok) {
+        fail(json, "invalid-option", parsed.problem);
+        return;
+    }
+    await commitWindow(docsDir, json, async (tree) => {
+        // The flat namespace: one name, one meaning, at any depth — a `new` that
+        // collides with ANY service or subsystem would be the exact state
+        // `subsystem.name-collision` refuses after the fact.
+        const taken = findInTree(tree, name);
+        if (taken !== null) {
+            const where = taken.kind === "service" ? taken.service.dir : taken.subsystem.dir;
+            fail(json, "already-exists", `'${name}' is already a ${taken.kind} (${repoPath(docsDir, where)}) — ` +
+                `service ids and subsystem names share one flat namespace, unique at any depth. Pick another name.`);
+            return null;
+        }
+        let parentDir = servicesDir(docsDir);
+        let parentPath = [];
+        if (opts.under !== undefined) {
+            const parent = findInTree(tree, opts.under);
+            if (parent === null) {
+                fail(json, "unknown-target", `No subsystem '${opts.under}' in the tree.` +
+                    closeNamesHint(opts.under, tree.subsystems.map((s) => s.name), " `loam subsystem list` shows what exists."));
+                return null;
+            }
+            if (parent.kind === "service") {
+                fail(json, "invalid-option", `--under names the service '${opts.under}' — a service never contains subsystems.`);
+                return null;
+            }
+            parentDir = parent.subsystem.dir;
+            parentPath = parent.subsystem.path;
+        }
+        const dir = subsystemPathUnder(parentDir, parsed.name);
+        // The flat-namespace check above compares exact strings; the FILESYSTEM
+        // may not. On a case-folding volume (macOS APFS by default) `Billing`
+        // and an existing `services/billing` are one directory, so the marker
+        // write below would land subsystem.yaml INSIDE the live service — the
+        // exact marker-beside-artifacts state `subsystem.marker-misplaced`
+        // refuses after the fact, created by a blessed command. A plain file of
+        // the same name reaches here too (files at the root are not walked). So
+        // the disk is probed directly and anything already there refuses closed.
+        if (existsSync(dir)) {
+            fail(json, "already-exists", `${repoPath(docsDir, dir)} already exists on disk — the tree resolves no entry by that exact name, ` +
+                `so either this filesystem folds case (the directory answers to another spelling of the name) ` +
+                `or something non-loam created it. Pick another name, or move what is there first. Nothing was created.`);
+            return null;
+        }
+        const meta = {
+            ...(opts.title === undefined ? {} : { title: opts.title }),
+            ...(opts.description === undefined ? {} : { description: opts.description }),
+            ...(opts.owner === undefined ? {} : { owner: opts.owner }),
+        };
+        // An empty file is a valid marker — presence classifies, content is metadata.
+        const marker = Object.keys(meta).length === 0 ? "" : stringify(meta);
+        const after = {
+            ...tree,
+            subsystems: [...tree.subsystems, { name, path: [...parentPath, name], dir, meta }],
+        };
+        return {
+            target: name,
+            writes: [planWrite(join(dir, SUBSYSTEM_MARKER), marker)],
+            tree: after,
+            // A lost exclusive-create race on the marker IS the name being taken.
+            racedCode: "already-exists",
+            what: "created",
+            report: (views, recovered) => {
+                if (json) {
+                    emitJson({
+                        command: "subsystem",
+                        created: name,
+                        path: repoPath(docsDir, dir),
+                        views: views.subsystems,
+                        serviceViews: views.services,
+                        ...(recovered === null ? {} : { recovered }),
+                    });
+                    return;
+                }
+                console.log(`created ${repoPath(docsDir, dir)}/ (${SUBSYSTEM_MARKER} written)${reportViews(views)}`);
+            },
+        };
+    });
+}
+/** `subsystem rm <name>` — refuses anything but an empty group. */
+export async function runRm(docsDir, name, json) {
+    await commitWindow(docsDir, json, async (tree) => {
+        const hit = findInTree(tree, name);
+        if (hit === null) {
+            fail(json, "unknown-target", `No subsystem '${name}' in the tree.` +
+                closeNamesHint(name, tree.subsystems.map((s) => s.name), " `loam subsystem list` shows what exists."));
+            return null;
+        }
+        if (hit.kind === "service") {
+            fail(json, "invalid-option", `'${name}' is a service, not a subsystem — loam does not delete services (\`git rm -r ${repoPath(docsDir, hit.service.dir)}\` does, and version control keeps the record).`);
+            return null;
+        }
+        const sub = hit.subsystem;
+        const services = servicesUnder(tree, sub).map((s) => s.id);
+        const children = subsystemsUnder(tree, sub).map((s) => s.name);
+        // Stray entries beside the marker count as members too: after the marker
+        // is gone the directory would re-enter the walk as an empty "service" the
+        // moment anything keeps rmdir from removing it. But only entries the tree
+        // has NOT already counted — a member service or child subsystem is also a
+        // readdir entry here, and listing it a second time as "file X" made the
+        // count wrong and the same name appear under two kinds. What remains is
+        // discriminated by what it is (`entryIs`, the walk's own symlink-aware
+        // question): a file, or a directory the tree does not claim (an unmarked
+        // group, already its own `subsystem.unmarked` finding).
+        const counted = new Set([
+            ...servicesUnder(tree, sub).filter((s) => s.subsystem.length === sub.path.length).map((s) => s.id),
+            ...subsystemsUnder(tree, sub).filter((c) => c.path.length === sub.path.length + 1).map((c) => c.name),
+        ]);
+        const strays = (await readdir(sub.dir, { withFileTypes: true }))
+            .filter((e) => !e.name.startsWith(".") && e.name !== SUBSYSTEM_MARKER && !counted.has(e.name))
+            .map((e) => `${entryIs(sub.dir, e, "dir") ? "directory" : "file"} ${e.name}`);
+        const members = [
+            ...services.map((s) => `service ${s}`),
+            ...children.map((c) => `subsystem ${c}`),
+            ...strays,
+        ];
+        if (members.length > 0) {
+            fail(json, "subsystem-not-empty", `'${name}' still holds ${members.length} member(s): ${members.join(", ")}. ` +
+                "`loam subsystem move <name>... --into <sub|.>` moves them out; a destructive command never picks targets you did not name.");
+            return null;
+        }
+        const after = { ...tree, subsystems: tree.subsystems.filter((s) => s !== sub) };
+        return {
+            target: name,
+            writes: [{ path: join(sub.dir, SUBSYSTEM_MARKER), content: null }],
+            tree: after,
+            what: "removed",
+            report: async (views, recovered) => {
+                // The directory itself, after the transaction: the marker is gone, the
+                // group was verifiably empty, and an empty marker-less directory would
+                // read as an unfiled service. Dotfile litter (.DS_Store) can still
+                // defeat rmdir — reported, not swallowed.
+                let directoryRemoved = true;
+                try {
+                    await rmdir(sub.dir);
+                }
+                catch {
+                    directoryRemoved = !existsSync(sub.dir);
+                }
+                if (json) {
+                    emitJson({
+                        command: "subsystem",
+                        removed: name,
+                        path: repoPath(docsDir, sub.dir),
+                        directoryRemoved,
+                        views: views.subsystems,
+                        serviceViews: views.services,
+                        ...(recovered === null ? {} : { recovered }),
+                    });
+                    return;
+                }
+                console.log(`removed subsystem '${name}' (${repoPath(docsDir, sub.dir)}/)${reportViews(views)}`);
+                if (!directoryRemoved) {
+                    console.log(`note: the directory itself could not be removed (something non-loam is still inside) — ` +
+                        `until it is deleted by hand it will list as an empty unfiled service.`);
+                }
+            },
+        };
+    });
+}
+//# sourceMappingURL=edit.js.map

package/dist/commands/subsystem/edit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"edit.js","sourceRoot":"","sources":["../../../src/commands/subsystem/edit.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The two verbs that create and remove GROUPS: `subsystem new` and\n * `subsystem rm`. Both commit the marker AND the regenerated views file in\n * one journaled transaction, because a marker without its view (or a view\n * outliving its marker) is exactly the `subsystem.views-stale` state the\n * generated file's contract refuses to leave behind.\n *\n * `rm` refuses a subsystem with members — services, child subsystems, or any\n * stray non-dot entry beside the marker the tree does not already count —\n * naming each once, as what it is (`subsystem-not-empty`):\n * a destructive command never picks targets the caller did not name, and a\n * directory emptied of its marker but not of its contents would re-enter the\n * walk as a phantom service.\n */\nimport { existsSync } from \"node:fs\";\nimport { readdir, rmdir } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { stringify } from \"yaml\";\nimport type { DocsDir } from \"../../core/kernel/ids/dirs.js\";\nimport { parseSubsystemName } from \"../../core/kernel/ids/subsystem.js\";\nimport { emitJson, fail, repoPath } from \"../../core/envelope/json.js\";\nimport { servicesDir, subsystemPathUnder } from \"../../core/repo/paths.js\";\nimport { closeNamesHint, findInTree, servicesUnder, subsystemsUnder } from \"../../core/repo/tree/find.js\";\nimport { entryIs } from \"../../core/repo/tree/fs.js\";\nimport { SUBSYSTEM_MARKER } from \"../../core/repo/tree/marker.js\";\nimport type { FleetTree } from \"../../core/repo/tree/walk.js\";\nimport { planWrite } from \"../../core/staging/writes.js\";\nimport { commitWindow, reportViews, type SubsystemTxn } from \"./txn/txn.js\";\nimport type { SubsystemOptions } from \"./subsystem.js\";\n\n/** `subsystem new <name> [--under <parent>] [--title …] [--description …] [--owner …]` */\nexport async function runNew(\n  docsDir: DocsDir,\n  name: string,\n  opts: SubsystemOptions,\n  json: boolean,\n): Promise<void> {\n  const parsed = parseSubsystemName(name, \"subsystem name\");\n  if (!parsed.ok) {\n    fail(json, \"invalid-option\", parsed.problem);\n    return;\n  }\n  await commitWindow(docsDir, json, async (tree): Promise<SubsystemTxn | null> => {\n    // The flat namespace: one name, one meaning, at any depth — a `new` that\n    // collides with ANY service or subsystem would be the exact state\n    // `subsystem.name-collision` refuses after the fact.\n    const taken = findInTree(tree, name);\n    if (taken !== null) {\n      const where = taken.kind === \"service\" ? taken.service.dir : taken.subsystem.dir;\n      fail(\n        json,\n        \"already-exists\",\n        `'${name}' is already a ${taken.kind} (${repoPath(docsDir, where)}) — ` +\n          `service ids and subsystem names share one flat namespace, unique at any depth. Pick another name.`,\n      );\n      return null;\n    }\n    let parentDir = servicesDir(docsDir);\n    let parentPath: string[] = [];\n    if (opts.under !== undefined) {\n      const parent = findInTree(tree, opts.under);\n      if (parent === null) {\n        fail(\n          json,\n          \"unknown-target\",\n          `No subsystem '${opts.under}' in the tree.` +\n            closeNamesHint(opts.under, tree.subsystems.map((s) => s.name), \" `loam subsystem list` shows what exists.\"),\n        );\n        return null;\n      }\n      if (parent.kind === \"service\") {\n        fail(json, \"invalid-option\", `--under names the service '${opts.under}' — a service never contains subsystems.`);\n        return null;\n      }\n      parentDir = parent.subsystem.dir;\n      parentPath = parent.subsystem.path;\n    }\n    const dir = subsystemPathUnder(parentDir, parsed.name);\n    // The flat-namespace check above compares exact strings; the FILESYSTEM\n    // may not. On a case-folding volume (macOS APFS by default) `Billing`\n    // and an existing `services/billing` are one directory, so the marker\n    // write below would land subsystem.yaml INSIDE the live service — the\n    // exact marker-beside-artifacts state `subsystem.marker-misplaced`\n    // refuses after the fact, created by a blessed command. A plain file of\n    // the same name reaches here too (files at the root are not walked). So\n    // the disk is probed directly and anything already there refuses closed.\n    if (existsSync(dir)) {\n      fail(\n        json,\n        \"already-exists\",\n        `${repoPath(docsDir, dir)} already exists on disk — the tree resolves no entry by that exact name, ` +\n          `so either this filesystem folds case (the directory answers to another spelling of the name) ` +\n          `or something non-loam created it. Pick another name, or move what is there first. Nothing was created.`,\n      );\n      return null;\n    }\n    const meta = {\n      ...(opts.title === undefined ? {} : { title: opts.title }),\n      ...(opts.description === undefined ? {} : { description: opts.description }),\n      ...(opts.owner === undefined ? {} : { owner: opts.owner }),\n    };\n    // An empty file is a valid marker — presence classifies, content is metadata.\n    const marker = Object.keys(meta).length === 0 ? \"\" : stringify(meta);\n    const after: FleetTree = {\n      ...tree,\n      subsystems: [...tree.subsystems, { name, path: [...parentPath, name], dir, meta }],\n    };\n    return {\n      target: name,\n      writes: [planWrite(join(dir, SUBSYSTEM_MARKER), marker)],\n      tree: after,\n      // A lost exclusive-create race on the marker IS the name being taken.\n      racedCode: \"already-exists\",\n      what: \"created\",\n      report: (views, recovered) => {\n        if (json) {\n          emitJson({\n            command: \"subsystem\",\n            created: name,\n            path: repoPath(docsDir, dir),\n            views: views.subsystems,\n            serviceViews: views.services,\n            ...(recovered === null ? {} : { recovered }),\n          });\n          return;\n        }\n        console.log(`created ${repoPath(docsDir, dir)}/ (${SUBSYSTEM_MARKER} written)${reportViews(views)}`);\n      },\n    };\n  });\n}\n\n/** `subsystem rm <name>` — refuses anything but an empty group. */\nexport async function runRm(docsDir: DocsDir, name: string, json: boolean): Promise<void> {\n  await commitWindow(docsDir, json, async (tree): Promise<SubsystemTxn | null> => {\n    const hit = findInTree(tree, name);\n    if (hit === null) {\n      fail(\n        json,\n        \"unknown-target\",\n        `No subsystem '${name}' in the tree.` +\n          closeNamesHint(name, tree.subsystems.map((s) => s.name), \" `loam subsystem list` shows what exists.\"),\n      );\n      return null;\n    }\n    if (hit.kind === \"service\") {\n      fail(\n        json,\n        \"invalid-option\",\n        `'${name}' is a service, not a subsystem — loam does not delete services (\\`git rm -r ${repoPath(docsDir, hit.service.dir)}\\` does, and version control keeps the record).`,\n      );\n      return null;\n    }\n    const sub = hit.subsystem;\n    const services = servicesUnder(tree, sub).map((s) => s.id);\n    const children = subsystemsUnder(tree, sub).map((s) => s.name);\n    // Stray entries beside the marker count as members too: after the marker\n    // is gone the directory would re-enter the walk as an empty \"service\" the\n    // moment anything keeps rmdir from removing it. But only entries the tree\n    // has NOT already counted — a member service or child subsystem is also a\n    // readdir entry here, and listing it a second time as \"file X\" made the\n    // count wrong and the same name appear under two kinds. What remains is\n    // discriminated by what it is (`entryIs`, the walk's own symlink-aware\n    // question): a file, or a directory the tree does not claim (an unmarked\n    // group, already its own `subsystem.unmarked` finding).\n    const counted = new Set<string>([\n      ...servicesUnder(tree, sub).filter((s) => s.subsystem.length === sub.path.length).map((s) => s.id as string),\n      ...subsystemsUnder(tree, sub).filter((c) => c.path.length === sub.path.length + 1).map((c) => c.name),\n    ]);\n    const strays = (await readdir(sub.dir, { withFileTypes: true }))\n      .filter((e) => !e.name.startsWith(\".\") && e.name !== SUBSYSTEM_MARKER && !counted.has(e.name))\n      .map((e) => `${entryIs(sub.dir, e, \"dir\") ? \"directory\" : \"file\"} ${e.name}`);\n    const members = [\n      ...services.map((s) => `service ${s}`),\n      ...children.map((c) => `subsystem ${c}`),\n      ...strays,\n    ];\n    if (members.length > 0) {\n      fail(\n        json,\n        \"subsystem-not-empty\",\n        `'${name}' still holds ${members.length} member(s): ${members.join(\", \")}. ` +\n          \"`loam subsystem move <name>... --into <sub|.>` moves them out; a destructive command never picks targets you did not name.\",\n      );\n      return null;\n    }\n    const after: FleetTree = { ...tree, subsystems: tree.subsystems.filter((s) => s !== sub) };\n    return {\n      target: name,\n      writes: [{ path: join(sub.dir, SUBSYSTEM_MARKER), content: null }],\n      tree: after,\n      what: \"removed\",\n      report: async (views, recovered) => {\n        // The directory itself, after the transaction: the marker is gone, the\n        // group was verifiably empty, and an empty marker-less directory would\n        // read as an unfiled service. Dotfile litter (.DS_Store) can still\n        // defeat rmdir — reported, not swallowed.\n        let directoryRemoved = true;\n        try {\n          await rmdir(sub.dir);\n        } catch {\n          directoryRemoved = !existsSync(sub.dir);\n        }\n        if (json) {\n          emitJson({\n            command: \"subsystem\",\n            removed: name,\n            path: repoPath(docsDir, sub.dir),\n            directoryRemoved,\n            views: views.subsystems,\n            serviceViews: views.services,\n            ...(recovered === null ? {} : { recovered }),\n          });\n          return;\n        }\n        console.log(`removed subsystem '${name}' (${repoPath(docsDir, sub.dir)}/)${reportViews(views)}`);\n        if (!directoryRemoved) {\n          console.log(\n            `note: the directory itself could not be removed (something non-loam is still inside) — ` +\n              `until it is deleted by hand it will list as an empty unfiled service.`,\n          );\n        }\n      },\n    };\n  });\n}\n"]}