@peterxiaoyang/superspec 0.1.0

package/dist/src/tasks.js

@@ -0,0 +1,225 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { reason, renderList, walkFiles } from "./util.js";
+import { sidecar_test_contract_path } from "./paths.js";
+import { live_pass } from "./evidence.js";
+const TASK_LINE = /^- \[( |x|X)\]\s+(\S+)\s*(.*)$/;
+const ATTR_LINE = /^\s+- (\w+):\s*(.*)$/;
+const TEST_ID_RE = /\bTEST-\d+[A-Za-z0-9_-]*\b/g;
+const SCENARIO_RE = /^####\s+Scenario:?\s*(.+?)\s*$/;
+export function parse_tasks(changeRoot) {
+    const tasksMd = join(changeRoot, "tasks.md");
+    if (!existsSync(tasksMd) || !statSync(tasksMd).isFile())
+        return {};
+    const tasks = {};
+    let current = null;
+    for (const raw of readFileSync(tasksMd, "utf8").split(/\r?\n/)) {
+        const match = raw.match(TASK_LINE);
+        if (match) {
+            const checked = match[1].toLowerCase() === "x";
+            const taskId = match[2].trim();
+            current = { task_id: taskId, checked, desc: match[3].trim(), attrs: {} };
+            tasks[taskId] = current;
+            continue;
+        }
+        const attr = raw.match(ATTR_LINE);
+        if (attr && current) {
+            current.attrs[attr[1]] = attr[2].trim();
+        }
+        else if (raw && !raw.startsWith(" ") && !raw.startsWith("\t")) {
+            current = null;
+        }
+    }
+    return tasks;
+}
+// FIX-8 (audit A-5): checkbox-state-insensitive fingerprint of tasks.md. Checking a box is
+// normal apply progress; any other edit (new task, attrs, descriptions) changes the hash and
+// therefore invalidates the user's apply-scope approval.
+export function tasks_structure_hash(changeRoot) {
+    const tasksMd = join(changeRoot, "tasks.md");
+    if (!existsSync(tasksMd) || !statSync(tasksMd).isFile())
+        return null;
+    const normalized = readFileSync(tasksMd, "utf8").replace(/^(\s*[-*]\s*)\[[xX]\]/gm, "$1[ ]");
+    return `sha256:${createHash("sha256").update(normalized, "utf8").digest("hex")}`;
+}
+export function splitList(value) {
+    const stripped = value.trim().replace(/^\[/, "").replace(/\]$/, "");
+    if (!stripped)
+        return [];
+    return stripped.split(/[,\s]+/).map((item) => item.trim()).filter(Boolean);
+}
+function parseMarkdownRow(line) {
+    return line.trim().replace(/^\|/, "").replace(/\|$/, "").split("|").map((cell) => cell.trim());
+}
+function isSeparatorRow(cells) {
+    return cells.length > 0 && cells.every((cell) => /^:?-{3,}:?$/.test(cell));
+}
+function normalizeHeader(header) {
+    return header.trim().toLowerCase().replace(/\s+/g, "_");
+}
+function tableLinesAfterHeading(text, headings) {
+    const lines = text.split(/\r?\n/);
+    const start = lines.findIndex((line) => headings.some((heading) => heading.test(line.trim())));
+    if (start < 0)
+        return [];
+    const table = [];
+    let started = false;
+    for (const line of lines.slice(start + 1)) {
+        const trimmed = line.trim();
+        if (!trimmed && !started)
+            continue;
+        if (!trimmed.startsWith("|")) {
+            if (started)
+                break;
+            continue;
+        }
+        started = true;
+        table.push(line);
+    }
+    return table;
+}
+function columnIndex(headers, predicate) {
+    return headers.findIndex(predicate);
+}
+export function parse_test_contract_records(changeRoot) {
+    const text = test_contract_text(changeRoot);
+    const table = tableLinesAfterHeading(text, [/^##\s+测试覆盖矩阵\s*$/i, /^##\s+test coverage matrix\s*$/i]);
+    if (table.length < 3)
+        return [];
+    const headers = parseMarkdownRow(table[0]).map(normalizeHeader);
+    const testIdx = columnIndex(headers, (header) => header === "test-id" || header === "test_id" || header === "testid");
+    const scenarioIdx = columnIndex(headers, (header) => header.includes("scenario") || header.includes("req") || header.includes("需求") || header.includes("关联"));
+    const invIdx = columnIndex(headers, (header) => header.includes("inv"));
+    if (testIdx < 0)
+        return [];
+    const records = [];
+    for (const line of table.slice(1)) {
+        const cells = parseMarkdownRow(line);
+        if (isSeparatorRow(cells))
+            continue;
+        const testId = cells[testIdx] ?? "";
+        if (!TEST_ID_RE.test(testId))
+            continue;
+        TEST_ID_RE.lastIndex = 0;
+        records.push({
+            row: records.length + 1,
+            test_id: testId.match(TEST_ID_RE)?.[0] ?? "",
+            scenario_ref: scenarioIdx >= 0 ? cells[scenarioIdx] ?? "" : "",
+            invariant_refs: invIdx >= 0 ? splitList(cells[invIdx] ?? "").filter((item) => item.startsWith("INV-")) : [],
+        });
+    }
+    return records;
+}
+export function parse_test_contract_ids(changeRoot) {
+    return new Set(parse_test_contract_records(changeRoot).map((record) => record.test_id).filter(Boolean));
+}
+export function test_contract_text(changeRoot) {
+    const filePath = sidecar_test_contract_path(changeRoot);
+    if (!existsSync(filePath) || !statSync(filePath).isFile())
+        return "";
+    return readFileSync(filePath, "utf8");
+}
+export function parse_spec_scenarios(changeRoot) {
+    const specs = join(changeRoot, "specs");
+    const scenarios = [];
+    if (!existsSync(specs) || !statSync(specs).isDirectory())
+        return scenarios;
+    for (const filePath of walkFiles(specs).sort()) {
+        if (!filePath.endsWith(".md"))
+            continue;
+        for (const line of readFileSync(filePath, "utf8").split(/\r?\n/)) {
+            const match = line.match(SCENARIO_RE);
+            if (match)
+                scenarios.push(match[1].trim());
+        }
+    }
+    return scenarios;
+}
+export function test_contract_covers_scenario(changeRoot, scenario) {
+    return parse_test_contract_records(changeRoot).some((record) => record.scenario_ref.includes(scenario));
+}
+export function test_contract_invariant_refs_by_test(changeRoot) {
+    const out = new Map();
+    for (const record of parse_test_contract_records(changeRoot)) {
+        const refs = out.get(record.test_id) ?? new Set();
+        for (const ref of record.invariant_refs)
+            refs.add(ref);
+        out.set(record.test_id, refs);
+    }
+    return out;
+}
+export function task_test_refs(tasks) {
+    const refs = new Set();
+    for (const task of Object.values(tasks)) {
+        for (const ref of splitList(task.attrs.test_refs ?? ""))
+            refs.add(ref);
+    }
+    return refs;
+}
+export function write_scope_conflict_reasons(tasks) {
+    const byGroup = {};
+    for (const [taskId, task] of Object.entries(tasks)) {
+        const group = task.attrs.parallel_group;
+        if (!group)
+            continue;
+        for (const scope of splitList(task.attrs.write_scope ?? "")) {
+            byGroup[group] ??= {};
+            byGroup[group][scope] ??= [];
+            byGroup[group][scope].push(taskId);
+        }
+    }
+    const problems = [];
+    for (const [group, scopes] of Object.entries(byGroup)) {
+        for (const [scope, taskIds] of Object.entries(scopes)) {
+            if (taskIds.length > 1)
+                problems.push(reason("write_scope_conflict", `parallel_group ${group} has overlapping write_scope ${scope}: ${renderList(taskIds)}`));
+        }
+    }
+    return problems;
+}
+export function red_green_test_ids(evidences) {
+    const ids = new Set();
+    for (const ev of live_pass(evidences, { kind: "test_run" })) {
+        if (typeof ev.test_id === "string" && ev.test_id)
+            ids.add(ev.test_id);
+    }
+    return ids;
+}
+export function task_test_evidence(evidences, taskId, semanticStatus, gate = null) {
+    return live_pass(evidences, { gate, kind: "test_run", task_id: taskId }).filter((ev) => ev.semantic_status === semanticStatus);
+}
+export function task_alternative_verification(evidences, taskId) {
+    return [
+        ...live_pass(evidences, { kind: "alternative_verification", task_id: taskId }),
+        ...live_pass(evidences, { kind: "manual_verification", task_id: taskId }),
+    ];
+}
+export function evidence_test_id_reasons(evidences, taskId, declared, contractIds, semanticStatus) {
+    const problems = [];
+    for (const ev of evidences) {
+        const tid = ev.test_id;
+        if (typeof tid !== "string" || !tid) {
+            problems.push(reason("missing_test_id", `task ${taskId} ${semanticStatus} evidence requires test_id`));
+            continue;
+        }
+        if (declared.size > 0 && !declared.has(tid)) {
+            problems.push(reason("test_contract_not_honored", `task ${taskId} ${semanticStatus} test_id ${tid} not in declared test_refs ${renderList([...declared].sort())}`));
+        }
+        if (contractIds.size > 0 && !contractIds.has(tid)) {
+            problems.push(reason("test_contract_not_honored", `task ${taskId} ${semanticStatus} test_id ${tid} not in test-contract ids ${renderList([...contractIds].sort())}`));
+        }
+    }
+    return problems;
+}
+export function declared_test_evidence_reasons(evidences, taskId, declared, semanticStatus) {
+    if (declared.size === 0)
+        return [];
+    const covered = new Set(evidences
+        .map((ev) => typeof ev.test_id === "string" ? ev.test_id : "")
+        .filter((testId) => declared.has(testId)));
+    const missing = [...declared].filter((testId) => !covered.has(testId)).sort();
+    if (missing.length === 0)
+        return [];
+    return [reason("missing_declared_test_evidence", `task ${taskId} ${semanticStatus} evidence missing declared test_refs: ${renderList(missing)}`, missing)];
+}

package/dist/src/util.d.ts

@@ -0,0 +1,120 @@
+export declare const SCHEMA_VERSION = 1;
+export declare const GUARD_VERSION = "superspec-guard@1";
+export declare const CONFIG_FILENAME = "config.yaml";
+export declare const STATE_FILENAME = "superspec-state.json";
+export declare const STATE_LOCK_FILENAME = "superspec-state.lock";
+export declare const PROJECT_CONFIG_ALIASES: readonly [".superspec.yaml", ".superspec.yml", "superspec.yaml", "superspec.yml", "superspec.json", ".superspecrc", ".superspec/config.json"];
+export declare const CHANGE_CONFIG_ALIASES: readonly [".superspec.yaml", ".superspec.yml", "superspec.yaml", "superspec.yml", "superspec.json", ".superspecrc", ".superspec/config.json"];
+export declare const STATE_ALIASES: readonly [".superspec/state.json", ".superspec/state.lock", ".superspec/superspec_state.json", ".superspec/superspec-state.yaml"];
+export declare const REQUIRED_SIDECAR_DIRS: readonly ["artifacts", "evidence/discovery", "evidence/design", "evidence/invariants", "evidence/test-contract", "evidence/tasks", "evidence/red", "evidence/green", "evidence/reviews", "evidence/verification", "evidence/archive", "handoffs", "reports", "raw"];
+export type JsonMap = Record<string, any>;
+export type Reason = {
+    code: string;
+    message: string;
+    refs: string[];
+};
+export type Decision = {
+    allowed: boolean;
+    decision: "allow" | "block" | "status";
+    change_id: string;
+    gate: string;
+    task_id: string | null;
+    openspec_status_summary: Record<string, string>;
+    superspec_gate_summary: Record<string, any>;
+    block_reasons: Reason[];
+    next_allowed_actions: string[];
+    trust_warnings: string[];
+};
+export type TaskInfo = {
+    task_id: string;
+    checked: boolean;
+    desc: string;
+    attrs: Record<string, string>;
+};
+export declare const BUILTIN_CONFIG: JsonMap;
+export declare const ALLOWED_CONFIG_KEYS: Set<string>;
+export declare const EVIDENCE_STATUSES: Set<string>;
+export declare const EVIDENCE_KINDS: Set<string>;
+export declare const HUMAN_CONFIRMATION_GATES: Set<string>;
+export declare const NO_TDD_REASONS: Set<string>;
+export declare const TDD_MODES: Set<string>;
+export declare const ROLE_EVIDENCE_FIELDS: readonly ["agent_role", "agent_id", "prompt_ref", "output_ref", "source_anchors", "target_refs"];
+export declare const SELF_REVIEW_MARKERS: Set<string>;
+export declare const REVIEW_EVIDENCE_REQUIRED_FIELDS: readonly ["base_ref", "head_ref", "reviewed_files"];
+export declare const VERIFY_EVIDENCE_REQUIRED_FIELDS: readonly ["openspec_validate_ref", "task_matrix_ref", "invariant_matrix_ref", "scope_drift_ref", "test_evidence_refs"];
+export declare const REVIEW_GUIDANCE_ROLES: readonly ["code-reviewer", "architect", "critic"];
+export declare const FINAL_VERIFICATION_ROLES: readonly ["verifier", "critic"];
+export declare const SOURCE_GUIDANCE_REQUIRED_FIELDS: readonly ["source_refs", "required_load_refs", "required_claim_ids"];
+export declare const MAIN_ADJUDICATION_REQUIRED_FIELDS: readonly ["output_ref", "source_evidence_refs", "verification_evidence_refs", "loaded_refs", "claim_adjudications", "finding_adjudications"];
+export declare const MAIN_ADJUDICATION_DECISIONS: readonly ["allow", "request_changes"];
+export declare const REQUEST_CHANGES_ROUTES: readonly ["reopen_tasks", "change_update"];
+export declare const CLAIM_ADJUDICATION_DECISIONS: readonly ["accept", "reject", "needs_fix"];
+export declare const FINDING_ADJUDICATION_DECISIONS: readonly ["dismissed", "accepted_fixed", "accepted_deviation", "needs_fix"];
+export declare const FINAL_TEST_REQUIRED_FIELDS: readonly ["test_command", "output_ref"];
+export declare const TASK_REOPEN_REQUIRED_FIELDS: readonly ["task_id", "reopen_id", "source_adjudication_evidence_id", "source_guidance_evidence_id", "violated_test_ids", "violated_requirement_refs", "invalidated_completion_evidence_ids", "required_supersede_evidence_ids", "completion_invalidity_class", "scope_expansion", "why_completion_invalid", "required_fix", "before_tasks_sha256", "after_tasks_sha256"];
+export declare const TASK_REOPEN_RESOLVED_REQUIRED_FIELDS: readonly ["reopen_evidence_id", "reopen_id", "task_id", "successor_completion_evidence_ids", "after_tasks_sha256"];
+export declare const TASK_REOPEN_INVALIDITY_CLASSES: readonly ["insufficient_completion_evidence"];
+export declare const FORBIDDEN_FIELDS: Set<string>;
+export declare const OPENSPEC_ARTIFACTS: Set<string>;
+export declare const REQUIRED_OPENSPEC_CODEX_SKILLS: readonly ["openspec-explore", "openspec-propose", "openspec-apply-change", "openspec-archive-change"];
+export declare const REQUIRED_SUPERSPEC_WORKFLOW_SKILLS: readonly ["superspec-explore", "superspec-propose", "superspec-apply", "superspec-review", "superspec-archive"];
+export declare const REQUIRED_SUPERSPEC_AGENT_ROLES: readonly ["architect", "critic", "test-engineer", "code-reviewer", "verifier"];
+export declare const REQUIRED_OPENSPEC_CLI_SURFACES: readonly [readonly ["instructions", "--help"], readonly ["archive", "--help"], readonly ["validate", "--help"], readonly ["status", "--help"]];
+export declare const ARTIFACT_ENTER_GATE: Record<string, string>;
+export declare const ROUTE_ORDER: Record<string, number>;
+export declare const ROUTE_ALIASES: Record<string, string>;
+export declare const GATE_ALIASES: Record<string, string>;
+export declare const GATE_ROUTE: Record<string, string>;
+export declare class GuardError extends Error {
+}
+export declare const runtime: JsonMap;
+export declare function reason(code: string, message: string, refs?: string[] | null): Reason;
+export declare function pinned_ref_key(item: JsonMap): string;
+export declare function trustWarnings(): string[];
+export declare function allow(change: string, gate: string, opts?: {
+    task_id?: string | null;
+    openspec_summary?: Record<string, string>;
+    gate_summary?: Record<string, any>;
+}): Decision;
+export declare function block(change: string, gate: string, reasons: Reason[], opts?: {
+    task_id?: string | null;
+    openspec_summary?: Record<string, string>;
+    gate_summary?: Record<string, any>;
+    next_actions?: string[];
+}): Decision;
+export declare function printDecision(decision: JsonMap): void;
+export declare function runCommand(cmd: string, args: string[], opts?: {
+    cwd?: string;
+    timeout?: number;
+    platform?: NodeJS.Platform;
+}): {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+    error?: Error;
+};
+export declare function sha256_text(text: string): string;
+export declare function sha256_file(filePath: string): string | null;
+export declare function fingerprint_obj(obj: any): string;
+export declare function safe_within(base: string, candidate: string): string | null;
+export declare function now(): string;
+export declare function isObject(value: any): value is JsonMap;
+export declare function repr(value: any): string;
+export declare function renderList(items: any[]): string;
+export declare function walkFiles(root: string): string[];
+export declare function toPosix(pathValue: string): string;
+export declare function commandLookupInvocation(cmd: string, platform?: NodeJS.Platform): {
+    cmd: string;
+    args: string[];
+    shell: boolean;
+};
+export declare function windowsShellEscapeArg(arg: string): string;
+export declare function windowsCmdShimInvocation(cmdPath: string, args: string[], comspec?: string): {
+    cmd: string;
+    args: string[];
+};
+export declare function commandExists(cmd: string, opts?: {
+    cwd?: string;
+    platform?: NodeJS.Platform;
+}): boolean;
+export declare function deepEqual(a: any, b: any): boolean;