@sdd-method/author-cli 0.17.1 → 0.17.3

package/dist/lib/behaviour-store/archive.js

@@ -172,37 +172,48 @@ export function observedInProblems(evidence) {
  * `**Surfaces:** none` on one line is the typed claim that the baseline lists no surface, which only a baseline that
  * admits no behaviour may make (the caller decides; `none` is true and the list is empty).
  */
+/** What drives a service that serves no contract (sdm-xfln): the triggers `**Surfaces:** none served (...)` may name. */
+export const NONE_SERVED_TRIGGERS = ["scheduled", "queue-triggered", "stream-triggered"];
 export function parseSurfaces(evidence) {
     const lines = evidence.split("\n");
     // The LAST standalone line: an evidence file may carry an earlier prose section under the same label, and
     // the list is what the file ends up asserting.
     let at = -1;
-    let none = false;
-    let generated = false;
+    let claim = "list";
     lines.forEach((l, i) => {
         if (/^\s*\*\*Surfaces:\*\*\s*$/.test(l)) {
             at = i;
-            none = false;
-            generated = false;
+            claim = "list";
+        }
+        else if (/^\s*\*\*Surfaces:\*\*\s*none\s+served\b/i.test(l)) {
+            at = i;
+            claim = "none served";
         }
         else if (/^\s*\*\*Surfaces:\*\*\s*none\b/i.test(l)) {
             at = i;
-            none = true;
-            generated = false;
+            claim = "none";
         }
         else if (/^\s*\*\*Surfaces:\*\*\s*generated\b/i.test(l)) {
             at = i;
-            none = false;
-            generated = true;
+            claim = "generated";
         }
     });
+    const base = { present: true, none: false, generated: false, noneServed: null, repoClaims: [], entries: [], problems: [] };
     if (at < 0)
-        return { present: false, none: false, generated: false, entries: [], problems: [] };
-    if (none)
-        return { present: true, none: true, generated: false, entries: [], problems: [] };
-    if (generated)
-        return { present: true, none: false, generated: true, entries: [], problems: [] };
+        return { ...base, present: false };
+    if (claim === "none")
+        return { ...base, none: true };
+    if (claim === "generated")
+        return { ...base, generated: true };
+    if (claim === "none served") {
+        // `**Surfaces:** none served (scheduled)`: the service serves no contract; what drives it is named, from a
+        // closed vocabulary, so the claim says why and cannot be left vague.
+        const problems = [];
+        const triggers = noneServedTriggers(lines[at], "**Surfaces:** none served", problems);
+        return { ...base, noneServed: triggers, problems };
+    }
     const entries = [];
+    const repoClaims = [];
     const problems = [];
     for (const line of lines.slice(at + 1)) {
         if (line.trim() === "" && entries.length + problems.length === 0)
@@ -217,6 +228,12 @@ export function parseSurfaces(evidence) {
         }
         const contract = m[1].trim();
         const status = m[2].split(";")[0].trim();
+        if (/^none\s+served\b/i.test(status)) {
+            // `- <repo>: none served (<trigger>)`: that observed repository serves no contract (sdm-wz6a); the list's other
+            // items still account for the contracts the other observed repositories serve.
+            repoClaims.push({ repo: contract, triggers: noneServedTriggers(status, `- ${contract}: none served`, problems) });
+            continue;
+        }
         const excluded = /^excluded\s*,\s*(.+)$/i.exec(status);
         if (/^covered at transport$/i.test(status)) {
             if (contract.includes("*"))
@@ -234,9 +251,21 @@ export function parseSurfaces(evidence) {
             problems.push(`"${contract}: ${status}" is neither "covered at transport" nor "excluded, <reason>"`);
         }
     }
-    if (entries.length + problems.length === 0)
+    if (entries.length + repoClaims.length + problems.length === 0)
         problems.push('the **Surfaces:** line lists no contract; a baseline that admits no behaviour writes "**Surfaces:** none"');
-    return { present: true, none: false, generated: false, entries, problems };
+    return { present: true, none: false, generated: false, noneServed: null, repoClaims, entries, problems };
+}
+/** The triggers of a `none served (<trigger>[, <trigger>])` claim, reporting a missing or unknown one. */
+function noneServedTriggers(text, form, problems) {
+    const m = /none\s+served\s*\(([^)]*)\)\s*\.?\s*$/i.exec(text);
+    const triggers = m ? m[1].split(",").map((t) => t.trim()).filter((t) => t !== "") : [];
+    if (!m || triggers.length === 0)
+        problems.push(`"none served" names what drives the service: "${form} (${NONE_SERVED_TRIGGERS.join(" | ")})"`);
+    for (const t of triggers) {
+        if (!NONE_SERVED_TRIGGERS.includes(t))
+            problems.push(`"none served (${t})": "${t}" is not one of ${NONE_SERVED_TRIGGERS.join(", ")}`);
+    }
+    return triggers;
 }
 /**
  * A generator's baseline (agreement-record-schema.yaml, Baselines: generated behaviour) serves no contract; its

package/dist/lib/catalogue/builders/repositories.js

@@ -33,17 +33,20 @@ const LOC_REPORT_REL = join("docs", "platform", "reference", "loc-report.csv");
 const REPOS_DIR_REL = "repos";
 const REVERSE_METADATA_BASENAME = "reverse-metadata.yaml";
 // The contract kinds a repo-config `contracts:` block keys, under `contracts/<kind>/`. The sdd-index reader
-// accepts the same six; `spicedb` (an `authz` contract) was once missing here, and zod strips an unknown key,
+// accepts the same seven; `spicedb` (an `authz` contract) was once missing here, and zod strips an unknown key,
 // so a declared `.zed` schema vanished without a finding. `cli` (schema 4.1.0) declares the command manifest a
 // command-line repository serves, and `ui` (schema 7.2.0) the manifest of an embeddable UI surface a UI-only
-// repository serves. GraphQL is not keyed in repo-config: that is its own question, on this schema.
-export const REPO_CONFIG_CONTRACT_KINDS = ["openapi", "proto", "avro", "spicedb", "cli", "ui"];
+// repository serves. `graphql` declares a GraphQL SDL a repository serves: the contracts builder discovered it,
+// and the kind enum held it, while repo-config could not key it, so a repository serving only GraphQL had no
+// served contract and its baselines' Surfaces could never be cross-checked (sdm-pvy8).
+export const REPO_CONFIG_CONTRACT_KINDS = ["openapi", "proto", "avro", "spicedb", "graphql", "cli", "ui"];
 const ContractsBlockSchema = z
     .object({
     openapi: z.array(z.string()).optional(),
     proto: z.array(z.string()).optional(),
     avro: z.array(z.string()).optional(),
     spicedb: z.array(z.string()).optional(),
+    graphql: z.array(z.string()).optional(),
     cli: z.array(z.string()).optional(),
     ui: z.array(z.string()).optional(),
 })

package/dist/lib/plan/read-sdd.js

@@ -62,6 +62,7 @@ function legacyShape(node, sourcePath) {
         proto: [],
         avro: [],
         spicedb: [],
+        graphql: [],
         cli: [],
         ui: [],
     };

package/dist/lib/sdd-index/repo-config.js

@@ -16,6 +16,7 @@ const CONTRACT_KINDS = [
     "proto",
     "avro",
     "spicedb",
+    "graphql",
     "cli",
     "ui",
 ];

package/dist/lib/validate/behaviour-store.js

@@ -848,6 +848,7 @@ export async function checkBehaviourStore(repo, options = {}) {
     let surfacesChecked = 0;
     let structureOnly = 0;
     let generatedBaselines = 0;
+    let noneServedBaselines = 0;
     // The contract moves each archived change records, in archive order. A contract's id derives from its path, so a
     // move changes it; an archived baseline's list names the contract as it was, and is resolved through the moves
     // archived after it rather than edited (M-ADR 0222 §4.4). A surface that vanished with no move still fails.
@@ -935,6 +936,8 @@ export async function checkBehaviourStore(repo, options = {}) {
         if (!admits) {
             if (parsed.generated)
                 return [`${dir}/baseline-evidence.md: **Surfaces:** generated, but the baseline admits no behaviour (no requirement in its spec deltas): write "**Surfaces:** none"`];
+            if (parsed.noneServed !== null)
+                return [`${dir}/baseline-evidence.md: **Surfaces:** none served, but the baseline admits no behaviour (no requirement in its spec deltas): write "**Surfaces:** none"`];
             if (parsed.none) {
                 structureOnly++;
                 return out;
@@ -946,6 +949,30 @@ export async function checkBehaviourStore(repo, options = {}) {
         else if (parsed.none) {
             return [`${dir}/baseline-evidence.md: **Surfaces:** none, but the baseline admits behaviour (requirements in ${dir}/specs/); name every contract the observed repositories serve, covered at transport or excluded with a reason`];
         }
+        if (parsed.noneServed !== null) {
+            // A service driven only by a schedule, a queue or a stream serves no contract: the Surfaces rule names what the
+            // observed repositories SERVE, and a contract a repository only consumes is not a surface. The claim holds only
+            // where the catalogue confirms that no observed repository serves a contract (sdm-xfln); anything else fails, so
+            // it is never a way past the list.
+            for (const p of parsed.problems)
+                out.push(`${dir}/baseline-evidence.md: Surfaces: ${p}`);
+            if (servedBy === null) {
+                out.push(`${dir}/baseline-evidence.md: **Surfaces:** none served cannot be cross-checked: catalogues/repo_contract.csv or catalogues/contracts.csv is missing; build the catalogue`);
+                return out;
+            }
+            const repos = observedIn(evidence);
+            if (repos.length === 0)
+                out.push(`${dir}/baseline-evidence.md: **Surfaces:** none served cannot be cross-checked: no **Observed in:** line names a repository`);
+            for (const r of repos) {
+                const served = servedBy.get(r)?.served ?? [];
+                if (served.length > 0) {
+                    out.push(`${dir}/baseline-evidence.md: **Surfaces:** none served, but ${r} serves ${served.length} contract(s) (catalogues/repo_contract.csv: ${served.slice(0, 3).map((c) => c.id).join(", ")}${served.length > 3 ? ", ..." : ""}); a repository that serves contracts lists each, covered at transport or excluded with a reason`);
+                }
+            }
+            if (out.length === 0)
+                noneServedBaselines++;
+            return out;
+        }
         if (parsed.generated) {
             // A generator serves nothing: its transport is the generated tree (agreement-record-schema.yaml, Baselines). The
             // claim holds only where the catalogue confirms that no observed repository serves a contract, and where the run
@@ -983,8 +1010,25 @@ export async function checkBehaviourStore(repo, options = {}) {
         const repos = observedIn(evidence);
         if (repos.length === 0)
             out.push(`${dir}/baseline-evidence.md: Surfaces cannot be cross-checked: no **Observed in:** line names a repository`);
+        // `- <repo>: none served (<trigger>)` items (sdm-wz6a): each names an observed repository the catalogue records
+        // serving no contract; one serving a contract lists its contracts instead.
+        const claimed = new Set();
+        for (const c of parsed.repoClaims) {
+            if (!repos.includes(c.repo)) {
+                out.push(`${dir}/baseline-evidence.md: Surfaces: "- ${c.repo}: none served" names a repository **Observed in:** does not (${repos.join(", ") || "none"})`);
+                continue;
+            }
+            const served = servedBy.get(c.repo)?.served ?? [];
+            if (served.length > 0) {
+                out.push(`${dir}/baseline-evidence.md: Surfaces: "- ${c.repo}: none served", but ${c.repo} serves ${served.length} contract(s) (catalogues/repo_contract.csv: ${served.slice(0, 3).map((x) => x.id).join(", ")}${served.length > 3 ? ", ..." : ""}); list each, covered at transport or excluded with a reason`);
+                continue;
+            }
+            claimed.add(c.repo);
+        }
         for (const r of repos) {
             const known = servedBy.get(r);
+            if (claimed.has(r))
+                continue;
             if ((known?.served ?? []).length === 0) {
                 const consumed = known?.consumed ? ` (it consumes ${known.consumed}, which a baseline does not list)` : "";
                 out.push(`${dir}/baseline-evidence.md: Surfaces cannot be cross-checked: the catalogue records no contract that ${r} serves${consumed}; declare the contracts it serves in its repo-config`);
@@ -1088,7 +1132,7 @@ export async function checkBehaviourStore(repo, options = {}) {
     if (openBaselines.length > 0)
         lines.push(`open baselines: ${openBaselines.length}, asked the archive's questions as warnings`);
     const unseen = servedBy === null ? "" : `; repositories with no catalogue contracts: ${[...new Set(await observedInAll(repo, archiveRel, order))].filter((r) => (servedBy.get(r)?.served ?? []).length === 0).join(", ") || "none"}`;
-    lines.push(baselines === 0 ? "surfaces: vacuous (no baseline)" : `surfaces: ${baselines} baseline(s), ${surfacesChecked} served contract(s) checked against catalogues/repo_contract.csv less what service_contract records only consumed${unseen}${structureOnly ? `; ${structureOnly} structure-only baseline(s) admitting no behaviour, Surfaces: none` : ""}${generatedBaselines ? `; ${generatedBaselines} generator baseline(s) serving no contract, Surfaces: generated` : ""}${historical.size ? `; ${historical.size} historical baseline(s) not checked (every requirement they baselined has left the living specs)` : ""}`);
+    lines.push(baselines === 0 ? "surfaces: vacuous (no baseline)" : `surfaces: ${baselines} baseline(s), ${surfacesChecked} served contract(s) checked against catalogues/repo_contract.csv less what service_contract records only consumed${unseen}${structureOnly ? `; ${structureOnly} structure-only baseline(s) admitting no behaviour, Surfaces: none` : ""}${generatedBaselines ? `; ${generatedBaselines} generator baseline(s) serving no contract, Surfaces: generated` : ""}${noneServedBaselines ? `; ${noneServedBaselines} baseline(s) of services serving no contract, Surfaces: none served` : ""}${historical.size ? `; ${historical.size} historical baseline(s) not checked (every requirement they baselined has left the living specs)` : ""}`);
     lines.push(scopeChecked === 0 ? "scope: vacuous (no baseline removes, modifies or renames a requirement)" : `scope: ${scopeChecked} requirement(s) a baseline removes, modifies or renames, checked against their lineage`);
     if (!history && archived.length > 0)
         lines.push("order: no git history (not a git work tree, or git log failed), so same-day archives cannot be ordered");

package/dist/maintain-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "0.18.1",
-  "built_against_sdd_cli": "5.4.1"
+  "version": "0.18.3",
+  "built_against_sdd_cli": "5.4.3"
 }

package/dist/verify-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "5.4.1",
-  "built_against_sdd_cli": "5.4.1"
+  "version": "5.4.3",
+  "built_against_sdd_cli": "5.4.3"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sdd-method/author-cli",
-  "version": "0.17.1",
-  "sddCliVersion": "5.4.1",
+  "version": "0.17.3",
+  "sddCliVersion": "5.4.3",
   "description": "Re-author one SDD's content — scaffold, plan, contracts, conformance, api-surface, snapshots, briefings, catalogue check — plus every read-only verify verb. Ships only the code those verbs reach; it cannot sync the baseline or rebuild the catalogues. Maintenance is in @sdd-method/maintain-cli, administration in @sdd-method/sdd-cli.",
   "license": "UNLICENSED",
   "type": "module",

package/scripts/validate-app-docs.sh

@@ -149,6 +149,10 @@ check_feature_specs() {
     local specs_failed=0
     local specs_passed=0
     local specs_flat=0
+    local sdd_id=""
+    if [[ -f "$APP_ROOT/.sdd/sdd-manifest.yaml" ]]; then
+        sdd_id="$(sed -nE 's/^sdd_id:[[:space:]]*["'"'"']?([^"'"'"' ]+)["'"'"']?[[:space:]]*$/\1/p' "$APP_ROOT/.sdd/sdd-manifest.yaml" | head -1)"
+    fi
 
     # Discover feature specs under features/*/
     local feature_spec
@@ -166,7 +170,11 @@ check_feature_specs() {
 
         if [[ "$(dirname "$feature_spec")" == "$APP_ROOT/features" ]]; then
             local name; name="$(basename "$feature_spec" .md)"
-            log_warn "$rel: stored flat under features/; a feature spec's path is features/${name}/${name}.md, one directory per feature with its story files beside it (app-feature-spec skill). Advisory: reported, not failed"
+            # The directory and file take the feature's slug, the one feature-tree.md uses: a stem repeating the
+            # product id (the manifest's sdd_id) is not the slug, and the catalogue build refuses it.
+            local slug="$name"
+            if [[ -n "$sdd_id" && "$name" == "${sdd_id}-"* ]]; then slug="${name#"${sdd_id}-"}"; fi
+            log_warn "$rel: stored flat under features/; a feature spec's path is features/${slug}/${slug}.md, one directory per feature named by its feature-tree slug (app-feature-spec skill). Advisory: reported, not failed"
             specs_flat=$((specs_flat + 1))
         fi