@sdd-method/sdd-cli 2.5.0 → 4.0.0

package/dist/verbs/structure.js

@@ -0,0 +1,124 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { stringify } from "yaml";
+import { extractStructure, writeExtraction } from "../lib/structure/extract.js";
+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, Proposed). 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, Proposed), 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;
+}
+// `migrate structure [--dry-run]`: extract an SDD's first structural model from its sources, with its report
+// (M-ADR 0230 §6 step 1, Proposed). Refuses an SDD that has a model; writes no source file.
+export async function runMigrateStructure(sddPath, options, write) {
+    const x = await extractStructure(sddPath);
+    if (x.refused !== null) {
+        write(`[FAIL] migrate structure: ${x.refused}\n`);
+        return 1;
+    }
+    const total = [...x.counts.values()].reduce((a, b) => a + b, 0);
+    write(`${options.dryRun ? "would extract" : "extracted"} ${total} element(s) in ${x.counts.size} catalogue(s), ${x.files.size} partition(s); ${x.loss.length + x.extraction.length} fact(s) the model could not carry\n`);
+    if (options.dryRun) {
+        write(x.report);
+        return 0;
+    }
+    for (const p of await writeExtraction(sddPath, x))
+        write(`wrote ${p}\n`);
+    write("[INFO] migrate structure: the model is now the record of structure, and the catalogue is built from it. Keep the original sources until it is reviewed against the code; removing openspec/structure/ withdraws it\n");
+    return 0;
+}
+export function registerStructure(program) {
+    const migrate = program.commands.find((c) => c.name() === "migrate");
+    if (migrate) {
+        migrate
+            .command("structure")
+            .description("Extract the SDD's first structural model from its sources into openspec/structure/, with an extraction report; source files are untouched (M-ADR 0230, Proposed)")
+            .option("--sdd-path <path>", "the SDD (default: the current directory)", ".")
+            .option("--dry-run", "write nothing; print the report", false)
+            .action(async (opts) => {
+            process.exitCode = await runMigrateStructure(opts.sddPath, { dryRun: opts.dryRun }, (s) => process.stdout.write(s));
+        });
+    }
+    const structure = program.command("structure").description("Read the structural model, and write its generated views (M-ADR 0230, Proposed)");
+    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/verbs/structure.js.map

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

package/dist/verify-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "2.5.0",
-  "built_against_sdd_cli": "2.5.0"
+  "version": "4.0.0",
+  "built_against_sdd_cli": "4.0.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdd-method/sdd-cli",
-  "version": "2.5.0",
+  "version": "4.0.0",
   "description": "The full SDD method CLI (sdd-cli): init, sync, validate, catalogue build and aggregate, scaffold, plan, pack build and every other method verb for spec-driven-development repositories. The verify-only, author and maintain personas ship as @sdd-method/verify-cli, @sdd-method/author-cli and @sdd-method/maintain-cli.",
   "keywords": [
     "sdd-method",

package/scripts/author-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "0.10.0",
-  "built_against_sdd_cli": "2.5.0"
+  "version": "0.12.0",
+  "built_against_sdd_cli": "4.0.0"
 }

package/scripts/build-persona-package.mjs

@@ -44,6 +44,11 @@ const ADMIN_CANARIES = [
   "verbs/metamodel.js",
   "verbs/catalogue.js",
   "lib/catalogue/migration-map.js",
+  // The archive operation and extraction (M-ADR 0230 §4.6, §6, Proposed) are sdd-cli's while the record is Proposed: no persona carries them.
+  "verbs/change.js",
+  "lib/structure/archive.js",
+  "lib/structure/apply.js",
+  "lib/structure/extract.js",
 ];
 const AUTHOR_ONLY_MODULES = [
   "verbs/conformance.js",

package/scripts/maintain-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "0.11.0",
-  "built_against_sdd_cli": "2.5.0"
+  "version": "0.13.0",
+  "built_against_sdd_cli": "4.0.0"
 }

package/scripts/verify-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "2.5.0",
-  "built_against_sdd_cli": "2.5.0"
+  "version": "4.0.0",
+  "built_against_sdd_cli": "4.0.0"
 }