@sdd-method/maintain-cli 0.13.1 → 0.15.0

package/dist/maintain-program.js

@@ -7,7 +7,8 @@
 // (M-ADR 0218 §4.2–4.3): the method payload, lock, CI block and briefing (`sync`,
 // `generate-briefing`), the derived model (`catalogue build | aggregate | graph | diff`), an
 // output the caller names (`pack build`, `render screen`), and a code repository's briefing
-// (`context pull`). Plus the whole verify surface, because the personas nest.
+// (`context pull`), and the structural model's generated views (`structure render`, with `structure show` beside
+// them). Plus the whole verify surface, because the personas nest.
 //
 // ⚠ As with sdd-verify, the boundary is ABSENCE, not a menu: the package ships only the import
 // closure of maintain-bin.js, so authoring verbs (init, scaffold, plan, conformance,
@@ -23,6 +24,7 @@ import { registerContext } from "./verbs/context.js";
 import { registerGenerateBriefing } from "./verbs/generate-briefing.js";
 import { registerPackBuild } from "./verbs/pack-build.js";
 import { registerRender } from "./verbs/render.js";
+import { registerStructure } from "./verbs/structure.js";
 import { registerSync } from "./verbs/sync.js";
 const SPEC_URL = "docs/method/cli/sdd-cli-specification.md (in the method distribution)";
 /** The verbs maintain adds to verify, as `<verb>` or `<verb> <subcommand>`. Asserted by test. */
@@ -37,6 +39,8 @@ export const MAINTAIN_ONLY_SURFACE = [
     "catalogue diff",
     "pack build",
     "render screen",
+    "structure show",
+    "structure render",
 ];
 /** The full surface: verify's, plus maintain's own. */
 export const MAINTAIN_SURFACE = [...VERIFY_SURFACE, ...MAINTAIN_ONLY_SURFACE];
@@ -79,6 +83,8 @@ export function buildMaintainProgram() {
     registerGenerateBriefing(program);
     registerContext(program);
     registerRender(program);
+    // The structural model's generated views are derived (M-ADR 0230 §4.3); show is the read beside them.
+    registerStructure(program);
     const catalogue = program.commands.find((c) => c.name() === "catalogue");
     catalogue.description("Build, aggregate, validate and query per-SDD catalogues (M-ADR 0134) — the derived model");
     registerCatalogueBuild(catalogue);

package/dist/maintain-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "0.13.1",
-  "built_against_sdd_cli": "4.0.1"
+  "version": "0.15.0",
+  "built_against_sdd_cli": "5.1.0"
 }

package/dist/verbs/structure.js

@@ -0,0 +1,95 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { stringify } from "yaml";
+import { elementKey, loadModel, STRUCTURE_DIR } from "../lib/structure/model.js";
+import { describeState, renderViews, viewState } from "../lib/structure/render.js";
+import { revisionOf, viewOf } from "../lib/structure/view.js";
+// `structure show <catalogue>/<id>`: one element of the structural model and its revision, the value a change's
+// `base:` records for it (M-ADR 0230 §4.4). Read only.
+export async function runStructureShow(sddPath, ref, write) {
+    const slash = ref.indexOf("/");
+    if (slash <= 0 || slash === ref.length - 1) {
+        write(`[FAIL] structure show: name an element as <catalogue>/<id>, not ${JSON.stringify(ref)}\n`);
+        return 2;
+    }
+    const catalogue = ref.slice(0, slash);
+    const id = ref.slice(slash + 1);
+    const problems = [];
+    const files = await loadModel(sddPath, problems);
+    if (files === null) {
+        write(`[FAIL] structure show: no structural model (${STRUCTURE_DIR}/) in ${sddPath}\n`);
+        return 1;
+    }
+    const e = viewOf(files, problems).get(catalogue)?.get(id);
+    if (!e) {
+        write(`[FAIL] structure show: the model holds no ${elementKey(catalogue, id)}\n`);
+        for (const p of problems)
+            write(`  ${p}\n`);
+        return 1;
+    }
+    write(`# ${elementKey(catalogue, id)} in ${e.file} (partition ${e.partition})\n`);
+    write(`revision: ${revisionOf(e)}\n`);
+    write(stringify({ id: e.id, ...e.columns }));
+    return 0;
+}
+// `structure render [--check]`: write the generated views of the current view (M-ADR 0230 §4.3), or, with
+// --check, write nothing and report each view that is missing, stale or edited by hand (exit 1 if any is).
+export async function runStructureRender(sddPath, options, write) {
+    const problems = [];
+    const files = await loadModel(sddPath, problems);
+    if (files === null) {
+        write(`[FAIL] structure render: no structural model (${STRUCTURE_DIR}/) in ${sddPath}\n`);
+        return 1;
+    }
+    const view = viewOf(files, problems);
+    if (problems.length > 0) {
+        write(`[FAIL] structure render: the model does not load cleanly; run \`sdd-cli validate --validator structural-model\`\n`);
+        for (const p of problems)
+            write(`  ${p}\n`);
+        return 1;
+    }
+    let off = 0;
+    for (const [path, rendered] of renderViews(view)) {
+        const abs = join(sddPath, path);
+        const text = await readFile(abs, "utf8").catch(() => null);
+        const state = viewState(rendered, text);
+        if (options.check) {
+            if (state !== "current") {
+                off++;
+                write(`[WARN] ${describeState(path, state)}\n`);
+            }
+            continue;
+        }
+        if (state === "hand-edited")
+            write(`[WARN] ${describeState(path, state)}; the edit is overwritten\n`);
+        if (state !== "current") {
+            await mkdir(dirname(abs), { recursive: true });
+            await writeFile(abs, rendered, "utf8");
+        }
+        write(`${state === "current" ? "unchanged" : "wrote"} ${path}\n`);
+    }
+    if (options.check)
+        write(off === 0 ? "[PASS] structure render --check: every view is current\n" : `[FAIL] structure render --check: ${off} view(s) not current\n`);
+    return options.check && off > 0 ? 1 : 0;
+}
+// Read the model and write its generated views: maintain's and sdd-cli's (M-ADR 0230 §4.3, at its acceptance).
+// Extraction is the author's (migrate-structure.ts), registered apart so this module's closure carries no extractor.
+export function registerStructure(program) {
+    const structure = program.command("structure").description("Read the structural model, and write its generated views (M-ADR 0230)");
+    structure
+        .command("show <element>")
+        .description("Print one element of the structural model, <catalogue>/<id>, with its revision")
+        .option("--sdd-path <path>", "the SDD (default: the current directory)", ".")
+        .action(async (element, opts) => {
+        process.exitCode = await runStructureShow(opts.sddPath, element, (s) => process.stdout.write(s));
+    });
+    structure
+        .command("render")
+        .description("Write the generated views of the structural model under docs/structure/; --check reports instead")
+        .option("--sdd-path <path>", "the SDD (default: the current directory)", ".")
+        .option("--check", "write nothing; report each view that is missing, stale or edited by hand", false)
+        .action(async (opts) => {
+        process.exitCode = await runStructureRender(opts.sddPath, { check: opts.check }, (s) => process.stdout.write(s));
+    });
+}
+//# sourceMappingURL=structure.js.map

package/dist/verify-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "4.0.1",
-  "built_against_sdd_cli": "4.0.1"
+  "version": "5.1.0",
+  "built_against_sdd_cli": "5.1.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sdd-method/maintain-cli",
-  "version": "0.13.1",
-  "sddCliVersion": "4.0.1",
+  "version": "0.15.0",
+  "sddCliVersion": "5.1.0",
   "description": "Bring an SDD repository current and rebuild its derived model — sync, briefing, catalogue build and aggregate, pack build, context pull — plus every read-only verify verb. Ships only the code those verbs reach; it cannot author specification content. Authoring is in @sdd-method/sdd-cli.",
   "license": "UNLICENSED",
   "type": "module",