@enwithai/product-check 0.1.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/importers/operational.d.ts

@@ -0,0 +1,56 @@
+/** The parsed documents of one input file. */
+export interface InputDocs {
+    source: string;
+    docs: unknown[];
+}
+/** One OpenSLO SLO. */
+export interface SloInfo {
+    name: string;
+    service: string | null;
+    /** Missing parts: "service", "time window", "objective target", "indicator". Empty when complete. */
+    missing: string[];
+    has_alert_policy: boolean;
+    dangling_policy_refs: string[];
+}
+/** Summary of the imported OpenSLO files. */
+export interface OpenSloSummary {
+    slos: SloInfo[];
+    slis: number;
+    alert_policies: number;
+    /** Documents with another OpenSLO apiVersion (v1alpha, v2alpha). */
+    unsupported: number;
+    /** openslo/v1 documents of kinds that are not read (Service, DataSource, AlertCondition, …). */
+    other: number;
+}
+/** Parses OpenSLO v1 files; references resolve across all of them by metadata.name. */
+export declare function parseOpenSlo(files: InputDocs[]): OpenSloSummary;
+/** An alerting rule. `expr` is used for matching only and never written to results. */
+export interface AlertRule {
+    name: string;
+    expr: string;
+    labels: Record<string, string>;
+}
+/** Summary of the imported alert rules. */
+export interface AlertRulesSummary {
+    alerting: AlertRule[];
+    recording: number;
+}
+/** Parses Prometheus/Mimir rule files, PrometheusRule resources and /api/v1/rules exports. */
+export declare function parseAlertRules(files: InputDocs[]): AlertRulesSummary;
+/** A rule matches an SLO by a label value or a label matcher in its expression (name-based: an inference). */
+export declare function sloMatchesRule(slo: string, rule: AlertRule): boolean;
+/** One runtime edge. */
+export interface ServiceEdge {
+    client: string;
+    server: string;
+    count: number;
+}
+/** Summary of a service-graph export. */
+export interface ServiceGraphSummary {
+    format: "jaeger" | "prometheus";
+    edges: ServiceEdge[];
+    /** Distinct peers that look like hosts (not named in results, never matched). */
+    external_peers: number;
+}
+/** Parses a Jaeger /api/dependencies export or a service-graph metrics query result. */
+export declare function parseServiceGraph(data: unknown, source: string): ServiceGraphSummary;

package/dist/importers/operational.js

@@ -0,0 +1,217 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2026 EnWithAI Technologies
+/**
+ * Operational importers for CT-T4 (docs/operational-imports.md): OpenSLO v1 documents, Prometheus/Mimir alert rules
+ * and service-graph exports (Jaeger dependencies, `traces_service_graph_request_total` query results). Each reads only
+ * the documented fields it needs and rejects inputs it does not recognize instead of guessing. Rule expressions are
+ * kept in memory for matching and never written to results.
+ */
+import { inputError } from "../errors.js";
+const isObj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const str = (v) => (typeof v === "string" && v.trim() !== "" ? v.trim() : null);
+const byName = (a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+const OPENSLO_V1 = "openslo/v1";
+/** Parses OpenSLO v1 files; references resolve across all of them by metadata.name. */
+export function parseOpenSlo(files) {
+    const slos = [];
+    const slis = new Set();
+    const policies = new Set();
+    let unsupported = 0;
+    let other = 0;
+    for (const file of files) {
+        let v1 = 0;
+        for (const doc of file.docs) {
+            if (!isObj(doc))
+                continue;
+            const api = doc["apiVersion"];
+            if (typeof api === "string" && api.startsWith("openslo/") && api !== OPENSLO_V1) {
+                unsupported++;
+                continue;
+            }
+            if (api !== OPENSLO_V1)
+                continue;
+            v1++;
+            const name = isObj(doc["metadata"]) ? str(doc["metadata"]["name"]) : null;
+            const kind = doc["kind"];
+            if (kind === "SLO")
+                slos.push({
+                    name: name ?? `(unnamed SLO ${slos.length + 1})`,
+                    spec: isObj(doc["spec"]) ? doc["spec"] : {},
+                });
+            else if (kind === "SLI" && name !== null)
+                slis.add(name);
+            else if (kind === "AlertPolicy" && name !== null)
+                policies.add(name);
+            else
+                other++;
+        }
+        if (v1 === 0)
+            throw inputError(`${file.source} contains no OpenSLO v1 document (apiVersion: ${OPENSLO_V1}).`, "Pass OpenSLO v1 files (SLO, SLI, AlertPolicy) to --openslo.");
+    }
+    const infos = slos.map(({ name, spec }) => {
+        const missing = [];
+        const service = str(spec["service"]);
+        if (service === null)
+            missing.push("service");
+        const window = spec["timeWindow"];
+        if (!Array.isArray(window) ||
+            window.length !== 1 ||
+            !isObj(window[0]) ||
+            str(window[0]["duration"]) === null)
+            missing.push("time window");
+        const objectives = Array.isArray(spec["objectives"]) ? spec["objectives"].filter(isObj) : [];
+        if (!objectives.some((o) => typeof o["target"] === "number" || typeof o["targetPercent"] === "number"))
+            missing.push("objective target");
+        const ref = str(spec["indicatorRef"]);
+        if (!isObj(spec["indicator"]) && (ref === null || !slis.has(ref)))
+            missing.push("indicator");
+        const entries = Array.isArray(spec["alertPolicies"]) ? spec["alertPolicies"] : [];
+        const dangling = [];
+        let resolved = 0;
+        for (const entry of entries) {
+            if (!isObj(entry))
+                continue;
+            const policyRef = str(entry["alertPolicyRef"]);
+            if (policyRef !== null) {
+                if (policies.has(policyRef))
+                    resolved++;
+                else
+                    dangling.push(policyRef);
+            }
+            else if (entry["kind"] === "AlertPolicy")
+                resolved++;
+        }
+        return {
+            name,
+            service,
+            missing,
+            has_alert_policy: entries.length > 0 && resolved === entries.length,
+            dangling_policy_refs: [...new Set(dangling)].sort(),
+        };
+    });
+    return {
+        slos: infos.sort(byName),
+        slis: slis.size,
+        alert_policies: policies.size,
+        unsupported,
+        other,
+    };
+}
+/** The rule groups of one document, in any of the three accepted shapes; null when it has none. */
+function groupsOf(doc) {
+    if (!isObj(doc))
+        return null;
+    if (Array.isArray(doc["groups"]))
+        return doc["groups"];
+    if (isObj(doc["spec"]) && Array.isArray(doc["spec"]["groups"]))
+        return doc["spec"]["groups"];
+    if (isObj(doc["data"]) && Array.isArray(doc["data"]["groups"]))
+        return doc["data"]["groups"];
+    return null;
+}
+/** Parses Prometheus/Mimir rule files, PrometheusRule resources and /api/v1/rules exports. */
+export function parseAlertRules(files) {
+    const alerting = [];
+    let recording = 0;
+    for (const file of files) {
+        const groups = file.docs.map(groupsOf).filter((g) => g !== null);
+        if (groups.length === 0)
+            throw inputError(`${file.source} has no rule groups (groups, spec.groups or data.groups).`, "Pass a Prometheus/Mimir rule file, a PrometheusRule resource or the /api/v1/rules JSON export to --alert-rules.");
+        for (const group of groups.flat()) {
+            if (!isObj(group) || !Array.isArray(group["rules"]))
+                continue;
+            for (const rule of group["rules"]) {
+                if (!isObj(rule))
+                    continue;
+                const name = str(rule["alert"]) ?? (rule["type"] === "alerting" ? str(rule["name"]) : null);
+                if (name === null) {
+                    if (str(rule["record"]) !== null || rule["type"] === "recording")
+                        recording++;
+                    continue;
+                }
+                const labels = {};
+                if (isObj(rule["labels"]))
+                    for (const [k, v] of Object.entries(rule["labels"]))
+                        if (typeof v === "string")
+                            labels[k] = v;
+                alerting.push({ name, expr: String(rule["expr"] ?? rule["query"] ?? ""), labels });
+            }
+        }
+    }
+    return { alerting: alerting.sort(byName), recording };
+}
+/** A rule matches an SLO by a label value or a label matcher in its expression (name-based: an inference). */
+export function sloMatchesRule(slo, rule) {
+    if (Object.values(rule.labels).includes(slo))
+        return true;
+    const quoted = slo.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`[A-Za-z_][A-Za-z0-9_]*\\s*=~?\\s*"${quoted}"`).test(rule.expr);
+}
+/** A peer that looks like a host: contains ':' or a dot, or is an IPv4 address. */
+const hostLike = (name) => name.includes(":") || name.includes(".");
+/** Parses a Jaeger /api/dependencies export or a service-graph metrics query result. */
+export function parseServiceGraph(data, source) {
+    const bad = () => {
+        throw inputError(`${source} is not a service graph export (Jaeger /api/dependencies, or a traces_service_graph_request_total query result).`, "Export it from Jaeger, Tempo or Prometheus as JSON and pass it to --service-graph.");
+    };
+    const raw = [];
+    let format;
+    if (isObj(data) && Array.isArray(data["data"])) {
+        format = "jaeger";
+        for (const link of data["data"]) {
+            if (!isObj(link))
+                continue;
+            const client = str(link["parent"]);
+            const server = str(link["child"]);
+            const count = link["callCount"];
+            if (client === null || server === null || typeof count !== "number")
+                return bad();
+            raw.push({ client, server, count });
+        }
+    }
+    else if (isObj(data) &&
+        data["status"] === "success" &&
+        isObj(data["data"]) &&
+        Array.isArray(data["data"]["result"])) {
+        format = "prometheus";
+        for (const series of data["data"]["result"]) {
+            if (!isObj(series) || !isObj(series["metric"]))
+                return bad();
+            const metric = series["metric"];
+            const name = metric["__name__"];
+            if (typeof name === "string" && !name.endsWith("service_graph_request_total"))
+                return bad();
+            const client = str(metric["client"]);
+            const server = str(metric["server"]);
+            const sample = Array.isArray(series["value"])
+                ? series["value"]
+                : Array.isArray(series["values"])
+                    ? series["values"].at(-1)
+                    : null;
+            const count = Array.isArray(sample) ? Number(sample[1]) : NaN;
+            if (client === null || server === null || !Number.isFinite(count))
+                return bad();
+            raw.push({ client, server, count });
+        }
+    }
+    else
+        return bad();
+    const external = new Set();
+    const sums = new Map();
+    for (const e of raw) {
+        if (e.count <= 0)
+            continue;
+        if (hostLike(e.client) || hostLike(e.server)) {
+            for (const peer of [e.client, e.server])
+                if (hostLike(peer))
+                    external.add(peer);
+            continue;
+        }
+        const key = `${e.client}\u0000${e.server}`;
+        const edge = sums.get(key) ?? { client: e.client, server: e.server, count: 0 };
+        edge.count += e.count;
+        sums.set(key, edge);
+    }
+    const edges = [...sums.values()].sort((a, b) => a.client === b.client ? (a.server < b.server ? -1 : 1) : a.client < b.client ? -1 : 1);
+    return { format, edges, external_peers: external.size };
+}

package/dist/importers/reports.d.ts

@@ -36,3 +36,27 @@ export interface OutcomeCheckSummary {
 }
 /** Parses an Outcome Check report (schema 1.0); reads the all-PR segment of two metrics. */
 export declare function parseOutcomeCheck(data: unknown, source: string): OutcomeCheckSummary;
+/** Summary of an Architecture Check report. */
+export interface ArchitectureCheckSummary {
+    schema_version: string;
+    model_path: string | null;
+    model_format: string | null;
+    model_usable: boolean;
+    complete_mapping: boolean;
+    findings: number;
+    /** Verified static facts of high or medium severity. */
+    verified_drift: number;
+    verified_rules: string[];
+    hypotheses: number;
+    unknown: number;
+    /** Declared relationships with no static evidence (`relationship-unobserved`), as declared IDs. */
+    unobserved: {
+        from: string;
+        to: string;
+    }[];
+}
+/**
+ * Parses an Architecture Check `analyze`/`check` report (schema 1.0 or 1.1; 1.1 only adds enum values). A `derive`
+ * report has no declared model and describes no drift, so it is rejected.
+ */
+export declare function parseArchitectureCheck(data: unknown, source: string): ArchitectureCheckSummary;

package/dist/importers/reports.js

@@ -2,7 +2,8 @@
 // SPDX-FileCopyrightText: 2026 EnWithAI Technologies
 /**
  * Optional importers for artifacts produced by other tools: `npm audit --json`, and the JSON reports of the
- * sibling Engineering Commons tools (Spec Check 1.0, Impact Check 2.0, Outcome Check 1.0). Each importer reads
+ * sibling Engineering Commons tools (Spec Check 1.0, Impact Check 2.0, Outcome Check 1.0, Architecture Check 1.0/1.1).
+ * Each importer reads
  * only the documented fields it needs and rejects unknown schema versions instead of guessing.
  */
 import { inputError } from "../errors.js";
@@ -82,3 +83,38 @@ export function parseOutcomeCheck(data, source) {
         reverted_prs: reverts && typeof reverts["numerator"] === "number" ? reverts["numerator"] : null,
     };
 }
+/**
+ * Parses an Architecture Check `analyze`/`check` report (schema 1.0 or 1.1; 1.1 only adds enum values). A `derive`
+ * report has no declared model and describes no drift, so it is rejected.
+ */
+export function parseArchitectureCheck(data, source) {
+    if (!isObj(data) ||
+        data["kind"] !== "architecture-check-report" ||
+        (data["schema_version"] !== "1.0" && data["schema_version"] !== "1.1") ||
+        !Array.isArray(data["findings"]) ||
+        !isObj(data["declared_model"])) {
+        throw inputError(`${source} is not an Architecture Check report with a declared model (schema 1.0 or 1.1).`, "Produce it with `architecture-check check --format json` (or `analyze`); `derive` output has no drift to import.");
+    }
+    const model = data["declared_model"];
+    const findings = data["findings"].filter(isObj);
+    const drift = findings.filter((f) => f["status"] === "verified_static_fact" && (f["severity"] === "high" || f["severity"] === "medium"));
+    const str = (v) => (typeof v === "string" ? v : null);
+    return {
+        schema_version: data["schema_version"],
+        model_path: str(model["path"]),
+        model_format: str(model["format"]),
+        model_usable: model["usable"] === true,
+        complete_mapping: data["complete_mapping"] === true,
+        findings: findings.length,
+        verified_drift: drift.length,
+        verified_rules: [...new Set(drift.map((f) => String(f["rule_id"])))].sort(),
+        hypotheses: findings.filter((f) => f["status"] === "hypothesis").length,
+        unknown: findings.filter((f) => f["status"] === "unknown").length,
+        unobserved: findings
+            .filter((f) => f["rule_id"] === "relationship-unobserved" && typeof f["subject"] === "string")
+            .map((f) => /^(\S+) -> (\S+)$/.exec(f["subject"]))
+            .filter((m) => m !== null)
+            .map((m) => ({ from: m[1], to: m[2] }))
+            .sort((a, b) => (`${a.from} ${a.to}` < `${b.from} ${b.to}` ? -1 : 1)),
+    };
+}

package/dist/inspectors/source/surface.d.ts

@@ -0,0 +1,30 @@
+import { type RepoFacts } from "./facts.js";
+export type SurfaceKind = "page" | "endpoint" | "entity" | "config" | "integration" | "auth-boundary" | "test";
+/** One element of the product surface. */
+export interface SurfaceItem {
+    kind: SurfaceKind;
+    /** Route path, entity name, variable name, package name or test title. */
+    name: string;
+    /** HTTP method for endpoints (`ANY` when the handler dispatches on method itself); null otherwise. */
+    method: string | null;
+    /** Grouping area: first meaningful route segment, or the entity/integration category. */
+    area: string;
+    /** Short human-readable detail (fields, category, matcher, how it was recognised). */
+    detail: string;
+    path: string;
+    line: number | null;
+    excerpt: string | null;
+    certainty: "observed" | "inferred";
+    /** Endpoints and pages whose source references a session or auth helper (inference). */
+    auth_hint: boolean;
+}
+/** Everything derived about the surface. */
+export interface ProductSurface {
+    items: SurfaceItem[];
+    /** Notes about what could not be determined (for the spec's uncertainties). */
+    notes: string[];
+}
+/** The grouping area of a URL path: first static segment after an optional `api` prefix. */
+export declare function areaOf(route: string): string;
+/** Derives the product surface. */
+export declare function deriveSurface(facts: RepoFacts): ProductSurface;