@lsctech/polaris 0.5.10 → 0.5.12

package/dist/qc/providers/coderabbit.js

@@ -16,7 +16,7 @@ function pickString(...candidates) {
     }
     return undefined;
 }
-const FINDING_LOCATION_KEYS = ["file", "filePath", "path"];
+const FINDING_LOCATION_KEYS = ["file", "filePath", "path", "fileName"];
 const FINDING_CONTENT_KEYS = [
     "message",
     "title",
@@ -26,6 +26,7 @@ const FINDING_CONTENT_KEYS = [
     "suggestion",
     "suggestedAction",
     "fix",
+    "codegenInstructions",
 ];
 const FINDING_BOOKKEEPING_KEYS = [
     "severity",
@@ -36,6 +37,8 @@ const FINDING_BOOKKEEPING_KEYS = [
     "findingId",
 ];
 const PROGRESS_SHAPE_KEYS = new Set(["event", "progress", "heartbeat", "complete", "review_context"]);
+const ERROR_TYPE_RATE_LIMIT = new Set(["rate_limit", "rate-limit", "ratelimit", "rate limit"]);
+const ERROR_TYPE_AUTH = new Set(["auth", "authentication", "unauthorized", "unauthorised", "forbidden"]);
 const PROGRESS_TYPE_VALUES = new Set([
     "progress",
     "status",
@@ -55,6 +58,14 @@ const PROGRESS_STATUS_VALUES = new Set([
     "ok",
     "success",
 ]);
+const TERMINAL_COMPLETE_STATUSES = new Set([
+    "review_completed",
+    "review_skipped",
+    "completed",
+    "complete",
+    "done",
+    "success",
+]);
 function hasFindingLocation(record) {
     return FINDING_LOCATION_KEYS.some((key) => record[key] !== undefined);
 }
@@ -111,6 +122,8 @@ function isProgressRecord(record) {
     return false;
 }
 function isActionableFinding(record) {
+    if (isErrorRecord(record))
+        return false;
     if (isProgressRecord(record))
         return false;
     return hasFindingLocation(record) || hasFindingContent(record);
@@ -123,6 +136,85 @@ function makeUnusableOutputError(message) {
     err.qcFailureReason = "unusable-output";
     return err;
 }
+function makeQcFailureError(reason, message) {
+    const err = new Error(message);
+    err.qcFailureReason = reason;
+    return err;
+}
+function isErrorRecord(record) {
+    if (record.type === "error")
+        return true;
+    if (typeof record.errorType === "string")
+        return true;
+    if (record.error === true || record.error === "true")
+        return true;
+    return false;
+}
+function errorTypeFromRecord(record) {
+    const fromType = typeof record.errorType === "string" ? record.errorType : undefined;
+    const fromMessage = typeof record.message === "string" ? record.message : undefined;
+    return fromType ?? fromMessage;
+}
+function classifyErrorType(record) {
+    const raw = errorTypeFromRecord(record);
+    const errorType = (raw ?? "").toString().toLowerCase().trim();
+    if (errorType === "")
+        return "unavailable-provider";
+    if (ERROR_TYPE_RATE_LIMIT.has(errorType))
+        return "rate-limited";
+    if (ERROR_TYPE_AUTH.has(errorType))
+        return "auth-failure";
+    if (errorType.includes("rate limit"))
+        return "rate-limited";
+    if (errorType.includes("auth"))
+        return "auth-failure";
+    if (errorType.includes("unauthorized"))
+        return "auth-failure";
+    if (errorType.includes("forbidden"))
+        return "auth-failure";
+    if (["timeout", "timed out"].includes(errorType))
+        return "timeout";
+    if (errorType.includes("not found") || errorType.includes("not_found"))
+        return "command-not-found";
+    if (errorType.includes("unavailable") || errorType.includes("api_error") || errorType.includes("apierror") || errorType.includes("server") || errorType.includes("network") || errorType.includes("connection") || errorType.includes("internal")) {
+        return "unavailable-provider";
+    }
+    return "unavailable-provider";
+}
+function getTerminalCompleteFindingsCount(record) {
+    if (record.findings !== undefined) {
+        if (Array.isArray(record.findings)) {
+            return record.findings.length;
+        }
+        const count = typeof record.findings === "number" ? record.findings : Number(record.findings);
+        if (Number.isFinite(count))
+            return count;
+    }
+    const summary = record.summary;
+    if (summary && typeof summary === "object") {
+        const summaryRecord = summary;
+        if (summaryRecord.total !== undefined) {
+            const count = Number(summaryRecord.total);
+            if (Number.isFinite(count))
+                return count;
+        }
+        if (summaryRecord.issues !== undefined) {
+            const count = Number(summaryRecord.issues);
+            if (Number.isFinite(count))
+                return count;
+        }
+    }
+    return undefined;
+}
+function isTerminalCompleteNoFindings(record) {
+    if (record.type !== "complete")
+        return false;
+    const status = typeof record.status === "string" ? record.status.trim().toLowerCase() : "";
+    if (!TERMINAL_COMPLETE_STATUSES.has(status))
+        return false;
+    const count = getTerminalCompleteFindingsCount(record);
+    return count === undefined || count === 0;
+}
 function buildRange(raw) {
     const startLine = coerceNumber(raw.startLine ?? raw.line) ?? 1;
     const endLine = coerceNumber(raw.endLine);
@@ -143,14 +235,27 @@ function parseFindingsFromPayload(payload) {
         return [];
     }
     const record = payload;
-    if (Array.isArray(record.findings)) {
-        return record.findings.filter((item) => typeof item === "object" && item !== null && isActionableFinding(item));
-    }
-    if (Array.isArray(record.issues)) {
-        return record.issues.filter((item) => typeof item === "object" && item !== null && isActionableFinding(item));
+    if (isErrorRecord(record)) {
+        throw makeQcFailureError(classifyErrorType(record), `CodeRabbit provider returned an error: ${record.message ?? record.errorType ?? "unknown"}`);
     }
-    if (Array.isArray(record.results)) {
-        return record.results.filter((item) => typeof item === "object" && item !== null && isActionableFinding(item));
+    const arrays = [record.findings, record.issues, record.results];
+    for (const arr of arrays) {
+        if (Array.isArray(arr)) {
+            const findings = [];
+            for (const item of arr) {
+                if (typeof item !== "object" || item === null) {
+                    continue;
+                }
+                const itemRecord = item;
+                if (isErrorRecord(itemRecord)) {
+                    throw makeQcFailureError(classifyErrorType(itemRecord), `CodeRabbit provider returned an error in findings array: ${itemRecord.message ?? itemRecord.errorType ?? "unknown"}`);
+                }
+                if (isActionableFinding(itemRecord)) {
+                    findings.push(item);
+                }
+            }
+            return findings;
+        }
     }
     // Single finding wrapped in an object
     if (isActionableFinding(record)) {
@@ -171,6 +276,9 @@ function parseReport(output, format, parser) {
         const findings = parseFindingsFromPayload(data);
         const record = data;
         if (findings.length === 0) {
+            if (isTerminalCompleteNoFindings(record)) {
+                return { findings: [] };
+            }
             if (isProgressRecord(record)) {
                 throw makeUnusableOutputError("CodeRabbit output was a progress/status/heartbeat record");
             }
@@ -197,7 +305,19 @@ function parseReport(output, format, parser) {
         try {
             const parsed = JSON.parse(text);
             if (Array.isArray(parsed)) {
-                const findings = parsed.filter((item) => typeof item === "object" && item !== null && isActionableFinding(item));
+                const findings = [];
+                for (const item of parsed) {
+                    if (typeof item !== "object" || item === null) {
+                        continue;
+                    }
+                    const itemRecord = item;
+                    if (isErrorRecord(itemRecord)) {
+                        throw makeQcFailureError(classifyErrorType(itemRecord), `CodeRabbit provider returned an error in JSON array: ${itemRecord.message ?? itemRecord.errorType ?? "unknown"}`);
+                    }
+                    if (isActionableFinding(itemRecord)) {
+                        findings.push(item);
+                    }
+                }
                 if (findings.length === 0 && parsed.length > 0) {
                     const unusableCount = parsed.filter((item) => typeof item === "object" && item !== null && isUnusableFindingRecord(item)).length;
                     if (unusableCount > 0) {
@@ -209,6 +329,9 @@ function parseReport(output, format, parser) {
             const findings = parseFindingsFromPayload(parsed);
             if (findings.length === 0) {
                 const parsedRecord = parsed;
+                if (isTerminalCompleteNoFindings(parsedRecord)) {
+                    return { findings: [] };
+                }
                 if (isProgressRecord(parsedRecord)) {
                     throw makeUnusableOutputError("CodeRabbit output was a progress/status/heartbeat record");
                 }
@@ -250,6 +373,7 @@ function parseReport(output, format, parser) {
     let progressLineCount = 0;
     let unusableLineCount = 0;
     let parsedLineCount = 0;
+    let sawExplicitSkip = false;
     for (const line of lines) {
         try {
             const parsed = JSON.parse(line);
@@ -258,6 +382,12 @@ function parseReport(output, format, parser) {
                 continue;
             }
             const record = parsed;
+            if (isTerminalCompleteNoFindings(record)) {
+                sawExplicitSkip = true;
+            }
+            if (isErrorRecord(record)) {
+                throw makeQcFailureError(classifyErrorType(record), `CodeRabbit provider returned an error in JSONL: ${record.message ?? record.errorType ?? "unknown"}`);
+            }
             if (isProgressRecord(record)) {
                 progressLineCount++;
                 continue;
@@ -269,13 +399,19 @@ function parseReport(output, format, parser) {
                 unusableLineCount++;
             }
         }
-        catch {
+        catch (err) {
+            if (typeof err === "object" && err !== null && "qcFailureReason" in err) {
+                throw err;
+            }
             // Ignore unparseable lines.
         }
     }
     if (lineFindings.length > 0) {
         return { findings: lineFindings };
     }
+    if (sawExplicitSkip) {
+        return { findings: [] };
+    }
     if (progressLineCount > 0 || unusableLineCount > 0) {
         throw makeUnusableOutputError(`CodeRabbit output contained only progress/status/heartbeat and bookkeeping records (${progressLineCount + unusableLineCount} lines)`);
     }
@@ -288,9 +424,9 @@ function normalizeFinding(raw, index) {
     const severityLabel = pickString(raw.severity, raw.level) ?? "info";
     const severity = (0, severity_js_1.normalizeSeverity)(severityLabel);
     const title = pickString(raw.title, raw.summary, raw.rule, raw.type, raw.category) ?? `Finding #${index + 1}`;
-    const message = pickString(raw.message, raw.description, raw.body);
-    const filePath = pickString(raw.file, raw.filePath, raw.path);
-    const suggestedAction = pickString(raw.suggestion, raw.suggestedAction, raw.fix);
+    const message = pickString(raw.message, raw.description, raw.body, raw.codegenInstructions);
+    const filePath = pickString(raw.file, raw.filePath, raw.path, raw.fileName);
+    const suggestedAction = pickString(raw.suggestion, raw.suggestedAction, raw.fix, ...(Array.isArray(raw.suggestions) ? raw.suggestions : []));
     const providerFindingId = pickString(raw.providerFindingId, raw.id, raw.findingId);
     const confidence = coerceNumber(raw.confidence);
     const attribution = {
@@ -298,7 +434,10 @@ function normalizeFinding(raw, index) {
         reason: "provider-uncertain",
         filePath,
     };
-    const fixAvailable = raw.fixAvailable === true || raw.autofixEligible === true || Boolean(raw.fix);
+    const fixAvailable = raw.fixAvailable === true ||
+        raw.autofixEligible === true ||
+        Boolean(raw.fix) ||
+        Boolean(raw.codegenInstructions);
     return {
         findingId: `coderabbit-${index + 1}-${Date.now()}`,
         ...(providerFindingId ? { providerFindingId } : {}),

package/dist/qc/repair-loop.js

@@ -19,10 +19,18 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_REPAIR_DISPATCH_TIMEOUT_MS = exports.DEFAULT_MAX_REPAIR_ROUNDS = void 0;
 exports.partitionRepairPackets = partitionRepairPackets;
 exports.initRepairLoopState = initRepairLoopState;
+exports.getQcResolutionArtifactPath = getQcResolutionArtifactPath;
+exports.resolveQcResolutionFindings = resolveQcResolutionFindings;
+exports.getResolverIdentity = getResolverIdentity;
+exports.isValidQcResolutionArtifact = isValidQcResolutionArtifact;
+exports.readQcResolutionArtifact = readQcResolutionArtifact;
+exports.writeQcResolutionArtifact = writeQcResolutionArtifact;
 exports.runQcRepairLoop = runQcRepairLoop;
 const node_fs_1 = require("node:fs");
+const node_child_process_1 = require("node:child_process");
 const node_path_1 = require("node:path");
 const repair_packets_js_1 = require("./repair-packets.js");
+const types_js_1 = require("./types.js");
 const orchestration_js_1 = require("./orchestration.js");
 const store_js_1 = require("../cluster-state/store.js");
 // ── Constants ─────────────────────────────────────────────────────────────────
@@ -189,6 +197,127 @@ function initRepairLoopState(opts) {
         updated_at: now,
     };
 }
+// ── Operator resolution artifact helpers ──────────────────────────────────────
+/** Path for the operator-written resolution artifact for a repair round. */
+function getQcResolutionArtifactPath(clusterId, round, repoRoot) {
+    return (0, node_path_1.join)((0, repair_packets_js_1.getRepairRoundDir)(clusterId, round, repoRoot), "resolution.json");
+}
+/** Resolve the finding IDs covered by a resolution artifact. */
+function resolveQcResolutionFindings(manifest, explicitFindings) {
+    const manifestFindings = [
+        ...new Set(manifest.packets.flatMap((p) => p.findingIds)),
+    ].sort();
+    if (!explicitFindings || explicitFindings.length === 0) {
+        return manifestFindings;
+    }
+    const allowed = new Set(manifestFindings);
+    const unknown = explicitFindings.filter((id) => !allowed.has(id));
+    if (unknown.length > 0) {
+        throw new Error(`Unknown finding IDs: ${unknown.join(", ")}. Expected one of: ${manifestFindings.join(", ") || "none"}`);
+    }
+    return [...new Set(explicitFindings)].sort();
+}
+/** Determine the resolver identity from git config or the default operator. */
+function getResolverIdentity(repoRoot) {
+    try {
+        const name = (0, node_child_process_1.execFileSync)("git", ["config", "user.name"], {
+            cwd: repoRoot || process.cwd(),
+            encoding: "utf-8",
+        }).trim();
+        return name || "lsctech";
+    }
+    catch {
+        return "lsctech";
+    }
+}
+const QC_RESOLUTION_OUTCOME_SET = new Set(types_js_1.QC_RESOLUTION_OUTCOMES);
+/** Validate a resolution artifact object. */
+function isValidQcResolutionArtifact(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const v = value;
+    if (typeof v.schemaVersion !== "string")
+        return false;
+    if (typeof v.clusterId !== "string")
+        return false;
+    if (typeof v.round !== "number")
+        return false;
+    if (typeof v.resolvedAt !== "string")
+        return false;
+    if (typeof v.resolver !== "string" || v.resolver === "")
+        return false;
+    if (typeof v.resolvedOutcome !== "string" ||
+        !QC_RESOLUTION_OUTCOME_SET.has(v.resolvedOutcome)) {
+        return false;
+    }
+    if (typeof v.reason !== "string" || v.reason.trim() === "")
+        return false;
+    if (!Array.isArray(v.findings) ||
+        v.findings.length === 0 ||
+        !v.findings.every((f) => typeof f === "string")) {
+        return false;
+    }
+    return true;
+}
+/** Read and validate a resolution artifact, if it exists. */
+function readQcResolutionArtifact(clusterId, round, repoRoot) {
+    const artifactPath = getQcResolutionArtifactPath(clusterId, round, repoRoot);
+    try {
+        const data = (0, node_fs_1.readFileSync)(artifactPath, "utf-8");
+        const parsed = JSON.parse(data);
+        if (isValidQcResolutionArtifact(parsed)) {
+            // Verify identity matches expected clusterId and round
+            if (parsed.clusterId !== clusterId || parsed.round !== round) {
+                return null;
+            }
+            return parsed;
+        }
+        return null;
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return null;
+        }
+        if (error instanceof SyntaxError) {
+            return null;
+        }
+        throw error;
+    }
+}
+/** Write a resolution artifact atomically and return its absolute path. */
+function writeQcResolutionArtifact(options) {
+    const { clusterId, round, resolver, resolvedOutcome, reason, findings, repoRoot, } = options;
+    const artifactPath = getQcResolutionArtifactPath(clusterId, round, repoRoot);
+    const dir = (0, node_path_1.dirname)(artifactPath);
+    (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    const artifact = {
+        schemaVersion: "1.0",
+        clusterId,
+        round,
+        resolvedAt: new Date().toISOString(),
+        resolver,
+        resolvedOutcome,
+        reason,
+        findings,
+    };
+    const tempPath = `${artifactPath}.tmp.${process.pid}.${Date.now()}.${Math.random()
+        .toString(36)
+        .slice(2, 8)}`;
+    try {
+        (0, node_fs_1.writeFileSync)(tempPath, JSON.stringify(artifact, null, 2), "utf-8");
+        (0, node_fs_1.renameSync)(tempPath, artifactPath);
+    }
+    catch (error) {
+        try {
+            (0, node_fs_1.unlinkSync)(tempPath);
+        }
+        catch {
+            // Ignore cleanup failure.
+        }
+        throw error;
+    }
+    return artifactPath;
+}
 // ── Main repair loop ───────────────────────────────────────────────────────────
 /**
  * Run the bounded QC repair loop.
@@ -293,10 +422,21 @@ async function runQcRepairLoop(options) {
         else {
             const existingManifestPath = loopState.manifest_path ??
                 (0, node_path_1.join)(repoRoot, ".polaris", "clusters", clusterId, "qc", "repair-rounds", String(round), "repair-packets.json");
+            // Synchronize manifest packet statuses with the persisted loop state.
+            const completedSet = new Set(loopState.completed_packet_ids);
+            for (const packet of manifest.packets) {
+                if (completedSet.has(packet.packetId)) {
+                    packet.status = "completed";
+                }
+            }
+            (0, repair_packets_js_1.writeRepairPacketManifest)(manifest, repoRoot);
             loopState = {
                 ...loopState,
                 current_round: round,
                 manifest_path: existingManifestPath,
+                pending_packet_ids: manifest.packets
+                    .filter((p) => p.status === "pending" && !completedSet.has(p.packetId))
+                    .map((p) => p.packetId),
                 updated_at: new Date().toISOString(),
             };
             onStateUpdate?.(loopState);
@@ -367,10 +507,16 @@ async function runQcRepairLoop(options) {
             const result = await dispatchRepairWorkerWithTimeout(dispatchRepairWorker, pkt, round, manifest, repairDispatchTimeoutMs, telemetryFile, runId, clusterId);
             allWorkerResults.push(result);
         }
-        // Record completed packet IDs.
+        // Record completed packet IDs and update manifest statuses.
         const completedIds = allWorkerResults
             .filter((r) => r.status !== "skipped")
             .map((r) => r.packetId);
+        for (const packet of manifest.packets) {
+            if (completedIds.includes(packet.packetId)) {
+                packet.status = "completed";
+            }
+        }
+        (0, repair_packets_js_1.writeRepairPacketManifest)(manifest, repoRoot);
         loopState = {
             ...loopState,
             completed_packet_ids: [...loopState.completed_packet_ids, ...completedIds],

package/dist/qc/repair-packets.js

@@ -78,6 +78,16 @@ function subsystemFromFilePath(filePath) {
     const lastSlash = filePath.lastIndexOf("/");
     return lastSlash === -1 ? "root" : filePath.slice(0, lastSlash);
 }
+function deriveSourceQcRunId(finding, fallbackRunId) {
+    // Some findingId formats encode the source QC run as `<provider>-<index>-<runId>`
+    // (e.g. coderabbit-1-1783818427443). Prefer that provenance over the result
+    // run ID so packet sourceQcRunIds match the runs that emitted the findings.
+    const match = finding.findingId.match(/^(.+?)-(\d+)-(\d+)$/);
+    if (match) {
+        return `${match[1]}-${match[3]}`;
+    }
+    return fallbackRunId;
+}
 function enrichFinding(finding, config, sourceQcRunId) {
     return {
         ...finding,
@@ -85,7 +95,7 @@ function enrichFinding(finding, config, sourceQcRunId) {
         risk: riskLevel(finding),
         confidenceBand: confidenceBand(finding),
         subsystem: subsystemFromFilePath(finding.filePath),
-        sourceQcRunId,
+        sourceQcRunId: deriveSourceQcRunId(finding, sourceQcRunId),
     };
 }
 /**
@@ -213,6 +223,8 @@ function buildPacket(group, index, clusterId, round, allRunIds, validationComman
     const packetId = `pkt-${clusterId}-r${round}-${String(index).padStart(3, "0")}`;
     const findingIds = group.map((f) => f.findingId).sort();
     const sourceRunIds = [...new Set(group.map((f) => f.sourceQcRunId))].sort();
+    // Preserve the artifact run ID while also capturing the finding-level source run.
+    const combinedSourceRunIds = [...new Set([...allRunIds, ...sourceRunIds])].sort();
     const severityFloor = group.reduce((acc, f) => (0, severity_js_1.maxSeverity)(acc, f.severity), "info");
     const categories = [...new Set(group.map((f) => f.category).filter(Boolean))].sort();
     const filePaths = group.map((f) => f.filePath).filter((f) => Boolean(f));
@@ -230,7 +242,7 @@ function buildPacket(group, index, clusterId, round, allRunIds, validationComman
         packetId,
         round,
         clusterId,
-        sourceQcRunIds: sourceRunIds.length > 0 ? sourceRunIds : allRunIds,
+        sourceQcRunIds: combinedSourceRunIds,
         findingIds,
         severityFloor,
         rootCauseHint,
@@ -346,12 +358,13 @@ function compileRepairPackets(input) {
         packets.push(buildPacket(group, packets.length, clusterId, round, allRunIds, validationCommands, compiledAt));
     }
     const finalPackets = assignParallelGroups(packets);
+    const manifestSourceRunIds = [...new Set(finalPackets.flatMap((p) => p.sourceQcRunIds))].sort();
     const manifest = {
         schemaVersion: "1.0",
         clusterId,
         round,
         compiledAt,
-        sourceQcRunIds: allRunIds,
+        sourceQcRunIds: manifestSourceRunIds.length > 0 ? manifestSourceRunIds : allRunIds,
         packets: finalPackets,
     };
     const manifestPath = getRepairPacketManifestPath(clusterId, round, repoRoot);

package/dist/qc/routing.js

@@ -12,6 +12,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.decideRepairRouting = decideRepairRouting;
 const security_category_js_1 = require("./security-category.js");
 const severity_js_1 = require("./severity.js");
+function isStateRepairCategory(category) {
+    return category === "state-repair";
+}
 function getBlockThreshold(config, context) {
     const route = context.routeName ? config.routes?.[context.routeName] : undefined;
     return route?.blockThreshold ?? config.severityThresholds?.block ?? "high";
@@ -34,6 +37,9 @@ function decideRepairRouting(finding, config, autofixEligible, context = {}) {
     if ((0, security_category_js_1.isSecurityCategory)(finding.category)) {
         return "operator-review";
     }
+    if (isStateRepairCategory(finding.category)) {
+        return "operator-review";
+    }
     const attribution = finding.attribution;
     const clearAttribution = attribution.confidence === "high" || attribution.confidence === "medium";
     if (autofixEligible && clearAttribution && attribution.childId) {

package/dist/qc/types.js

@@ -7,3 +7,6 @@
  * shapes so that Polaris can support multiple QC backends without vendor lock-in.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.QC_RESOLUTION_OUTCOMES = void 0;
+/** Allowed outcomes for an operator resolution artifact. */
+exports.QC_RESOLUTION_OUTCOMES = ["pass", "no-repairable"];