@query-doctor/core 0.10.9 → 0.11.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/ci/policy.cjs +73 -0
- package/dist/ci/policy.cjs.map +1 -0
- package/dist/ci/policy.d.cts +57 -0
- package/dist/ci/policy.d.cts.map +1 -0
- package/dist/ci/policy.d.mts +57 -0
- package/dist/ci/policy.d.mts.map +1 -0
- package/dist/ci/policy.mjs +70 -0
- package/dist/ci/policy.mjs.map +1 -0
- package/dist/ci/taxonomy.cjs +28 -0
- package/dist/ci/taxonomy.cjs.map +1 -0
- package/dist/ci/taxonomy.d.cts +22 -0
- package/dist/ci/taxonomy.d.cts.map +1 -0
- package/dist/ci/taxonomy.d.mts +22 -0
- package/dist/ci/taxonomy.d.mts.map +1 -0
- package/dist/ci/taxonomy.mjs +26 -0
- package/dist/ci/taxonomy.mjs.map +1 -0
- package/dist/ci/verdict.cjs +117 -0
- package/dist/ci/verdict.cjs.map +1 -0
- package/dist/ci/verdict.d.cts +120 -0
- package/dist/ci/verdict.d.cts.map +1 -0
- package/dist/ci/verdict.d.mts +120 -0
- package/dist/ci/verdict.d.mts.map +1 -0
- package/dist/ci/verdict.mjs +109 -0
- package/dist/ci/verdict.mjs.map +1 -0
- package/dist/index.cjs +18 -0
- package/dist/index.d.cts +4 -1
- package/dist/index.d.mts +4 -1
- package/dist/index.mjs +4 -1
- package/dist/schema.cjs +2 -0
- package/dist/schema.cjs.map +1 -1
- package/dist/schema.d.cts +4 -0
- package/dist/schema.d.cts.map +1 -1
- package/dist/schema.d.mts +4 -0
- package/dist/schema.d.mts.map +1 -1
- package/dist/schema.mjs +2 -0
- package/dist/schema.mjs.map +1 -1
- package/package.json +1 -1
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
"use client";
|
|
2
|
+
const require_taxonomy = require("./taxonomy.cjs");
|
|
3
|
+
//#region src/ci/policy.ts
|
|
4
|
+
/**
|
|
5
|
+
* Opinionated safe defaults (epic #3493). A captured new query already ran in a
|
|
6
|
+
* test (tested by definition), so it's informational; everything that marks a
|
|
7
|
+
* genuine, diff-introduced problem fails by default. The set is deliberately
|
|
8
|
+
* narrow so the gate under-fires.
|
|
9
|
+
*/
|
|
10
|
+
const DEFAULT_CONDITION_POLICIES = {
|
|
11
|
+
"untested-data-access": "fail",
|
|
12
|
+
"schema-drift": "fail",
|
|
13
|
+
"new-query": "warn",
|
|
14
|
+
"regression-beyond-threshold": "fail",
|
|
15
|
+
"high-value-nudge": "fail"
|
|
16
|
+
};
|
|
17
|
+
/**
|
|
18
|
+
* Fallback for a condition with neither a repo setting nor a documented default:
|
|
19
|
+
* surface it, don't block. Under-firing on an unrecognised condition is the safe
|
|
20
|
+
* side of the line.
|
|
21
|
+
*/
|
|
22
|
+
const FALLBACK_POLICY = "warn";
|
|
23
|
+
/** Resolve the effective policy for a condition: repo config, else default, else fallback. */
|
|
24
|
+
function policyFor(condition, config = {}) {
|
|
25
|
+
return config[condition] ?? DEFAULT_CONDITION_POLICIES[condition] ?? "warn";
|
|
26
|
+
}
|
|
27
|
+
/**
|
|
28
|
+
* Fold a policy over a condition's base (taxonomy) conclusion. `fail` respects
|
|
29
|
+
* the taxonomy; `warn` caps a failure at `neutral` (still surfaced, never
|
|
30
|
+
* blocking); `off` is handled by dropping the condition before this runs.
|
|
31
|
+
*/
|
|
32
|
+
function applyPolicy(base, policy) {
|
|
33
|
+
if (policy === "warn") return base === "failure" ? "neutral" : base;
|
|
34
|
+
return base;
|
|
35
|
+
}
|
|
36
|
+
const SEVERITY = {
|
|
37
|
+
success: 0,
|
|
38
|
+
neutral: 1,
|
|
39
|
+
failure: 2
|
|
40
|
+
};
|
|
41
|
+
/**
|
|
42
|
+
* Evaluate a run: apply each condition's policy, then take the run conclusion as
|
|
43
|
+
* the worst surfaced conclusion. Pure — the same (results, config) always yields
|
|
44
|
+
* the same evaluation.
|
|
45
|
+
*
|
|
46
|
+
* Only diff-introduced conditions should reach here: detectors (e.g. the crude
|
|
47
|
+
* gate, #3496) evaluate the PR diff, so pre-existing untouched code never
|
|
48
|
+
* produces a result and can't trip a condition. With no results, the run passes.
|
|
49
|
+
*/
|
|
50
|
+
function evaluateRun(results, config = {}) {
|
|
51
|
+
const conditions = [];
|
|
52
|
+
for (const result of results) {
|
|
53
|
+
const policy = policyFor(result.condition, config);
|
|
54
|
+
if (policy === "off") continue;
|
|
55
|
+
conditions.push({
|
|
56
|
+
condition: result.condition,
|
|
57
|
+
policy,
|
|
58
|
+
verdict: result.verdict,
|
|
59
|
+
conclusion: applyPolicy(require_taxonomy.conclusionForVerdict(result.verdict), policy)
|
|
60
|
+
});
|
|
61
|
+
}
|
|
62
|
+
return {
|
|
63
|
+
conclusion: conditions.reduce((worst, c) => SEVERITY[c.conclusion] > SEVERITY[worst] ? c.conclusion : worst, "success"),
|
|
64
|
+
conditions
|
|
65
|
+
};
|
|
66
|
+
}
|
|
67
|
+
//#endregion
|
|
68
|
+
exports.DEFAULT_CONDITION_POLICIES = DEFAULT_CONDITION_POLICIES;
|
|
69
|
+
exports.FALLBACK_POLICY = FALLBACK_POLICY;
|
|
70
|
+
exports.evaluateRun = evaluateRun;
|
|
71
|
+
exports.policyFor = policyFor;
|
|
72
|
+
|
|
73
|
+
//# sourceMappingURL=policy.cjs.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"policy.cjs","names":["conclusionForVerdict"],"sources":["../../src/ci/policy.ts"],"sourcesContent":["import { conclusionForVerdict, type CiConclusion } from \"./taxonomy.ts\";\nimport type { CiVerdict } from \"./verdict.ts\";\n\n// The policy engine (#3500). Turns the single hard-coded gate into a\n// configurable condition set: a per-repo config gives each condition\n// `fail | warn | off`, and this pure function folds (config, condition results)\n// into one run conclusion plus the per-condition verdicts that produced it.\n//\n// It sits one layer above the taxonomy (#3498): the taxonomy says what a\n// verdict *would* conclude; the policy decides whether this repo lets that\n// condition fail, soften to a warning, or be suppressed entirely.\n\n/** What a repo lets a condition do: fail the run, warn-only, or ignore it. */\nexport type ConditionPolicy = \"fail\" | \"warn\" | \"off\";\n\n/** One condition's evaluated outcome, before policy is applied. */\nexport interface ConditionResult {\n /** Stable condition key, matched against the repo config (e.g. \"untested-data-access\"). */\n condition: string;\n verdict: CiVerdict;\n}\n\n/** A condition after policy resolution — its effective conclusion and the policy that shaped it. */\nexport interface ResolvedCondition {\n condition: string;\n policy: ConditionPolicy;\n verdict: CiVerdict;\n conclusion: CiConclusion;\n}\n\nexport interface RunEvaluation {\n /** The run's overall conclusion — the worst surfaced per-condition conclusion. */\n conclusion: CiConclusion;\n /** Per-condition results that were surfaced (an `off` condition is dropped). */\n conditions: ResolvedCondition[];\n}\n\n/** Per-repo policy: condition key → its policy. Absent keys fall back to defaults. */\nexport type RepoPolicyConfig = Record<string, ConditionPolicy>;\n\n/**\n * Opinionated safe defaults (epic #3493). A captured new query already ran in a\n * test (tested by definition), so it's informational; everything that marks a\n * genuine, diff-introduced problem fails by default. The set is deliberately\n * narrow so the gate under-fires.\n */\nexport const DEFAULT_CONDITION_POLICIES: RepoPolicyConfig = {\n \"untested-data-access\": \"fail\",\n \"schema-drift\": \"fail\", // #3296 owns the signal; this just gates on it\n \"new-query\": \"warn\", // captured ⇒ tested — informational, surfaced, non-blocking\n \"regression-beyond-threshold\": \"fail\", // #3104\n \"high-value-nudge\": \"fail\", // narrow set only\n};\n\n/**\n * Fallback for a condition with neither a repo setting nor a documented default:\n * surface it, don't block. Under-firing on an unrecognised condition is the safe\n * side of the line.\n */\nexport const FALLBACK_POLICY: ConditionPolicy = \"warn\";\n\n/** Resolve the effective policy for a condition: repo config, else default, else fallback. */\nexport function policyFor(\n condition: string,\n config: RepoPolicyConfig = {},\n): ConditionPolicy {\n return (\n config[condition] ??\n DEFAULT_CONDITION_POLICIES[condition] ??\n FALLBACK_POLICY\n );\n}\n\n/**\n * Fold a policy over a condition's base (taxonomy) conclusion. `fail` respects\n * the taxonomy; `warn` caps a failure at `neutral` (still surfaced, never\n * blocking); `off` is handled by dropping the condition before this runs.\n */\nfunction applyPolicy(\n base: CiConclusion,\n policy: ConditionPolicy,\n): CiConclusion {\n if (policy === \"warn\") return base === \"failure\" ? \"neutral\" : base;\n return base;\n}\n\nconst SEVERITY: Record<CiConclusion, number> = {\n success: 0,\n neutral: 1,\n failure: 2,\n};\n\n/**\n * Evaluate a run: apply each condition's policy, then take the run conclusion as\n * the worst surfaced conclusion. Pure — the same (results, config) always yields\n * the same evaluation.\n *\n * Only diff-introduced conditions should reach here: detectors (e.g. the crude\n * gate, #3496) evaluate the PR diff, so pre-existing untouched code never\n * produces a result and can't trip a condition. With no results, the run passes.\n */\nexport function evaluateRun(\n results: ConditionResult[],\n config: RepoPolicyConfig = {},\n): RunEvaluation {\n const conditions: ResolvedCondition[] = [];\n for (const result of results) {\n const policy = policyFor(result.condition, config);\n if (policy === \"off\") continue; // suppressed entirely — not surfaced\n conditions.push({\n condition: result.condition,\n policy,\n verdict: result.verdict,\n conclusion: applyPolicy(conclusionForVerdict(result.verdict), policy),\n });\n }\n const conclusion = conditions.reduce<CiConclusion>(\n (worst, c) =>\n SEVERITY[c.conclusion] > SEVERITY[worst] ? c.conclusion : worst,\n \"success\",\n );\n return { conclusion, conditions };\n}\n"],"mappings":";;;;;;;;;AA8CA,MAAa,6BAA+C;CAC1D,wBAAwB;CACxB,gBAAgB;CAChB,aAAa;CACb,+BAA+B;CAC/B,oBAAoB;CACrB;;;;;;AAOD,MAAa,kBAAmC;;AAGhD,SAAgB,UACd,WACA,SAA2B,EAAE,EACZ;AACjB,QACE,OAAO,cACP,2BAA2B,cAAA;;;;;;;AAU/B,SAAS,YACP,MACA,QACc;AACd,KAAI,WAAW,OAAQ,QAAO,SAAS,YAAY,YAAY;AAC/D,QAAO;;AAGT,MAAM,WAAyC;CAC7C,SAAS;CACT,SAAS;CACT,SAAS;CACV;;;;;;;;;;AAWD,SAAgB,YACd,SACA,SAA2B,EAAE,EACd;CACf,MAAM,aAAkC,EAAE;AAC1C,MAAK,MAAM,UAAU,SAAS;EAC5B,MAAM,SAAS,UAAU,OAAO,WAAW,OAAO;AAClD,MAAI,WAAW,MAAO;AACtB,aAAW,KAAK;GACd,WAAW,OAAO;GAClB;GACA,SAAS,OAAO;GAChB,YAAY,YAAYA,iBAAAA,qBAAqB,OAAO,QAAQ,EAAE,OAAO;GACtE,CAAC;;AAOJ,QAAO;EAAE,YALU,WAAW,QAC3B,OAAO,MACN,SAAS,EAAE,cAAc,SAAS,SAAS,EAAE,aAAa,OAC5D,UACD;EACoB;EAAY"}
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
'use client';
|
|
2
|
+
|
|
3
|
+
import { CiVerdict } from "./verdict.cjs";
|
|
4
|
+
import { CiConclusion } from "./taxonomy.cjs";
|
|
5
|
+
|
|
6
|
+
//#region src/ci/policy.d.ts
|
|
7
|
+
/** What a repo lets a condition do: fail the run, warn-only, or ignore it. */
|
|
8
|
+
type ConditionPolicy = "fail" | "warn" | "off";
|
|
9
|
+
/** One condition's evaluated outcome, before policy is applied. */
|
|
10
|
+
interface ConditionResult {
|
|
11
|
+
/** Stable condition key, matched against the repo config (e.g. "untested-data-access"). */
|
|
12
|
+
condition: string;
|
|
13
|
+
verdict: CiVerdict;
|
|
14
|
+
}
|
|
15
|
+
/** A condition after policy resolution — its effective conclusion and the policy that shaped it. */
|
|
16
|
+
interface ResolvedCondition {
|
|
17
|
+
condition: string;
|
|
18
|
+
policy: ConditionPolicy;
|
|
19
|
+
verdict: CiVerdict;
|
|
20
|
+
conclusion: CiConclusion;
|
|
21
|
+
}
|
|
22
|
+
interface RunEvaluation {
|
|
23
|
+
/** The run's overall conclusion — the worst surfaced per-condition conclusion. */
|
|
24
|
+
conclusion: CiConclusion;
|
|
25
|
+
/** Per-condition results that were surfaced (an `off` condition is dropped). */
|
|
26
|
+
conditions: ResolvedCondition[];
|
|
27
|
+
}
|
|
28
|
+
/** Per-repo policy: condition key → its policy. Absent keys fall back to defaults. */
|
|
29
|
+
type RepoPolicyConfig = Record<string, ConditionPolicy>;
|
|
30
|
+
/**
|
|
31
|
+
* Opinionated safe defaults (epic #3493). A captured new query already ran in a
|
|
32
|
+
* test (tested by definition), so it's informational; everything that marks a
|
|
33
|
+
* genuine, diff-introduced problem fails by default. The set is deliberately
|
|
34
|
+
* narrow so the gate under-fires.
|
|
35
|
+
*/
|
|
36
|
+
declare const DEFAULT_CONDITION_POLICIES: RepoPolicyConfig;
|
|
37
|
+
/**
|
|
38
|
+
* Fallback for a condition with neither a repo setting nor a documented default:
|
|
39
|
+
* surface it, don't block. Under-firing on an unrecognised condition is the safe
|
|
40
|
+
* side of the line.
|
|
41
|
+
*/
|
|
42
|
+
declare const FALLBACK_POLICY: ConditionPolicy;
|
|
43
|
+
/** Resolve the effective policy for a condition: repo config, else default, else fallback. */
|
|
44
|
+
declare function policyFor(condition: string, config?: RepoPolicyConfig): ConditionPolicy;
|
|
45
|
+
/**
|
|
46
|
+
* Evaluate a run: apply each condition's policy, then take the run conclusion as
|
|
47
|
+
* the worst surfaced conclusion. Pure — the same (results, config) always yields
|
|
48
|
+
* the same evaluation.
|
|
49
|
+
*
|
|
50
|
+
* Only diff-introduced conditions should reach here: detectors (e.g. the crude
|
|
51
|
+
* gate, #3496) evaluate the PR diff, so pre-existing untouched code never
|
|
52
|
+
* produces a result and can't trip a condition. With no results, the run passes.
|
|
53
|
+
*/
|
|
54
|
+
declare function evaluateRun(results: ConditionResult[], config?: RepoPolicyConfig): RunEvaluation;
|
|
55
|
+
//#endregion
|
|
56
|
+
export { ConditionPolicy, ConditionResult, DEFAULT_CONDITION_POLICIES, FALLBACK_POLICY, RepoPolicyConfig, ResolvedCondition, RunEvaluation, evaluateRun, policyFor };
|
|
57
|
+
//# sourceMappingURL=policy.d.cts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"policy.d.cts","names":[],"sources":["../../src/ci/policy.ts"],"mappings":";;;;;;;KAaY,eAAA;;UAGK,eAAA;EAHU;EAKzB,SAAA;EACA,OAAA,EAAS,SAAA;AAAA;AAHX;AAAA,UAOiB,iBAAA;EACf,SAAA;EACA,MAAA,EAAQ,eAAA;EACR,OAAA,EAAS,SAAA;EACT,UAAA,EAAY,YAAA;AAAA;AAAA,UAGG,aAAA;EAXG;EAalB,UAAA,EAAY,YAAA;EAToB;EAWhC,UAAA,EAAY,iBAAA;AAAA;;KAIF,gBAAA,GAAmB,MAAA,SAAe,eAAA;;;;;;;cAQjC,0BAAA,EAA4B,gBAAA;;;;;AAhBzC;cA6Ba,eAAA,EAAiB,eAAA;;iBAGd,SAAA,CACd,SAAA,UACA,MAAA,GAAQ,gBAAA,GACP,eAAA;;;;;;;AA3BH;;;iBA+DgB,WAAA,CACd,OAAA,EAAS,eAAA,IACT,MAAA,GAAQ,gBAAA,GACP,aAAA"}
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
'use client';
|
|
2
|
+
|
|
3
|
+
import { CiVerdict } from "./verdict.mjs";
|
|
4
|
+
import { CiConclusion } from "./taxonomy.mjs";
|
|
5
|
+
|
|
6
|
+
//#region src/ci/policy.d.ts
|
|
7
|
+
/** What a repo lets a condition do: fail the run, warn-only, or ignore it. */
|
|
8
|
+
type ConditionPolicy = "fail" | "warn" | "off";
|
|
9
|
+
/** One condition's evaluated outcome, before policy is applied. */
|
|
10
|
+
interface ConditionResult {
|
|
11
|
+
/** Stable condition key, matched against the repo config (e.g. "untested-data-access"). */
|
|
12
|
+
condition: string;
|
|
13
|
+
verdict: CiVerdict;
|
|
14
|
+
}
|
|
15
|
+
/** A condition after policy resolution — its effective conclusion and the policy that shaped it. */
|
|
16
|
+
interface ResolvedCondition {
|
|
17
|
+
condition: string;
|
|
18
|
+
policy: ConditionPolicy;
|
|
19
|
+
verdict: CiVerdict;
|
|
20
|
+
conclusion: CiConclusion;
|
|
21
|
+
}
|
|
22
|
+
interface RunEvaluation {
|
|
23
|
+
/** The run's overall conclusion — the worst surfaced per-condition conclusion. */
|
|
24
|
+
conclusion: CiConclusion;
|
|
25
|
+
/** Per-condition results that were surfaced (an `off` condition is dropped). */
|
|
26
|
+
conditions: ResolvedCondition[];
|
|
27
|
+
}
|
|
28
|
+
/** Per-repo policy: condition key → its policy. Absent keys fall back to defaults. */
|
|
29
|
+
type RepoPolicyConfig = Record<string, ConditionPolicy>;
|
|
30
|
+
/**
|
|
31
|
+
* Opinionated safe defaults (epic #3493). A captured new query already ran in a
|
|
32
|
+
* test (tested by definition), so it's informational; everything that marks a
|
|
33
|
+
* genuine, diff-introduced problem fails by default. The set is deliberately
|
|
34
|
+
* narrow so the gate under-fires.
|
|
35
|
+
*/
|
|
36
|
+
declare const DEFAULT_CONDITION_POLICIES: RepoPolicyConfig;
|
|
37
|
+
/**
|
|
38
|
+
* Fallback for a condition with neither a repo setting nor a documented default:
|
|
39
|
+
* surface it, don't block. Under-firing on an unrecognised condition is the safe
|
|
40
|
+
* side of the line.
|
|
41
|
+
*/
|
|
42
|
+
declare const FALLBACK_POLICY: ConditionPolicy;
|
|
43
|
+
/** Resolve the effective policy for a condition: repo config, else default, else fallback. */
|
|
44
|
+
declare function policyFor(condition: string, config?: RepoPolicyConfig): ConditionPolicy;
|
|
45
|
+
/**
|
|
46
|
+
* Evaluate a run: apply each condition's policy, then take the run conclusion as
|
|
47
|
+
* the worst surfaced conclusion. Pure — the same (results, config) always yields
|
|
48
|
+
* the same evaluation.
|
|
49
|
+
*
|
|
50
|
+
* Only diff-introduced conditions should reach here: detectors (e.g. the crude
|
|
51
|
+
* gate, #3496) evaluate the PR diff, so pre-existing untouched code never
|
|
52
|
+
* produces a result and can't trip a condition. With no results, the run passes.
|
|
53
|
+
*/
|
|
54
|
+
declare function evaluateRun(results: ConditionResult[], config?: RepoPolicyConfig): RunEvaluation;
|
|
55
|
+
//#endregion
|
|
56
|
+
export { ConditionPolicy, ConditionResult, DEFAULT_CONDITION_POLICIES, FALLBACK_POLICY, RepoPolicyConfig, ResolvedCondition, RunEvaluation, evaluateRun, policyFor };
|
|
57
|
+
//# sourceMappingURL=policy.d.mts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"policy.d.mts","names":[],"sources":["../../src/ci/policy.ts"],"mappings":";;;;;;;KAaY,eAAA;;UAGK,eAAA;EAHU;EAKzB,SAAA;EACA,OAAA,EAAS,SAAA;AAAA;AAHX;AAAA,UAOiB,iBAAA;EACf,SAAA;EACA,MAAA,EAAQ,eAAA;EACR,OAAA,EAAS,SAAA;EACT,UAAA,EAAY,YAAA;AAAA;AAAA,UAGG,aAAA;EAXG;EAalB,UAAA,EAAY,YAAA;EAToB;EAWhC,UAAA,EAAY,iBAAA;AAAA;;KAIF,gBAAA,GAAmB,MAAA,SAAe,eAAA;;;;;;;cAQjC,0BAAA,EAA4B,gBAAA;;;;;AAhBzC;cA6Ba,eAAA,EAAiB,eAAA;;iBAGd,SAAA,CACd,SAAA,UACA,MAAA,GAAQ,gBAAA,GACP,eAAA;;;;;;;AA3BH;;;iBA+DgB,WAAA,CACd,OAAA,EAAS,eAAA,IACT,MAAA,GAAQ,gBAAA,GACP,aAAA"}
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
"use client";
|
|
2
|
+
import { conclusionForVerdict } from "./taxonomy.mjs";
|
|
3
|
+
//#region src/ci/policy.ts
|
|
4
|
+
/**
|
|
5
|
+
* Opinionated safe defaults (epic #3493). A captured new query already ran in a
|
|
6
|
+
* test (tested by definition), so it's informational; everything that marks a
|
|
7
|
+
* genuine, diff-introduced problem fails by default. The set is deliberately
|
|
8
|
+
* narrow so the gate under-fires.
|
|
9
|
+
*/
|
|
10
|
+
const DEFAULT_CONDITION_POLICIES = {
|
|
11
|
+
"untested-data-access": "fail",
|
|
12
|
+
"schema-drift": "fail",
|
|
13
|
+
"new-query": "warn",
|
|
14
|
+
"regression-beyond-threshold": "fail",
|
|
15
|
+
"high-value-nudge": "fail"
|
|
16
|
+
};
|
|
17
|
+
/**
|
|
18
|
+
* Fallback for a condition with neither a repo setting nor a documented default:
|
|
19
|
+
* surface it, don't block. Under-firing on an unrecognised condition is the safe
|
|
20
|
+
* side of the line.
|
|
21
|
+
*/
|
|
22
|
+
const FALLBACK_POLICY = "warn";
|
|
23
|
+
/** Resolve the effective policy for a condition: repo config, else default, else fallback. */
|
|
24
|
+
function policyFor(condition, config = {}) {
|
|
25
|
+
return config[condition] ?? DEFAULT_CONDITION_POLICIES[condition] ?? "warn";
|
|
26
|
+
}
|
|
27
|
+
/**
|
|
28
|
+
* Fold a policy over a condition's base (taxonomy) conclusion. `fail` respects
|
|
29
|
+
* the taxonomy; `warn` caps a failure at `neutral` (still surfaced, never
|
|
30
|
+
* blocking); `off` is handled by dropping the condition before this runs.
|
|
31
|
+
*/
|
|
32
|
+
function applyPolicy(base, policy) {
|
|
33
|
+
if (policy === "warn") return base === "failure" ? "neutral" : base;
|
|
34
|
+
return base;
|
|
35
|
+
}
|
|
36
|
+
const SEVERITY = {
|
|
37
|
+
success: 0,
|
|
38
|
+
neutral: 1,
|
|
39
|
+
failure: 2
|
|
40
|
+
};
|
|
41
|
+
/**
|
|
42
|
+
* Evaluate a run: apply each condition's policy, then take the run conclusion as
|
|
43
|
+
* the worst surfaced conclusion. Pure — the same (results, config) always yields
|
|
44
|
+
* the same evaluation.
|
|
45
|
+
*
|
|
46
|
+
* Only diff-introduced conditions should reach here: detectors (e.g. the crude
|
|
47
|
+
* gate, #3496) evaluate the PR diff, so pre-existing untouched code never
|
|
48
|
+
* produces a result and can't trip a condition. With no results, the run passes.
|
|
49
|
+
*/
|
|
50
|
+
function evaluateRun(results, config = {}) {
|
|
51
|
+
const conditions = [];
|
|
52
|
+
for (const result of results) {
|
|
53
|
+
const policy = policyFor(result.condition, config);
|
|
54
|
+
if (policy === "off") continue;
|
|
55
|
+
conditions.push({
|
|
56
|
+
condition: result.condition,
|
|
57
|
+
policy,
|
|
58
|
+
verdict: result.verdict,
|
|
59
|
+
conclusion: applyPolicy(conclusionForVerdict(result.verdict), policy)
|
|
60
|
+
});
|
|
61
|
+
}
|
|
62
|
+
return {
|
|
63
|
+
conclusion: conditions.reduce((worst, c) => SEVERITY[c.conclusion] > SEVERITY[worst] ? c.conclusion : worst, "success"),
|
|
64
|
+
conditions
|
|
65
|
+
};
|
|
66
|
+
}
|
|
67
|
+
//#endregion
|
|
68
|
+
export { DEFAULT_CONDITION_POLICIES, FALLBACK_POLICY, evaluateRun, policyFor };
|
|
69
|
+
|
|
70
|
+
//# sourceMappingURL=policy.mjs.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"policy.mjs","names":[],"sources":["../../src/ci/policy.ts"],"sourcesContent":["import { conclusionForVerdict, type CiConclusion } from \"./taxonomy.ts\";\nimport type { CiVerdict } from \"./verdict.ts\";\n\n// The policy engine (#3500). Turns the single hard-coded gate into a\n// configurable condition set: a per-repo config gives each condition\n// `fail | warn | off`, and this pure function folds (config, condition results)\n// into one run conclusion plus the per-condition verdicts that produced it.\n//\n// It sits one layer above the taxonomy (#3498): the taxonomy says what a\n// verdict *would* conclude; the policy decides whether this repo lets that\n// condition fail, soften to a warning, or be suppressed entirely.\n\n/** What a repo lets a condition do: fail the run, warn-only, or ignore it. */\nexport type ConditionPolicy = \"fail\" | \"warn\" | \"off\";\n\n/** One condition's evaluated outcome, before policy is applied. */\nexport interface ConditionResult {\n /** Stable condition key, matched against the repo config (e.g. \"untested-data-access\"). */\n condition: string;\n verdict: CiVerdict;\n}\n\n/** A condition after policy resolution — its effective conclusion and the policy that shaped it. */\nexport interface ResolvedCondition {\n condition: string;\n policy: ConditionPolicy;\n verdict: CiVerdict;\n conclusion: CiConclusion;\n}\n\nexport interface RunEvaluation {\n /** The run's overall conclusion — the worst surfaced per-condition conclusion. */\n conclusion: CiConclusion;\n /** Per-condition results that were surfaced (an `off` condition is dropped). */\n conditions: ResolvedCondition[];\n}\n\n/** Per-repo policy: condition key → its policy. Absent keys fall back to defaults. */\nexport type RepoPolicyConfig = Record<string, ConditionPolicy>;\n\n/**\n * Opinionated safe defaults (epic #3493). A captured new query already ran in a\n * test (tested by definition), so it's informational; everything that marks a\n * genuine, diff-introduced problem fails by default. The set is deliberately\n * narrow so the gate under-fires.\n */\nexport const DEFAULT_CONDITION_POLICIES: RepoPolicyConfig = {\n \"untested-data-access\": \"fail\",\n \"schema-drift\": \"fail\", // #3296 owns the signal; this just gates on it\n \"new-query\": \"warn\", // captured ⇒ tested — informational, surfaced, non-blocking\n \"regression-beyond-threshold\": \"fail\", // #3104\n \"high-value-nudge\": \"fail\", // narrow set only\n};\n\n/**\n * Fallback for a condition with neither a repo setting nor a documented default:\n * surface it, don't block. Under-firing on an unrecognised condition is the safe\n * side of the line.\n */\nexport const FALLBACK_POLICY: ConditionPolicy = \"warn\";\n\n/** Resolve the effective policy for a condition: repo config, else default, else fallback. */\nexport function policyFor(\n condition: string,\n config: RepoPolicyConfig = {},\n): ConditionPolicy {\n return (\n config[condition] ??\n DEFAULT_CONDITION_POLICIES[condition] ??\n FALLBACK_POLICY\n );\n}\n\n/**\n * Fold a policy over a condition's base (taxonomy) conclusion. `fail` respects\n * the taxonomy; `warn` caps a failure at `neutral` (still surfaced, never\n * blocking); `off` is handled by dropping the condition before this runs.\n */\nfunction applyPolicy(\n base: CiConclusion,\n policy: ConditionPolicy,\n): CiConclusion {\n if (policy === \"warn\") return base === \"failure\" ? \"neutral\" : base;\n return base;\n}\n\nconst SEVERITY: Record<CiConclusion, number> = {\n success: 0,\n neutral: 1,\n failure: 2,\n};\n\n/**\n * Evaluate a run: apply each condition's policy, then take the run conclusion as\n * the worst surfaced conclusion. Pure — the same (results, config) always yields\n * the same evaluation.\n *\n * Only diff-introduced conditions should reach here: detectors (e.g. the crude\n * gate, #3496) evaluate the PR diff, so pre-existing untouched code never\n * produces a result and can't trip a condition. With no results, the run passes.\n */\nexport function evaluateRun(\n results: ConditionResult[],\n config: RepoPolicyConfig = {},\n): RunEvaluation {\n const conditions: ResolvedCondition[] = [];\n for (const result of results) {\n const policy = policyFor(result.condition, config);\n if (policy === \"off\") continue; // suppressed entirely — not surfaced\n conditions.push({\n condition: result.condition,\n policy,\n verdict: result.verdict,\n conclusion: applyPolicy(conclusionForVerdict(result.verdict), policy),\n });\n }\n const conclusion = conditions.reduce<CiConclusion>(\n (worst, c) =>\n SEVERITY[c.conclusion] > SEVERITY[worst] ? c.conclusion : worst,\n \"success\",\n );\n return { conclusion, conditions };\n}\n"],"mappings":";;;;;;;;;AA8CA,MAAa,6BAA+C;CAC1D,wBAAwB;CACxB,gBAAgB;CAChB,aAAa;CACb,+BAA+B;CAC/B,oBAAoB;CACrB;;;;;;AAOD,MAAa,kBAAmC;;AAGhD,SAAgB,UACd,WACA,SAA2B,EAAE,EACZ;AACjB,QACE,OAAO,cACP,2BAA2B,cAAA;;;;;;;AAU/B,SAAS,YACP,MACA,QACc;AACd,KAAI,WAAW,OAAQ,QAAO,SAAS,YAAY,YAAY;AAC/D,QAAO;;AAGT,MAAM,WAAyC;CAC7C,SAAS;CACT,SAAS;CACT,SAAS;CACV;;;;;;;;;;AAWD,SAAgB,YACd,SACA,SAA2B,EAAE,EACd;CACf,MAAM,aAAkC,EAAE;AAC1C,MAAK,MAAM,UAAU,SAAS;EAC5B,MAAM,SAAS,UAAU,OAAO,WAAW,OAAO;AAClD,MAAI,WAAW,MAAO;AACtB,aAAW,KAAK;GACd,WAAW,OAAO;GAClB;GACA,SAAS,OAAO;GAChB,YAAY,YAAY,qBAAqB,OAAO,QAAQ,EAAE,OAAO;GACtE,CAAC;;AAOJ,QAAO;EAAE,YALU,WAAW,QAC3B,OAAO,MACN,SAAS,EAAE,cAAc,SAAS,SAAS,EAAE,aAAa,OAC5D,UACD;EACoB;EAAY"}
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
"use client";
|
|
2
|
+
//#region src/ci/taxonomy.ts
|
|
3
|
+
const CLASS_TO_CONCLUSION = {
|
|
4
|
+
pass: "success",
|
|
5
|
+
"coverage-gap": "failure",
|
|
6
|
+
finding: "failure",
|
|
7
|
+
"uncertain-conservative-flag": "failure",
|
|
8
|
+
"setup-broken": "failure",
|
|
9
|
+
"infra-error": "neutral"
|
|
10
|
+
};
|
|
11
|
+
/** Map one verdict class to its CI conclusion. Total and deterministic. */
|
|
12
|
+
function conclusionForVerdictClass(verdictClass) {
|
|
13
|
+
return CLASS_TO_CONCLUSION[verdictClass];
|
|
14
|
+
}
|
|
15
|
+
/** Convenience over {@link conclusionForVerdictClass} for a whole verdict. */
|
|
16
|
+
function conclusionForVerdict(verdict) {
|
|
17
|
+
return conclusionForVerdictClass(verdict.verdictClass);
|
|
18
|
+
}
|
|
19
|
+
/** True when a class blocks the PR (a red check), as opposed to passing or neutral. */
|
|
20
|
+
function isBlocking(verdictClass) {
|
|
21
|
+
return conclusionForVerdictClass(verdictClass) === "failure";
|
|
22
|
+
}
|
|
23
|
+
//#endregion
|
|
24
|
+
exports.conclusionForVerdict = conclusionForVerdict;
|
|
25
|
+
exports.conclusionForVerdictClass = conclusionForVerdictClass;
|
|
26
|
+
exports.isBlocking = isBlocking;
|
|
27
|
+
|
|
28
|
+
//# sourceMappingURL=taxonomy.cjs.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"taxonomy.cjs","names":[],"sources":["../../src/ci/taxonomy.ts"],"sourcesContent":["import type { VerdictClass } from \"./verdict.ts\";\n\n// The failure taxonomy (#3498). The single deterministic hinge between \"what the\n// tool honestly knows\" (the verdict class) and \"what the CI check concludes\".\n// Keeping it a pure function of the verdict class — not scattered `if` branches\n// at each call site — is what guarantees every condition gets the *right*\n// conclusion and the same one every time.\n\n/**\n * A GitHub check-run conclusion, narrowed to the three this loop uses.\n * `neutral` reports \"we didn't/couldn't decide\" without a red X; `failure`\n * blocks; `success` is the clean pass.\n */\nexport type CiConclusion = \"success\" | \"failure\" | \"neutral\";\n\nconst CLASS_TO_CONCLUSION: Record<VerdictClass, CiConclusion> = {\n pass: \"success\",\n // A known coverage gap, a real finding, and a conservative \"unverified\" flag\n // all block the PR. They differ in their *reason and framing* (carried by the\n // verdict), not in whether they gate — an uncertain result still fails, but\n // with honest \"we're not sure, flagging to be safe\" messaging rather than a\n // \"your query is broken\" claim.\n \"coverage-gap\": \"failure\",\n finding: \"failure\",\n \"uncertain-conservative-flag\": \"failure\",\n // Capture isn't emitting: a setup problem the user must fix, surfaced as a\n // failure with setup next-steps — never silently green, or it reads as safe.\n \"setup-broken\": \"failure\",\n // A transient infra/transport error (e.g. a dropped WebSocket to the API) is\n // not the user's query problem, so it resolves to neutral, never a red X\n // (adopts #3401).\n \"infra-error\": \"neutral\",\n};\n\n/** Map one verdict class to its CI conclusion. Total and deterministic. */\nexport function conclusionForVerdictClass(\n verdictClass: VerdictClass,\n): CiConclusion {\n return CLASS_TO_CONCLUSION[verdictClass];\n}\n\n/** Convenience over {@link conclusionForVerdictClass} for a whole verdict. */\nexport function conclusionForVerdict(verdict: {\n verdictClass: VerdictClass;\n}): CiConclusion {\n return conclusionForVerdictClass(verdict.verdictClass);\n}\n\n/** True when a class blocks the PR (a red check), as opposed to passing or neutral. */\nexport function isBlocking(verdictClass: VerdictClass): boolean {\n return conclusionForVerdictClass(verdictClass) === \"failure\";\n}\n"],"mappings":";;AAeA,MAAM,sBAA0D;CAC9D,MAAM;CAMN,gBAAgB;CAChB,SAAS;CACT,+BAA+B;CAG/B,gBAAgB;CAIhB,eAAe;CAChB;;AAGD,SAAgB,0BACd,cACc;AACd,QAAO,oBAAoB;;;AAI7B,SAAgB,qBAAqB,SAEpB;AACf,QAAO,0BAA0B,QAAQ,aAAa;;;AAIxD,SAAgB,WAAW,cAAqC;AAC9D,QAAO,0BAA0B,aAAa,KAAK"}
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
'use client';
|
|
2
|
+
|
|
3
|
+
import { VerdictClass } from "./verdict.cjs";
|
|
4
|
+
|
|
5
|
+
//#region src/ci/taxonomy.d.ts
|
|
6
|
+
/**
|
|
7
|
+
* A GitHub check-run conclusion, narrowed to the three this loop uses.
|
|
8
|
+
* `neutral` reports "we didn't/couldn't decide" without a red X; `failure`
|
|
9
|
+
* blocks; `success` is the clean pass.
|
|
10
|
+
*/
|
|
11
|
+
type CiConclusion = "success" | "failure" | "neutral";
|
|
12
|
+
/** Map one verdict class to its CI conclusion. Total and deterministic. */
|
|
13
|
+
declare function conclusionForVerdictClass(verdictClass: VerdictClass): CiConclusion;
|
|
14
|
+
/** Convenience over {@link conclusionForVerdictClass} for a whole verdict. */
|
|
15
|
+
declare function conclusionForVerdict(verdict: {
|
|
16
|
+
verdictClass: VerdictClass;
|
|
17
|
+
}): CiConclusion;
|
|
18
|
+
/** True when a class blocks the PR (a red check), as opposed to passing or neutral. */
|
|
19
|
+
declare function isBlocking(verdictClass: VerdictClass): boolean;
|
|
20
|
+
//#endregion
|
|
21
|
+
export { CiConclusion, conclusionForVerdict, conclusionForVerdictClass, isBlocking };
|
|
22
|
+
//# sourceMappingURL=taxonomy.d.cts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"taxonomy.d.cts","names":[],"sources":["../../src/ci/taxonomy.ts"],"mappings":";;;;;;;;AAaA;;KAAY,YAAA;;iBAsBI,yBAAA,CACd,YAAA,EAAc,YAAA,GACb,YAAA;AAFH;AAAA,iBAOgB,oBAAA,CAAqB,OAAA;EACnC,YAAA,EAAc,YAAA;AAAA,IACZ,YAAA;;iBAKY,UAAA,CAAW,YAAA,EAAc,YAAA"}
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
'use client';
|
|
2
|
+
|
|
3
|
+
import { VerdictClass } from "./verdict.mjs";
|
|
4
|
+
|
|
5
|
+
//#region src/ci/taxonomy.d.ts
|
|
6
|
+
/**
|
|
7
|
+
* A GitHub check-run conclusion, narrowed to the three this loop uses.
|
|
8
|
+
* `neutral` reports "we didn't/couldn't decide" without a red X; `failure`
|
|
9
|
+
* blocks; `success` is the clean pass.
|
|
10
|
+
*/
|
|
11
|
+
type CiConclusion = "success" | "failure" | "neutral";
|
|
12
|
+
/** Map one verdict class to its CI conclusion. Total and deterministic. */
|
|
13
|
+
declare function conclusionForVerdictClass(verdictClass: VerdictClass): CiConclusion;
|
|
14
|
+
/** Convenience over {@link conclusionForVerdictClass} for a whole verdict. */
|
|
15
|
+
declare function conclusionForVerdict(verdict: {
|
|
16
|
+
verdictClass: VerdictClass;
|
|
17
|
+
}): CiConclusion;
|
|
18
|
+
/** True when a class blocks the PR (a red check), as opposed to passing or neutral. */
|
|
19
|
+
declare function isBlocking(verdictClass: VerdictClass): boolean;
|
|
20
|
+
//#endregion
|
|
21
|
+
export { CiConclusion, conclusionForVerdict, conclusionForVerdictClass, isBlocking };
|
|
22
|
+
//# sourceMappingURL=taxonomy.d.mts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"taxonomy.d.mts","names":[],"sources":["../../src/ci/taxonomy.ts"],"mappings":";;;;;;;;AAaA;;KAAY,YAAA;;iBAsBI,yBAAA,CACd,YAAA,EAAc,YAAA,GACb,YAAA;AAFH;AAAA,iBAOgB,oBAAA,CAAqB,OAAA;EACnC,YAAA,EAAc,YAAA;AAAA,IACZ,YAAA;;iBAKY,UAAA,CAAW,YAAA,EAAc,YAAA"}
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
"use client";
|
|
2
|
+
//#region src/ci/taxonomy.ts
|
|
3
|
+
const CLASS_TO_CONCLUSION = {
|
|
4
|
+
pass: "success",
|
|
5
|
+
"coverage-gap": "failure",
|
|
6
|
+
finding: "failure",
|
|
7
|
+
"uncertain-conservative-flag": "failure",
|
|
8
|
+
"setup-broken": "failure",
|
|
9
|
+
"infra-error": "neutral"
|
|
10
|
+
};
|
|
11
|
+
/** Map one verdict class to its CI conclusion. Total and deterministic. */
|
|
12
|
+
function conclusionForVerdictClass(verdictClass) {
|
|
13
|
+
return CLASS_TO_CONCLUSION[verdictClass];
|
|
14
|
+
}
|
|
15
|
+
/** Convenience over {@link conclusionForVerdictClass} for a whole verdict. */
|
|
16
|
+
function conclusionForVerdict(verdict) {
|
|
17
|
+
return conclusionForVerdictClass(verdict.verdictClass);
|
|
18
|
+
}
|
|
19
|
+
/** True when a class blocks the PR (a red check), as opposed to passing or neutral. */
|
|
20
|
+
function isBlocking(verdictClass) {
|
|
21
|
+
return conclusionForVerdictClass(verdictClass) === "failure";
|
|
22
|
+
}
|
|
23
|
+
//#endregion
|
|
24
|
+
export { conclusionForVerdict, conclusionForVerdictClass, isBlocking };
|
|
25
|
+
|
|
26
|
+
//# sourceMappingURL=taxonomy.mjs.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"taxonomy.mjs","names":[],"sources":["../../src/ci/taxonomy.ts"],"sourcesContent":["import type { VerdictClass } from \"./verdict.ts\";\n\n// The failure taxonomy (#3498). The single deterministic hinge between \"what the\n// tool honestly knows\" (the verdict class) and \"what the CI check concludes\".\n// Keeping it a pure function of the verdict class — not scattered `if` branches\n// at each call site — is what guarantees every condition gets the *right*\n// conclusion and the same one every time.\n\n/**\n * A GitHub check-run conclusion, narrowed to the three this loop uses.\n * `neutral` reports \"we didn't/couldn't decide\" without a red X; `failure`\n * blocks; `success` is the clean pass.\n */\nexport type CiConclusion = \"success\" | \"failure\" | \"neutral\";\n\nconst CLASS_TO_CONCLUSION: Record<VerdictClass, CiConclusion> = {\n pass: \"success\",\n // A known coverage gap, a real finding, and a conservative \"unverified\" flag\n // all block the PR. They differ in their *reason and framing* (carried by the\n // verdict), not in whether they gate — an uncertain result still fails, but\n // with honest \"we're not sure, flagging to be safe\" messaging rather than a\n // \"your query is broken\" claim.\n \"coverage-gap\": \"failure\",\n finding: \"failure\",\n \"uncertain-conservative-flag\": \"failure\",\n // Capture isn't emitting: a setup problem the user must fix, surfaced as a\n // failure with setup next-steps — never silently green, or it reads as safe.\n \"setup-broken\": \"failure\",\n // A transient infra/transport error (e.g. a dropped WebSocket to the API) is\n // not the user's query problem, so it resolves to neutral, never a red X\n // (adopts #3401).\n \"infra-error\": \"neutral\",\n};\n\n/** Map one verdict class to its CI conclusion. Total and deterministic. */\nexport function conclusionForVerdictClass(\n verdictClass: VerdictClass,\n): CiConclusion {\n return CLASS_TO_CONCLUSION[verdictClass];\n}\n\n/** Convenience over {@link conclusionForVerdictClass} for a whole verdict. */\nexport function conclusionForVerdict(verdict: {\n verdictClass: VerdictClass;\n}): CiConclusion {\n return conclusionForVerdictClass(verdict.verdictClass);\n}\n\n/** True when a class blocks the PR (a red check), as opposed to passing or neutral. */\nexport function isBlocking(verdictClass: VerdictClass): boolean {\n return conclusionForVerdictClass(verdictClass) === \"failure\";\n}\n"],"mappings":";;AAeA,MAAM,sBAA0D;CAC9D,MAAM;CAMN,gBAAgB;CAChB,SAAS;CACT,+BAA+B;CAG/B,gBAAgB;CAIhB,eAAe;CAChB;;AAGD,SAAgB,0BACd,cACc;AACd,QAAO,oBAAoB;;;AAI7B,SAAgB,qBAAqB,SAEpB;AACf,QAAO,0BAA0B,QAAQ,aAAa;;;AAIxD,SAAgB,WAAW,cAAqC;AAC9D,QAAO,0BAA0B,aAAa,KAAK"}
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
"use client";
|
|
2
|
+
require("../_virtual/_rolldown/runtime.cjs");
|
|
3
|
+
let zod = require("zod");
|
|
4
|
+
//#region src/ci/verdict.ts
|
|
5
|
+
/**
|
|
6
|
+
* The versioned, shared verdict contract (#3497) — the cohesion mechanism for
|
|
7
|
+
* the CI⇄MCP verdict loop (epic #3493). One condition's outcome on a CI run,
|
|
8
|
+
* structured so an agent can *route* it (fix / add a test / escalate) without
|
|
9
|
+
* scraping a build log. Every future condition — coverage gaps, regressions,
|
|
10
|
+
* schema drift, nudges — emits this same shape, so no condition grows its own
|
|
11
|
+
* red/green or its own remediation UX.
|
|
12
|
+
*
|
|
13
|
+
* The same payload is meant to render to the PR comment and to surface in the
|
|
14
|
+
* MCP run object; the surfacing itself is owned by #3106/#3105, so this module
|
|
15
|
+
* defines and validates the contract they consume, plus a reference renderer.
|
|
16
|
+
*/
|
|
17
|
+
/**
|
|
18
|
+
* Bump only on a *breaking* change to the shape below, so a consumer can refuse
|
|
19
|
+
* a payload it doesn't understand. Additive, backward-compatible fields do not
|
|
20
|
+
* require a bump.
|
|
21
|
+
*/
|
|
22
|
+
const VERDICT_CONTRACT_VERSION = 1;
|
|
23
|
+
/**
|
|
24
|
+
* How honest the run can be about a condition. `pass` is the only clean
|
|
25
|
+
* outcome; every other class is a non-pass the loop must route.
|
|
26
|
+
* `uncertain-conservative-flag` is the deliberate "we could not check this, so
|
|
27
|
+
* we're flagging to be safe" state — kept distinct so the tool's blindness is
|
|
28
|
+
* never dressed up as either a clean pass or a hard failure.
|
|
29
|
+
*/
|
|
30
|
+
const VerdictClass = zod.z.enum([
|
|
31
|
+
"pass",
|
|
32
|
+
"coverage-gap",
|
|
33
|
+
"finding",
|
|
34
|
+
"infra-error",
|
|
35
|
+
"setup-broken",
|
|
36
|
+
"uncertain-conservative-flag"
|
|
37
|
+
]);
|
|
38
|
+
/**
|
|
39
|
+
* The kind of action a verdict routes to. The ceiling is `auto-fix`; the floor
|
|
40
|
+
* is `notify-human` — escalate-to-human-with-context, a designed success state
|
|
41
|
+
* rather than a gap. `none` is only for a clean pass.
|
|
42
|
+
*/
|
|
43
|
+
const VerdictActionKind = zod.z.enum([
|
|
44
|
+
"auto-fix",
|
|
45
|
+
"add-test",
|
|
46
|
+
"triage",
|
|
47
|
+
"notify-human",
|
|
48
|
+
"none"
|
|
49
|
+
]);
|
|
50
|
+
/**
|
|
51
|
+
* A routable next action. `detail` always carries the human- and
|
|
52
|
+
* machine-readable specifics: the fix instruction, the test to add, or — for
|
|
53
|
+
* `notify-human` — the context handed to the person. Modeling "notify human
|
|
54
|
+
* (with context)" as a first-class value, not an absent field, is the point:
|
|
55
|
+
* the escalate-to-human floor is always well-formed, never an absence.
|
|
56
|
+
*/
|
|
57
|
+
const VerdictAction = zod.z.object({
|
|
58
|
+
kind: VerdictActionKind,
|
|
59
|
+
detail: zod.z.string()
|
|
60
|
+
});
|
|
61
|
+
/** A next step / triage action that escalates to a human, carrying context. */
|
|
62
|
+
function notifyHuman(context) {
|
|
63
|
+
return {
|
|
64
|
+
kind: "notify-human",
|
|
65
|
+
detail: context
|
|
66
|
+
};
|
|
67
|
+
}
|
|
68
|
+
/** The "nothing to do" action, for a clean pass. */
|
|
69
|
+
const NO_ACTION = {
|
|
70
|
+
kind: "none",
|
|
71
|
+
detail: ""
|
|
72
|
+
};
|
|
73
|
+
const CiVerdict = zod.z.object({
|
|
74
|
+
version: zod.z.literal(1),
|
|
75
|
+
condition: zod.z.string().min(1),
|
|
76
|
+
verdictClass: VerdictClass,
|
|
77
|
+
reason: zod.z.string().min(1),
|
|
78
|
+
nextStep: VerdictAction,
|
|
79
|
+
triageAction: VerdictAction,
|
|
80
|
+
docsUrl: zod.z.string().url().optional(),
|
|
81
|
+
suggestedMcpTools: zod.z.array(zod.z.string()).default([])
|
|
82
|
+
});
|
|
83
|
+
const ACTION_LABEL = {
|
|
84
|
+
"auto-fix": "Fix",
|
|
85
|
+
"add-test": "Add a test",
|
|
86
|
+
triage: "Triage",
|
|
87
|
+
"notify-human": "Notify a human",
|
|
88
|
+
none: "No action"
|
|
89
|
+
};
|
|
90
|
+
/**
|
|
91
|
+
* Render a verdict to Markdown for a PR comment. Intentionally presentation
|
|
92
|
+
* only: it shows the fields, it does not decide pass/fail (that mapping is the
|
|
93
|
+
* failure taxonomy, #3498). Kept alongside the contract so "the comment renders
|
|
94
|
+
* from the contract" is demonstrably true and ready for the analyzer to import.
|
|
95
|
+
*/
|
|
96
|
+
function renderVerdictMarkdown(verdict) {
|
|
97
|
+
const parts = [`**${verdict.condition}** — ${verdict.reason}`];
|
|
98
|
+
if (verdict.nextStep.kind !== "none") parts.push(`**Next step (${ACTION_LABEL[verdict.nextStep.kind]}):** ${verdict.nextStep.detail}`);
|
|
99
|
+
if (verdict.triageAction.kind !== "none") parts.push(`**Triage (${ACTION_LABEL[verdict.triageAction.kind]}):** ${verdict.triageAction.detail}`);
|
|
100
|
+
if (verdict.suggestedMcpTools.length > 0) {
|
|
101
|
+
const tools = verdict.suggestedMcpTools.map((t) => `\`${t}\``).join(", ");
|
|
102
|
+
parts.push(`**MCP tools:** ${tools}`);
|
|
103
|
+
}
|
|
104
|
+
if (verdict.docsUrl) parts.push(`[Learn more](${verdict.docsUrl})`);
|
|
105
|
+
return parts.join("\n\n");
|
|
106
|
+
}
|
|
107
|
+
//#endregion
|
|
108
|
+
exports.CiVerdict = CiVerdict;
|
|
109
|
+
exports.NO_ACTION = NO_ACTION;
|
|
110
|
+
exports.VERDICT_CONTRACT_VERSION = VERDICT_CONTRACT_VERSION;
|
|
111
|
+
exports.VerdictAction = VerdictAction;
|
|
112
|
+
exports.VerdictActionKind = VerdictActionKind;
|
|
113
|
+
exports.VerdictClass = VerdictClass;
|
|
114
|
+
exports.notifyHuman = notifyHuman;
|
|
115
|
+
exports.renderVerdictMarkdown = renderVerdictMarkdown;
|
|
116
|
+
|
|
117
|
+
//# sourceMappingURL=verdict.cjs.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"verdict.cjs","names":["z"],"sources":["../../src/ci/verdict.ts"],"sourcesContent":["import { z } from \"zod\";\n\n/**\n * The versioned, shared verdict contract (#3497) — the cohesion mechanism for\n * the CI⇄MCP verdict loop (epic #3493). One condition's outcome on a CI run,\n * structured so an agent can *route* it (fix / add a test / escalate) without\n * scraping a build log. Every future condition — coverage gaps, regressions,\n * schema drift, nudges — emits this same shape, so no condition grows its own\n * red/green or its own remediation UX.\n *\n * The same payload is meant to render to the PR comment and to surface in the\n * MCP run object; the surfacing itself is owned by #3106/#3105, so this module\n * defines and validates the contract they consume, plus a reference renderer.\n */\n\n/**\n * Bump only on a *breaking* change to the shape below, so a consumer can refuse\n * a payload it doesn't understand. Additive, backward-compatible fields do not\n * require a bump.\n */\nexport const VERDICT_CONTRACT_VERSION = 1;\n\n/**\n * How honest the run can be about a condition. `pass` is the only clean\n * outcome; every other class is a non-pass the loop must route.\n * `uncertain-conservative-flag` is the deliberate \"we could not check this, so\n * we're flagging to be safe\" state — kept distinct so the tool's blindness is\n * never dressed up as either a clean pass or a hard failure.\n */\nexport const VerdictClass = z.enum([\n \"pass\",\n \"coverage-gap\",\n \"finding\",\n \"infra-error\",\n \"setup-broken\",\n \"uncertain-conservative-flag\",\n]);\nexport type VerdictClass = z.infer<typeof VerdictClass>;\n\n/**\n * The kind of action a verdict routes to. The ceiling is `auto-fix`; the floor\n * is `notify-human` — escalate-to-human-with-context, a designed success state\n * rather than a gap. `none` is only for a clean pass.\n */\nexport const VerdictActionKind = z.enum([\n \"auto-fix\",\n \"add-test\",\n \"triage\",\n \"notify-human\",\n \"none\",\n]);\nexport type VerdictActionKind = z.infer<typeof VerdictActionKind>;\n\n/**\n * A routable next action. `detail` always carries the human- and\n * machine-readable specifics: the fix instruction, the test to add, or — for\n * `notify-human` — the context handed to the person. Modeling \"notify human\n * (with context)\" as a first-class value, not an absent field, is the point:\n * the escalate-to-human floor is always well-formed, never an absence.\n */\nexport const VerdictAction = z.object({\n kind: VerdictActionKind,\n detail: z.string(),\n});\nexport type VerdictAction = z.infer<typeof VerdictAction>;\n\n/** A next step / triage action that escalates to a human, carrying context. */\nexport function notifyHuman(context: string): VerdictAction {\n return { kind: \"notify-human\", detail: context };\n}\n\n/** The \"nothing to do\" action, for a clean pass. */\nexport const NO_ACTION: VerdictAction = { kind: \"none\", detail: \"\" };\n\nexport const CiVerdict = z.object({\n version: z.literal(VERDICT_CONTRACT_VERSION),\n /** The condition evaluated, e.g. \"untested-data-access\", \"regression-beyond-threshold\". */\n condition: z.string().min(1),\n verdictClass: VerdictClass,\n /** Plain-language why, honest about the tool's epistemic state. */\n reason: z.string().min(1),\n /** The best-available next step; `notify-human` is a valid, well-formed value. */\n nextStep: VerdictAction,\n /** The non-fix exit — triage/acknowledge, or escalate to a human. */\n triageAction: VerdictAction,\n /** Deep link to the relevant guide, when one applies. */\n docsUrl: z.string().url().optional(),\n /** MCP tools an agent should reach for to act on this verdict. */\n suggestedMcpTools: z.array(z.string()).default([]),\n});\nexport type CiVerdict = z.infer<typeof CiVerdict>;\n\nconst ACTION_LABEL: Record<VerdictActionKind, string> = {\n \"auto-fix\": \"Fix\",\n \"add-test\": \"Add a test\",\n triage: \"Triage\",\n \"notify-human\": \"Notify a human\",\n none: \"No action\",\n};\n\n/**\n * Render a verdict to Markdown for a PR comment. Intentionally presentation\n * only: it shows the fields, it does not decide pass/fail (that mapping is the\n * failure taxonomy, #3498). Kept alongside the contract so \"the comment renders\n * from the contract\" is demonstrably true and ready for the analyzer to import.\n */\nexport function renderVerdictMarkdown(verdict: CiVerdict): string {\n const parts: string[] = [`**${verdict.condition}** — ${verdict.reason}`];\n if (verdict.nextStep.kind !== \"none\") {\n parts.push(\n `**Next step (${ACTION_LABEL[verdict.nextStep.kind]}):** ${verdict.nextStep.detail}`,\n );\n }\n if (verdict.triageAction.kind !== \"none\") {\n parts.push(\n `**Triage (${ACTION_LABEL[verdict.triageAction.kind]}):** ${verdict.triageAction.detail}`,\n );\n }\n if (verdict.suggestedMcpTools.length > 0) {\n const tools = verdict.suggestedMcpTools.map((t) => `\\`${t}\\``).join(\", \");\n parts.push(`**MCP tools:** ${tools}`);\n }\n if (verdict.docsUrl) {\n parts.push(`[Learn more](${verdict.docsUrl})`);\n }\n return parts.join(\"\\n\\n\");\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAoBA,MAAa,2BAA2B;;;;;;;;AASxC,MAAa,eAAeA,IAAAA,EAAE,KAAK;CACjC;CACA;CACA;CACA;CACA;CACA;CACD,CAAC;;;;;;AAQF,MAAa,oBAAoBA,IAAAA,EAAE,KAAK;CACtC;CACA;CACA;CACA;CACA;CACD,CAAC;;;;;;;;AAUF,MAAa,gBAAgBA,IAAAA,EAAE,OAAO;CACpC,MAAM;CACN,QAAQA,IAAAA,EAAE,QAAQ;CACnB,CAAC;;AAIF,SAAgB,YAAY,SAAgC;AAC1D,QAAO;EAAE,MAAM;EAAgB,QAAQ;EAAS;;;AAIlD,MAAa,YAA2B;CAAE,MAAM;CAAQ,QAAQ;CAAI;AAEpE,MAAa,YAAYA,IAAAA,EAAE,OAAO;CAChC,SAASA,IAAAA,EAAE,QAAA,EAAiC;CAE5C,WAAWA,IAAAA,EAAE,QAAQ,CAAC,IAAI,EAAE;CAC5B,cAAc;CAEd,QAAQA,IAAAA,EAAE,QAAQ,CAAC,IAAI,EAAE;CAEzB,UAAU;CAEV,cAAc;CAEd,SAASA,IAAAA,EAAE,QAAQ,CAAC,KAAK,CAAC,UAAU;CAEpC,mBAAmBA,IAAAA,EAAE,MAAMA,IAAAA,EAAE,QAAQ,CAAC,CAAC,QAAQ,EAAE,CAAC;CACnD,CAAC;AAGF,MAAM,eAAkD;CACtD,YAAY;CACZ,YAAY;CACZ,QAAQ;CACR,gBAAgB;CAChB,MAAM;CACP;;;;;;;AAQD,SAAgB,sBAAsB,SAA4B;CAChE,MAAM,QAAkB,CAAC,KAAK,QAAQ,UAAU,OAAO,QAAQ,SAAS;AACxE,KAAI,QAAQ,SAAS,SAAS,OAC5B,OAAM,KACJ,gBAAgB,aAAa,QAAQ,SAAS,MAAM,OAAO,QAAQ,SAAS,SAC7E;AAEH,KAAI,QAAQ,aAAa,SAAS,OAChC,OAAM,KACJ,aAAa,aAAa,QAAQ,aAAa,MAAM,OAAO,QAAQ,aAAa,SAClF;AAEH,KAAI,QAAQ,kBAAkB,SAAS,GAAG;EACxC,MAAM,QAAQ,QAAQ,kBAAkB,KAAK,MAAM,KAAK,EAAE,IAAI,CAAC,KAAK,KAAK;AACzE,QAAM,KAAK,kBAAkB,QAAQ;;AAEvC,KAAI,QAAQ,QACV,OAAM,KAAK,gBAAgB,QAAQ,QAAQ,GAAG;AAEhD,QAAO,MAAM,KAAK,OAAO"}
|