@sdd-method/verify-cli 0.1.1 → 0.2.0

package/dist/lib/validate/yaml-parse.js

@@ -0,0 +1,112 @@
+// YAML parse gate — every tracked YAML source must parse STRICTLY.
+//
+// The catalogue builders read YAML file by file and, for most sources, log
+// `invalid YAML` and move on: the file becomes wholly invisible to the
+// catalogue and nothing ever fails. Measured: 19 unparseable files across 4
+// SDDs, 16 in one repo, accumulated that way.
+//
+// THE LOADER IS THE GATE. PyYAML (and any last-key-wins loader) accepts a
+// duplicate key and silently keeps the second value, so a parse-only check
+// with it certifies exactly the corruption a line-surgery transformer
+// produces. `yaml` v2 refuses duplicate keys (DUPLICATE_KEY) and the other
+// malformations a lenient parse glosses — e.g. a `: ` inside an unquoted
+// scalar (`path: (none — tel: URL)`), which no pattern rule catches.
+//
+// Scope: the YAML files git TRACKS (`*.yaml`, `*.yml`) — the repo's sources,
+// not build output or dependencies. Outside a git work tree there is no
+// honest scope, so the check reports a SKIP rather than a pass.
+//
+// A TEMPLATE is not YAML until rendered (Helm/Go `{{- … -}}`, Handlebars).
+// A file that fails to parse AND carries a template directive is listed as
+// templated and not failed — UNLESS one of its errors is a duplicate key: a
+// duplicate key is a duplicate however the file is produced, and exempting it
+// would let any `{{ }}` in a value hide exactly the defect this gate exists for.
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { parseAllDocuments } from "yaml";
+const execFileAsync = promisify(execFile);
+const TEMPLATE_DIRECTIVE_RE = /\{\{[\s\S]*?\}\}/;
+/** Strict-parse one YAML text; returns the errors (empty = parses). */
+export function strictYamlErrors(text) {
+    return parseAllDocuments(text).flatMap((doc) => doc.errors.map((e) => ({
+        code: e.code,
+        message: e.message.split("\n")[0] ?? e.message,
+    })));
+}
+async function trackedYamlFiles(repo) {
+    try {
+        const { stdout } = await execFileAsync("git", ["-C", repo, "ls-files", "-z", "--", "*.yaml", "*.yml"], { maxBuffer: 64 * 1024 * 1024 });
+        return stdout.split("\0").filter((p) => p !== "");
+    }
+    catch {
+        return null;
+    }
+}
+export async function checkYamlParse(targetRepo) {
+    const files = await trackedYamlFiles(targetRepo);
+    if (files === null) {
+        return {
+            exitCode: 0,
+            stdout: "",
+            skipped: "not a git work tree — no tracked-file scope to check",
+        };
+    }
+    const failures = [];
+    const templated = [];
+    let read = 0;
+    for (const file of files) {
+        let text;
+        try {
+            text = await readFile(join(targetRepo, file), "utf-8");
+        }
+        catch {
+            continue; // tracked but deleted in the work tree: not a parse question
+        }
+        read += 1;
+        const errors = strictYamlErrors(text);
+        if (errors.length > 0 &&
+            !errors.some((e) => e.code === "DUPLICATE_KEY") &&
+            TEMPLATE_DIRECTIVE_RE.test(text)) {
+            templated.push(file);
+            continue;
+        }
+        for (const e of errors) {
+            failures.push({ file, code: e.code, message: e.message });
+        }
+    }
+    const checked = read - templated.length;
+    const templatedNote = templated.length === 0
+        ? ""
+        : `[INFO] yaml-parse: ${templated.length} templated file(s) not checked — they do not parse ` +
+            `until rendered and carry a {{ … }} directive: ${templated.join(", ")}\n`;
+    if (failures.length === 0 && checked === 0) {
+        // Zero files checked is absence of evidence, never a pass.
+        return {
+            exitCode: 0,
+            stdout: templatedNote,
+            skipped: "no tracked YAML files to parse — nothing to check",
+        };
+    }
+    if (failures.length === 0) {
+        return {
+            exitCode: 0,
+            stdout: templatedNote +
+                `[PASS] yaml-parse: ${checked} tracked YAML file(s) parse strictly (duplicate keys refused)\n`,
+        };
+    }
+    const failedFiles = new Set(failures.map((f) => f.file)).size;
+    const byCode = new Map();
+    for (const f of failures)
+        byCode.set(f.code, (byCode.get(f.code) ?? 0) + 1);
+    const lines = failures.map((f) => `[FAIL] yaml-parse: ${f.file}: ${f.code}: ${f.message}\n`);
+    if (templatedNote !== "")
+        lines.unshift(templatedNote);
+    lines.push(`[FAIL] yaml-parse: ${failedFiles} of ${checked} tracked YAML file(s) do not parse strictly ` +
+        `(${[...byCode].map(([c, n]) => `${c} ×${n}`).join(", ")}). ` +
+        `A file that does not parse is invisible to the catalogue; a duplicate key keeps only one ` +
+        `of its values under a lenient loader. Fix the file — do not relax the loader.\n`);
+    return { exitCode: 1, stdout: lines.join("") };
+}
+//# sourceMappingURL=yaml-parse.js.map

package/dist/verbs/catalogue-verify.js

@@ -57,7 +57,7 @@ export function registerCatalogueImpact(catalogue) {
         .description("Change-impact closure of a node (M-ADR 0206): each relationship is traversed per its declared impact-flow from the rubric-coverage-map — dependency edges reach their consumers, membership edges propagate part-to-whole only, xref/lineage records are inert — computed by recursive SQL on the embedded engine, with the co-directionality invariant asserted on every run")
         .requiredOption("--of <node-id>", 'Node to compute impact of, in the projection\'s "<catalogue>/<id>" form (e.g. contracts/orders-api)')
         .option("--sdd-path <path>", "Path to the SDD repo root (defaults to cwd)")
-        .option("--catalogues-dir <dir>", "Catalogues directory relative to the SDD root (default catalogues)")
+        .option("--catalogues-dir <dir>", "Catalogues directory relative to the SDD root (default: catalogues, or catalogues-aggregated at --tier aggregate)")
         .option("--tier <tier>", "Tier, explicit never inferred (member | aggregate; default member)")
         .action(async (opts) => {
         if (opts.tier !== undefined &&

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdd-method/verify-cli",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Verify an SDD repository without changing it — validate, list, and read-only catalogue and pack checks. Ships only the code those verbs reach; it cannot write to the repository it is pointed at. Authoring and maintenance are in @sdd-method/sdd-cli.",
   "license": "Apache-2.0",
   "type": "module",

package/scripts/validate-app-dependencies.sh

@@ -65,6 +65,9 @@ log_info() { echo -e "${GREEN}[INFO]${NC} $1"; }
 log_warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
 log_fail() { echo -e "${RED}[FAIL]${NC} $1"; }
 log_pass() { echo -e "${GREEN}[PASS]${NC} $1"; }
+# R1: an empty population is "measured nothing", not a pass — the [N/A] tag
+# must start the line (no leading colour escape) so callers can detect it.
+log_na() { echo -e "[N/A] $1"; }
 log_section() {
     echo -e "\n${BLUE}═══════════════════════════════════════════════════════════${NC}"
     echo -e "${BLUE}  $1${NC}"
@@ -224,22 +227,38 @@ UNRESOLVED_SERVICE_IDS=0
 UNRESOLVED_CONTRACT_PATHS=0
 
 # ──────────────────────────────────────────────────────────────────────────────
+# R1: with zero declared dependencies the run measures nothing, so the
+# prerequisite checks report as [INFO] rather than [PASS] — a [PASS] line would
+# make the empty run read as a pass. Counted up front, quietly; the real count
+# (with parse-failure reporting) happens in main.
+PRE_DEP_COUNT=0
+log_prereq() {
+    if [[ "$PRE_DEP_COUNT" -gt 0 ]]; then log_pass "$1"; else log_info "$1"; fi
+}
+
 check_prerequisites() {
     log_section "Prerequisites"
 
+    if command -v yq &>/dev/null; then
+        local _src
+        for _src in "${DEP_SOURCES[@]+"${DEP_SOURCES[@]}"}"; do
+            PRE_DEP_COUNT=$((PRE_DEP_COUNT + $(quiet_dep_count "$_src")))
+        done
+    fi
+
     if [[ ${#DEP_SOURCES[@]} -eq 0 ]]; then
         log_fail "no dependency source found: neither $APP_DEPS_FILE nor any reverse-evidence/**/feature-grounding-evidence.yaml"
         exit 1
     fi
     for src in "${DEP_SOURCES[@]}"; do
-        log_pass "dependency source: ${src#"$APP_ROOT"/}"
+        log_prereq "dependency source: ${src#"$APP_ROOT"/}"
     done
 
     if ! command -v yq &>/dev/null; then
         log_fail "yq is required but not installed. Install with: brew install yq"
         exit 1
     fi
-    log_pass "yq available"
+    log_prereq "yq available"
 
     if [[ "$PLATFORM_AVAILABLE" -eq 0 ]]; then
         PLATFORM_SERVICES_CSV=""
@@ -249,7 +268,7 @@ check_prerequisites() {
     fi
 
     if [[ -f "$PLATFORM_SERVICES_CSV" ]]; then
-        log_pass "Platform services catalogue found (canonical service_id source)"
+        log_prereq "Platform services catalogue found (canonical service_id source)"
     else
         PLATFORM_SERVICES_CSV=""
     fi
@@ -258,7 +277,7 @@ check_prerequisites() {
         log_warn "Platform service-architecture.md not found: $PLATFORM_SERVICE_ARCH"
         PLATFORM_SERVICE_ARCH=""
     else
-        log_pass "Platform service-architecture.md found"
+        log_prereq "Platform service-architecture.md found"
     fi
 
     if [[ -z "$PLATFORM_SERVICES_CSV" && -z "$PLATFORM_SERVICE_ARCH" ]]; then
@@ -600,6 +619,7 @@ main() {
         fi
         log_warn "No platform_dependencies entries found in ${#DEP_SOURCES[@]} source(s)"
         log_info "If this app has no platform deps, this is acceptable."
+        log_na "App dependencies: 0 platform_dependencies entries found — nothing to check"
         exit 0
     fi
 

package/scripts/validate-app-docs.sh

@@ -34,6 +34,9 @@ log_info() { echo -e "${GREEN}[INFO]${NC} $1"; }
 log_warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
 log_fail() { echo -e "${RED}[FAIL]${NC} $1"; }
 log_pass() { echo -e "${GREEN}[PASS]${NC} $1"; }
+# R1: an empty population is "measured nothing", not a pass — the [N/A] tag
+# must start the line (no leading colour escape) so callers can detect it.
+log_na() { echo -e "[N/A] $1"; }
 log_section() {
     echo -e "\n${BLUE}═══════════════════════════════════════════════════════════${NC}"
     echo -e "${BLUE}  $1${NC}"
@@ -66,6 +69,14 @@ fi
 
 FAILURES=0
 
+# R1: the feature specs are the population this validator measures. With none,
+# the Group 1 file-presence checks are reported as [INFO] rather than [PASS] so
+# the run reads as "measured nothing", not as a pass.
+FEATURE_SPEC_COUNT="$( (find "$APP_ROOT/features" -type f -name "*.md" 2>/dev/null || true) | wc -l | tr -d ' ')"
+log_found() {
+    if [[ "$FEATURE_SPEC_COUNT" -gt 0 ]]; then log_pass "$1"; else log_info "$1"; fi
+}
+
 # ──────────────────────────────────────────────────────────────────────────────
 check_required_files() {
     log_section "Group 1: Required App Repo Files"
@@ -85,7 +96,7 @@ check_required_files() {
         log_fail "service-architecture.md not found (checked docs/service-architecture.md and service-architecture.md)"
         checks_failed=$((checks_failed + 1))
     else
-        log_pass "service-architecture.md found: ${service_arch#$APP_ROOT/}"
+        log_found "service-architecture.md found: ${service_arch#$APP_ROOT/}"
         checks_passed=$((checks_passed + 1))
     fi
 
@@ -103,13 +114,13 @@ check_required_files() {
         log_warn "feature-tree.md not found (checked docs/platform/, docs/, and repo root) — create when features are classified"
         # warn only; not a hard fail at exploration stage
     else
-        log_pass "feature-tree.md found: ${feature_tree#$APP_ROOT/}"
+        log_found "feature-tree.md found: ${feature_tree#$APP_ROOT/}"
         checks_passed=$((checks_passed + 1))
     fi
 
     # 1c. app-platform-dependencies.yaml
     if [[ -f "$APP_ROOT/app-platform-dependencies.yaml" ]]; then
-        log_pass "app-platform-dependencies.yaml found"
+        log_found "app-platform-dependencies.yaml found"
         checks_passed=$((checks_passed + 1))
     else
         log_fail "app-platform-dependencies.yaml not found in repo root"
@@ -173,7 +184,10 @@ main() {
 
     log_section "Summary"
 
-    if [[ "$FAILURES" -eq 0 ]]; then
+    if [[ "$FAILURES" -eq 0 && "$FEATURE_SPEC_COUNT" -eq 0 ]]; then
+        log_na "App documentation: required files present, but 0 feature specs found under features/ — nothing to check"
+        exit 0
+    elif [[ "$FAILURES" -eq 0 ]]; then
         log_pass "All app documentation checks passed."
         exit 0
     else