@lsctech/polaris 0.5.0 → 0.5.3

package/dist/qc/schemas.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.qcResultSchema = exports.qcPolicyDecisionSchema = exports.qcFindingSchema = exports.qcAttributionSchema = exports.qcCodeRangeSchema = exports.qcAttributionReasonSchema = exports.qcAttributionConfidenceSchema = exports.qcRoutingDecisionSchema = exports.qcFindingStatusSchema = exports.qcSeveritySchema = void 0;
+exports.validateQcResult = validateQcResult;
+exports.validateQcFinding = validateQcFinding;
+const zod_1 = require("zod");
+exports.qcSeveritySchema = zod_1.z.enum(["critical", "high", "medium", "low", "info"]);
+exports.qcFindingStatusSchema = zod_1.z.enum([
+    "open",
+    "autofixed",
+    "repaired",
+    "waived",
+    "follow-up",
+]);
+exports.qcRoutingDecisionSchema = zod_1.z.enum([
+    "original-worker",
+    "repair-worker",
+    "follow-up",
+    "operator-review",
+]);
+exports.qcAttributionConfidenceSchema = zod_1.z.enum([
+    "high",
+    "medium",
+    "low",
+    "unattributed",
+]);
+exports.qcAttributionReasonSchema = zod_1.z.enum([
+    "commit-line-match",
+    "changed-file-owner",
+    "child-scope-match",
+    "shared-file",
+    "pre-existing",
+    "provider-uncertain",
+    "unattributed",
+]);
+exports.qcCodeRangeSchema = zod_1.z.object({
+    startLine: zod_1.z.number().int().positive(),
+    startColumn: zod_1.z.number().int().positive().optional(),
+    endLine: zod_1.z.number().int().positive().optional(),
+    endColumn: zod_1.z.number().int().positive().optional(),
+});
+exports.qcAttributionSchema = zod_1.z.object({
+    confidence: exports.qcAttributionConfidenceSchema,
+    reason: exports.qcAttributionReasonSchema,
+    childId: zod_1.z.string().optional(),
+    filePath: zod_1.z.string().optional(),
+    commitSha: zod_1.z.string().optional(),
+});
+exports.qcFindingSchema = zod_1.z.object({
+    findingId: zod_1.z.string(),
+    providerFindingId: zod_1.z.string().optional(),
+    severity: exports.qcSeveritySchema,
+    category: zod_1.z.string().optional(),
+    title: zod_1.z.string(),
+    message: zod_1.z.string().optional(),
+    filePath: zod_1.z.string().optional(),
+    commitSha: zod_1.z.string().optional(),
+    range: exports.qcCodeRangeSchema.optional(),
+    confidence: zod_1.z.number().min(0).max(1).optional(),
+    suggestedAction: zod_1.z.string().optional(),
+    fixAvailable: zod_1.z.boolean(),
+    autofixEligible: zod_1.z.boolean(),
+    attribution: exports.qcAttributionSchema,
+    routingDecision: exports.qcRoutingDecisionSchema.optional(),
+    status: exports.qcFindingStatusSchema,
+});
+exports.qcPolicyDecisionSchema = zod_1.z.object({
+    blocksDelivery: zod_1.z.boolean(),
+    requiresOperatorReview: zod_1.z.boolean(),
+    routedToRepair: zod_1.z.boolean(),
+    summary: zod_1.z.string(),
+});
+exports.qcResultSchema = zod_1.z.object({
+    schemaVersion: zod_1.z.string(),
+    qcRunId: zod_1.z.string(),
+    runId: zod_1.z.string(),
+    clusterId: zod_1.z.string(),
+    trigger: zod_1.z.enum(["pr", "completed-cluster", "child"]),
+    provider: zod_1.z.string(),
+    providerMode: zod_1.z.enum(["local", "pr", "metrics-import"]),
+    prUrl: zod_1.z.string().optional(),
+    startedAt: zod_1.z.string().datetime(),
+    completedAt: zod_1.z.string().datetime(),
+    status: zod_1.z.enum(["passed", "findings", "blocked", "failed", "skipped"]),
+    findings: zod_1.z.array(exports.qcFindingSchema),
+    rawArtifactPaths: zod_1.z.array(zod_1.z.string()),
+    parserVersion: zod_1.z.string(),
+    policyDecision: exports.qcPolicyDecisionSchema,
+});
+/**
+ * Validate an unknown value as a normalized QC result.
+ * Returns a typed result on success or a Zod-safe parsed error on failure.
+ */
+function validateQcResult(value) {
+    const parsed = exports.qcResultSchema.safeParse(value);
+    if (parsed.success) {
+        return { success: true, result: parsed.data };
+    }
+    return { success: false, errors: parsed.error.issues.map((issue) => issue.message) };
+}
+/**
+ * Validate an unknown value as a normalized QC finding.
+ */
+function validateQcFinding(value) {
+    const parsed = exports.qcFindingSchema.safeParse(value);
+    if (parsed.success) {
+        return { success: true, finding: parsed.data };
+    }
+    return { success: false, errors: parsed.error.issues.map((issue) => issue.message) };
+}

package/dist/qc/security-category.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SECURITY_CATEGORY_PATTERN = void 0;
+exports.isSecurityCategory = isSecurityCategory;
+/** Shared QC security-category classification. */
+exports.SECURITY_CATEGORY_PATTERN = /security|secret|vulnerability|vuln|auth|crypto|injection|xss|csrf|sql/i;
+function isSecurityCategory(category) {
+    if (!category)
+        return false;
+    return exports.SECURITY_CATEGORY_PATTERN.test(category);
+}

package/dist/qc/severity.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SEVERITY_ORDER = exports.DEFAULT_SEVERITY_MAPPING = void 0;
+exports.normalizeSeverity = normalizeSeverity;
+exports.compareSeverity = compareSeverity;
+exports.maxSeverity = maxSeverity;
+/**
+ * Built-in severity label mappings for common QC providers.
+ * Provider-specific configs can override these.
+ */
+exports.DEFAULT_SEVERITY_MAPPING = {
+    // Common explicit labels
+    critical: "critical",
+    severe: "critical",
+    blocker: "critical",
+    high: "high",
+    major: "high",
+    error: "high",
+    medium: "medium",
+    moderate: "medium",
+    warning: "medium",
+    low: "low",
+    minor: "low",
+    info: "info",
+    informational: "info",
+    note: "info",
+    suggestion: "info",
+    // CodeRabbit-style labels
+    "needs-action": "high",
+    "needs-review": "medium",
+    nitpick: "low",
+};
+/**
+ * Normalize a provider severity label into a Polaris severity level.
+ * Unknown or empty labels fall back to "info" so that nothing is silently lost.
+ */
+function normalizeSeverity(label, mapping) {
+    const raw = (label ?? "").toString().trim().toLowerCase();
+    if (!raw) {
+        return "info";
+    }
+    const combined = { ...exports.DEFAULT_SEVERITY_MAPPING, ...mapping };
+    if (Object.hasOwn(combined, raw)) {
+        return combined[raw];
+    }
+    // Substring fallbacks for noisy provider labels
+    if (raw.includes("critical") || raw.includes("severe") || raw.includes("blocker")) {
+        return "critical";
+    }
+    if (raw.includes("high") || raw.includes("major") || raw.includes("error")) {
+        return "high";
+    }
+    if (raw.includes("medium") || raw.includes("moderate") || raw.includes("warning")) {
+        return "medium";
+    }
+    if (raw.includes("low") || raw.includes("minor") || raw.includes("nitpick")) {
+        return "low";
+    }
+    if (raw.includes("info") || raw.includes("note") || raw.includes("suggestion")) {
+        return "info";
+    }
+    return "info";
+}
+/** Ordered severity levels from least to most severe. */
+exports.SEVERITY_ORDER = ["info", "low", "medium", "high", "critical"];
+/**
+ * Compare two severities. Returns negative if a is less severe than b,
+ * positive if more severe, or zero if equal.
+ */
+function compareSeverity(a, b) {
+    return exports.SEVERITY_ORDER.indexOf(a) - exports.SEVERITY_ORDER.indexOf(b);
+}
+/**
+ * Return the more severe of two severity levels.
+ */
+function maxSeverity(a, b) {
+    return compareSeverity(a, b) >= 0 ? a : b;
+}

package/dist/qc/triggers.js

@@ -0,0 +1,92 @@
+"use strict";
+/**
+ * QC trigger selection logic.
+ *
+ * Decides which lifecycle trigger a configured provider participates in, and
+ * whether child-level QC should be selected for a given dispatch.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.effectiveProviderTrigger = effectiveProviderTrigger;
+exports.activeProvidersForTrigger = activeProvidersForTrigger;
+exports.isHighRiskScope = isHighRiskScope;
+exports.isChildQcSelected = isChildQcSelected;
+exports.selectChildQcTrigger = selectChildQcTrigger;
+/** High-risk scope patterns that make a child eligible for child-level QC. */
+const HIGH_RISK_SCOPE_PATTERNS = [
+    /src\/auth/i,
+    /src\/security/i,
+    /src\/payments/i,
+    /src\/crypto/i,
+    /src\/db/i,
+    /src\/database/i,
+    /src\/api/i,
+];
+/**
+ * Derive the effective trigger for a provider.
+ * Falls back to a sensible default derived from the provider mode, then the
+ * cluster-wide default trigger.
+ */
+function effectiveProviderTrigger(provider, defaultTrigger) {
+    if (provider.trigger)
+        return provider.trigger;
+    switch (provider.mode) {
+        case "pr":
+            return "pr";
+        case "local":
+            return "completed-cluster";
+        case "metrics-import":
+            return "completed-cluster";
+        default:
+            return defaultTrigger;
+    }
+}
+/**
+ * Return configured providers that participate in the given trigger.
+ */
+function activeProvidersForTrigger(config, trigger) {
+    if (!config?.enabled)
+        return [];
+    const defaultTrigger = config.defaultTrigger ?? "completed-cluster";
+    return Object.entries(config.providers ?? {}).filter(([, provider]) => {
+        return effectiveProviderTrigger(provider, defaultTrigger) === trigger;
+    });
+}
+/**
+ * Returns true when a scope touches files generally considered high-risk.
+ */
+function isHighRiskScope(scope) {
+    return scope.some((pattern) => HIGH_RISK_SCOPE_PATTERNS.some((re) => re.test(pattern)));
+}
+/**
+ * Decide whether child-level QC should be selected for a child.
+ *
+ * Child-level QC is intentionally opt-in. It is selected only when:
+ *   - QC is enabled and at least one provider is configured for the child trigger.
+ *   - A route policy explicitly enables child-level QC for this route, OR
+ *   - The child is explicitly tagged with "qc-child", OR
+ *   - The child's scope contains high-risk paths (auth, security, payments, etc.).
+ */
+function isChildQcSelected(config, childId, allowedScope, labels, routeName) {
+    if (!config?.enabled)
+        return false;
+    const childProviders = activeProvidersForTrigger(config, "child");
+    if (childProviders.length === 0)
+        return false;
+    const routePolicy = routeName ? config.routes?.[routeName] : undefined;
+    if (routePolicy?.childLevel)
+        return true;
+    if (labels?.includes("qc-child"))
+        return true;
+    if (isHighRiskScope(allowedScope))
+        return true;
+    return false;
+}
+/**
+ * Select the QC trigger for a child dispatch.
+ * Returns "child" when child-level QC is selected, otherwise null.
+ */
+function selectChildQcTrigger(config, childId, allowedScope, labels, routeName) {
+    return isChildQcSelected(config, childId, allowedScope, labels, routeName)
+        ? "child"
+        : null;
+}

package/dist/qc/types.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * Provider-neutral Quality Control types.
+ *
+ * These types mirror the normalized finding schema defined in the QC architecture
+ * spec. They intentionally do not reference tracker-specific or provider-specific
+ * shapes so that Polaris can support multiple QC backends without vendor lock-in.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lsctech/polaris",
-  "version": "0.5.0",
+  "version": "0.5.3",
   "description": "Polaris — standalone taskchain orchestration framework for governed AI agent workflows",
   "bin": {
     "polaris": "dist/cli/index.js",