@lsctech/polaris 0.5.0 → 0.5.2

package/dist/loop/parent.js

@@ -36,6 +36,7 @@ const body_parser_js_1 = require("./body-parser.js");
 const node_child_process_1 = require("node:child_process");
 const artifact_policy_js_1 = require("../finalize/artifact-policy.js");
 const dispatch_boundary_js_1 = require("./dispatch-boundary.js");
+const triggers_js_1 = require("../qc/triggers.js");
 const run_bootstrap_js_1 = require("./run-bootstrap.js");
 const ledger_js_1 = require("./ledger.js");
 const dispatch_js_1 = require("./dispatch.js");
@@ -1079,9 +1080,56 @@ async function runParentLoop(options) {
         const statePreDispatch = state;
         let stateBeforeDispatch = state;
         const packet = buildPacket(state, nextChild, stateFile, telemetryFile, repoRoot, resultFile, maxConcurrentWorkers);
+        // ── Child-level QC selection ─────────────────────────────────────────────
+        // Only opt-in conditions may select child-level QC. The dispatch boundary
+        // below enforces that any child-level marker on the packet is valid.
+        let packetWithQc = packet;
+        let stateWithQcMeta = state;
+        const childQcTrigger = (0, triggers_js_1.selectChildQcTrigger)(config.qc, nextChild, packet.instructions.allowed_scope, state.open_children_meta?.[nextChild]?.labels);
+        if (childQcTrigger) {
+            packetWithQc = { ...packet, qc_trigger: childQcTrigger };
+            stateWithQcMeta = {
+                ...state,
+                open_children_meta: {
+                    ...state.open_children_meta,
+                    [nextChild]: {
+                        ...(state.open_children_meta?.[nextChild] ?? {}),
+                        qc_trigger: childQcTrigger,
+                    },
+                },
+            };
+            if (!dryRun) {
+                appendTelemetry(telemetryFile, {
+                    event: "qc-child-trigger-selected",
+                    run_id: state.run_id,
+                    child_id: nextChild,
+                    qc_trigger: childQcTrigger,
+                    timestamp: new Date().toISOString(),
+                });
+            }
+        }
         if (!dryRun) {
             try {
-                writePacketArtifact(packetPath, packet);
+                (0, dispatch_boundary_js_1.assertChildQcSelectionAllowed)(stateWithQcMeta, nextChild, config.qc, packet.instructions.allowed_scope, state.open_children_meta?.[nextChild]?.labels, telemetryFile);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                appendTelemetry(telemetryFile, {
+                    event: "qc-child-selection-rejected",
+                    run_id: state.run_id,
+                    child_id: nextChild,
+                    error: msg,
+                    timestamp: new Date().toISOString(),
+                });
+                return {
+                    haltReason: 'worker-error',
+                    childrenDispatched,
+                    haltingChild: nextChild,
+                    message: msg,
+                };
+            }
+            try {
+                writePacketArtifact(packetPath, packetWithQc);
             }
             catch (err) {
                 const msg = err instanceof Error ? err.message : String(err);
@@ -1114,7 +1162,7 @@ async function runParentLoop(options) {
                 dispatchedAt,
             });
             const stateWithDispatch = {
-                ...withWorkerPoolState(withChildDispatchMetadata(state, nextChild, resultFile, dispatchRecord), maxConcurrentWorkers, nextSlotClaims),
+                ...withWorkerPoolState(withChildDispatchMetadata(stateWithQcMeta, nextChild, resultFile, dispatchRecord), maxConcurrentWorkers, nextSlotClaims),
                 active_child: nextChild,
                 step_cursor: "dispatch",
                 dispatch_boundary: (0, dispatch_boundary_js_1.advanceDispatchEpoch)(state.dispatch_boundary, nextChild),

package/dist/qc/artifacts.js

@@ -0,0 +1,117 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getQcArtifactDir = getQcArtifactDir;
+exports.writeQcArtifact = writeQcArtifact;
+exports.readQcArtifact = readQcArtifact;
+exports.listQcArtifactIds = listQcArtifactIds;
+const node_fs_1 = require("node:fs");
+const path = __importStar(require("node:path"));
+const schemas_js_1 = require("./schemas.js");
+/**
+ * Returns the cluster-scoped QC evidence directory.
+ * Artifacts live under `.polaris/clusters/<cluster-id>/qc/` so that finalize's
+ * artifact policy can promote them as durable evidence.
+ */
+function getQcArtifactDir(clusterId, repoRoot) {
+    return path.join(repoRoot || process.cwd(), ".polaris", "clusters", clusterId, "qc");
+}
+function getArtifactPath(clusterId, qcRunId, repoRoot) {
+    return path.join(getQcArtifactDir(clusterId, repoRoot), `${qcRunId}.json`);
+}
+/**
+ * Write a normalized QC result under the active cluster's evidence surface.
+ * The file is written atomically via a temp file + rename.
+ * Returns the absolute artifact path.
+ */
+function writeQcArtifact(clusterId, result, repoRoot) {
+    const artifactDir = getQcArtifactDir(clusterId, repoRoot);
+    (0, node_fs_1.mkdirSync)(artifactDir, { recursive: true });
+    const artifactPath = getArtifactPath(clusterId, result.qcRunId, repoRoot);
+    const tempPath = `${artifactPath}.tmp.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}`;
+    try {
+        (0, node_fs_1.writeFileSync)(tempPath, JSON.stringify(result, 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;
+}
+/**
+ * Read a QC artifact by its run id.
+ * Returns null if the file does not exist or fails validation.
+ */
+function readQcArtifact(clusterId, qcRunId, repoRoot) {
+    const artifactPath = getArtifactPath(clusterId, qcRunId, repoRoot);
+    try {
+        const data = (0, node_fs_1.readFileSync)(artifactPath, "utf-8");
+        const parsed = JSON.parse(data);
+        const validation = (0, schemas_js_1.validateQcResult)(parsed);
+        if (!validation.success) {
+            return null;
+        }
+        return validation.result;
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}
+/**
+ * List persisted QC run ids for a cluster.
+ */
+function listQcArtifactIds(clusterId, repoRoot) {
+    const artifactDir = getQcArtifactDir(clusterId, repoRoot);
+    try {
+        return (0, node_fs_1.readdirSync)(artifactDir, "utf-8")
+            .filter((name) => name.endsWith(".json"))
+            .map((name) => name.slice(0, -5));
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return [];
+        }
+        throw error;
+    }
+}

package/dist/qc/attribution.js

@@ -0,0 +1,266 @@
+"use strict";
+/**
+ * QC attribution resolver.
+ *
+ * Correlates normalized QC findings to the child/worker most likely responsible
+ * for the changed code. It uses durable evidence only: result packet pointers,
+ * child commits, dispatch records, optional PR review metadata, and (as a
+ * fallback) git history.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveAttribution = resolveAttribution;
+exports.buildChangedFileOwnership = buildChangedFileOwnership;
+exports.resolveAttributionWithOwnership = resolveAttributionWithOwnership;
+const path = __importStar(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+function normalizeFilePath(filePath, repoRoot) {
+    if (!filePath)
+        return null;
+    const absolute = path.isAbsolute(filePath) ? filePath : path.join(repoRoot ?? process.cwd(), filePath);
+    return path.relative(repoRoot ?? process.cwd(), absolute).replace(/\\/g, "/");
+}
+function collectResultChangedFiles(result) {
+    if (result.changed_files && result.changed_files.length > 0) {
+        return result.changed_files;
+    }
+    const fromData = result.result_data?.changed_files;
+    if (Array.isArray(fromData) && fromData.every((f) => typeof f === "string")) {
+        return fromData;
+    }
+    return [];
+}
+function collectChangedFilesByChild(context) {
+    if (context.changedFilesByChild) {
+        return context.changedFilesByChild;
+    }
+    const ownership = {};
+    if (context.completedResults) {
+        for (const [childId, result] of Object.entries(context.completedResults)) {
+            const files = collectResultChangedFiles(result);
+            if (files.length > 0) {
+                ownership[childId] = files.map((f) => normalizeFilePath(f, context.repoRoot)).filter((f) => f !== null);
+            }
+        }
+    }
+    if (Object.keys(ownership).length > 0) {
+        return ownership;
+    }
+    if (context.clusterState?.commits) {
+        const base = context.baseBranch ?? "main";
+        for (const [childId, commitSha] of Object.entries(context.clusterState.commits)) {
+            const files = diffFilesForCommit(context.repoRoot, base, commitSha);
+            if (files.length > 0) {
+                ownership[childId] = files.map((f) => normalizeFilePath(f, context.repoRoot)).filter((f) => f !== null);
+            }
+        }
+    }
+    return ownership;
+}
+function diffFilesForCommit(repoRoot, baseBranch, commitSha) {
+    if (!repoRoot)
+        return [];
+    try {
+        const output = (0, node_child_process_1.execFileSync)("git", ["diff", "--name-only", `${baseBranch}..${commitSha}`], { cwd: repoRoot, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
+        return output
+            .trim()
+            .split("\n")
+            .filter((line) => line.length > 0);
+    }
+    catch {
+        return [];
+    }
+}
+function ownersForFile(filePath, ownership) {
+    const owners = [];
+    for (const [childId, files] of Object.entries(ownership)) {
+        if (files.includes(filePath)) {
+            owners.push(childId);
+        }
+    }
+    return owners;
+}
+function resolveCommitSha(finding) {
+    return finding.commitSha ?? finding.attribution?.commitSha;
+}
+function isKnownChildCommit(commitSha, context) {
+    if (!commitSha)
+        return false;
+    const commits = Object.values(context.clusterState?.commits ?? {});
+    if (commits.includes(commitSha))
+        return true;
+    if (context.completedResults) {
+        return Object.values(context.completedResults).some((r) => r.commit === commitSha);
+    }
+    return false;
+}
+function isPreExistingFile(filePath, context) {
+    if (!context.repoRoot)
+        return false;
+    try {
+        (0, node_child_process_1.execFileSync)("git", ["cat-file", "-e", `HEAD:${filePath}`], {
+            cwd: context.repoRoot,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve the most likely attribution for a finding.
+ *
+ * The resolver never fabricates confidence. When evidence is weak it falls
+ * back to explicitly named reason codes so downstream routing can treat the
+ * finding conservatively.
+ */
+function resolveAttribution(finding, context) {
+    const threshold = context.providerConfidenceThreshold ?? 0.5;
+    const filePath = normalizeFilePath(finding.filePath, context.repoRoot);
+    const ownership = filePath ? collectChangedFilesByChild(context) : {};
+    const owners = filePath ? ownersForFile(filePath, ownership) : [];
+    const commitSha = resolveCommitSha(finding);
+    if (finding.confidence !== undefined && finding.confidence < threshold) {
+        const childId = owners.length === 1 ? owners[0] : undefined;
+        return {
+            confidence: "low",
+            reason: "provider-uncertain",
+            ...(childId ? { childId } : {}),
+            filePath: filePath ?? undefined,
+            commitSha,
+        };
+    }
+    if (!filePath) {
+        return {
+            confidence: "unattributed",
+            reason: "provider-uncertain",
+            commitSha,
+        };
+    }
+    const commitKnown = isKnownChildCommit(commitSha, context);
+    const commitMatchesOwner = commitSha && owners.some((childId) => {
+        const childCommit = context.clusterState?.commits?.[childId] ?? context.completedResults?.[childId]?.commit;
+        return childCommit === commitSha;
+    });
+    if (owners.length === 1) {
+        const childId = owners[0];
+        if (commitSha && !commitMatchesOwner) {
+            return {
+                confidence: "low",
+                reason: "provider-uncertain",
+                childId,
+                filePath,
+                commitSha,
+            };
+        }
+        if (commitMatchesOwner) {
+            return {
+                confidence: "high",
+                reason: "commit-line-match",
+                childId,
+                filePath,
+                commitSha,
+            };
+        }
+        return {
+            confidence: "high",
+            reason: "changed-file-owner",
+            childId,
+            filePath,
+            commitSha,
+        };
+    }
+    if (owners.length > 1) {
+        return {
+            confidence: "low",
+            reason: "shared-file",
+            childId: owners[0],
+            filePath,
+            commitSha,
+        };
+    }
+    // File is not owned by any child. Use PR review metadata as a weak signal.
+    const reviewerFiles = Object.values(context.prReviewMetadata?.changedFilesByReviewer ?? {}).flat();
+    if (reviewerFiles.includes(filePath)) {
+        return {
+            confidence: "low",
+            reason: "child-scope-match",
+            filePath,
+            commitSha,
+        };
+    }
+    if (commitSha) {
+        if (commitKnown) {
+            return {
+                confidence: "medium",
+                reason: "commit-line-match",
+                filePath,
+                commitSha,
+            };
+        }
+        return {
+            confidence: "low",
+            reason: "provider-uncertain",
+            filePath,
+            commitSha,
+        };
+    }
+    if (isPreExistingFile(filePath, context)) {
+        return {
+            confidence: "low",
+            reason: "pre-existing",
+            filePath,
+        };
+    }
+    return {
+        confidence: "unattributed",
+        reason: "unattributed",
+        filePath,
+    };
+}
+/**
+ * Expose the ownership map built by the resolver. Useful for tests and for
+ * callers that want to cache the map across many findings.
+ */
+function buildChangedFileOwnership(context) {
+    return collectChangedFilesByChild(context);
+}
+/**
+ * Re-resolve attribution using a pre-built ownership map.
+ */
+function resolveAttributionWithOwnership(finding, context, ownership) {
+    return resolveAttribution(finding, { ...context, changedFilesByChild: ownership });
+}

package/dist/qc/autofix.js

@@ -0,0 +1,77 @@
+"use strict";
+/**
+ * QC auto-fix gating.
+ *
+ * Determines whether a normalized finding is allowed to attempt an unattended
+ * auto-fix. Gating is intentionally conservative: auto-fix is allowed only for
+ * explicitly eligible providers, low/medium severities, non-security categories,
+ * clean branches, and fix modes that are known to be safe.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QC_SAFE_FIX_MODES = void 0;
+exports.isAutofixEligible = isAutofixEligible;
+const security_category_js_1 = require("./security-category.js");
+const severity_js_1 = require("./severity.js");
+/** Fix modes considered safe for unattended application. */
+exports.QC_SAFE_FIX_MODES = [
+    "refactor",
+    "style",
+    "format",
+    "typo",
+    "lint-fix",
+    "apply-suggestion",
+    "safe",
+];
+function providerConfig(config, provider) {
+    if (!provider)
+        return undefined;
+    return config.providers?.[provider];
+}
+function isSafeFixMode(suggestedAction) {
+    if (!suggestedAction?.trim())
+        return false;
+    const normalized = suggestedAction.trim().toLowerCase();
+    if (exports.QC_SAFE_FIX_MODES.includes(normalized))
+        return true;
+    // A provider may describe a safe fix with a sentence that starts with a safe mode keyword.
+    return exports.QC_SAFE_FIX_MODES.some((mode) => normalized.startsWith(mode));
+}
+/**
+ * Check whether a finding may attempt an unattended auto-fix.
+ *
+ * Returns an object so callers can log why a fix was blocked.
+ */
+function isAutofixEligible(finding, config, context = {}) {
+    const globalPolicy = config.autoFix ?? "disabled";
+    if (globalPolicy === "disabled") {
+        return { eligible: false, reason: "auto-fix disabled globally" };
+    }
+    const routePolicy = context.routeName ? config.routes?.[context.routeName]?.autoFix : undefined;
+    if (routePolicy === "disabled") {
+        return { eligible: false, reason: "auto-fix disabled for route" };
+    }
+    const pCfg = providerConfig(config, context.provider);
+    if (!pCfg?.autoFixEligible) {
+        return { eligible: false, reason: "provider not auto-fix eligible" };
+    }
+    const maxAutofixSeverity = "medium";
+    if ((0, severity_js_1.compareSeverity)(finding.severity, maxAutofixSeverity) > 0) {
+        return { eligible: false, reason: `severity ${finding.severity} exceeds auto-fix threshold` };
+    }
+    if ((0, security_category_js_1.isSecurityCategory)(finding.category)) {
+        return { eligible: false, reason: "security-sensitive finding" };
+    }
+    if (context.branchDirty) {
+        return { eligible: false, reason: "branch has uncommitted changes" };
+    }
+    if (!finding.fixAvailable) {
+        return { eligible: false, reason: "no fix available" };
+    }
+    if (!isSafeFixMode(finding.suggestedAction)) {
+        return { eligible: false, reason: `fix mode "${finding.suggestedAction}" is not in safe list` };
+    }
+    if (globalPolicy === "dry-run") {
+        return { eligible: true, reason: "dry-run mode: fix may be generated but not applied" };
+    }
+    return { eligible: true, reason: "auto-fix eligible" };
+}

package/dist/qc/index.js

@@ -0,0 +1,30 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types.js"), exports);
+__exportStar(require("./provider.js"), exports);
+__exportStar(require("./providers/index.js"), exports);
+__exportStar(require("./severity.js"), exports);
+__exportStar(require("./schemas.js"), exports);
+__exportStar(require("./artifacts.js"), exports);
+__exportStar(require("./triggers.js"), exports);
+__exportStar(require("./policy.js"), exports);
+__exportStar(require("./runner.js"), exports);
+__exportStar(require("./orchestration.js"), exports);
+__exportStar(require("./registry.js"), exports);
+__exportStar(require("./attribution.js"), exports);
+__exportStar(require("./autofix.js"), exports);
+__exportStar(require("./routing.js"), exports);