harnery 0.36.0 → 0.37.0

package/dist/core/diagnostics/advice.js

@@ -0,0 +1,112 @@
+import { DIAGNOSTIC_ADVICE_LIMITS, DIAGNOSTIC_ADVICE_SCHEMA_VERSION, } from "./contract.js";
+const SEVERITY_RANK = {
+    info: 0,
+    warning: 1,
+    critical: 2,
+};
+export function buildDiagnosticAdvice(input) {
+    const sourceAvailable = input.sourceCapability.state === "supported";
+    const active = sourceAvailable
+        ? input.findings.filter((finding) => finding.state === "opened").sort(compareFindings)
+        : [];
+    const pressureFindings = active.filter((finding) => finding.severity === "warning" || finding.severity === "critical");
+    const critical = pressureFindings.filter((finding) => finding.severity === "critical");
+    const warning = pressureFindings.filter((finding) => finding.severity === "warning");
+    const pressure = critical.length
+        ? "critical"
+        : warning.length
+            ? "elevated"
+            : sourceAvailable
+                ? "normal"
+                : "unknown";
+    const fanOutRecommendation = pressure === "critical"
+        ? "avoid-new-fan-out"
+        : pressure === "elevated"
+            ? "use-caution"
+            : pressure === "normal"
+                ? "proceed"
+                : "unknown";
+    const contributing = pressureFindings.slice(0, DIAGNOSTIC_ADVICE_LIMITS.max_contributing_findings);
+    return {
+        schema_version: DIAGNOSTIC_ADVICE_SCHEMA_VERSION,
+        evaluated_at: input.evaluatedAt,
+        pressure,
+        fan_out_recommendation: fanOutRecommendation,
+        observer_only: true,
+        summary: summaryFor(pressure),
+        source_capability: input.sourceCapability,
+        active_finding_count: active.length,
+        contributing_finding_count: pressureFindings.length,
+        omitted_contributing_finding_count: Math.max(0, pressureFindings.length - contributing.length),
+        contributing_findings: contributing.map(adviceFinding),
+        reasons: reasonsFor(critical, warning, input.sourceCapability),
+    };
+}
+function adviceFinding(finding) {
+    return {
+        finding_id: finding.id,
+        finding_kind: finding.finding_kind,
+        severity: finding.severity,
+        summary: finding.summary,
+        scope_kind: finding.scope_kind,
+        scope_id: finding.scope_id,
+        occurrence_count: finding.occurrence_count,
+        owner_kind: finding.attribution?.owner_kind,
+        owner_id: finding.attribution?.owner_id,
+        workload_relationship: finding.workload_context?.relationship,
+    };
+}
+function reasonsFor(critical, warning, capability) {
+    const reasons = [];
+    if (critical.length) {
+        reasons.push({
+            code: "critical_findings_active",
+            summary: `${critical.length} active critical finding${critical.length === 1 ? "" : "s"} ${critical.length === 1 ? "requires" : "require"} attention.`,
+            finding_ids: boundedIds(critical),
+        });
+    }
+    if (warning.length) {
+        reasons.push({
+            code: "warning_findings_active",
+            summary: `${warning.length} active warning finding${warning.length === 1 ? "" : "s"} ${warning.length === 1 ? "indicates" : "indicate"} elevated pressure.`,
+            finding_ids: boundedIds(warning),
+        });
+    }
+    if (capability.state !== "supported") {
+        reasons.push({
+            code: "findings_source_unavailable",
+            summary: `The findings source is ${capability.state}${capability.reason_code ? ` (${capability.reason_code})` : ""}.`,
+            finding_ids: [],
+        });
+    }
+    if (!critical.length && !warning.length && capability.state === "supported") {
+        reasons.push({
+            code: "no_active_pressure_findings",
+            summary: "No active warning or critical findings were observed.",
+            finding_ids: [],
+        });
+    }
+    return reasons.slice(0, DIAGNOSTIC_ADVICE_LIMITS.max_reasons);
+}
+function boundedIds(findings) {
+    return findings
+        .slice(0, DIAGNOSTIC_ADVICE_LIMITS.max_contributing_findings)
+        .map((finding) => finding.id);
+}
+function summaryFor(pressure) {
+    switch (pressure) {
+        case "critical":
+            return "Critical local pressure is active. Avoid starting additional agent work until the findings change.";
+        case "elevated":
+            return "Elevated local pressure is active. Limit new fan-out and inspect the contributing findings.";
+        case "normal":
+            return "No active warning or critical findings were observed. Diagnostics do not restrict new fan-out.";
+        case "unknown":
+            return "Local pressure cannot be determined because the findings source is unavailable.";
+    }
+}
+function compareFindings(left, right) {
+    return (SEVERITY_RANK[right.severity] - SEVERITY_RANK[left.severity] ||
+        right.observed_at.localeCompare(left.observed_at) ||
+        left.id.localeCompare(right.id));
+}

package/dist/core/diagnostics/bundle.d.ts

@@ -0,0 +1,35 @@
+import type { ArtifactActor, ArtifactInventoryEntry } from "../artifacts/index.js";
+import { type DiagnosticBundleManifest, type DiagnosticReplayResult, type DiagnosticSummary, type ValidatedDiagnosticBundle } from "./contract.js";
+export interface CaptureDiagnosticBundleInput {
+    findingId?: string;
+    startAt?: string;
+    endAt?: string;
+    actor?: ArtifactActor;
+    retentionDays?: number;
+    now?: Date;
+    machineLabel?: string;
+    engineVersion?: string;
+}
+export interface CapturedDiagnosticBundle {
+    path: string;
+    manifest: DiagnosticBundleManifest;
+    summary: DiagnosticSummary;
+}
+export interface DiagnosticBundleListRow {
+    artifact_id: string;
+    created_at: string;
+    expires_at: string | null;
+    classification: ArtifactInventoryEntry["classification"];
+    valid: boolean;
+    captured_at?: string;
+    finding_id?: string;
+    error?: string;
+}
+export declare function captureDiagnosticBundle(repoRootRaw: string, input?: CaptureDiagnosticBundleInput): CapturedDiagnosticBundle;
+export declare function validateDiagnosticBundle(repoRootRaw: string, ref: string): ValidatedDiagnosticBundle;
+/** Frozen web readers accept an opaque artifact id, never a filesystem path. */
+export declare function readFrozenDiagnosticBundle(repoRoot: string, artifactId: string): ValidatedDiagnosticBundle;
+export declare function showDiagnosticBundle(repoRoot: string, ref: string): ValidatedDiagnosticBundle;
+export declare function listDiagnosticBundles(repoRoot: string): DiagnosticBundleListRow[];
+export declare function replayDiagnosticBundle(repoRoot: string, ref: string, now?: Date): DiagnosticReplayResult;
+//# sourceMappingURL=bundle.d.ts.map

package/dist/core/diagnostics/bundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../../../src/core/diagnostics/bundle.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,aAAa,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAwBnF,OAAO,EAUL,KAAK,wBAAwB,EAG7B,KAAK,sBAAsB,EAE3B,KAAK,iBAAiB,EAEtB,KAAK,yBAAyB,EAC/B,MAAM,eAAe,CAAC;AA0BvB,MAAM,WAAW,4BAA4B;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,GAAG,CAAC,EAAE,IAAI,CAAC;IACX,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,wBAAwB,CAAC;IACnC,OAAO,EAAE,iBAAiB,CAAC;CAC5B;AAED,MAAM,WAAW,uBAAuB;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,cAAc,EAAE,sBAAsB,CAAC,gBAAgB,CAAC,CAAC;IACzD,KAAK,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,MAAM,EACnB,KAAK,GAAE,4BAAiC,GACvC,wBAAwB,CAqG1B;AAED,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,MAAM,GACV,yBAAyB,CA+C3B;AAED,gFAAgF;AAChF,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,yBAAyB,CAK3B;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,yBAAyB,CAE7F;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,uBAAuB,EAAE,CA0BjF;AAED,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,GAAG,OAAa,GACf,sBAAsB,CAgBxB"}