@peterxiaoyang/superspec 0.1.14 → 0.1.15-alpha

package/dist/src/archive.js

@@ -1,430 +0,0 @@
-import { closeSync, copyFileSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { dirname, join, relative } from "node:path";
-import { STATE_LOCK_FILENAME, allow, block, now, reason, renderList, repr, runtime, safe_within, sha256_file, sha256_text, toPosix, walkFiles, } from "./util.js";
-import { ensure_state_layout, sidecar_artifacts_dir, superspec_dir } from "./paths.js";
-export function archive_manifest_path(changeRoot) {
-    return join(sidecar_artifacts_dir(changeRoot), "archive-preservation.json");
-}
-export function archive_preservation_dir(changeRoot) {
-    return join(changeRoot, "superspec-preservation");
-}
-export function archive_preservation_manifest_path(changeRoot) {
-    return join(archive_preservation_dir(changeRoot), "manifest.json");
-}
-function archive_staging_root(changeRoot, runId) {
-    return join(changeRoot, ".superspec-staging", runId);
-}
-function fsync_dir_best_effort(dirPath) {
-    let fd = null;
-    try {
-        fd = openSync(dirPath, "r");
-        fsyncSync(fd);
-    }
-    catch {
-        // Directory fsync is best-effort across platforms.
-    }
-    finally {
-        if (fd !== null)
-            closeSync(fd);
-    }
-}
-function write_text(path, text) {
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, text, "utf8");
-}
-function excluded_manifest_entry(relPath) {
-    if (relPath.endsWith(STATE_LOCK_FILENAME) || relPath.endsWith("superspec-state.tmp"))
-        return true;
-    if (relPath === ".superspec/hook-runtime" || relPath.startsWith(".superspec/hook-runtime/"))
-        return true;
-    if (relPath === ".superspec/artifacts/archive-preservation.json")
-        return true;
-    return false;
-}
-function manifest_entries(changeRoot, fileOverrides = {}) {
-    const base = superspec_dir(changeRoot);
-    const entries = [];
-    const pendingOverrides = new Set(Object.keys(fileOverrides));
-    if (existsSync(base) && statSync(base).isDirectory()) {
-        for (const filePath of walkFiles(base).sort()) {
-            const relPath = toPosix(relative(changeRoot, filePath));
-            if (excluded_manifest_entry(relPath))
-                continue;
-            if (pendingOverrides.has(relPath)) {
-                entries.push({ path: relPath, sha256: sha256_text(fileOverrides[relPath]) });
-                pendingOverrides.delete(relPath);
-            }
-            else {
-                entries.push({ path: relPath, sha256: sha256_file(filePath) });
-            }
-        }
-    }
-    for (const relPath of [...pendingOverrides].sort()) {
-        if (excluded_manifest_entry(relPath))
-            continue;
-        entries.push({ path: relPath, sha256: sha256_text(fileOverrides[relPath]) });
-    }
-    return entries.sort((a, b) => String(a.path).localeCompare(String(b.path)));
-}
-export function sidecar_manifest_entries(changeRoot) {
-    return manifest_entries(changeRoot);
-}
-function archive_manifest_data(change, changeRoot, fileOverrides = {}) {
-    ensure_state_layout(changeRoot);
-    return {
-        schema_version: 1,
-        change_id: change,
-        created_at: now(),
-        kind: "superspec_archive_preservation",
-        entries: manifest_entries(changeRoot, fileOverrides),
-    };
-}
-function write_manifest_file(filePath, manifest) {
-    write_text(filePath, `${JSON.stringify(manifest, null, 2)}\n`);
-    return filePath;
-}
-export function write_archive_manifest(change, changeRoot) {
-    return write_manifest_file(archive_manifest_path(changeRoot), archive_manifest_data(change, changeRoot));
-}
-function stage_archive_bundle(change, changeRoot, runId, fileOverrides) {
-    const stagingRoot = archive_staging_root(changeRoot, runId);
-    const stagedManifestPath = join(stagingRoot, "next", "archive-preservation.json");
-    const stagedBundleDir = join(stagingRoot, "next", "superspec-preservation");
-    const stagedFilesRoot = join(stagedBundleDir, "files");
-    const manifest = archive_manifest_data(change, changeRoot, fileOverrides);
-    write_manifest_file(stagedManifestPath, manifest);
-    for (const entry of manifest.entries ?? []) {
-        const relPath = entry.path;
-        if (typeof relPath !== "string")
-            continue;
-        const dst = join(stagedFilesRoot, relPath);
-        if (relPath in fileOverrides) {
-            write_text(dst, fileOverrides[relPath]);
-            continue;
-        }
-        const src = join(changeRoot, relPath);
-        if (!existsSync(src) || !statSync(src).isFile())
-            continue;
-        mkdirSync(dirname(dst), { recursive: true });
-        copyFileSync(src, dst);
-    }
-    const bundleManifest = {
-        ...manifest,
-        kind: "superspec_archive_preservation_bundle",
-        source_manifest: ".superspec/artifacts/archive-preservation.json",
-        files_root: "files",
-    };
-    const stagedBundleManifestPath = join(stagedBundleDir, "manifest.json");
-    write_text(stagedBundleManifestPath, `${JSON.stringify(bundleManifest, null, 2)}\n`);
-    return { staged_manifest_path: stagedManifestPath, staged_bundle_dir: stagedBundleDir };
-}
-function restore_file_from_backup(finalPath, backupPath, hadFinal) {
-    if (existsSync(backupPath)) {
-        if (existsSync(finalPath))
-            rmSync(finalPath, { force: true });
-        mkdirSync(dirname(finalPath), { recursive: true });
-        renameSync(backupPath, finalPath);
-    }
-    else if (!hadFinal) {
-        if (existsSync(finalPath))
-            rmSync(finalPath, { force: true });
-    }
-    else {
-        throw new Error(`backup missing for ${finalPath}`);
-    }
-}
-function restore_dir_from_backup(finalPath, backupPath, hadFinal) {
-    if (existsSync(backupPath)) {
-        if (existsSync(finalPath))
-            rmSync(finalPath, { recursive: true, force: true });
-        renameSync(backupPath, finalPath);
-    }
-    else if (!hadFinal) {
-        if (existsSync(finalPath))
-            rmSync(finalPath, { recursive: true, force: true });
-    }
-    else {
-        throw new Error(`backup missing for ${finalPath}`);
-    }
-}
-function restore_promoted_bundle(state) {
-    restore_file_from_backup(state.final_manifest, state.backup_manifest, state.had_final_manifest);
-    restore_dir_from_backup(state.final_bundle_dir, state.backup_bundle_dir, state.had_final_bundle);
-}
-function promote_archive_bundle(changeRoot, runId, stagedManifestPath, stagedBundleDir) {
-    const finalManifest = archive_manifest_path(changeRoot);
-    const finalBundleDir = archive_preservation_dir(changeRoot);
-    const stagingRoot = archive_staging_root(changeRoot, runId);
-    const backupRoot = join(stagingRoot, "backup");
-    const backupManifest = join(backupRoot, "archive-preservation.json");
-    const backupBundleDir = join(backupRoot, "superspec-preservation");
-    const hadFinalManifest = existsSync(finalManifest);
-    const hadFinalBundle = existsSync(finalBundleDir);
-    const state = {
-        staging_root: stagingRoot,
-        final_manifest: finalManifest,
-        final_bundle_dir: finalBundleDir,
-        backup_manifest: backupManifest,
-        backup_bundle_dir: backupBundleDir,
-        had_final_manifest: hadFinalManifest,
-        had_final_bundle: hadFinalBundle,
-    };
-    mkdirSync(backupRoot, { recursive: true });
-    try {
-        if (hadFinalBundle) {
-            renameSync(finalBundleDir, backupBundleDir);
-            fsync_dir_best_effort(changeRoot);
-        }
-        if (hadFinalManifest) {
-            mkdirSync(dirname(backupManifest), { recursive: true });
-            renameSync(finalManifest, backupManifest);
-            fsync_dir_best_effort(dirname(finalManifest));
-        }
-        renameSync(stagedBundleDir, finalBundleDir);
-        fsync_dir_best_effort(changeRoot);
-        if (typeof runtime.after_archive_bundle_promote === "function") {
-            runtime.after_archive_bundle_promote({
-                change_root: changeRoot,
-                final_bundle_dir: finalBundleDir,
-                final_manifest: finalManifest,
-            });
-        }
-        mkdirSync(dirname(finalManifest), { recursive: true });
-        renameSync(stagedManifestPath, finalManifest);
-        fsync_dir_best_effort(dirname(finalManifest));
-        return state;
-    }
-    catch (err) {
-        try {
-            restore_promoted_bundle(state);
-            rmSync(stagingRoot, { recursive: true, force: true });
-        }
-        catch (restoreErr) {
-            throw new Error(`archive preservation promote failed: ${err.message}; rollback failed: ${restoreErr.message}`);
-        }
-        throw err;
-    }
-}
-export function begin_archive_preservation_bundle(change, changeRoot, opts = {}) {
-    const runId = `${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
-    const staged = stage_archive_bundle(change, changeRoot, runId, opts.file_overrides ?? {});
-    const promotion = promote_archive_bundle(changeRoot, runId, staged.staged_manifest_path, staged.staged_bundle_dir);
-    let settled = false;
-    return {
-        manifest_path: archive_manifest_path(changeRoot),
-        bundle_manifest_path: archive_preservation_manifest_path(changeRoot),
-        commit: () => {
-            if (settled)
-                return;
-            settled = true;
-            try {
-                rmSync(promotion.staging_root, { recursive: true, force: true });
-            }
-            catch {
-                // Commit is already durable; staging cleanup is best-effort.
-            }
-        },
-        rollback: () => {
-            if (settled)
-                return;
-            restore_promoted_bundle(promotion);
-            rmSync(promotion.staging_root, { recursive: true, force: true });
-            settled = true;
-        },
-    };
-}
-export function write_archive_preservation_bundle(change, changeRoot, opts = {}) {
-    const txn = begin_archive_preservation_bundle(change, changeRoot, opts);
-    txn.commit();
-    return txn.bundle_manifest_path;
-}
-export function find_archived_change(repoRoot, change) {
-    const archiveRoot = join(repoRoot, "openspec", "changes", "archive");
-    if (!existsSync(archiveRoot) || !lstatSync(archiveRoot).isDirectory())
-        return null;
-    const candidates = readdirSync(archiveRoot)
-        .filter((name) => name === change || (/^\d{4}-\d{2}-\d{2}-.+/.test(name) && name.slice(11) === change))
-        .map((name) => join(archiveRoot, name))
-        .filter((item) => {
-        const stat = lstatSync(item);
-        return !stat.isSymbolicLink() && stat.isDirectory();
-    })
-        .sort();
-    return candidates.at(-1) ?? null;
-}
-function manifest_change_id_reasons(change, manifest, label) {
-    if (manifest.change_id !== change) {
-        return [reason("archive_manifest_mismatch", `${label} manifest change_id=${repr(manifest.change_id)} does not match ${repr(change)}`)];
-    }
-    return [];
-}
-const PRIMARY_ARCHIVE_MANIFEST_KIND = "superspec_archive_preservation";
-const FALLBACK_ARCHIVE_MANIFEST_KIND = "superspec_archive_preservation_bundle";
-const REQUIRED_ARCHIVE_ENTRIES = [".superspec/ledger.jsonl", ".superspec/superspec-state.json"];
-function manifest_shape_reasons(change, manifest, label, expectedKind) {
-    const reasons = manifest_change_id_reasons(change, manifest, label);
-    if (manifest.kind !== expectedKind) {
-        reasons.push(reason("archive_manifest_mismatch", `${label} manifest kind=${repr(manifest.kind)} does not match ${repr(expectedKind)}`));
-    }
-    if (!Array.isArray(manifest.entries) || manifest.entries.length === 0) {
-        reasons.push(reason("archive_manifest_mismatch", `${label} manifest entries must be a non-empty list`));
-        return reasons;
-    }
-    const paths = new Set();
-    for (const entry of manifest.entries) {
-        if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
-            reasons.push(reason("archive_manifest_mismatch", `${label} manifest entries must be objects`));
-            continue;
-        }
-        if (typeof entry.path === "string")
-            paths.add(entry.path);
-    }
-    const missingRequired = REQUIRED_ARCHIVE_ENTRIES.filter((entry) => !paths.has(entry));
-    if (missingRequired.length > 0) {
-        reasons.push(reason("archive_manifest_mismatch", `${label} manifest missing required entries: ${renderList([...missingRequired])}`, [...missingRequired]));
-    }
-    return reasons;
-}
-function manifest_entry_target(baseRoot, relPath) {
-    if (!relPath.startsWith(".superspec/"))
-        return null;
-    return safe_within(baseRoot, relPath);
-}
-function preserved_file_sha(filePath) {
-    if (!existsSync(filePath))
-        return null;
-    const stat = lstatSync(filePath);
-    if (stat.isSymbolicLink() || !stat.isFile() || stat.nlink > 1)
-        return null;
-    return sha256_file(filePath);
-}
-export function check_archived(change, repoRoot) {
-    const archived = find_archived_change(repoRoot, change);
-    if (archived === null)
-        return block(change, "archived", [reason("archive_not_found", `archived change not found for ${change}`)]);
-    const manifestPath = archive_manifest_path(archived);
-    if (!existsSync(manifestPath) || !statSync(manifestPath).isFile()) {
-        const fallbackManifest = archive_preservation_manifest_path(archived);
-        if (!existsSync(fallbackManifest) || !statSync(fallbackManifest).isFile()) {
-            return block(change, "archived", [reason("superspec_not_preserved", "archive preservation manifest missing")]);
-        }
-        return check_archived_preservation_bundle(change, archived, fallbackManifest);
-    }
-    let manifest;
-    try {
-        manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
-    }
-    catch {
-        return block(change, "archived", [reason("superspec_not_preserved", "archive preservation manifest is invalid JSON")]);
-    }
-    const shapeReasons = manifest_shape_reasons(change, manifest, "archive preservation", PRIMARY_ARCHIVE_MANIFEST_KIND);
-    if (shapeReasons.length > 0)
-        return block(change, "archived", shapeReasons);
-    const missing = [];
-    const mismatched = [];
-    const invalid = [];
-    for (const entry of manifest.entries) {
-        const relPath = entry.path;
-        const expected = entry.sha256;
-        if (typeof relPath !== "string" || typeof expected !== "string") {
-            mismatched.push(String(relPath));
-            continue;
-        }
-        const filePath = manifest_entry_target(archived, relPath);
-        if (filePath === null) {
-            invalid.push(relPath);
-            continue;
-        }
-        const actual = preserved_file_sha(filePath);
-        if (actual === null)
-            missing.push(relPath);
-        else if (actual !== expected)
-            mismatched.push(relPath);
-    }
-    const reasons = [];
-    if (invalid.length > 0)
-        reasons.push(reason("archive_manifest_mismatch", `archived .superspec manifest paths are invalid: ${renderList(invalid.slice(0, 20))}`, invalid.slice(0, 20)));
-    if (missing.length > 0)
-        reasons.push(reason("superspec_not_preserved", `archived .superspec files missing: ${renderList(missing.slice(0, 20))}`));
-    if (mismatched.length > 0)
-        reasons.push(reason("archive_manifest_mismatch", `archived .superspec files changed: ${renderList(mismatched.slice(0, 20))}`));
-    if (reasons.length > 0)
-        return block(change, "archived", reasons);
-    return allow(change, "archived", { gate_summary: { archive_root: archived, manifest_entries: (manifest.entries ?? []).length } });
-}
-export function check_archived_preservation_bundle(change, archived, manifestPath) {
-    let manifest;
-    try {
-        manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
-    }
-    catch {
-        return block(change, "archived", [reason("superspec_not_preserved", "fallback preservation manifest is invalid JSON")]);
-    }
-    const shapeReasons = manifest_shape_reasons(change, manifest, "fallback preservation", FALLBACK_ARCHIVE_MANIFEST_KIND);
-    if (shapeReasons.length > 0)
-        return block(change, "archived", shapeReasons);
-    if (typeof manifest.files_root !== "string" || !manifest.files_root) {
-        return block(change, "archived", [reason("archive_manifest_mismatch", "fallback preservation manifest requires files_root")]);
-    }
-    const filesRoot = safe_within(dirname(manifestPath), manifest.files_root);
-    if (filesRoot === null || !existsSync(filesRoot) || !lstatSync(filesRoot).isDirectory()) {
-        return block(change, "archived", [reason("archive_manifest_mismatch", `fallback preservation files_root is invalid: ${repr(manifest.files_root)}`)]);
-    }
-    const missing = [];
-    const mismatched = [];
-    const invalid = [];
-    for (const entry of manifest.entries) {
-        const relPath = entry.path;
-        const expected = entry.sha256;
-        if (typeof relPath !== "string" || typeof expected !== "string") {
-            mismatched.push(String(relPath));
-            continue;
-        }
-        const filePath = manifest_entry_target(filesRoot, relPath);
-        if (filePath === null) {
-            invalid.push(relPath);
-            continue;
-        }
-        const actual = preserved_file_sha(filePath);
-        if (actual === null)
-            missing.push(relPath);
-        else if (actual !== expected)
-            mismatched.push(relPath);
-    }
-    const reasons = [];
-    if (invalid.length > 0)
-        reasons.push(reason("archive_manifest_mismatch", `fallback .superspec manifest paths are invalid: ${renderList(invalid.slice(0, 20))}`, invalid.slice(0, 20)));
-    if (missing.length > 0)
-        reasons.push(reason("superspec_not_preserved", `fallback .superspec files missing: ${renderList(missing.slice(0, 20))}`));
-    if (mismatched.length > 0)
-        reasons.push(reason("archive_manifest_mismatch", `fallback .superspec files changed: ${renderList(mismatched.slice(0, 20))}`));
-    if (reasons.length > 0)
-        return block(change, "archived", reasons);
-    return allow(change, "archived", {
-        gate_summary: {
-            archive_root: archived,
-            fallback_manifest: toPosix(relative(archived, manifestPath)),
-            manifest_entries: (manifest.entries ?? []).length,
-        },
-    });
-}
-export function preset_upgrade_required(preset, changedPaths, flags = {}) {
-    if (preset === "full")
-        return false;
-    if (preset === "hotfix")
-        return changedPaths.length >= 3 || Boolean(flags.architecture) || Boolean(flags.schema) || Boolean(flags.public_api) || Boolean(flags.cross_module);
-    if (preset === "tweak")
-        return changedPaths.length >= 5 || Boolean(flags.cross_module) || Number(flags.new_tests ?? 0) >= 5 || Boolean(flags.config_key_add_remove);
-    return true;
-}
-export function preset_upgrade_reasons(config, changedPaths, humanConfirmed = false, flags = {}) {
-    const preset = String(config.preset ?? "full");
-    if (!preset_upgrade_required(preset, changedPaths, flags))
-        return [];
-    if (humanConfirmed)
-        return [];
-    return [reason("preset_upgrade_requires_human_confirmation", `preset ${repr(preset)} must upgrade to full before proceeding`)];
-}
-export function preset_upgrade_required_from_context(config, changedPaths) {
-    return preset_upgrade_required(String(config.preset ?? "full"), changedPaths);
-}

package/dist/src/cli.d.ts

@@ -1 +0,0 @@
-export declare function main(argv?: string[]): number;

package/dist/src/cli.js

@@ -1,33 +0,0 @@
-import { block, dispatch, GuardError, printDecision, reason } from "./core.js";
-import { emitArgparsePreamble, parse_argv } from "./cli_args.js";
-import { dispatch_packet, is_packet_command } from "./packet_render.js";
-import { printPacket, printPacketError } from "./util.js";
-export function main(argv = process.argv.slice(2)) {
-    let args = null;
-    const rawCommand = argv[0] ?? "";
-    try {
-        const argparseExit = emitArgparsePreamble(argv);
-        if (argparseExit !== null)
-            return argparseExit;
-        args = parse_argv(argv);
-        if (is_packet_command(args.command)) {
-            const result = dispatch_packet(args);
-            printPacket(result.payload, { format: result.output_format });
-            return 0;
-        }
-        const [decision] = dispatch(args);
-        printDecision(decision, { command: args.command, format: args.format });
-        return decision.allowed ? 0 : 1;
-    }
-    catch (err) {
-        if ((args && is_packet_command(args.command)) || is_packet_command(rawCommand)) {
-            const errCode = err instanceof GuardError ? "guard_error" : "guard_internal_error";
-            printPacketError(errCode, `${err.message}`);
-            return 2;
-        }
-        const change = args?.change ?? "?";
-        const errReason = err instanceof GuardError ? reason("guard_error", err.message) : reason("guard_internal_error", `${err.name}: ${err.message}`);
-        printDecision(block(change, "guard_error", [errReason]), { command: args?.command, format: args?.format });
-        return 2;
-    }
-}

package/dist/src/cli_args.d.ts

@@ -1,32 +0,0 @@
-import { type DecisionOutputFormat, type PacketOutputFormat } from "./util.ts";
-export type ParsedArgs = {
-    command: string;
-    change: string;
-    format?: DecisionOutputFormat;
-    packet_format?: PacketOutputFormat;
-    artifact?: string;
-    gate?: string;
-    task_id?: string;
-    test_id?: string;
-    phase?: "red" | "characterization" | "green";
-    event_ref?: string;
-    workflow?: string;
-    entrypoint_token?: string;
-    end_reason?: string;
-    lifecycle_token?: string;
-    role?: string;
-    evidence_kind?: string;
-    round?: number;
-    executor_report_refs?: string[];
-    task_code_review_report_refs?: string[];
-    apply_worker_chain_refs?: string[];
-    green_test_run_evidence_refs?: string[];
-    alternative_verification_evidence_refs?: string[];
-    red_test_run_evidence_refs?: string[];
-    characterization_test_run_evidence_refs?: string[];
-    create?: boolean;
-    force_unlock?: boolean;
-    rebuild_corrupt?: boolean;
-};
-export declare function emitArgparsePreamble(argv: string[]): number | null;
-export declare function parse_argv(argv: string[]): ParsedArgs;