devcontour-harness 0.0.0-stage → 0.1.0-alpha.6

package/lib/verification/dependencies.d.ts

@@ -0,0 +1,66 @@
+import type { ExecutionPolicy } from '../contracts/index.ts';
+import type { AttemptState } from '../contracts/index.ts';
+type Repo = ExecutionPolicy['repositories'][number];
+export type DependencySnapshot = NonNullable<AttemptState['dependencies']>[number];
+export type DependencyFreshness = NonNullable<AttemptState['dependencyFreshness']>[number];
+/** Репозитории политики с разрешёнными путями checkout. */
+export interface Repositories {
+    repo(id: string): Repo;
+    path(repo: Repo): string;
+}
+/** Зависимости компонентов в топологическом порядке, транзитивно. */
+export declare function dependencyOrder(repos: Repositories, ids: string[]): string[];
+export declare function artifactDigest(root: string, path: string): Promise<string>;
+/**
+ * Снимок зависимостей компонента в топологическом порядке: рабочее дерево
+ * целевой ветки каждой зависимости, её `dependencyBuild` и digests
+ * `dependencyArtifacts`.
+ *
+ * `overrides` подставляет зависимость уже существующим деревом (проверка
+ * потребителя: компонент поручения — его интегрированный результат).
+ * Подстановка идёт до сборки: промежуточные зависимости собираются уже против
+ * неё. `predecessors` — принятые результаты поручений, от которых зависит
+ * работа: их SHA обязан быть в снимке. Каждое созданное здесь рабочее дерево
+ * принадлежит снимку с момента создания: при отказе на любом шаге созданные
+ * деревья убираются, и отказ очистки не скрывается.
+ */
+export declare function snapshotDependencies(input: {
+    repos: Repositories;
+    repositoryId: string;
+    dir: string;
+    artifacts: string;
+    runId: string;
+    policy: ExecutionPolicy;
+    environment: NodeJS.ProcessEnv;
+    signal: AbortSignal;
+    predecessors?: {
+        repositoryId: string;
+        resultSha: string;
+    }[];
+    overrides?: Map<string, {
+        path: string;
+        sha: string;
+    }>;
+}): Promise<{
+    repositoryId: string;
+    sha: string;
+    tree: string;
+    path: string;
+    artifacts: {
+        path: string;
+        digest: string;
+    }[];
+}[]>;
+/** Убирает рабочие деревья снимков; возвращает отказы, а не скрывает их. */
+export declare function removeSnapshots(repos: Repositories, snapshots: DependencySnapshot[]): Promise<string[]>;
+/** Закреплённый снимок не изменён: HEAD, отслеживаемые файлы и artifacts. */
+export declare function assertDependencies(snapshots: DependencySnapshot[]): Promise<void>;
+/**
+ * Свежесть снимка на момент окончания проверки: голова целевой ветки каждой
+ * зависимости и совпадает ли она со снимком. Параллельная работа законно
+ * двигает ветки зависимостей, поэтому сдвиг не отклоняет результат, а
+ * фиксируется в попытке и результате; сочетание версий проверяет совместная
+ * проверка по закреплённому манифесту.
+ */
+export declare function dependencyFreshness(repos: Repositories, snapshots: Pick<DependencySnapshot, 'repositoryId' | 'sha'>[]): Promise<DependencyFreshness[]>;
+export {};

package/lib/verification/dependencies.js

@@ -0,0 +1,144 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, realpath, writeFile } from 'node:fs/promises';
+import { join, sep } from 'node:path';
+import { git } from "../environment/process.js";
+import { executionEnvironment, runSteps } from "../environment/lifecycle.js";
+/** Зависимости компонентов в топологическом порядке, транзитивно. */
+export function dependencyOrder(repos, ids) {
+    const ordered = [];
+    const active = new Set();
+    const visit = (id) => {
+        if (ordered.includes(id))
+            return;
+        if (active.has(id))
+            throw new Error('Цикл зависимостей компонентов');
+        active.add(id);
+        for (const parent of repos.repo(id).dependsOn)
+            visit(parent);
+        active.delete(id);
+        ordered.push(id);
+    };
+    ids.forEach(visit);
+    return ordered;
+}
+export async function artifactDigest(root, path) {
+    const full = await realpath(join(root, path));
+    if (!full.startsWith((await realpath(root)) + sep))
+        throw new Error('Artifact выходит из компонента');
+    return createHash('sha256')
+        .update(await readFile(full))
+        .digest('hex');
+}
+/**
+ * Снимок зависимостей компонента в топологическом порядке: рабочее дерево
+ * целевой ветки каждой зависимости, её `dependencyBuild` и digests
+ * `dependencyArtifacts`.
+ *
+ * `overrides` подставляет зависимость уже существующим деревом (проверка
+ * потребителя: компонент поручения — его интегрированный результат).
+ * Подстановка идёт до сборки: промежуточные зависимости собираются уже против
+ * неё. `predecessors` — принятые результаты поручений, от которых зависит
+ * работа: их SHA обязан быть в снимке. Каждое созданное здесь рабочее дерево
+ * принадлежит снимку с момента создания: при отказе на любом шаге созданные
+ * деревья убираются, и отказ очистки не скрывается.
+ */
+export async function snapshotDependencies(input) {
+    const { repos, signal } = input;
+    const ids = dependencyOrder(repos, repos.repo(input.repositoryId).dependsOn);
+    const snapshots = [];
+    const created = [];
+    await mkdir(input.dir, { recursive: true });
+    try {
+        for (const id of ids) {
+            signal.throwIfAborted();
+            const repo = repos.repo(id);
+            const override = input.overrides?.get(id);
+            if (override) {
+                snapshots.push({
+                    repositoryId: id,
+                    sha: override.sha,
+                    tree: await git(override.path, 'rev-parse', 'HEAD^{tree}'),
+                    path: override.path,
+                    artifacts: [],
+                });
+                continue;
+            }
+            const checkout = repos.path(repo);
+            const sha = await git(checkout, 'rev-parse', repo.targetRef);
+            for (const predecessor of (input.predecessors ?? []).filter((p) => p.repositoryId === id))
+                await git(checkout, 'merge-base', '--is-ancestor', predecessor.resultSha, sha).catch(() => {
+                    throw new Error(`Принятый результат зависимости ${id} (${predecessor.resultSha}) отсутствует в ${repo.targetRef}`);
+                });
+            const path = join(input.dir, id);
+            await git(checkout, 'worktree', 'add', '--detach', path, sha);
+            const snapshot = {
+                repositoryId: id,
+                sha,
+                tree: await git(path, 'rev-parse', 'HEAD^{tree}'),
+                path,
+                artifacts: [],
+            };
+            created.push(snapshot);
+            snapshots.push(snapshot);
+        }
+        const paths = Object.fromEntries(snapshots.map((s) => [s.repositoryId, s.path]));
+        for (const snapshot of snapshots) {
+            const repo = repos.repo(snapshot.repositoryId);
+            const execution = executionEnvironment([input.policy.environment, repo.environment], {
+                DEVCONTOUR_RUN_ID: input.runId,
+                DEVCONTOUR_COMPONENTS_JSON: JSON.stringify(paths),
+            }, input.environment);
+            await runSteps(repo.dependencyBuild, snapshot.path, join(input.artifacts, 'dependency-build', repo.id), execution, signal);
+            for (const path of repo.dependencyArtifacts)
+                snapshot.artifacts.push({ path, digest: await artifactDigest(snapshot.path, path) });
+        }
+        await assertDependencies(snapshots);
+        await writeFile(join(input.dir, 'manifest.json'), JSON.stringify(snapshots, null, 2));
+        return snapshots;
+    }
+    catch (error) {
+        const failures = await removeSnapshots(repos, created);
+        if (failures.length)
+            throw new Error(`${error instanceof Error ? error.message : String(error)}; не удалось убрать снимки: ${failures.join('; ')}`, { cause: error });
+        throw error;
+    }
+}
+/** Убирает рабочие деревья снимков; возвращает отказы, а не скрывает их. */
+export async function removeSnapshots(repos, snapshots) {
+    const failures = [];
+    for (const snapshot of snapshots)
+        await git(repos.path(repos.repo(snapshot.repositoryId)), 'worktree', 'remove', '--force', snapshot.path).catch((e) => failures.push(`${snapshot.repositoryId}: ${e instanceof Error ? e.message : String(e)}`));
+    return failures;
+}
+/** Закреплённый снимок не изменён: HEAD, отслеживаемые файлы и artifacts. */
+export async function assertDependencies(snapshots) {
+    for (const snapshot of snapshots) {
+        if ((await git(snapshot.path, 'rev-parse', 'HEAD')) !== snapshot.sha ||
+            (await git(snapshot.path, 'status', '--porcelain', '--untracked-files=no')))
+            throw new Error('Изменён закреплённый dependency snapshot: ' + snapshot.repositoryId);
+        for (const artifact of snapshot.artifacts)
+            if ((await artifactDigest(snapshot.path, artifact.path)) !== artifact.digest)
+                throw new Error('Изменён artifact зависимости: ' + snapshot.repositoryId + '/' + artifact.path);
+    }
+}
+/**
+ * Свежесть снимка на момент окончания проверки: голова целевой ветки каждой
+ * зависимости и совпадает ли она со снимком. Параллельная работа законно
+ * двигает ветки зависимостей, поэтому сдвиг не отклоняет результат, а
+ * фиксируется в попытке и результате; сочетание версий проверяет совместная
+ * проверка по закреплённому манифесту.
+ */
+export async function dependencyFreshness(repos, snapshots) {
+    const result = [];
+    for (const snapshot of snapshots) {
+        const repo = repos.repo(snapshot.repositoryId);
+        const head = await git(repos.path(repo), 'rev-parse', repo.targetRef);
+        result.push({
+            repositoryId: repo.id,
+            snapshot: snapshot.sha,
+            head,
+            fresh: head === snapshot.sha,
+        });
+    }
+    return result;
+}

package/lib/verification/gates.d.ts

@@ -0,0 +1,160 @@
+import { type EvidenceRecord, type ExecutionPolicy, type GatePolicy } from '../contracts/index.ts';
+import { isolationSupport } from '../environment/isolation.ts';
+import { type CheckManifest } from './property.ts';
+/** Длинное имя testcase заменяется хешем, а не обрезается: обрезка дала бы ложные совпадения. */
+export declare const TEST_ID_LIMIT = 1000;
+export declare function portableTest<T extends {
+    id: string;
+    opaque?: true;
+}>(test: T): T;
+/**
+ * Сводка JUnit-отчёта.
+ *
+ * `redact` применяется к именам и сообщениям до любой обрезки: обрезанный
+ * секрет redactor уже не узнаёт, и в сводке оставался бы его префикс. Имя
+ * testcase тоже проходит redact — оно попадает в состояние, журнал и API.
+ * Изменённое так имя не совпадёт с названным критерием, и подтверждения
+ * не будет: для секрета в имени теста это правильный исход.
+ */
+/**
+ * Значение атрибута XML: парсер работает без обработки сущностей (DOCTYPE
+ * запрещён, внешних сущностей нет), поэтому предопределённые сущности и
+ * числовые ссылки раскрываются здесь — один раз, без рекурсии. Иначе testcase
+ * `a["b"]` сохранялся как `a[&quot;b&quot;]` и не совпадал с названным
+ * testId требования или критерия. Репортер JUnit Node.js экранирует `"`
+ * дважды (`&amp;quot;`); оставшийся после раскрытия `&quot;` поэтому тоже
+ * читается как `"`.
+ */
+export declare function xmlAttribute(value: string): string;
+export declare function junitSummary(xml: string, redact?: (value: string) => string): {
+    tests: number;
+    failures: number;
+    skipped: number;
+    /** Имена провалившихся testcases: по ним различаются разные провалы. */
+    failed: string[];
+    /** Те же testcases с первыми словами сообщения о провале. */
+    failedDetails: string[];
+    /** Что именно выполнилось и с каким исходом. */
+    cases: NonNullable<EvidenceRecord['tests']>;
+    /** Список обрезан: отсутствие теста по нему доказать нельзя. */
+    truncated: boolean;
+};
+/**
+ * Песочница отказала до запуска команды: процесс завершился неуспешно, а
+ * метка старта, которую обёртка создаёт перед exec, не появилась. Текст
+ * stderr признаком не служит — его может напечатать и сама проверка.
+ */
+export declare function sandboxNotStarted(result: {
+    code: number;
+}, started: string | undefined): boolean;
+/**
+ * Путь отчёта внутри корня, созданный без выхода за него.
+ *
+ * Раньше каталоги создавались рекурсивно, а граница проверялась потом:
+ * symlink внутри worktree успевал увести создание каталога наружу до отказа.
+ * Теперь путь проходится от корня по одному компоненту: существующий symlink
+ * или не-каталог — отказ до любой записи, недостающий каталог создаётся
+ * только внутри уже проверенного родителя.
+ */
+export declare function prepareReportPath(root: string, path: string, escape: string): Promise<string>;
+/**
+ * Команда проверки — задачи или общей приёмки workspace — в песочнице ОС.
+ *
+ * Прежде проверка шла обычным процессом хоста и могла читать базу контура и
+ * соседние файлы, писать вне worktree и ходить в сеть: сверка HEAD и
+ * отслеживаемых файлов после неё этого не видит. Без механизма песочницы
+ * проверка не запускается — снять изоляцию можно только явным
+ * isolation.mode: none. Запись — в `write` и собственный scratch (TMPDIR).
+ */
+export declare function runCheck(h: {
+    config: Pick<ExecutionPolicy, 'isolation'>;
+}, options: {
+    argv: string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    redact?: (value: string) => string;
+    timeoutMs?: number;
+    signal: AbortSignal;
+    write: string[];
+    readable: string[];
+    controller: string[];
+    settingsDir: string;
+}): Promise<{
+    attempts: number;
+    code: number;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+    diagnostics: import("../contracts/execution.ts").RuntimeDiagnostics;
+}>;
+/** Проверка механизма песочницы; тест подменяет её, чтобы проверить отказ. */
+export declare const isolationBackend: {
+    check: typeof isolationSupport;
+};
+/**
+ * Хосты, в сети к которым проверке, по всей видимости, отказала песочница.
+ *
+ * Прокси песочницы отвечает на запрещённый домен `403`, но клиенты вроде
+ * pnpm показывают только «Forbidden - 403» и URL. На пилоте такой отказ
+ * записывался провалом проверки, и контур переписывал код, который был ни
+ * при чём. Признак узкий: в выводе есть отказ (403, Forbidden, прокси или
+ * тело ответа песочницы) и URL хоста, которого нет в `isolation.domains`.
+ */
+export declare function sandboxBlockedHosts(output: string, allowed: string[]): string[];
+/**
+ * Окружение свежести test gate: те же переменные у gate движка и у gate,
+ * запущенного проверкой reviewer, — иначе probe мог бы прочитать cache там,
+ * где gate исполняет тесты заново.
+ */
+export declare function freshnessEnv(kind: GatePolicy['kind'], env: NodeJS.ProcessEnv): Record<string, string>;
+/** Что нужно для запуска gate попытки. */
+export interface GateRun {
+    policy: Pick<ExecutionPolicy, 'isolation'>;
+    /** Запись evidence под fencing попытки. */
+    record: (evidence: Omit<EvidenceRecord, 'id' | 'runId' | 'createdAt'>) => EvidenceRecord;
+    cwd: string;
+    sha: string;
+    phase: EvidenceRecord['phase'];
+    gate: GatePolicy;
+    artifactDir: string;
+    signal: AbortSignal;
+    /** Окружение фазы: переменные и маска секретов. */
+    execution: {
+        env: NodeJS.ProcessEnv;
+        redact: (value: string) => string;
+    };
+    /** Закрытое проверке (состояние controller, чужие checkout) и открытое внутри него. */
+    boundary: {
+        hidden: string[];
+        readable: string[];
+    };
+    /** Проверка потребителя: evidence несёт его компонент и не закрывает собственные gates. */
+    consumer?: string;
+    /**
+     * Генеративный gate (`gate.property`): попытка, от которой seed, и
+     * ожидаемая проверка поручения. Без `expected` — прежний уровень (отчёт
+     * сверяется сам с собой и с JUnit).
+     */
+    property?: {
+        runId: string;
+        expected?: CheckManifest;
+        /** Закреплённый корпус попытки: материализуется вне worktree только для чтения. */
+        corpus?: {
+            digest: string;
+            content: string;
+        };
+        /** Контракты поручения по digest и их закреплённые файлы. */
+        contracts: Record<string, string>;
+        artifacts: {
+            path: string;
+            blob: string;
+        }[];
+    };
+}
+/**
+ * Gate попытки. `test` принимается только по свежему (прежний отчёт удалён до
+ * запуска) непустому JUnit без failures, errors и skips на этом SHA; exit 0
+ * без отчёта — отказ. Gate, изменивший HEAD или отслеживаемые файлы, не
+ * проходит. Evidence записывается при любом исходе; провал — `TaskFailure`.
+ */
+export declare function runGate(run: GateRun): Promise<EvidenceRecord>;