@lsctech/polaris 0.1.0

package/dist/finalize/delivery-integrity.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateDeliveryIntegrity = validateDeliveryIntegrity;
+const node_child_process_1 = require("node:child_process");
+const artifact_policy_js_1 = require("./artifact-policy.js");
+const git_custody_js_1 = require("../loop/git-custody.js");
+function getBranchDiff(repoRoot, baseBranch, currentBranch) {
+    if (baseBranch === currentBranch) {
+        return [];
+    }
+    try {
+        const output = (0, node_child_process_1.execFileSync)("git", ["diff", "--name-only", `${baseBranch}...${currentBranch}`], { cwd: repoRoot, encoding: "utf-8" }).trim();
+        return output ? output.split("\n").filter(Boolean) : [];
+    }
+    catch (err) {
+        throw new Error(`delivery-integrity: git diff failed for ${baseBranch}...${currentBranch}: ` +
+            (err instanceof Error ? err.message : String(err)));
+    }
+}
+function getStagedFiles(repoRoot) {
+    try {
+        const output = (0, node_child_process_1.execFileSync)("git", ["diff", "--cached", "--name-only"], { cwd: repoRoot, encoding: "utf-8" }).trim();
+        return output ? output.split("\n").filter(Boolean) : [];
+    }
+    catch {
+        return [];
+    }
+}
+function classifyAll(files, clusterId) {
+    const impl = [];
+    const map = [];
+    const telemetry = [];
+    const other = [];
+    for (const file of files) {
+        const cls = (0, artifact_policy_js_1.classifyArtifactPath)(file, clusterId);
+        if (cls === "non-artifact") {
+            impl.push(file);
+        }
+        else if (cls === "promoted-map-artifact") {
+            map.push(file);
+        }
+        else if (cls === "promoted-run-ledger") {
+            telemetry.push(file);
+        }
+        else {
+            other.push(file);
+        }
+    }
+    return { impl, map, telemetry, other };
+}
+/**
+ * Validates that a finalization delivery actually contains implementation work.
+ *
+ * Checks the combined view of committed branch diff (baseBranch...currentBranch) and
+ * currently staged files. This handles both the normal case (implementation already
+ * committed to delivery branch by workers) and the edge case where implementation is
+ * being staged as part of the finalize commit itself.
+ *
+ * Fails closed: if the check cannot confirm implementation delivery, it returns an
+ * error result instead of passing.
+ */
+function validateDeliveryIntegrity(opts) {
+    const { repoRoot, currentBranch, baseBranch, clusterId, completedChildren, childCommits } = opts;
+    // Combine committed branch diff with staged files to capture the full delivery picture.
+    // Workers commit implementation during execution; the finalize commit adds artifacts.
+    // Either source of non-artifact files is valid evidence of real implementation work.
+    const committedFiles = getBranchDiff(repoRoot, baseBranch, currentBranch);
+    const stagedFiles = getStagedFiles(repoRoot);
+    const allFiles = [...new Set([...committedFiles, ...stagedFiles])];
+    const classified = classifyAll(allFiles, clusterId);
+    if (classified.impl.length > 0) {
+        return { ok: true };
+    }
+    // No implementation source files found. Determine whether this is because
+    // implementation is already on the base branch (PR #93 scenario) or because
+    // the branch genuinely contains no implementation work.
+    const childrenWithCommits = completedChildren.filter((id) => id in childCommits);
+    const childrenAlreadyOnBase = childrenWithCommits.filter((id) => {
+        const commit = childCommits[id];
+        return (0, git_custody_js_1.isCommitReachableFrom)(repoRoot, commit, baseBranch);
+    });
+    if (childrenWithCommits.length > 0 &&
+        childrenAlreadyOnBase.length === childrenWithCommits.length) {
+        return {
+            ok: false,
+            kind: "impl-already-on-base",
+            reason: `Implementation for completed children (${childrenAlreadyOnBase.join(", ")}) is already ` +
+                `reachable from base branch "${baseBranch}". ` +
+                `The delivery branch "${currentBranch}" contains no new implementation relative to "${baseBranch}". ` +
+                `This PR would not deliver any implementation work — only leftover metadata.`,
+        };
+    }
+    if (allFiles.length === 0) {
+        return {
+            ok: false,
+            kind: "empty-branch",
+            reason: `No changes found between "${baseBranch}" and "${currentBranch}" (including staged files). ` +
+                `Nothing to deliver.`,
+        };
+    }
+    // All changes are artifacts/metadata. Produce a specific error for each category
+    // to make the failure reason immediately actionable.
+    const hasMap = classified.map.length > 0;
+    const hasTelemetry = classified.telemetry.length > 0;
+    const hasOther = classified.other.length > 0;
+    const fileList = (files, max = 3) => files.slice(0, max).join(", ") + (files.length > max ? ` (and ${files.length - max} more)` : "");
+    if (hasMap && !hasTelemetry && !hasOther) {
+        return {
+            ok: false,
+            kind: "map-only",
+            reason: `The delivery branch "${currentBranch}" contains only Polaris map artifact changes ` +
+                `(${fileList(classified.map)}) relative to "${baseBranch}". ` +
+                `No implementation source files were found. This PR would deliver only metadata.`,
+        };
+    }
+    if (hasTelemetry && !hasMap && !hasOther) {
+        return {
+            ok: false,
+            kind: "telemetry-only",
+            reason: `The delivery branch "${currentBranch}" contains only telemetry/ledger changes ` +
+                `(${fileList(classified.telemetry)}) relative to "${baseBranch}". ` +
+                `No implementation source files were found. This PR would deliver only telemetry.`,
+        };
+    }
+    if (!hasOther) {
+        return {
+            ok: false,
+            kind: "runtime-artifacts-only",
+            reason: `The delivery branch "${currentBranch}" contains only runtime artifact changes ` +
+                `(map: ${classified.map.length}, telemetry: ${classified.telemetry.length} file(s)) ` +
+                `relative to "${baseBranch}". No implementation source files were found.`,
+        };
+    }
+    return {
+        ok: false,
+        kind: "artifact-only",
+        reason: `The delivery branch "${currentBranch}" contains only artifact/metadata changes ` +
+            `(${fileList(allFiles, 5)}) relative to "${baseBranch}". ` +
+            `No implementation source files were found. This PR would not deliver any implementation work.`,
+    };
+}

package/dist/finalize/finalize.test.js

@@ -0,0 +1,210 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
+const node_child_process_1 = require("node:child_process");
+// ---- helpers ----------------------------------------------------------------
+function makeTestDir() {
+    const dir = (0, node_path_1.join)((0, node_os_1.tmpdir)(), `polaris-finalize-test-${Date.now()}`);
+    (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    (0, node_child_process_1.execFileSync)("git", ["init"], { cwd: dir, stdio: "pipe" });
+    (0, node_child_process_1.execFileSync)("git", ["config", "user.email", "test@test.com"], { cwd: dir, stdio: "pipe" });
+    (0, node_child_process_1.execFileSync)("git", ["config", "user.name", "Test"], { cwd: dir, stdio: "pipe" });
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(dir, "README.md"), "test\n");
+    (0, node_child_process_1.execFileSync)("git", ["add", "."], { cwd: dir, stdio: "pipe" });
+    (0, node_child_process_1.execFileSync)("git", ["commit", "-m", "init"], { cwd: dir, stdio: "pipe" });
+    return dir;
+}
+function writeState(dir, extra = {}) {
+    const stateFile = (0, node_path_1.join)(dir, ".polaris", "runs", "current-state.json");
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(dir, ".polaris", "runs"), { recursive: true });
+    const state = {
+        schema_version: "1.0",
+        run_id: "test-finalize-001",
+        cluster_id: "POL-6",
+        active_child: "",
+        completed_children: ["POL-9", "POL-10", "POL-11"],
+        open_children: [],
+        step_cursor: "CLUSTER-COMPLETE",
+        context_budget: { children_completed: 3 },
+        status: "complete",
+        next_open_child: null,
+        ...extra,
+    };
+    (0, node_fs_1.writeFileSync)(stateFile, JSON.stringify(state, null, 2));
+    return stateFile;
+}
+function writeEmptyAtlas(dir) {
+    const mapDir = (0, node_path_1.join)(dir, ".polaris", "map");
+    (0, node_fs_1.mkdirSync)(mapDir, { recursive: true });
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(mapDir, "file-routes.json"), "{}");
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(mapDir, "needs-review.json"), "{}");
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(mapDir, "exemptions.json"), "{}");
+}
+// ---- step 03: schema validate -----------------------------------------------
+(0, vitest_1.describe)("stepSchemaValidate", () => {
+    (0, vitest_1.it)("passes for valid state", async () => {
+        const { stepSchemaValidate } = await import("./steps/03-schema-validate.js");
+        const validState = {
+            schema_version: "1.0",
+            run_id: "test-finalize-001",
+            cluster_id: "POL-6",
+            active_child: "",
+            completed_children: [],
+            open_children: [],
+            step_cursor: "CLUSTER-COMPLETE",
+            context_budget: { children_completed: 3 },
+            status: "complete",
+        };
+        (0, vitest_1.expect)(() => stepSchemaValidate(validState)).not.toThrow();
+    });
+    (0, vitest_1.it)("calls process.exit(1) for invalid state", async () => {
+        const { stepSchemaValidate } = await import("./steps/03-schema-validate.js");
+        const exitSpy = vitest_1.vi.spyOn(process, "exit").mockImplementation((() => {
+            throw new Error("process.exit called");
+        }));
+        (0, vitest_1.expect)(() => stepSchemaValidate({ schema_version: "1.0" })).toThrow("process.exit called");
+        exitSpy.mockRestore();
+    });
+});
+// ---- step 05: generate report -----------------------------------------------
+(0, vitest_1.describe)("stepGenerateReport", () => {
+    let testDir;
+    (0, vitest_1.beforeEach)(() => { testDir = makeTestDir(); });
+    (0, vitest_1.afterEach)(() => { (0, node_fs_1.rmSync)(testDir, { recursive: true, force: true }); });
+    (0, vitest_1.it)("writes run-report.md with correct sections", async () => {
+        const { stepGenerateReport } = await import("./steps/05-generate-report.js");
+        const stateFile = writeState(testDir);
+        const { readState } = await import("../loop/checkpoint.js");
+        const state = readState(stateFile);
+        const reportPath = stepGenerateReport(testDir, state, "test/finalize-integration", true);
+        (0, vitest_1.expect)((0, node_fs_1.existsSync)(reportPath)).toBe(true);
+        const content = (0, node_fs_1.readFileSync)(reportPath, "utf-8");
+        (0, vitest_1.expect)(content).toContain("# Run Report: test-finalize-001");
+        (0, vitest_1.expect)(content).toContain("**Branch:** test/finalize-integration");
+        (0, vitest_1.expect)(content).toContain("**Validation:** passed");
+        (0, vitest_1.expect)(content).toContain("POL-9");
+        (0, vitest_1.expect)(content).toContain("POL-10");
+        (0, vitest_1.expect)(content).toContain("POL-11");
+    });
+});
+// ---- step 09: update state --------------------------------------------------
+(0, vitest_1.describe)("stepUpdateState", () => {
+    let testDir;
+    (0, vitest_1.beforeEach)(() => { testDir = makeTestDir(); });
+    (0, vitest_1.afterEach)(() => { (0, node_fs_1.rmSync)(testDir, { recursive: true, force: true }); });
+    (0, vitest_1.it)("writes pr_url to current-state.json", async () => {
+        const { stepUpdateState } = await import("./steps/09-update-state.js");
+        const { readState } = await import("../loop/checkpoint.js");
+        const stateFile = writeState(testDir);
+        const state = readState(stateFile);
+        stepUpdateState(stateFile, state, "https://github.com/test/repo/pull/42");
+        const updated = JSON.parse((0, node_fs_1.readFileSync)(stateFile, "utf-8"));
+        (0, vitest_1.expect)(updated["pr_url"]).toBe("https://github.com/test/repo/pull/42");
+    });
+});
+// ---- step 10: append jsonl --------------------------------------------------
+(0, vitest_1.describe)("stepAppendJsonl", () => {
+    let testDir;
+    (0, vitest_1.beforeEach)(() => { testDir = makeTestDir(); });
+    (0, vitest_1.afterEach)(() => { (0, node_fs_1.rmSync)(testDir, { recursive: true, force: true }); });
+    (0, vitest_1.it)("appends pr-opened and run-complete events", async () => {
+        const { stepAppendJsonl } = await import("./steps/10-append-jsonl.js");
+        const { readState } = await import("../loop/checkpoint.js");
+        const stateFile = writeState(testDir);
+        const state = readState(stateFile);
+        const telemetryFile = (0, node_path_1.join)(testDir, "telemetry.jsonl");
+        const prUrl = "https://github.com/test/repo/pull/42";
+        stepAppendJsonl(telemetryFile, state, prUrl);
+        const lines = (0, node_fs_1.readFileSync)(telemetryFile, "utf-8")
+            .trim()
+            .split("\n")
+            .map((l) => JSON.parse(l));
+        (0, vitest_1.expect)(lines).toHaveLength(2);
+        (0, vitest_1.expect)(lines[0]["event"]).toBe("pr-opened");
+        (0, vitest_1.expect)(lines[0]["pr_url"]).toBe(prUrl);
+        (0, vitest_1.expect)(lines[0]["run_id"]).toBe("test-finalize-001");
+        (0, vitest_1.expect)(lines[1]["event"]).toBe("run-complete");
+        (0, vitest_1.expect)(lines[1]["children_completed"]).toBe(3);
+    });
+});
+// ---- step 11: update linear (disabled) --------------------------------------
+(0, vitest_1.describe)("stepUpdateLinear", () => {
+    (0, vitest_1.it)("skips when linearEnabled is false", async () => {
+        const { stepUpdateLinear } = await import("./steps/11-update-linear.js");
+        const { readState } = await import("../loop/checkpoint.js");
+        const dir = makeTestDir();
+        const stateFile = writeState(dir);
+        const state = readState(stateFile);
+        // Should resolve without error when disabled
+        await (0, vitest_1.expect)(stepUpdateLinear(state, "test-branch", "https://example.com/pr/1", true, false)).resolves.toBeUndefined();
+        (0, node_fs_1.rmSync)(dir, { recursive: true, force: true });
+    });
+});
+// ---- step 12: archive -------------------------------------------------------
+(0, vitest_1.describe)("stepArchive", () => {
+    let testDir;
+    (0, vitest_1.beforeEach)(() => { testDir = makeTestDir(); });
+    (0, vitest_1.afterEach)(() => { (0, node_fs_1.rmSync)(testDir, { recursive: true, force: true }); });
+    (0, vitest_1.it)("copies state and report to .polaris/runs/<run_id>/", async () => {
+        const { stepArchive } = await import("./steps/12-archive.js");
+        const { readState } = await import("../loop/checkpoint.js");
+        const stateFile = writeState(testDir);
+        const state = readState(stateFile);
+        const reportPath = (0, node_path_1.join)(testDir, ".polaris", "runs", "run-report.md");
+        (0, node_fs_1.mkdirSync)((0, node_path_1.join)(testDir, ".polaris", "runs"), { recursive: true });
+        (0, node_fs_1.writeFileSync)(reportPath, "# Run Report: test-finalize-001\n");
+        stepArchive(testDir, state, stateFile, reportPath);
+        const archiveDir = (0, node_path_1.join)(testDir, ".polaris", "runs", "test-finalize-001");
+        (0, vitest_1.expect)((0, node_fs_1.existsSync)((0, node_path_1.join)(archiveDir, "current-state.json"))).toBe(true);
+        (0, vitest_1.expect)((0, node_fs_1.existsSync)((0, node_path_1.join)(archiveDir, "run-report.md"))).toBe(true);
+    });
+});
+// ---- runFinalize steps 1–6 (skip-delivery) ----------------------------------
+(0, vitest_1.describe)("runFinalize (steps 1–6, skip-delivery)", () => {
+    let testDir;
+    (0, vitest_1.beforeEach)(() => { testDir = makeTestDir(); });
+    (0, vitest_1.afterEach)(() => { (0, node_fs_1.rmSync)(testDir, { recursive: true, force: true }); });
+    (0, vitest_1.it)("runs steps 1–6 end-to-end and creates a commit", async () => {
+        const { runFinalize } = await import("./index.js");
+        const stateFile = writeState(testDir);
+        writeEmptyAtlas(testDir);
+        // Capture stdout
+        const logSpy = vitest_1.vi.spyOn(console, "log").mockImplementation(() => { });
+        try {
+            await runFinalize({ repoRoot: testDir, stateFile, skipDelivery: true });
+        }
+        finally {
+            logSpy.mockRestore();
+        }
+        // Step 5 verification: run-report.md written
+        const reportPath = (0, node_path_1.join)(testDir, ".polaris", "runs", "run-report.md");
+        (0, vitest_1.expect)((0, node_fs_1.existsSync)(reportPath)).toBe(true);
+        const report = (0, node_fs_1.readFileSync)(reportPath, "utf-8");
+        (0, vitest_1.expect)(report).toContain("# Run Report: test-finalize-001");
+        (0, vitest_1.expect)(report).toContain("**Validation:** passed");
+        // Step 6 verification: commit created
+        const log = (0, node_child_process_1.execFileSync)("git", ["log", "--oneline", "-1"], {
+            cwd: testDir,
+            encoding: "utf-8",
+        });
+        (0, vitest_1.expect)(log).toContain("polaris finalize: test-finalize-001");
+    });
+    (0, vitest_1.it)("aborts on missing state file", async () => {
+        const { runFinalize } = await import("./index.js");
+        writeEmptyAtlas(testDir);
+        const exitSpy = vitest_1.vi.spyOn(process, "exit").mockImplementation((() => {
+            throw new Error("process.exit called");
+        }));
+        const stderrSpy = vitest_1.vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+        await (0, vitest_1.expect)(runFinalize({
+            repoRoot: testDir,
+            stateFile: (0, node_path_1.join)(testDir, "nonexistent.json"),
+            skipDelivery: true,
+        })).rejects.toThrow("process.exit called");
+        exitSpy.mockRestore();
+        stderrSpy.mockRestore();
+    });
+});

package/dist/finalize/github.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDraftPr = createDraftPr;
+const node_child_process_1 = require("node:child_process");
+function createDraftPr(options) {
+    const { repoRoot, branch, state, draft } = options;
+    if (!state.cluster_id) {
+        throw new Error(`createDraftPr: state.cluster_id is empty — cannot create PR without a cluster identifier`);
+    }
+    const clusterSlug = state.cluster_id.toLowerCase().replace(/[^a-z0-9]/g, "-");
+    const branchNorm = branch.toLowerCase().replace(/[^a-z0-9]/g, "-");
+    // Boundary-aware: clusterSlug must match as a full token (surrounded by start/end or hyphens)
+    const slugPattern = new RegExp(`(^|-)${clusterSlug.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(-|$)`);
+    if (!slugPattern.test(branchNorm)) {
+        throw new Error(`createDraftPr: branch "${branch}" does not contain cluster ID slug "${clusterSlug}" — ` +
+            `branch/cluster mismatch, aborting PR creation`);
+    }
+    const title = `polaris finalize: ${state.cluster_id} (${state.run_id})`;
+    const body = [
+        `**Cluster ID:** ${state.cluster_id}`,
+        `**Run ID:** ${state.run_id}`,
+        `**Branch:** ${branch}`,
+        `**Children completed:** ${state.completed_children.length}`,
+        ``,
+        `_Generated by polaris finalize_`,
+    ].join("\n");
+    const args = [
+        "pr", "create",
+        "--title", title,
+        "--body", body,
+        "--head", branch,
+    ];
+    if (draft)
+        args.push("--draft");
+    const output = (0, node_child_process_1.execFileSync)("gh", args, {
+        cwd: repoRoot,
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "inherit"],
+    });
+    return output.trim();
+}