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

package/lib/toolchains/manifests.d.ts

@@ -0,0 +1,67 @@
+/** Lockfile → менеджер пакетов, которому он принадлежит. */
+export declare const lockfiles: {
+    readonly 'package-lock.json': "npm";
+    readonly 'npm-shrinkwrap.json': "npm";
+    readonly 'pnpm-lock.yaml': "pnpm";
+    readonly 'yarn.lock': "yarn";
+    readonly 'bun.lock': "bun";
+    readonly 'bun.lockb': "bun";
+};
+export type LockManager = (typeof lockfiles)[keyof typeof lockfiles];
+export declare class Manifests {
+    readonly root: string;
+    private cache;
+    constructor(root: string);
+    /** Путь `rel` относительно корня; `.` — корень. */
+    abs(rel: string): string;
+    /** Относительный путь каталога; вне корня — undefined. */
+    rel(abs: string): string | undefined;
+    /** Каталог внутри корня без symlink на пути. */
+    isDir(rel: string): boolean;
+    isFile(rel: string): boolean;
+    private stat;
+    /** Текст файла внутри корня (до 4 MiB) или undefined. */
+    text(rel: string): string | undefined;
+    json(rel: string): Record<string, unknown> | undefined;
+    /** Каталог и его предки до корня включительно, от ближнего. */
+    ancestors(dir: string): string[];
+    /** Ближайший к `dir` каталог (до корня), где есть файл `name`. */
+    nearest(dir: string, name: string): string | undefined;
+    lockfilesIn(dir: string): string[];
+    list(rel: string): string[];
+}
+export declare const join2: (dir: string, name: string) => string;
+/** Скрипты package.json каталога. */
+export declare function scriptsOf(m: Manifests, dir: string): Record<string, string> | undefined;
+/** `packageManager` из package.json: `pnpm@10.12.3+sha512…` → { name, version }. */
+export declare function packageManagerField(m: Manifests, dir: string): {
+    name: string;
+    version: string;
+    raw: string;
+} | {
+    name: string;
+    raw: string;
+    version?: undefined;
+} | undefined;
+/** Пакеты workspace pnpm: `packages:` из pnpm-workspace.yaml (простые шаблоны `dir/*`). */
+export declare function workspacePackages(m: Manifests, workspaceRoot: string): {
+    dir: string;
+    name: string | undefined;
+    scripts: Record<string, string>;
+}[];
+/** Задачи turbo.json (`tasks` v2 либо `pipeline` v1). */
+export declare function turboTasks(m: Manifests, dir: string): string[] | undefined;
+/** go.mod: директивы `go`, `toolchain` и наличие require. */
+export declare function goModule(m: Manifests, dir: string): {
+    go: string | undefined;
+    toolchain: string | undefined;
+    requires: boolean;
+} | undefined;
+/** Пакеты, закреплённые uv.lock (`name = "…"` записей `[[package]]`). */
+export declare function uvLocked(m: Manifests, dir: string): Map<string, string> | undefined;
+/**
+ * Точная версия зависимости `name` корневого пакета каталога, закреплённая
+ * lockfile: `importers['.']` pnpm-lock.yaml либо `packages['node_modules/<name>']`
+ * package-lock.json. Нет закрепления — undefined.
+ */
+export declare function lockedVersion(m: Manifests, dir: string, name: string): string | undefined;

package/lib/toolchains/manifests.js

@@ -0,0 +1,238 @@
+import { lstatSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+/**
+ * Чтение манифестов целевого репозитория — только чтение файлов внутри его
+ * корня, без symlink наружу и без исполнения чего-либо. Всё, что здесь
+ * разбирается (package.json, pnpm-workspace.yaml, turbo.json, go.mod,
+ * pyproject.toml, uv.lock), читается как данные.
+ */
+const FILE_LIMIT = 4 * 1024 * 1024;
+/** Lockfile → менеджер пакетов, которому он принадлежит. */
+export const lockfiles = {
+    'package-lock.json': 'npm',
+    'npm-shrinkwrap.json': 'npm',
+    'pnpm-lock.yaml': 'pnpm',
+    'yarn.lock': 'yarn',
+    'bun.lock': 'bun',
+    'bun.lockb': 'bun',
+};
+export class Manifests {
+    root;
+    cache = new Map();
+    constructor(root) {
+        this.root = realpathSync(root);
+    }
+    /** Путь `rel` относительно корня; `.` — корень. */
+    abs(rel) {
+        return rel === '.' ? this.root : join(this.root, rel);
+    }
+    /** Относительный путь каталога; вне корня — undefined. */
+    rel(abs) {
+        const r = relative(this.root, resolve(abs));
+        if (r === '')
+            return '.';
+        if (r === '..' || r.startsWith('..' + sep) || r.startsWith(sep))
+            return undefined;
+        return r.split(sep).join('/');
+    }
+    /** Каталог внутри корня без symlink на пути. */
+    isDir(rel) {
+        const stat = this.stat(rel);
+        return stat?.isDirectory() ?? false;
+    }
+    isFile(rel) {
+        const stat = this.stat(rel);
+        return stat?.isFile() ?? false;
+    }
+    stat(rel) {
+        if (rel === '.')
+            return lstatSync(this.root);
+        let cursor = this.root;
+        let stat;
+        for (const part of rel.split('/')) {
+            if (!part || part === '..')
+                return undefined;
+            if (part === '.')
+                continue;
+            cursor = join(cursor, part);
+            try {
+                stat = lstatSync(cursor);
+            }
+            catch {
+                return undefined;
+            }
+            if (stat.isSymbolicLink())
+                return undefined;
+        }
+        return stat;
+    }
+    /** Текст файла внутри корня (до 4 MiB) или undefined. */
+    text(rel) {
+        if (this.cache.has(rel))
+            return this.cache.get(rel);
+        const stat = this.stat(rel);
+        const value = stat?.isFile() && stat.size <= FILE_LIMIT ? readFileSync(this.abs(rel), 'utf8') : undefined;
+        this.cache.set(rel, value);
+        return value;
+    }
+    json(rel) {
+        const text = this.text(rel);
+        if (text === undefined)
+            return undefined;
+        try {
+            const value = JSON.parse(text);
+            return value && typeof value === 'object' && !Array.isArray(value)
+                ? value
+                : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Каталог и его предки до корня включительно, от ближнего. */
+    ancestors(dir) {
+        const out = [];
+        let cursor = dir;
+        for (;;) {
+            out.push(cursor);
+            if (cursor === '.')
+                return out;
+            const up = dirname(cursor);
+            cursor = up === '' || up === '.' ? '.' : up;
+        }
+    }
+    /** Ближайший к `dir` каталог (до корня), где есть файл `name`. */
+    nearest(dir, name) {
+        return this.ancestors(dir).find((d) => this.isFile(join2(d, name)));
+    }
+    lockfilesIn(dir) {
+        return Object.keys(lockfiles).filter((f) => this.isFile(join2(dir, f)));
+    }
+    list(rel) {
+        if (!this.isDir(rel))
+            return [];
+        return readdirSync(this.abs(rel), { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name)
+            .sort();
+    }
+}
+export const join2 = (dir, name) => (dir === '.' ? name : `${dir}/${name}`);
+/** Скрипты package.json каталога. */
+export function scriptsOf(m, dir) {
+    const pkg = m.json(join2(dir, 'package.json'));
+    if (!pkg)
+        return undefined;
+    const scripts = pkg.scripts;
+    return scripts && typeof scripts === 'object' ? scripts : {};
+}
+/** `packageManager` из package.json: `pnpm@10.12.3+sha512…` → { name, version }. */
+export function packageManagerField(m, dir) {
+    const value = m.json(join2(dir, 'package.json'))?.packageManager;
+    if (typeof value !== 'string')
+        return undefined;
+    const match = /^(npm|pnpm|yarn|bun)@(\d+\.\d+\.\d+[^+]*)/.exec(value);
+    return match ? { name: match[1], version: match[2], raw: value } : { name: value, raw: value };
+}
+/** Пакеты workspace pnpm: `packages:` из pnpm-workspace.yaml (простые шаблоны `dir/*`). */
+export function workspacePackages(m, workspaceRoot) {
+    const text = m.text(join2(workspaceRoot, 'pnpm-workspace.yaml'));
+    const patterns = [];
+    if (text) {
+        let inPackages = false;
+        for (const line of text.split('\n')) {
+            if (/^packages\s*:/.test(line)) {
+                inPackages = true;
+                continue;
+            }
+            if (inPackages) {
+                const item = /^\s+-\s*['"]?([^'"#]+?)['"]?\s*(?:#.*)?$/.exec(line);
+                if (item)
+                    patterns.push(item[1].trim());
+                else if (/^\S/.test(line))
+                    inPackages = false;
+            }
+        }
+    }
+    else {
+        const workspaces = m.json(join2(workspaceRoot, 'package.json'))?.workspaces;
+        if (Array.isArray(workspaces))
+            patterns.push(...workspaces.filter((w) => typeof w === 'string'));
+    }
+    const dirs = new Set([workspaceRoot]);
+    for (const pattern of patterns) {
+        if (pattern.startsWith('!'))
+            continue;
+        const clean = pattern.replace(/\/$/, '');
+        if (clean.endsWith('/*') || clean.endsWith('/**')) {
+            const base = join2(workspaceRoot, clean.replace(/\/\*\*?$/, ''));
+            for (const child of m.list(base))
+                dirs.add(join2(base, child));
+        }
+        else
+            dirs.add(join2(workspaceRoot, clean));
+    }
+    return [...dirs]
+        .filter((d) => m.isFile(join2(d, 'package.json')))
+        .map((dir) => {
+        const pkg = m.json(join2(dir, 'package.json')) ?? {};
+        return {
+            dir,
+            name: typeof pkg.name === 'string' ? pkg.name : undefined,
+            scripts: scriptsOf(m, dir) ?? {},
+        };
+    });
+}
+/** Задачи turbo.json (`tasks` v2 либо `pipeline` v1). */
+export function turboTasks(m, dir) {
+    const turbo = m.json(join2(dir, 'turbo.json'));
+    if (!turbo)
+        return undefined;
+    const tasks = (turbo.tasks ?? turbo.pipeline);
+    return tasks && typeof tasks === 'object' ? Object.keys(tasks) : [];
+}
+/** go.mod: директивы `go`, `toolchain` и наличие require. */
+export function goModule(m, dir) {
+    const text = m.text(join2(dir, 'go.mod'));
+    if (text === undefined)
+        return undefined;
+    return {
+        go: /^go\s+(\d+\.\d+(?:\.\d+)?)\s*$/m.exec(text)?.[1],
+        toolchain: /^toolchain\s+go(\d+\.\d+(?:\.\d+)?)\s*$/m.exec(text)?.[1],
+        requires: /^require\b/m.test(text),
+    };
+}
+/** Пакеты, закреплённые uv.lock (`name = "…"` записей `[[package]]`). */
+export function uvLocked(m, dir) {
+    const text = m.text(join2(dir, 'uv.lock'));
+    if (text === undefined)
+        return undefined;
+    const names = new Map();
+    for (const block of text.split(/^\[\[package\]\]\s*$/m).slice(1)) {
+        const name = /^name\s*=\s*"([^"]+)"/m.exec(block)?.[1];
+        const version = /^version\s*=\s*"([^"]+)"/m.exec(block)?.[1];
+        if (name)
+            names.set(name.toLowerCase(), version ?? '');
+    }
+    return names;
+}
+/**
+ * Точная версия зависимости `name` корневого пакета каталога, закреплённая
+ * lockfile: `importers['.']` pnpm-lock.yaml либо `packages['node_modules/<name>']`
+ * package-lock.json. Нет закрепления — undefined.
+ */
+export function lockedVersion(m, dir, name) {
+    const pnpm = m.text(join2(dir, 'pnpm-lock.yaml'));
+    if (pnpm !== undefined) {
+        const importers = pnpm.split(/^importers:\s*$/m)[1]?.split(/^\S/m)[0] ?? '';
+        const root = /^ {2}\.:\s*$([\s\S]*?)(?=^ {2}\S|(?![\s\S]))/m.exec(importers)?.[1] ?? '';
+        const quoted = name.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
+        const entry = new RegExp(`^ {6}'?${quoted}'?:\\s*$\\n {8}specifier:[^\\n]*\\n {8}version: ([^\\s(]+)`, 'm').exec(root);
+        if (entry && /^\d+\.\d+\.\d+/.test(entry[1]))
+            return entry[1];
+    }
+    const npm = m.json(join2(dir, 'package-lock.json'));
+    const packages = npm?.packages;
+    const version = packages?.[`node_modules/${name}`]?.version;
+    return version && /^\d+\.\d+\.\d+/.test(version) ? version : undefined;
+}

package/lib/toolchains/probe.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Проба версии — единственный процесс, который запускает диагностика
+ * toolchain: `<tool> --version` (у go — `go version`, у собранного без метки
+ * версии Go-бинарника — `go version -m <файл>`, который только читает файл).
+ * Каталог пробы — нейтральный временный: менеджер пакетов не должен увидеть
+ * `packageManager` проекта и переключиться на другую версию.
+ */
+export interface ToolProbe {
+    (argv: string[], options: {
+        timeoutMs: number;
+        env: NodeJS.ProcessEnv;
+    }): Promise<{
+        code: number;
+        stdout: string;
+        stderr: string;
+        timedOut: boolean;
+    }>;
+}
+export declare const PROBE_TIMEOUT_MS = 10000;
+export declare const defaultProbe: ToolProbe;
+/** Исполняемый файл из PATH (как его нашёл бы spawn) или undefined. */
+export declare function resolveExecutable(name: string, path: string | undefined): string | undefined;
+/** Версия из вывода пробы: первое `1.2.3`/`1.2` (в том числе `go1.24.5`, `v24.3.0`). */
+export declare function versionOf(output: string): string | undefined;
+/** Версия модуля в build info Go-бинарника (`go version -m`). */
+export declare function moduleVersionOf(output: string): string | undefined;
+/** Требование версии: `1.12.3` — названные компоненты совпадают, `>=1.24` — не ниже. */
+export declare function satisfies(version: string, required: string): boolean;

package/lib/toolchains/probe.js

@@ -0,0 +1,54 @@
+import { accessSync, constants, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { delimiter, isAbsolute, join } from 'node:path';
+import { command } from "../environment/process.js";
+export const PROBE_TIMEOUT_MS = 10000;
+export const defaultProbe = async (argv, options) => {
+    const r = await command(argv, tmpdir(), { timeoutMs: options.timeoutMs, env: options.env });
+    return { code: r.code, stdout: r.stdout, stderr: r.stderr, timedOut: r.timedOut };
+};
+/** Исполняемый файл из PATH (как его нашёл бы spawn) или undefined. */
+export function resolveExecutable(name, path) {
+    if (isAbsolute(name))
+        return executable(name) ? name : undefined;
+    for (const dir of (path ?? '').split(delimiter).filter(Boolean)) {
+        const file = join(dir, name);
+        if (executable(file))
+            return file;
+    }
+    return undefined;
+}
+function executable(file) {
+    try {
+        accessSync(file, constants.X_OK);
+        return statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** Версия из вывода пробы: первое `1.2.3`/`1.2` (в том числе `go1.24.5`, `v24.3.0`). */
+export function versionOf(output) {
+    return /(?:^|[^\d.])v?(?:go)?(\d+\.\d+(?:\.\d+)?)/.exec(output)?.[1];
+}
+/** Версия модуля в build info Go-бинарника (`go version -m`). */
+export function moduleVersionOf(output) {
+    return /^\s*mod\s+\S+\s+v(\d+\.\d+\.\d+)/m.exec(output)?.[1];
+}
+/** Требование версии: `1.12.3` — названные компоненты совпадают, `>=1.24` — не ниже. */
+export function satisfies(version, required) {
+    const parse = (v) => v.split('.').map((n) => Number(n));
+    if (required.startsWith('>=')) {
+        const want = parse(required.slice(2));
+        const have = parse(version);
+        for (let i = 0; i < want.length; i++) {
+            const h = have[i] ?? 0;
+            if (h !== want[i])
+                return h > want[i];
+        }
+        return true;
+    }
+    const want = parse(required);
+    const have = parse(version);
+    return want.every((n, i) => have[i] === n);
+}

package/lib/toolchains/recipes.d.ts

@@ -0,0 +1,33 @@
+import type { z } from 'zod';
+import type { gateSchema, repositoryPolicySchema } from '../contracts/index.ts';
+type Gate = z.input<typeof gateSchema>;
+type RepositoryInput = z.input<typeof repositoryPolicySchema>;
+/**
+ * Рецепты установки зависимостей: точные locked-команды менеджера, каталог —
+ * собственным флагом инструмента (шаг `prepare` исполняется в корне
+ * worktree). Рецепт не меняет lockfile: несовместимый lockfile — отказ шага.
+ */
+export declare const installRecipes: {
+    readonly npm: (dir: string) => string[];
+    readonly pnpm: (dir: string) => string[];
+    readonly uv: (dir: string) => string[];
+    readonly go: (dir: string) => string[];
+};
+export type InstallRecipe = keyof typeof installRecipes;
+export interface ToolchainComponent {
+    /** Каталог компонента в репозитории (`.` — корень); gates исполняются в нём. */
+    dir: string;
+    install?: InstallRecipe;
+    installTimeoutMs?: number;
+    /** Gates компонента; `cwd` по умолчанию — каталог компонента. */
+    gates: Gate[];
+}
+/**
+ * Описание репозитория политики из компонентов: у каждого свой рецепт
+ * установки, каталог и gates; один Git root — одна запись репозитория.
+ * Никакого «типа проекта»: Node-компонент на pnpm и Go-компонент — просто два
+ * компонента с разными рецептами. Для node-компонента выбор менеджера
+ * записывается явно (`toolchain.packageManagers`).
+ */
+export declare function composeRepository(own: Pick<RepositoryInput, 'id' | 'path' | 'targetRef'> & Partial<RepositoryInput>, components: ToolchainComponent[], tools?: Record<string, string>): RepositoryInput;
+export {};

package/lib/toolchains/recipes.js

@@ -0,0 +1,51 @@
+/**
+ * Рецепты установки зависимостей: точные locked-команды менеджера, каталог —
+ * собственным флагом инструмента (шаг `prepare` исполняется в корне
+ * worktree). Рецепт не меняет lockfile: несовместимый lockfile — отказ шага.
+ */
+export const installRecipes = {
+    npm: (dir) => (dir === '.' ? ['npm', 'ci'] : ['npm', '--prefix', dir, 'ci']),
+    pnpm: (dir) => [
+        'pnpm',
+        ...(dir === '.' ? [] : ['--dir', dir]),
+        'install',
+        '--frozen-lockfile',
+    ],
+    uv: (dir) => ['uv', 'sync', '--locked', ...(dir === '.' ? [] : ['--directory', dir])],
+    go: (dir) => ['go', ...(dir === '.' ? [] : ['-C', dir]), 'mod', 'download'],
+};
+/**
+ * Описание репозитория политики из компонентов: у каждого свой рецепт
+ * установки, каталог и gates; один Git root — одна запись репозитория.
+ * Никакого «типа проекта»: Node-компонент на pnpm и Go-компонент — просто два
+ * компонента с разными рецептами. Для node-компонента выбор менеджера
+ * записывается явно (`toolchain.packageManagers`).
+ */
+export function composeRepository(own, components, tools = {}) {
+    const prepare = [];
+    const gates = [];
+    const packageManagers = {};
+    for (const c of components) {
+        if (c.install) {
+            const id = (c.dir === '.' ? 'root' : c.dir.replace(/[^A-Za-z0-9_-]/g, '-')) + '-install';
+            prepare.push({
+                id,
+                command: [...installRecipes[c.install](c.dir)],
+                timeoutMs: c.installTimeoutMs ?? 600000,
+            });
+            if (c.install === 'npm' || c.install === 'pnpm')
+                packageManagers[c.dir] = c.install;
+        }
+        for (const g of c.gates)
+            gates.push({ ...g, ...(g.cwd === undefined && c.dir !== '.' ? { cwd: c.dir } : {}) });
+    }
+    return {
+        ...own,
+        prepare: [...(own.prepare ?? []), ...prepare],
+        gates: [...(own.gates ?? []), ...gates],
+        toolchain: {
+            tools: { ...own.toolchain?.tools, ...tools },
+            packageManagers: { ...own.toolchain?.packageManagers, ...packageManagers },
+        },
+    };
+}

package/lib/validate.d.ts

@@ -0,0 +1,36 @@
+import { type ErrorIssue, type ExecutionPolicy, type WorkGraph } from './contracts/index.ts';
+type CodedIssue = ErrorIssue & {
+    code: string;
+};
+/** Путь внутри одного из префиксов (как `withinPaths` DevContour). */
+export declare const withinPaths: (path: string, prefixes: string[]) => boolean;
+/**
+ * Связь поручений с политикой — проверки DevContour `validateTaskContext`,
+ * выполнимые без модели и без внешних источников: репозиторий и роль
+ * объявлены; ресурсы известны; область записи пересекается с областью роли;
+ * область доказательства раскрывается, замкнута по `dependsOn` gates и
+ * содержит test gate; требования не повторяются, их текст совпадает с
+ * digest, а gate — test gate из области; потребители уникальны, отличны от
+ * провайдера, зависят от него и проверяются test gate; поручение уровня
+ * workspace затрагивает минимум два известных репозитория.
+ *
+ * Не проверяется здесь: байты и digests контекста и контрактов — их
+ * сверяет движок с `ContextSource` при регистрации графа.
+ */
+export declare function crossIssues(graph: WorkGraph, policy: ExecutionPolicy): CodedIssue[];
+/**
+ * Проверка входов без вызова моделей и без записи состояния. Ошибки
+ * собираются все сразу; код первой определяет класс отказа.
+ */
+export declare function validateInputs(input: {
+    graph: unknown;
+    policy: unknown;
+    context?: unknown;
+}): {
+    contextDigest?: string | undefined;
+    graphId: string;
+    graphDigest: string;
+    policyDigest: string;
+    orders: number;
+};
+export {};