devcontour-harness 0.1.0-alpha.42 → 0.1.0-alpha.45

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.
Files changed (65) hide show
  1. package/README.md +25 -2
  2. package/docs/architecture.md +38 -3
  3. package/docs/contracts.md +117 -3
  4. package/docs/release-notes/0.1.0-alpha.43.md +40 -0
  5. package/docs/release-notes/0.1.0-alpha.44.md +44 -0
  6. package/docs/release-notes/0.1.0-alpha.45.md +77 -0
  7. package/docs/upgrade.md +107 -17
  8. package/lib/contracts/cli.d.ts +115 -4
  9. package/lib/contracts/cli.js +6 -1
  10. package/lib/contracts/events.d.ts +65 -5
  11. package/lib/contracts/events.js +18 -1
  12. package/lib/contracts/execution.d.ts +76 -0
  13. package/lib/contracts/execution.js +35 -2
  14. package/lib/contracts/policy.d.ts +39 -0
  15. package/lib/contracts/policy.js +64 -0
  16. package/lib/contracts/profiles.d.ts +6 -0
  17. package/lib/contracts/published.d.ts +97 -2
  18. package/lib/contracts/report.d.ts +8 -0
  19. package/lib/contracts/report.js +7 -1
  20. package/lib/contracts/result.d.ts +93 -0
  21. package/lib/contracts/result.js +37 -1
  22. package/lib/contracts/review.d.ts +1 -1
  23. package/lib/control/harness.d.ts +29 -2
  24. package/lib/engine/engine.d.ts +54 -6
  25. package/lib/engine/engine.js +191 -24
  26. package/lib/engine/joint-runner.d.ts +2 -0
  27. package/lib/engine/joint-runner.js +13 -3
  28. package/lib/engine/result.js +7 -3
  29. package/lib/engine/runner.d.ts +8 -0
  30. package/lib/engine/runner.js +91 -3
  31. package/lib/environment/git-trust.js +3 -0
  32. package/lib/environment/isolation.d.ts +1 -1
  33. package/lib/environment/isolation.js +38 -4
  34. package/lib/environment/process.d.ts +2 -0
  35. package/lib/environment/process.js +7 -1
  36. package/lib/explain/state.js +1 -1
  37. package/lib/index.d.ts +1 -0
  38. package/lib/index.js +1 -0
  39. package/lib/integrations/connector/history.js +1 -1
  40. package/lib/integrations/connector/summary.js +2 -1
  41. package/lib/profiles/resolve.d.ts +6 -0
  42. package/lib/projections/attempt.d.ts +4 -2
  43. package/lib/projections/attempt.js +14 -1
  44. package/lib/report/compute.js +7 -3
  45. package/lib/report/document.js +1 -1
  46. package/lib/storage/document.d.ts +28 -2
  47. package/lib/testing/store-contract.d.ts +8 -2
  48. package/lib/testing/store-contract.js +56 -1
  49. package/lib/verification/acceptance.d.ts +12 -0
  50. package/lib/verification/acceptance.js +62 -7
  51. package/lib/verification/applicability.d.ts +134 -0
  52. package/lib/verification/applicability.js +373 -0
  53. package/lib/verification/gates.d.ts +6 -0
  54. package/lib/verification/joint.d.ts +179 -1
  55. package/lib/verification/joint.js +23 -3
  56. package/lib/verification/proof.d.ts +18 -4
  57. package/lib/verification/proof.js +52 -9
  58. package/package.json +1 -1
  59. package/schemas/execution-document.schema.json +77 -1
  60. package/schemas/execution-policy.schema.json +38 -0
  61. package/schemas/joint-verification.schema.json +4 -0
  62. package/schemas/result-envelope.schema.json +138 -2
  63. package/schemas/run-event.schema.json +100 -0
  64. package/schemas/run-result.schema.json +138 -2
  65. package/schemas/value-report.schema.json +20 -0
@@ -0,0 +1,134 @@
1
+ import { type ExecutionPolicy, type ContractDocument, type GateApplicability, type GatePolicy, type WorkOrder } from '../contracts/index.ts';
2
+ /**
3
+ * Применимость gate с `when.paths`. Решение принимает controller по
4
+ * настоящему diff фазы из Git, а не по заявлению исполнителя. Правило
5
+ * консервативное: всё, в чём нет уверенности, исполняет gate.
6
+ */
7
+ /** Изменённые пути фазы: объединение diff сравненных пар коммитов. */
8
+ export interface ChangedPaths {
9
+ ranges: {
10
+ from: string;
11
+ to: string;
12
+ }[];
13
+ /** Отсортированные уникальные пути; при `complete: false` — неполны. */
14
+ files: string[];
15
+ /** Diff прочитан целиком и не превысил предел. */
16
+ complete: boolean;
17
+ /** Почему diff неполон. */
18
+ problem?: string;
19
+ }
20
+ /**
21
+ * Регулярное выражение шаблона `when.paths`. `**` целым сегментом — любое
22
+ * число сегментов (и ни одного), `*` — любые символы внутри сегмента, `?` —
23
+ * один символ сегмента, `{a,b}` — варианты. Шаблон задевает и всё внутри
24
+ * совпавшего каталога: `src/ui` и `src/ui/` задевают `src/ui/a.ts`.
25
+ */
26
+ export declare function gatePathRegExp(pattern: string): RegExp;
27
+ /**
28
+ * Пути, которые задевает хотя бы один шаблон: совпадение glob или путь —
29
+ * каталог-предок буквального префикса шаблона (`vendor` для `vendor/lib/**`:
30
+ * файл или подмодуль на месте каталога шаблона).
31
+ */
32
+ export declare function matchingPaths(patterns: readonly string[], files: readonly string[]): string[];
33
+ /**
34
+ * Изменённые пути объединения пар `from..to` (`git diff --no-renames
35
+ * --name-only`: переименование — оба пути; удаление, смена режима и
36
+ * подмодуль — их пути). Ошибка Git или больше `gateApplicabilityLimits.changed`
37
+ * путей — `complete: false`, и gate исполняется.
38
+ */
39
+ export declare function changedPaths(cwd: string, ranges: {
40
+ from: string;
41
+ to: string;
42
+ }[]): Promise<ChangedPaths>;
43
+ /**
44
+ * Неявный вход gate, задетый изменением, или undefined: защищённые пути
45
+ * репозитория, каталог проекта harness, манифесты и lockfiles, файлы и
46
+ * каталоги, названные в команде gate.
47
+ */
48
+ export declare function implicitInput(repo: {
49
+ protectedPaths: readonly string[];
50
+ }, gate: Pick<GatePolicy, 'command' | 'cwd'>, files: readonly string[]): string | undefined;
51
+ /**
52
+ * Основание исполнения условного gate: его определение (`gateDigest`),
53
+ * описания его ресурсов, определения и ресурсы его предпосылок
54
+ * (`gatePrerequisites`, транзитивно), окружение, lifecycle, подготовка, хранилище
55
+ * зависимостей и toolchain репозитория, изоляция и версия harness. Зелёный
56
+ * SHA gate засчитывается только под тем же основанием: смена любого из них
57
+ * исполняет gate заново.
58
+ */
59
+ export declare function gateBasis(policy: Pick<ExecutionPolicy, 'resources' | 'environment' | 'lifecycle' | 'isolation'>, repo: Pick<ExecutionPolicy['repositories'][number], 'gates' | 'environment' | 'lifecycle' | 'prepare' | 'dependencyStore' | 'toolchain'>, gate: GatePolicy, harnessVersion: string): string;
60
+ /** Решение по одному gate с `when`: исполнять (с причиной) или нет (с записью). */
61
+ export type PathDecision = {
62
+ applies: true;
63
+ reason: string;
64
+ } | {
65
+ applies: false;
66
+ record: GateApplicability;
67
+ };
68
+ /** Применимость gate с `when` по diff (без правил области задачи). */
69
+ export declare function pathApplicability(repo: {
70
+ protectedPaths: readonly string[];
71
+ }, gate: GatePolicy, changed: ChangedPaths): PathDecision;
72
+ /**
73
+ * Gates, которые не бывают неприменимыми у поручения: источник требований,
74
+ * gates его требований и gates договоров проверки (свойства, эталоны,
75
+ * обязательства). Их доказательство — только исполнение.
76
+ */
77
+ export declare function proofGates(order: Pick<WorkOrder, 'requirements' | 'properties'>, contracts: readonly ContractDocument[]): Set<string>;
78
+ export interface GateDecisionInput {
79
+ repo: {
80
+ gates: GatePolicy[];
81
+ protectedPaths: readonly string[];
82
+ };
83
+ /** Область фазы в порядке исполнения. */
84
+ scope: GatePolicy[];
85
+ /**
86
+ * Diff фазы условного gate от его последнего зелёного SHA (integration
87
+ * принятой попытки под тем же основанием gate, предок базы попытки) до
88
+ * SHA фазы; undefined — такого SHA нет, и gate исполняется.
89
+ */
90
+ changedFor(gate: GatePolicy): ChangedPaths | undefined;
91
+ /** `proofGates` поручения. */
92
+ proof: ReadonlySet<string>;
93
+ }
94
+ export interface GateDecision {
95
+ gate: GatePolicy;
96
+ run: boolean;
97
+ reason: string;
98
+ record?: GateApplicability;
99
+ }
100
+ /**
101
+ * Решения по области фазы. Gate без `when` исполняется всегда. Условный
102
+ * исполняется, если: он доказывает требование или договор; среди предков
103
+ * базы нет его зелёного SHA под тем же основанием (`changedFor`); diff
104
+ * неизвестен, пуст или задевает его путь или неявный вход; он — предпосылка
105
+ * (`gatePrerequisites`: `dependsOn` или более ранний check gate) исполняемого
106
+ * gate области. Иначе — запись `not-applicable`.
107
+ */
108
+ export declare function gateDecisions(input: GateDecisionInput): GateDecision[];
109
+ /**
110
+ * Почему запись `not-applicable` не закрывает обязательный gate, или
111
+ * undefined. Закрывает только обычный gate с `when` под тем же определением,
112
+ * не доказательство требования или договора и не предпосылку исполненного
113
+ * gate той же фазы.
114
+ */
115
+ export declare function notApplicableProblem(input: {
116
+ gates: readonly GatePolicy[];
117
+ gate: string;
118
+ record: {
119
+ notApplicable?: GateApplicability | undefined;
120
+ };
121
+ proof: ReadonlySet<string>;
122
+ /** Gates той же фазы с решающей записью исполнения. */
123
+ ran: readonly string[];
124
+ }): string | undefined;
125
+ /**
126
+ * Объединённый diff набора для `uncoveredGates`: от зелёного SHA каждой
127
+ * записи неприменимости фазы интеграции (`notApplicable.ranges[0].from`) до
128
+ * итогового SHA репозитория. Хосту не нужно собирать пары самому.
129
+ */
130
+ export declare function coverageChanges(cwd: string, evidence: readonly {
131
+ kind: string;
132
+ phase: string;
133
+ notApplicable?: GateApplicability | undefined;
134
+ }[], finalSha: string): Promise<ChangedPaths>;
@@ -0,0 +1,373 @@
1
+ import { existsSync } from 'node:fs';
2
+ import { posix, resolve } from 'node:path';
3
+ import { HARNESS_PROJECT_DIR, digestOf, gateApplicabilityLimits, gateDigest, sha256, } from "../contracts/index.js";
4
+ import { gitRawOutput } from "../environment/process.js";
5
+ import { gatePrerequisites } from "./gate-scope.js";
6
+ import { REQUIREMENT_GATE } from "./requirements.js";
7
+ const globCache = new Map();
8
+ /**
9
+ * Регулярное выражение шаблона `when.paths`. `**` целым сегментом — любое
10
+ * число сегментов (и ни одного), `*` — любые символы внутри сегмента, `?` —
11
+ * один символ сегмента, `{a,b}` — варианты. Шаблон задевает и всё внутри
12
+ * совпавшего каталога: `src/ui` и `src/ui/` задевают `src/ui/a.ts`.
13
+ */
14
+ export function gatePathRegExp(pattern) {
15
+ const cached = globCache.get(pattern);
16
+ if (cached)
17
+ return cached;
18
+ const normal = pattern.normalize('NFC');
19
+ const trimmed = normal.endsWith('/') ? normal.slice(0, -1) : normal;
20
+ // `X/**` задевает и сам путь `X` (подмодуль, файл вместо каталога).
21
+ const body = trimmed.endsWith('/**') ? trimmed.slice(0, -3) : trimmed;
22
+ let re = '';
23
+ for (let i = 0; i < body.length; i++) {
24
+ const c = body[i];
25
+ const segmentStart = i === 0 || body[i - 1] === '/';
26
+ if (c === '*' && body[i + 1] === '*') {
27
+ const segmentEnd = i + 2 === body.length || body[i + 2] === '/';
28
+ if (segmentStart && segmentEnd) {
29
+ if (i + 2 === body.length)
30
+ re += '.*';
31
+ else {
32
+ re += '(?:.*/)?';
33
+ i += 2;
34
+ continue;
35
+ }
36
+ i += 1;
37
+ continue;
38
+ }
39
+ re += '[^/]*';
40
+ i += 1;
41
+ }
42
+ else if (c === '*')
43
+ re += '[^/]*';
44
+ else if (c === '?')
45
+ re += '[^/]';
46
+ else if (c === '{')
47
+ re += '(?:';
48
+ else if (c === '}')
49
+ re += ')';
50
+ else if (c === ',' && openBrace(body, i))
51
+ re += '|';
52
+ else
53
+ re += c.replace(/[.+^$()|\\]/g, '\\$&');
54
+ }
55
+ // Без учёта регистра и в NFC: лишнее совпадение только чаще исполняет gate.
56
+ const out = new RegExp('^(?:' + re + ')(?:/.*)?$', 'si');
57
+ globCache.set(pattern, out);
58
+ return out;
59
+ }
60
+ const openBrace = (body, at) => body.lastIndexOf('{', at) > body.lastIndexOf('}', at);
61
+ /** Буквальный префикс шаблона до первого glob-символа, по целым сегментам. */
62
+ const literalPrefix = (pattern) => {
63
+ const normal = pattern.normalize('NFC').toLowerCase();
64
+ const glob = normal.search(/[*?{]/);
65
+ if (glob < 0)
66
+ return normal.replace(/\/$/, '');
67
+ return normal.slice(0, normal.lastIndexOf('/', glob) + 1).replace(/\/$/, '');
68
+ };
69
+ /**
70
+ * Пути, которые задевает хотя бы один шаблон: совпадение glob или путь —
71
+ * каталог-предок буквального префикса шаблона (`vendor` для `vendor/lib/**`:
72
+ * файл или подмодуль на месте каталога шаблона).
73
+ */
74
+ export function matchingPaths(patterns, files) {
75
+ const res = patterns.map(gatePathRegExp);
76
+ const prefixes = patterns.map(literalPrefix).filter(Boolean);
77
+ const segmented = patterns.map(patternSegments);
78
+ return files.filter((f) => {
79
+ const path = f.normalize('NFC');
80
+ if (res.some((re) => re.test(path)))
81
+ return true;
82
+ const lower = path.toLowerCase();
83
+ if (prefixes.some((p) => p === lower || p.startsWith(lower + '/')))
84
+ return true;
85
+ const parts = path.split('/');
86
+ return segmented.some((segments) => coversPrefix(segments, parts));
87
+ });
88
+ }
89
+ /** Сегменты шаблона по `/` вне `{}`. */
90
+ function patternSegments(pattern) {
91
+ const body = pattern.normalize('NFC').replace(/\/$/, '');
92
+ const out = [];
93
+ let depth = 0;
94
+ let current = '';
95
+ for (const c of body) {
96
+ if (c === '{')
97
+ depth++;
98
+ if (c === '}')
99
+ depth--;
100
+ if (c === '/' && depth === 0) {
101
+ out.push(current);
102
+ current = '';
103
+ }
104
+ else
105
+ current += c;
106
+ }
107
+ out.push(current);
108
+ return out;
109
+ }
110
+ /**
111
+ * Изменённый путь — каталог (подмодуль, ссылка), внутри которого шаблон
112
+ * может что-то задеть: его сегменты совпадают с первыми сегментами шаблона
113
+ * (`packages/ui` для `packages/*\/src/**`); до `**` — не дальше.
114
+ */
115
+ function coversPrefix(segments, parts) {
116
+ if (parts.length >= segments.length)
117
+ return false;
118
+ for (let i = 0; i < parts.length; i++) {
119
+ // Под `**` любой путь мог бы быть каталогом: подмодули и ссылки там
120
+ // называют в `when.paths` явно (иначе любой файл исполнял бы gate).
121
+ if (segments[i] === '**')
122
+ return false;
123
+ if (segments[i].includes('/'))
124
+ return true;
125
+ if (!gatePathRegExp(segments[i]).test(parts[i]))
126
+ return false;
127
+ }
128
+ return true;
129
+ }
130
+ /**
131
+ * Изменённые пути объединения пар `from..to` (`git diff --no-renames
132
+ * --name-only`: переименование — оба пути; удаление, смена режима и
133
+ * подмодуль — их пути). Ошибка Git или больше `gateApplicabilityLimits.changed`
134
+ * путей — `complete: false`, и gate исполняется.
135
+ */
136
+ export async function changedPaths(cwd, ranges) {
137
+ const files = new Set();
138
+ try {
139
+ // Замены объектов и grafts подменяют историю для git: такой diff не
140
+ // доказывает ничего, и условные gates исполняются.
141
+ const replaced = await gitRawOutput(cwd, 'for-each-ref', '--count=1', 'refs/replace/');
142
+ const common = (await gitRawOutput(cwd, 'rev-parse', '--git-common-dir')).trim();
143
+ if (replaced.trim() || existsSync(resolve(cwd, common, 'info', 'grafts')))
144
+ return {
145
+ ranges,
146
+ files: [],
147
+ complete: false,
148
+ problem: 'в репозитории есть refs/replace или info/grafts',
149
+ };
150
+ for (const { from, to } of ranges) {
151
+ // Подмодули — всегда (`ignore` из .gitmodules пишет исполнитель),
152
+ // без относительных путей и textconv.
153
+ const text = await gitRawOutput(cwd, 'diff', '--no-renames', '--no-ext-diff', '--no-textconv', '--no-relative', '--ignore-submodules=none', '--name-only', '-z', from, to);
154
+ for (const f of text.split('\0'))
155
+ if (f)
156
+ files.add(f);
157
+ if (files.size > gateApplicabilityLimits.changed)
158
+ return {
159
+ ranges,
160
+ files: [...files].sort(),
161
+ complete: false,
162
+ problem: `изменено больше ${gateApplicabilityLimits.changed} путей`,
163
+ };
164
+ }
165
+ }
166
+ catch (error) {
167
+ return {
168
+ ranges,
169
+ files: [...files].sort(),
170
+ complete: false,
171
+ problem: 'git diff: ' + (error instanceof Error ? error.message : String(error)).slice(0, 300),
172
+ };
173
+ }
174
+ return { ranges, files: [...files].sort(), complete: true };
175
+ }
176
+ /**
177
+ * Манифесты, lockfiles и версии инструментов в любом каталоге: их смена
178
+ * меняет то, что ставится и чем собирается, — любой условный gate исполняется.
179
+ */
180
+ const installInputs = /(^|\/)(package\.json|package-lock\.json|npm-shrinkwrap\.json|pnpm-lock\.yaml|pnpm-workspace\.yaml|yarn\.lock|\.yarnrc\.yml|bun\.lockb?|\.npmrc|\.pnpmfile\.cjs|\.nvmrc|\.node-version|\.tool-versions|Cargo\.toml|Cargo\.lock|go\.mod|go\.sum|go\.work|go\.work\.sum|pyproject\.toml|poetry\.lock|uv\.lock|Pipfile|Pipfile\.lock|requirements[^/]*\.txt|Gemfile|Gemfile\.lock|composer\.json|composer\.lock|\.gitattributes|\.gitmodules|\.lfsconfig)$/i;
181
+ const fold = (path) => path.normalize('NFC').toLowerCase();
182
+ /** Путь внутри префикса (без учёта регистра, NFC): лишнее совпадение только чаще исполняет gate. */
183
+ const under = (raw, rawPrefix) => {
184
+ const path = fold(raw);
185
+ const prefix = fold(rawPrefix);
186
+ return (prefix === '.' ||
187
+ prefix === '' ||
188
+ path === prefix ||
189
+ path === prefix.replace(/\/$/, '') ||
190
+ path.startsWith(prefix.endsWith('/') ? prefix : prefix + '/'));
191
+ };
192
+ /** Пути в argv gate, относительные корню репозитория (с учётом `cwd`). */
193
+ function commandPaths(gate) {
194
+ const out = new Set();
195
+ for (const raw of gate.command) {
196
+ for (const arg of [raw, raw.includes('=') ? raw.slice(raw.indexOf('=') + 1) : '']) {
197
+ if (!arg || arg.startsWith('-') || posix.isAbsolute(arg) || !/[/.]/.test(arg))
198
+ continue;
199
+ if (/[\s$`|&;<>*?{}]/.test(arg))
200
+ continue;
201
+ const path = posix.normalize(posix.join(gate.cwd ?? '.', arg));
202
+ if (path === '.' || path.startsWith('..'))
203
+ continue;
204
+ out.add(path.replace(/\/$/, ''));
205
+ }
206
+ }
207
+ return [...out];
208
+ }
209
+ /**
210
+ * Неявный вход gate, задетый изменением, или undefined: защищённые пути
211
+ * репозитория, каталог проекта harness, манифесты и lockfiles, файлы и
212
+ * каталоги, названные в команде gate.
213
+ */
214
+ export function implicitInput(repo, gate, files) {
215
+ const named = commandPaths(gate);
216
+ return files.find((f) => repo.protectedPaths.some((p) => under(f, p)) ||
217
+ under(f, HARNESS_PROJECT_DIR + '/') ||
218
+ installInputs.test(f) ||
219
+ named.some((n) => under(f, n)));
220
+ }
221
+ /**
222
+ * Основание исполнения условного gate: его определение (`gateDigest`),
223
+ * описания его ресурсов, определения и ресурсы его предпосылок
224
+ * (`gatePrerequisites`, транзитивно), окружение, lifecycle, подготовка, хранилище
225
+ * зависимостей и toolchain репозитория, изоляция и версия harness. Зелёный
226
+ * SHA gate засчитывается только под тем же основанием: смена любого из них
227
+ * исполняет gate заново.
228
+ */
229
+ export function gateBasis(policy, repo, gate, harnessVersion) {
230
+ const resources = (g) => policy.resources.filter((r) => g.resources?.includes(r.id));
231
+ // Предпосылки (`dependsOn` или, в режиме порядка массива, более ранние
232
+ // check gates) исполняются перед gate в том же дереве: их вывод — его вход.
233
+ const prerequisites = gatePrerequisites(repo.gates, gate.id)
234
+ .sort()
235
+ .map((id) => repo.gates.find((g) => g.id === id))
236
+ .map((g) => ({ id: g.id, gate: gateDigest(g), resources: resources(g) }));
237
+ return digestOf({
238
+ gate: gateDigest(gate),
239
+ resources: resources(gate),
240
+ prerequisites,
241
+ environment: [policy.environment, repo.environment],
242
+ lifecycle: repo.lifecycle ?? policy.lifecycle,
243
+ prepare: repo.prepare,
244
+ dependencyStore: repo.dependencyStore,
245
+ toolchain: repo.toolchain,
246
+ isolation: policy.isolation,
247
+ harness: harnessVersion,
248
+ });
249
+ }
250
+ /** Применимость gate с `when` по diff (без правил области задачи). */
251
+ export function pathApplicability(repo, gate, changed) {
252
+ if (!gate.when)
253
+ return { applies: true, reason: 'gate без when' };
254
+ if (!changed.complete)
255
+ return { applies: true, reason: 'diff неизвестен: ' + changed.problem };
256
+ if (!changed.files.length)
257
+ return { applies: true, reason: 'изменений нет' };
258
+ const matched = matchingPaths(gate.when.paths, changed.files);
259
+ if (matched.length)
260
+ return { applies: true, reason: 'изменён путь gate: ' + matched[0] };
261
+ const input = implicitInput(repo, gate, changed.files);
262
+ if (input)
263
+ return { applies: true, reason: 'изменён неявный вход gate: ' + input };
264
+ return {
265
+ applies: false,
266
+ record: {
267
+ gateDigest: gateDigest(gate),
268
+ patterns: [...gate.when.paths],
269
+ ranges: changed.ranges.map(({ from, to }) => ({ from, to })),
270
+ count: changed.files.length,
271
+ // Длинный путь (их пишет исполнитель) не перечисляется: он в `count` и `pathsDigest`.
272
+ files: changed.files.filter((f) => f.length <= 1000).slice(0, gateApplicabilityLimits.files),
273
+ pathsDigest: sha256(changed.files.join('\0')),
274
+ },
275
+ };
276
+ }
277
+ /**
278
+ * Gates, которые не бывают неприменимыми у поручения: источник требований,
279
+ * gates его требований и gates договоров проверки (свойства, эталоны,
280
+ * обязательства). Их доказательство — только исполнение.
281
+ */
282
+ export function proofGates(order, contracts) {
283
+ const out = new Set([REQUIREMENT_GATE]);
284
+ for (const r of order.requirements ?? [])
285
+ out.add(r.gate);
286
+ for (const c of contracts) {
287
+ if (!c.checks)
288
+ continue;
289
+ out.add(c.checks.gate);
290
+ for (const o of c.checks.obligations)
291
+ for (const g of o.gates ?? [])
292
+ out.add(g);
293
+ }
294
+ return out;
295
+ }
296
+ /**
297
+ * Решения по области фазы. Gate без `when` исполняется всегда. Условный
298
+ * исполняется, если: он доказывает требование или договор; среди предков
299
+ * базы нет его зелёного SHA под тем же основанием (`changedFor`); diff
300
+ * неизвестен, пуст или задевает его путь или неявный вход; он — предпосылка
301
+ * (`gatePrerequisites`: `dependsOn` или более ранний check gate) исполняемого
302
+ * gate области. Иначе — запись `not-applicable`.
303
+ */
304
+ export function gateDecisions(input) {
305
+ const decisions = input.scope.map((gate) => {
306
+ if (!gate.when)
307
+ return { gate, run: true, reason: 'gate без when' };
308
+ if (input.proof.has(gate.id))
309
+ return { gate, run: true, reason: 'gate доказывает требование или договор поручения' };
310
+ const changed = input.changedFor(gate);
311
+ if (!changed)
312
+ return {
313
+ gate,
314
+ run: true,
315
+ reason: 'нет зелёного SHA gate под тем же основанием среди предков базы',
316
+ };
317
+ const path = pathApplicability(input.repo, gate, changed);
318
+ return path.applies
319
+ ? { gate, run: true, reason: path.reason }
320
+ : { gate, run: false, reason: 'diff не задел пути gate', record: path.record };
321
+ });
322
+ const ids = new Set(input.scope.map((g) => g.id));
323
+ for (let grew = true; grew;) {
324
+ grew = false;
325
+ for (const d of decisions) {
326
+ if (!d.run)
327
+ continue;
328
+ for (const pre of gatePrerequisites(input.repo.gates, d.gate.id)) {
329
+ const dep = decisions.find((x) => x.gate.id === pre);
330
+ if (!ids.has(pre) || !dep || dep.run)
331
+ continue;
332
+ dep.run = true;
333
+ dep.reason = 'предпосылка исполняемого gate ' + d.gate.id;
334
+ delete dep.record;
335
+ grew = true;
336
+ }
337
+ }
338
+ }
339
+ return decisions;
340
+ }
341
+ /**
342
+ * Почему запись `not-applicable` не закрывает обязательный gate, или
343
+ * undefined. Закрывает только обычный gate с `when` под тем же определением,
344
+ * не доказательство требования или договора и не предпосылку исполненного
345
+ * gate той же фазы.
346
+ */
347
+ export function notApplicableProblem(input) {
348
+ const gate = input.gates.find((g) => g.id === input.gate);
349
+ if (!gate?.when)
350
+ return `gate ${input.gate} без when не бывает неприменимым`;
351
+ if (input.proof.has(gate.id))
352
+ return `gate ${gate.id} доказывает требование или договор: нужен PASS`;
353
+ if (!input.record.notApplicable || input.record.notApplicable.gateDigest !== gateDigest(gate))
354
+ return `решение о неприменимости ${gate.id} принято под другим определением gate`;
355
+ const dependent = input.ran.find((id) => input.gates.some((g) => g.id === id) &&
356
+ gatePrerequisites([...input.gates], id).includes(gate.id));
357
+ if (dependent)
358
+ return `gate ${gate.id} — предпосылка исполненного ${dependent}: нужен PASS`;
359
+ return undefined;
360
+ }
361
+ /**
362
+ * Объединённый diff набора для `uncoveredGates`: от зелёного SHA каждой
363
+ * записи неприменимости фазы интеграции (`notApplicable.ranges[0].from`) до
364
+ * итогового SHA репозитория. Хосту не нужно собирать пары самому.
365
+ */
366
+ export function coverageChanges(cwd, evidence, finalSha) {
367
+ const anchors = [
368
+ ...new Set(evidence
369
+ .filter((e) => e.kind === 'not-applicable' && e.phase === 'integration')
370
+ .flatMap((e) => (e.notApplicable?.ranges[0] ? [e.notApplicable.ranges[0].from] : []))),
371
+ ];
372
+ return changedPaths(cwd, anchors.map((from) => ({ from, to: finalSha })));
373
+ }
@@ -338,6 +338,9 @@ export declare function writerDependencyGates(gates: readonly GatePolicy[]): ({
338
338
  command: string[];
339
339
  timeoutMs: number;
340
340
  artifacts?: string[] | undefined;
341
+ when?: {
342
+ paths: string[];
343
+ } | undefined;
341
344
  property?: {
342
345
  path?: string | undefined;
343
346
  } | undefined;
@@ -354,6 +357,9 @@ export declare function writerDependencyGates(gates: readonly GatePolicy[]): ({
354
357
  path: string;
355
358
  } | undefined;
356
359
  artifacts?: string[] | undefined;
360
+ when?: {
361
+ paths: string[];
362
+ } | undefined;
357
363
  property?: {
358
364
  path?: string | undefined;
359
365
  } | undefined;