@enwithai/product-check 0.2.0 → 0.3.0

package/dist/exec/process.js

@@ -0,0 +1,175 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 EnWithAI Technologies
+/**
+ * The ONLY module in src/ that starts processes (tests enforce this). Two narrow entry points:
+ *
+ * - `gitRead`: read-only git plumbing (rev-parse, diff, show, status, log, merge-base) with a fixed, hardened
+ *   argument prefix: no hooks, no fsmonitor, no external diff or textconv drivers, no pager, no system config, no
+ *   prompts. Revisions are validated so a value can never be read as an option.
+ * - `execCommand`: runs one operator-declared command (argv, never a shell) for author-side proof (VC-P1) and
+ *   closure verification (VC-P5). Callers must have checked that execution was authorized for this invocation
+ *   (`--allow-exec`); this module refuses otherwise. The environment is reduced to an allowlist, output is capped,
+ *   digested and redacted, and nothing is retried.
+ *
+ * The scan pipeline (`run`, `retest`, `scan`, `spec`) never calls this module.
+ */
+import { spawnSync } from "node:child_process";
+import { devNull } from "node:os";
+import { resolve, sep } from "node:path";
+import { safetyError } from "../errors.js";
+import { sha256 } from "../util/hash.js";
+import { redact } from "../util/redact.js";
+import { stableId } from "../util/hash.js";
+const GIT_SUBCOMMANDS = new Set(["rev-parse", "diff", "show", "status", "log", "merge-base"]);
+const GIT_PREFIX = [
+    "-c",
+    "core.fsmonitor=false",
+    "-c",
+    `core.hooksPath=${devNull}`,
+    "-c",
+    "diff.external=",
+    "-c",
+    "core.pager=cat",
+    "-c",
+    "protocol.allow=never",
+    "--no-pager",
+];
+/** Runs a read-only git subcommand in `repo`. */
+export function gitRead(repo, args, maxBuffer = 64 * 1024 * 1024) {
+    const sub = args[0];
+    if (sub === undefined || !GIT_SUBCOMMANDS.has(sub))
+        throw safetyError(`git ${sub ?? ""} is not a read-only subcommand.`);
+    const extra = sub === "diff" || sub === "show" ? ["--no-ext-diff", "--no-textconv", "--no-color"] : [];
+    const r = spawnSync("git", [...GIT_PREFIX, sub, ...extra, ...args.slice(1)], {
+        cwd: repo,
+        encoding: "utf8",
+        maxBuffer,
+        shell: false,
+        windowsHide: true,
+        env: {
+            PATH: process.env["PATH"] ?? "",
+            HOME: process.env["HOME"] ?? "",
+            GIT_CONFIG_NOSYSTEM: "1",
+            GIT_TERMINAL_PROMPT: "0",
+            GIT_OPTIONAL_LOCKS: "0",
+            LC_ALL: "C",
+        },
+    });
+    return {
+        ok: r.status === 0 && !r.error,
+        stdout: r.stdout ?? "",
+        stderr: r.stderr ?? r.error?.message ?? "",
+    };
+}
+/** A NOT_TESTED/BLOCKED execution record that ran nothing. */
+function notRun(input, status, reason) {
+    return {
+        execution_id: stableId("EXE", [
+            input.spec.id,
+            input.spec.argv.join(" "),
+            input.commitSha,
+            status,
+            reason,
+        ]),
+        command_id: input.spec.id,
+        purpose: input.spec.purpose,
+        argv: input.spec.argv,
+        cwd: input.spec.cwd,
+        status,
+        exit_code: null,
+        signal: null,
+        duration_ms: 0,
+        started_at: input.now().toISOString(),
+        environment_id: input.environmentId,
+        commit_sha: input.commitSha,
+        stdout_digest: null,
+        stderr_digest: null,
+        output_bytes: 0,
+        output_truncated: false,
+        excerpt: null,
+        reason,
+        evidence_id: null,
+    };
+}
+/** Executes one declared command (argv, no shell). Never throws for command failures. */
+export function execCommand(input) {
+    const { spec } = input;
+    if (!input.permission.allowed)
+        return notRun(input, "NOT_TESTED", input.permission.reason);
+    if (spec.argv.length === 0 || spec.argv[0] === "")
+        return notRun(input, "BLOCKED", "Empty command.");
+    const root = resolve(input.repo);
+    const cwd = resolve(root, spec.cwd);
+    if (cwd !== root && !cwd.startsWith(root + sep))
+        return notRun(input, "BLOCKED", `Working directory ${spec.cwd} is outside the repository.`);
+    const env = { CI: "1", PRODUCT_CHECK_VERIFY: "1" };
+    for (const name of input.envAllowlist) {
+        const v = process.env[name];
+        if (v !== undefined)
+            env[name] = v;
+    }
+    const started = input.now();
+    const t0 = performance.now();
+    const r = spawnSync(spec.argv[0], spec.argv.slice(1), {
+        cwd,
+        env,
+        shell: false,
+        windowsHide: true,
+        timeout: spec.timeout_ms,
+        maxBuffer: input.maxOutputBytes,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    const duration = Math.round(performance.now() - t0);
+    const stdout = r.stdout ?? Buffer.alloc(0);
+    const stderr = r.stderr ?? Buffer.alloc(0);
+    const err = r.error;
+    const truncated = err?.code === "ENOBUFS";
+    const timedOut = err?.code === "ETIMEDOUT" || (r.signal === "SIGTERM" && duration >= spec.timeout_ms);
+    const spawnFailed = err !== undefined && !truncated && !timedOut;
+    const combined = `${stdout.toString("utf8")}\n${stderr.toString("utf8")}`.trim();
+    const excerpt = combined ? redact(combined.slice(-400)) : null;
+    let status;
+    let reason = null;
+    if (spawnFailed) {
+        status = "BLOCKED";
+        reason = `Could not start ${spec.argv[0]}: ${err.code ?? err.message}`;
+    }
+    else if (timedOut) {
+        status = "FAIL";
+        reason = `Timed out after ${spec.timeout_ms} ms.`;
+    }
+    else if (truncated) {
+        status = "FAIL";
+        reason = `Output exceeded ${input.maxOutputBytes} bytes; the run was stopped.`;
+    }
+    else
+        status = r.status === 0 ? "PASS" : "FAIL";
+    return {
+        execution_id: stableId("EXE", [
+            spec.id,
+            spec.argv.join(" "),
+            input.commitSha,
+            started.toISOString(),
+            sha256(stdout),
+            sha256(stderr),
+        ]),
+        command_id: spec.id,
+        purpose: spec.purpose,
+        argv: spec.argv,
+        cwd: spec.cwd,
+        status,
+        exit_code: r.status,
+        signal: r.signal ?? null,
+        duration_ms: duration,
+        started_at: started.toISOString(),
+        environment_id: input.environmentId,
+        commit_sha: input.commitSha,
+        stdout_digest: sha256(stdout),
+        stderr_digest: sha256(stderr),
+        output_bytes: stdout.length + stderr.length,
+        output_truncated: truncated,
+        excerpt,
+        reason,
+        evidence_id: null,
+    };
+}

package/dist/reporting/markdown.d.ts

@@ -9,6 +9,7 @@ import { PILLARS } from "../types.js";
 export interface RenderOptions {
     branding: boolean;
 }
+export declare const BRANDING = "Generated by Product Check, an EnWithAI Engineering Commons tool. JSON is the source of truth; this file is a rendering.";
 /** One-line score text for a pillar. */
 export declare function scoreText(r: Results, p: (typeof PILLARS)[number]): string;
 /** The assessment report. */

package/dist/reporting/markdown.js

@@ -4,7 +4,7 @@ import { TIER_INFO } from "../validation/tiers.js";
 import { code, md } from "./escape.js";
 const pct = (n) => `${Math.round(n * 100)}%`;
 const PILLAR_LABEL = { customer: "Customer", technology: "Technology", trust: "Trust" };
-const BRANDING = "Generated by Product Check, an EnWithAI Engineering Commons tool. JSON is the source of truth; this file is a rendering.";
+export const BRANDING = "Generated by Product Check, an EnWithAI Engineering Commons tool. JSON is the source of truth; this file is a rendering.";
 /** One-line score text for a pillar. */
 export function scoreText(r, p) {
     const s = r.scorecard.pillars[p];

package/dist/schema/registry.js

@@ -17,6 +17,15 @@ export const KIND_SCHEMA = {
     "release-verdict": "release-verdict.schema.json",
     observations: "observations.schema.json",
     "as-built-spec": "as-built-spec.schema.json",
+    "assurance-policy": "assurance-policy.schema.json",
+    "evidence-record": "evidence-record.schema.json",
+    "change-review": "change-review.schema.json",
+    approval: "approval.schema.json",
+    "verification-run": "verification-run.schema.json",
+    "fix-packet": "fix-packet.schema.json",
+    "closure-register": "closure-register.schema.json",
+    "release-gate": "release-gate.schema.json",
+    "reviewer-findings": "reviewer-findings.schema.json",
 };
 let cached = null;
 /** Lazily loads the bundled schemas. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enwithai/product-check",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Evidence-led product assurance and software blueprinting: scan a repository and/or an authorized deployed app, validate Customer, Technology and Trust controls with evidence, and get findings, a remediation blueprint, a readiness verdict and a local dashboard. Local-first; JSON is the source of truth.",
   "license": "MIT",
   "author": "EnWithAI Technologies",

package/schemas/approval.schema.json

@@ -0,0 +1,98 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/enwithai/product-check/schemas/approval.schema.json",
+  "title": "Product Check approval",
+  "description": "A signed accountable decision. Counts only when the Ed25519 signature verifies against an approver key in the policy, the approver is human, the scope matches and reviewed_sha is the current commit.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "kind",
+    "approval_id",
+    "approver",
+    "scope",
+    "reviewed_sha",
+    "decision",
+    "comment",
+    "created_at",
+    "signature"
+  ],
+  "properties": {
+    "schema_version": {
+      "$ref": "assurance-common.schema.json#/$defs/schema_version"
+    },
+    "kind": {
+      "const": "approval"
+    },
+    "approval_id": {
+      "type": "string",
+      "pattern": "^AP-[0-9A-F]{12}$"
+    },
+    "approver": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "type"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "type": {
+          "enum": ["human", "bot"]
+        }
+      }
+    },
+    "scope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "ref"],
+      "properties": {
+        "type": {
+          "enum": ["change", "closure", "risk-acceptance", "false-positive", "release", "continue"]
+        },
+        "ref": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "reviewed_sha": {
+      "type": "string",
+      "minLength": 7
+    },
+    "decision": {
+      "enum": ["approve", "reject"]
+    },
+    "comment": {
+      "type": "string"
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "signature": {
+      "oneOf": [
+        {
+          "type": "null"
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["algorithm", "key_id", "value"],
+          "properties": {
+            "algorithm": {
+              "const": "ed25519"
+            },
+            "key_id": {
+              "type": "string",
+              "pattern": "^[0-9a-f]{16}$"
+            },
+            "value": {
+              "type": "string"
+            }
+          }
+        }
+      ]
+    }
+  }
+}

package/schemas/assurance-common.schema.json

@@ -0,0 +1,291 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/enwithai/product-check/schemas/assurance-common.schema.json",
+  "title": "Product Check assurance shared definitions",
+  "description": "Enumerations and shapes shared by the CT3 v3.2 review and closure artifacts.",
+  "$defs": {
+    "schema_version": {
+      "const": "0.1.0"
+    },
+    "methodology_version": {
+      "const": "CT3 v3.2"
+    },
+    "verification_state": {
+      "enum": [
+        "SUSPECTED",
+        "EVIDENCE_COLLECTED",
+        "REPRODUCED",
+        "CORROBORATED",
+        "CONFIRMED",
+        "DISPROVEN",
+        "NEEDS_HUMAN_TRIAGE"
+      ]
+    },
+    "closure_state": {
+      "enum": [
+        "OPEN",
+        "ACKNOWLEDGED",
+        "IN_PROGRESS",
+        "FIX_PROPOSED",
+        "RETEST_REQUIRED",
+        "VERIFIED_FIXED",
+        "CLOSED",
+        "REJECTED_FALSE_POSITIVE",
+        "ACCEPTED_RISK",
+        "DEFERRED",
+        "REGRESSED"
+      ]
+    },
+    "risk_level": {
+      "enum": ["LOW", "MEDIUM", "HIGH", "UNDETERMINED"]
+    },
+    "gate_status": {
+      "enum": ["PASS", "CONDITIONAL", "BLOCK", "NOT_EVALUATED"]
+    },
+    "release_decision": {
+      "enum": ["GO", "CONDITIONAL_GO", "NO_GO", "UNKNOWN"]
+    },
+    "fix_status": {
+      "enum": ["PROPOSED", "IMPLEMENTED_UNVERIFIED", "VERIFIED", "REGRESSED"]
+    },
+    "lane": {
+      "enum": ["spec-outcome", "correctness", "impact", "trust-security", "experience", "operations"]
+    },
+    "phase": {
+      "enum": ["VC-P0", "VC-P1", "VC-P2", "VC-P3", "VC-P4", "VC-P5", "VC-P6", "VC-P7"]
+    },
+    "actor": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "type"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "type": {
+          "enum": ["human", "agent", "system"]
+        }
+      }
+    },
+    "command_spec": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "argv", "purpose", "timeout_ms", "cwd", "source"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "argv": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "minItems": 1
+        },
+        "purpose": {
+          "enum": ["build", "typecheck", "lint", "test", "smoke", "reproduction", "regression", "other"]
+        },
+        "timeout_ms": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "cwd": {
+          "type": "string"
+        },
+        "source": {
+          "enum": ["policy", "fix", "corpus"]
+        }
+      }
+    },
+    "environment": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["environment_id", "runner", "lockfile_digest"],
+      "properties": {
+        "environment_id": {
+          "type": "string"
+        },
+        "runner": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["platform", "arch", "node_version", "tool_version"],
+          "properties": {
+            "platform": {
+              "type": "string"
+            },
+            "arch": {
+              "type": "string"
+            },
+            "node_version": {
+              "type": "string"
+            },
+            "tool_version": {
+              "type": "string"
+            }
+          }
+        },
+        "lockfile_digest": {
+          "type": ["string", "null"],
+          "pattern": "^[0-9a-f]{64}$"
+        }
+      }
+    },
+    "execution": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "execution_id",
+        "command_id",
+        "purpose",
+        "argv",
+        "cwd",
+        "status",
+        "exit_code",
+        "signal",
+        "duration_ms",
+        "started_at",
+        "environment_id",
+        "commit_sha",
+        "stdout_digest",
+        "stderr_digest",
+        "output_bytes",
+        "output_truncated",
+        "excerpt",
+        "reason",
+        "evidence_id"
+      ],
+      "properties": {
+        "execution_id": {
+          "type": "string"
+        },
+        "command_id": {
+          "type": "string"
+        },
+        "purpose": {
+          "enum": ["build", "typecheck", "lint", "test", "smoke", "reproduction", "regression", "other"]
+        },
+        "argv": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "cwd": {
+          "type": "string"
+        },
+        "status": {
+          "$ref": "common.schema.json#/$defs/validation_status"
+        },
+        "exit_code": {
+          "type": ["integer", "null"]
+        },
+        "signal": {
+          "type": ["string", "null"]
+        },
+        "duration_ms": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "started_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "environment_id": {
+          "type": "string"
+        },
+        "commit_sha": {
+          "type": ["string", "null"],
+          "pattern": "^[0-9a-f]{40}([0-9a-f]{24})?$"
+        },
+        "stdout_digest": {
+          "type": ["string", "null"],
+          "pattern": "^[0-9a-f]{64}$"
+        },
+        "stderr_digest": {
+          "type": ["string", "null"],
+          "pattern": "^[0-9a-f]{64}$"
+        },
+        "output_bytes": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "output_truncated": {
+          "type": "boolean"
+        },
+        "excerpt": {
+          "type": ["string", "null"],
+          "maxLength": 400
+        },
+        "reason": {
+          "type": ["string", "null"]
+        },
+        "evidence_id": {
+          "type": ["string", "null"]
+        }
+      }
+    },
+    "check": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["check", "result", "detail"],
+      "properties": {
+        "check": {
+          "type": "string"
+        },
+        "result": {
+          "enum": ["pass", "fail", "not-run"]
+        },
+        "detail": {
+          "type": "string"
+        }
+      }
+    },
+    "verification": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["state", "checks"],
+      "properties": {
+        "state": {
+          "$ref": "assurance-common.schema.json#/$defs/verification_state"
+        },
+        "checks": {
+          "type": "array",
+          "items": {
+            "$ref": "assurance-common.schema.json#/$defs/check"
+          }
+        }
+      }
+    },
+    "approval_evaluation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["approval_id", "approver_id", "status", "reason"],
+      "properties": {
+        "approval_id": {
+          "type": "string"
+        },
+        "approver_id": {
+          "type": "string"
+        },
+        "status": {
+          "enum": [
+            "VALID",
+            "STALE",
+            "INVALID_SIGNATURE",
+            "UNSIGNED",
+            "UNKNOWN_APPROVER",
+            "NOT_HUMAN",
+            "SELF_APPROVAL",
+            "WRONG_SCOPE",
+            "REJECTED"
+          ]
+        },
+        "reason": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}