pactwright 0.0.1

package/dist/pack/resolve.d.ts

@@ -0,0 +1,92 @@
+import type { PactwrightConfig } from "../config/config.js";
+import type { LockFile } from "../config/lock.js";
+import { type Problem } from "../errors.js";
+import { type Project } from "../loader.js";
+import { type ResolvedExtension } from "../extension/resolve.js";
+import { isValidRange, satisfiesRange, sha256 } from "./locate.js";
+import { type PackManifest } from "./manifest.js";
+/** A pack resolved from a project's configuration, with every hash the lock records. */
+export interface ResolvedPack {
+    /** Absolute pack root: where `pack.yml`, `agents/` and `skills/` live. */
+    readonly dir: string;
+    readonly manifest: PackManifest;
+    readonly hashes: {
+        /** Hash of the whole resolved pack: manifest plus every agent and skill hash. */
+        readonly pack: string;
+        /** Agent key → hash of its prompt file. */
+        readonly agents: Readonly<Record<string, string>>;
+        /** Skill name → hash of its file. */
+        readonly skills: Readonly<Record<string, string>>;
+    };
+}
+export interface ResolvePackOptions {
+    /** Project root; path sources and package lookups start here. */
+    readonly root: string;
+    readonly config: PactwrightConfig;
+    /** Defaults to the running runtime's version. */
+    readonly runtimeVersion?: string;
+}
+export { isValidRange, satisfiesRange, sha256 };
+/** Where the configured pack lives; see `locatePackage`. */
+export declare function locatePack(root: string, source: string): string | Problem;
+/**
+ * Resolves the configured pack: locate → load/validate the manifest → check
+ * runtime and requested-version compatibility → hash prompts, skills and
+ * the pack. Returns every problem found; a pack that resolves is complete
+ * in itself but not yet checked against required capabilities (see
+ * `assertPackComplete`).
+ */
+export declare function resolvePack(options: ResolvePackOptions): {
+    value: ResolvedPack | undefined;
+    problems: readonly Problem[];
+};
+/**
+ * The capability check that guards canonical graph mutation (Distribution
+ * §7): resolves the project's pack and throws `missing-capability` — listing
+ * every missing capability — or the resolution problems. Nothing is written
+ * by this function; callers run it before their first write.
+ */
+export declare function assertPackComplete(project: Project): ResolvedPack;
+/** Desired installation state resolved to exact state: pack, extensions and the lock recording them. */
+export interface DesiredState {
+    readonly pack: ResolvedPack;
+    readonly extensions: readonly ResolvedExtension[];
+    readonly lock: LockFile;
+}
+/**
+ * Resolves desired state (configuration) to exact state (a lock value):
+ * resolve every configured extension, resolve the configured pack, check
+ * the required capability union, record runtime version and
+ * pack/agent/skill/extension hashes (Distribution §§3–6). Pure — nothing
+ * is written — and deterministic: the same desired state always resolves to
+ * the same lock. Never throws; mirrors `resolvePack`'s result idiom.
+ */
+export declare function resolveDesiredState(options: ResolvePackOptions): {
+    value: DesiredState | undefined;
+    problems: readonly Problem[];
+};
+/** The agent key and definition implementing `capability`, if the pack maps it. */
+export declare function agentFor(pack: ResolvedPack, capability: string): {
+    readonly key: string;
+    readonly prompt: string;
+    readonly skills: readonly string[];
+} | undefined;
+/**
+ * The lock-file value recording exactly this resolved pack and runtime.
+ * `extensions` is the seam for extension resolution: nothing resolves
+ * extensions in this checkpoint, so it defaults to empty.
+ */
+export declare function lockEntriesFor(pack: ResolvedPack, runtime?: string, extensions?: LockFile["extensions"]): LockFile;
+/** Serialises a lock file deterministically in the `.pactwright/lock.yml` shape. */
+export declare function serialiseLock(lock: LockFile): string;
+/** Writes the lock file atomically (temporary sibling + rename). */
+export declare function writeLock(lockPath: string, lock: LockFile): void;
+/**
+ * Resolves the configured pack, checks required capabilities and only then
+ * records the exact runtime/pack/agent/skill state in `.pactwright/lock.yml`.
+ * Any failure leaves the lock file untouched.
+ */
+export declare function resolveAndLock(root: string): {
+    pack: ResolvedPack;
+    lock: LockFile;
+};

package/dist/pack/resolve.js

@@ -0,0 +1,238 @@
+import { renameSync, writeFileSync } from "node:fs";
+import { dump } from "js-yaml";
+import { join } from "node:path";
+import { tempSibling } from "../atomic.js";
+import { PactwrightError } from "../errors.js";
+import { canonicalJson } from "../graph/revision.js";
+import { loadProject } from "../loader.js";
+import { runtimeVersion } from "../version.js";
+import { enabledManifests, extensionLockEntries, resolveExtensions, } from "../extension/resolve.js";
+import { missingCapabilities, requiredCapabilities } from "./capabilities.js";
+import { isPathSource, isValidRange, locatePackage, satisfiesRange, sha256 } from "./locate.js";
+import { loadPackManifest, readPackFile, skillPath } from "./manifest.js";
+export { isValidRange, satisfiesRange, sha256 };
+/** Where the configured pack lives; see `locatePackage`. */
+export function locatePack(root, source) {
+    return locatePackage(root, source, "agent pack");
+}
+/**
+ * Resolves the configured pack: locate → load/validate the manifest → check
+ * runtime and requested-version compatibility → hash prompts, skills and
+ * the pack. Returns every problem found; a pack that resolves is complete
+ * in itself but not yet checked against required capabilities (see
+ * `assertPackComplete`).
+ */
+export function resolvePack(options) {
+    const source = options.config.agentPack.source;
+    const located = locatePack(options.root, source);
+    if (typeof located !== "string")
+        return { value: undefined, problems: [located] };
+    const dir = located;
+    const loaded = loadPackManifest(dir);
+    if (loaded.value === undefined)
+        return { value: undefined, problems: loaded.problems };
+    const manifest = loaded.value;
+    const path = join(dir, "pack.yml");
+    const problems = [];
+    if (manifest.name !== source && !isPathSource(source)) {
+        problems.push({
+            code: "pack-name-mismatch",
+            message: `pack manifest declares name "${manifest.name}" but config.agent_pack.source is "${source}"`,
+            path,
+        });
+    }
+    const runtime = options.runtimeVersion ?? runtimeVersion();
+    if (!satisfiesRange(runtime, manifest.pactwright)) {
+        problems.push({
+            code: "incompatible-runtime",
+            message: `pack "${manifest.name}@${manifest.version}" requires pactwright ${manifest.pactwright}; this runtime is ${runtime}`,
+            path,
+        });
+    }
+    const wanted = options.config.agentPack.version;
+    if (wanted !== undefined && !isValidRange(wanted)) {
+        // A range the runtime cannot parse is its own problem, not a mismatch.
+        problems.push({
+            code: "invalid-version-range",
+            message: `config.agent_pack.version "${wanted}" is not a supported range; use x.y.z or ^x.y.z`,
+            path,
+        });
+    }
+    else if (wanted !== undefined && !satisfiesRange(manifest.version, wanted)) {
+        problems.push({
+            code: "incompatible-pack-version",
+            message: `config.agent_pack.version wants ${wanted} but the installed pack "${manifest.name}" is ${manifest.version}`,
+            path,
+        });
+    }
+    if (problems.length > 0)
+        return { value: undefined, problems };
+    const agents = {};
+    const skills = {};
+    for (const key of Object.keys(manifest.agents).sort()) {
+        const agent = manifest.agents[key];
+        agents[key] = sha256(readPackFile(dir, agent.prompt));
+        for (const skill of agent.skills) {
+            skills[skill] ??= sha256(readPackFile(dir, skillPath("", skill)));
+        }
+    }
+    const sortedSkills = Object.fromEntries(Object.keys(skills)
+        .sort()
+        .map((k) => [k, skills[k]]));
+    const pack = sha256(canonicalJson({
+        name: manifest.name,
+        version: manifest.version,
+        pactwright: manifest.pactwright,
+        capabilities: manifest.capabilities,
+        agents: Object.fromEntries(Object.keys(manifest.agents)
+            .sort()
+            .map((key) => [key, { prompt: agents[key], skills: manifest.agents[key].skills }])),
+        skills: sortedSkills,
+    }));
+    return {
+        value: { dir, manifest, hashes: { pack, agents, skills: sortedSkills } },
+        problems: [],
+    };
+}
+/**
+ * The one resolution pipeline behind every desired-state surface: resolve
+ * the configured pack, then check it provides every required capability —
+ * the core set plus the capabilities of the given enabled extensions.
+ */
+function resolveComplete(options, extensions = []) {
+    const resolved = resolvePack(options);
+    if (resolved.value === undefined)
+        return { kind: "unresolved", problems: resolved.problems };
+    const pack = resolved.value;
+    const required = requiredCapabilities(extensions);
+    const missing = missingCapabilities(pack.manifest, required);
+    if (missing.length === 0)
+        return { kind: "ok", pack };
+    return {
+        kind: "incomplete",
+        pack,
+        missing,
+        required,
+        problems: missing.map((capability) => ({
+            code: "missing-capability",
+            message: `required capability "${capability}" is not provided by the selected agent pack`,
+            path: join(pack.dir, "pack.yml"),
+        })),
+    };
+}
+/**
+ * The capability check that guards canonical graph mutation (Distribution
+ * §7): resolves the project's pack and throws `missing-capability` — listing
+ * every missing capability — or the resolution problems. Nothing is written
+ * by this function; callers run it before their first write.
+ */
+export function assertPackComplete(project) {
+    const resolution = resolveComplete({ root: project.paths.root, config: project.config }, enabledManifests(project.extensions));
+    if (resolution.kind === "unresolved") {
+        throw PactwrightError.fromProblems("pack-unresolved", resolution.problems);
+    }
+    if (resolution.kind === "incomplete") {
+        const { pack, missing, required } = resolution;
+        throw new PactwrightError("missing-capability", `agent pack "${pack.manifest.name}@${pack.manifest.version}" does not provide required capabilit${missing.length === 1 ? "y" : "ies"}: ${missing.join(", ")} (required: ${required.join(", ")})`, resolution.problems);
+    }
+    return resolution.pack;
+}
+/**
+ * Resolves desired state (configuration) to exact state (a lock value):
+ * resolve every configured extension, resolve the configured pack, check
+ * the required capability union, record runtime version and
+ * pack/agent/skill/extension hashes (Distribution §§3–6). Pure — nothing
+ * is written — and deterministic: the same desired state always resolves to
+ * the same lock. Never throws; mirrors `resolvePack`'s result idiom.
+ */
+export function resolveDesiredState(options) {
+    const extensions = resolveExtensions(options);
+    if (extensions.value === undefined)
+        return { value: undefined, problems: extensions.problems };
+    const resolution = resolveComplete(options, enabledManifests(extensions.value));
+    if (resolution.kind !== "ok")
+        return { value: undefined, problems: resolution.problems };
+    const lock = lockEntriesFor(resolution.pack, options.runtimeVersion ?? runtimeVersion(), extensionLockEntries(extensions.value));
+    return { value: { pack: resolution.pack, extensions: extensions.value, lock }, problems: [] };
+}
+/** The agent key and definition implementing `capability`, if the pack maps it. */
+export function agentFor(pack, capability) {
+    const key = pack.manifest.capabilities[capability];
+    if (key === undefined)
+        return undefined;
+    const agent = pack.manifest.agents[key];
+    if (agent === undefined)
+        return undefined;
+    return { key, prompt: join(pack.dir, agent.prompt), skills: agent.skills };
+}
+/**
+ * The lock-file value recording exactly this resolved pack and runtime.
+ * `extensions` is the seam for extension resolution: nothing resolves
+ * extensions in this checkpoint, so it defaults to empty.
+ */
+export function lockEntriesFor(pack, runtime = runtimeVersion(), extensions = {}) {
+    return {
+        runtime: { version: runtime },
+        agentPack: { name: pack.manifest.name, version: pack.manifest.version, hash: pack.hashes.pack },
+        agents: pack.hashes.agents,
+        skills: pack.hashes.skills,
+        extensions,
+    };
+}
+function sortedMap(entries) {
+    return Object.fromEntries(Object.keys(entries)
+        .sort()
+        .map((key) => [key, entries[key]]));
+}
+/** Extensions in serialisation order: sorted ids, fixed key order, sorted dependencies. */
+function serialisedExtensions(extensions) {
+    return Object.fromEntries(Object.keys(extensions)
+        .sort()
+        .map((id) => {
+        const extension = extensions[id];
+        return [
+            id,
+            {
+                package: extension.package,
+                version: extension.version,
+                hash: extension.hash,
+                ...(extension.dependencies === undefined ||
+                    Object.keys(extension.dependencies).length === 0
+                    ? {}
+                    : { dependencies: sortedMap(extension.dependencies) }),
+            },
+        ];
+    }));
+}
+/** Serialises a lock file deterministically in the `.pactwright/lock.yml` shape. */
+export function serialiseLock(lock) {
+    return dump({
+        runtime: { version: lock.runtime.version },
+        agent_pack: {
+            name: lock.agentPack.name,
+            version: lock.agentPack.version,
+            hash: lock.agentPack.hash,
+        },
+        agents: sortedMap(lock.agents),
+        skills: sortedMap(lock.skills),
+        extensions: serialisedExtensions(lock.extensions),
+    }, { lineWidth: -1, noRefs: true });
+}
+/** Writes the lock file atomically (temporary sibling + rename). */
+export function writeLock(lockPath, lock) {
+    const temp = tempSibling(lockPath);
+    writeFileSync(temp, serialiseLock(lock), "utf8");
+    renameSync(temp, lockPath);
+}
+/**
+ * Resolves the configured pack, checks required capabilities and only then
+ * records the exact runtime/pack/agent/skill state in `.pactwright/lock.yml`.
+ * Any failure leaves the lock file untouched.
+ */
+export function resolveAndLock(root) {
+    const project = loadProject({ root });
+    const pack = assertPackComplete(project);
+    const lock = lockEntriesFor(pack, runtimeVersion(), extensionLockEntries(project.extensions));
+    writeLock(project.paths.lock, lock);
+    return { pack, lock };
+}

package/dist/project.d.ts

@@ -0,0 +1,22 @@
+/** File and directory layout of a Pactwright project (Delivery Graph §4). */
+export interface ProjectPaths {
+    readonly root: string;
+    readonly pactwrightDir: string;
+    readonly config: string;
+    readonly lifecycle: string;
+    readonly lock: string;
+    readonly specsDir: string;
+    readonly nodesDir: string;
+    readonly edges: string;
+}
+export declare const CONFIG_FILE = ".pactwright/config.yml";
+export declare const LIFECYCLE_FILE = ".pactwright/lifecycle.yml";
+export declare const LOCK_FILE = ".pactwright/lock.yml";
+export declare const NODES_DIR = "specs/nodes";
+export declare const EDGES_FILE = "specs/graph/edges.yml";
+export declare function projectPaths(root: string): ProjectPaths;
+/**
+ * Walks up from `cwd` until a directory containing `.pactwright/config.yml`
+ * is found. Throws when no Pactwright project encloses `cwd`.
+ */
+export declare function findProjectRoot(cwd?: string): string;

package/dist/project.js

@@ -0,0 +1,37 @@
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { PactwrightError } from "./errors.js";
+export const CONFIG_FILE = ".pactwright/config.yml";
+export const LIFECYCLE_FILE = ".pactwright/lifecycle.yml";
+export const LOCK_FILE = ".pactwright/lock.yml";
+export const NODES_DIR = "specs/nodes";
+export const EDGES_FILE = "specs/graph/edges.yml";
+export function projectPaths(root) {
+    const absoluteRoot = resolve(root);
+    return {
+        root: absoluteRoot,
+        pactwrightDir: join(absoluteRoot, ".pactwright"),
+        config: join(absoluteRoot, CONFIG_FILE),
+        lifecycle: join(absoluteRoot, LIFECYCLE_FILE),
+        lock: join(absoluteRoot, LOCK_FILE),
+        specsDir: join(absoluteRoot, "specs"),
+        nodesDir: join(absoluteRoot, NODES_DIR),
+        edges: join(absoluteRoot, EDGES_FILE),
+    };
+}
+/**
+ * Walks up from `cwd` until a directory containing `.pactwright/config.yml`
+ * is found. Throws when no Pactwright project encloses `cwd`.
+ */
+export function findProjectRoot(cwd = process.cwd()) {
+    let current = resolve(cwd);
+    for (;;) {
+        if (existsSync(join(current, CONFIG_FILE)))
+            return current;
+        const parent = dirname(current);
+        if (parent === current) {
+            throw new PactwrightError("project-not-found", `no Pactwright project found from ${resolve(cwd)} (expected ${CONFIG_FILE} in this directory or a parent)`);
+        }
+        current = parent;
+    }
+}

package/dist/sync.d.ts

@@ -0,0 +1,54 @@
+import { type RenderedFiles } from "./adapter/claude-code.js";
+import { type Problem } from "./errors.js";
+import { type Project } from "./loader.js";
+import { type ResolvedPack } from "./pack/resolve.js";
+/** `pactwright sync` result. */
+export interface SyncReport {
+    readonly ok: boolean;
+    readonly root: string;
+    /** Rendered files whose on-disk bytes differed (or were absent) before this sync. */
+    readonly changed: readonly string[];
+    /** Rendered files that were already byte-identical on disk. */
+    readonly unchanged: readonly string[];
+    /** Files Pactwright had generated that the render no longer produces, deleted. */
+    readonly removed: readonly string[];
+    /**
+     * Files inside the managed directories that Pactwright did not generate, so
+     * are not Pactwright's to remove. Reported, never deleted.
+     */
+    readonly kept: readonly string[];
+    /**
+     * Rendered paths already occupied by an unmarked file. The file is left
+     * untouched and the sync fails, so the collision is resolved deliberately
+     * rather than by overwriting user state.
+     */
+    readonly conflicts: readonly string[];
+    /** Empty when `ok`. */
+    readonly problems: readonly Problem[];
+}
+/**
+ * The Distribution §8 GitHub-workflow rendering step. It is a seam in this
+ * checkpoint: GitHub provisioning arrives in Checkpoint 2, so no workflow
+ * files are rendered and nothing under `.github/` is ever Pactwright-managed
+ * yet. When it activates it renders only files Pactwright explicitly owns
+ * (e.g. `.github/workflows/pactwright*.yml`) — `sync` never claims
+ * ownership of user-authored `.github/workflows/**`.
+ */
+export declare function renderGitHubWorkflows(project: Project, pack: ResolvedPack): RenderedFiles;
+/**
+ * Deterministic local synchronisation (Distribution §8): load configuration,
+ * lock and extensions through the canonical loader, validate the required
+ * capability union, assemble agents and skills from the resolved pack, and
+ * render only the Pactwright-managed `.claude/` adapter surface. Enabled
+ * extensions contribute through the same adapter process; in this checkpoint
+ * their contribution is the capability union, since extension manifests
+ * declare no renderable adapter content yet. Repeated sync with unchanged
+ * inputs is byte-identical. Never throws for expected failures, and writes
+ * nothing when resolution fails.
+ *
+ * Only files whose banner stands in its rendered position are overwritten or
+ * removed, so a hand-written file inside `.claude/agents` or
+ * `.claude/commands` survives every sync — including one that quotes the
+ * banner in its prose.
+ */
+export declare function syncProject(root?: string): SyncReport;

package/dist/sync.js

@@ -0,0 +1,98 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { GENERATED_MARKER, renderClaudeCodeAdapter, writeAdapter, } from "./adapter/claude-code.js";
+import { PactwrightError } from "./errors.js";
+import { loadProject } from "./loader.js";
+import { assertPackComplete } from "./pack/resolve.js";
+import { projectPaths } from "./project.js";
+/**
+ * The Distribution §8 GitHub-workflow rendering step. It is a seam in this
+ * checkpoint: GitHub provisioning arrives in Checkpoint 2, so no workflow
+ * files are rendered and nothing under `.github/` is ever Pactwright-managed
+ * yet. When it activates it renders only files Pactwright explicitly owns
+ * (e.g. `.github/workflows/pactwright*.yml`) — `sync` never claims
+ * ownership of user-authored `.github/workflows/**`.
+ */
+export function renderGitHubWorkflows(project, pack) {
+    void project;
+    void pack;
+    return new Map();
+}
+/**
+ * Deterministic local synchronisation (Distribution §8): load configuration,
+ * lock and extensions through the canonical loader, validate the required
+ * capability union, assemble agents and skills from the resolved pack, and
+ * render only the Pactwright-managed `.claude/` adapter surface. Enabled
+ * extensions contribute through the same adapter process; in this checkpoint
+ * their contribution is the capability union, since extension manifests
+ * declare no renderable adapter content yet. Repeated sync with unchanged
+ * inputs is byte-identical. Never throws for expected failures, and writes
+ * nothing when resolution fails.
+ *
+ * Only files whose banner stands in its rendered position are overwritten or
+ * removed, so a hand-written file inside `.claude/agents` or
+ * `.claude/commands` survives every sync — including one that quotes the
+ * banner in its prose.
+ */
+export function syncProject(root = process.cwd()) {
+    const paths = projectPaths(root);
+    const failure = (problems) => ({
+        ok: false,
+        root: paths.root,
+        changed: [],
+        unchanged: [],
+        removed: [],
+        kept: [],
+        conflicts: [],
+        problems,
+    });
+    let project;
+    let pack;
+    try {
+        project = loadProject({ root: paths.root });
+        pack = assertPackComplete(project);
+    }
+    catch (error) {
+        if (!(error instanceof PactwrightError))
+            throw error;
+        return failure(error.problems);
+    }
+    const files = new Map([
+        ...renderClaudeCodeAdapter(pack),
+        ...renderGitHubWorkflows(project, pack),
+    ]);
+    // Compared before the write, or every rendered file would read back as
+    // unchanged. Paths that turn out to collide with user state are dropped
+    // afterwards: nothing was written there.
+    const changed = [];
+    const unchanged = [];
+    for (const [relPath, content] of files) {
+        const target = join(paths.root, relPath);
+        if (existsSync(target) && readFileSync(target, "utf8") === content) {
+            unchanged.push(relPath);
+        }
+        else {
+            changed.push(relPath);
+        }
+    }
+    const written = writeAdapter(paths.root, files);
+    const conflicted = new Set(written.conflicts);
+    // A collision with an unmarked file is reported, never resolved by
+    // overwriting: `sync` fails so the state is visible to the user and to CI
+    // (Distribution §14 — leave ambiguous state intact and report it).
+    const problems = written.conflicts.map((path) => ({
+        code: "unmanaged-conflict",
+        message: `"${path}" is not a Pactwright-generated file, so it was not overwritten: delete it, or restore its "${GENERATED_MARKER}" banner, then run \`pactwright sync\` again`,
+        path,
+    }));
+    return {
+        ok: problems.length === 0,
+        root: paths.root,
+        changed: changed.filter((path) => !conflicted.has(path)).sort(),
+        unchanged: unchanged.filter((path) => !conflicted.has(path)).sort(),
+        removed: written.removed,
+        kept: written.kept,
+        conflicts: written.conflicts,
+        problems,
+    };
+}

package/dist/validate.d.ts

@@ -0,0 +1,23 @@
+import { type Problem } from "./errors.js";
+import { type LoadProjectOptions } from "./loader.js";
+/** `pactwright validate` result (Delivery Graph §21). */
+export interface ValidationReport {
+    readonly ok: boolean;
+    /** Every problem found in one pass; empty when `ok`. */
+    readonly problems: readonly Problem[];
+    /** Present when `ok`: what was validated. */
+    readonly summary?: {
+        readonly nodes: number;
+        readonly edges: number;
+        readonly lineages: number;
+        readonly revision: string;
+    };
+}
+/**
+ * Validates core Delivery Graph integrity and shared typed-edge integrity
+ * through the one canonical loading path (config, lifecycle, lock, node
+ * schemas, typed-edge registry, current-lineage ambiguity). Validation does
+ * not require the lifecycle to be complete. Never throws for expected
+ * failures: an unloadable or absent project is reported as problems.
+ */
+export declare function validateProject(options?: LoadProjectOptions): ValidationReport;

package/dist/validate.js

@@ -0,0 +1,32 @@
+import { PactwrightError } from "./errors.js";
+import { deriveLineages } from "./graph/lineage.js";
+import { graphRevision } from "./graph/revision.js";
+import { loadProject } from "./loader.js";
+/**
+ * Validates core Delivery Graph integrity and shared typed-edge integrity
+ * through the one canonical loading path (config, lifecycle, lock, node
+ * schemas, typed-edge registry, current-lineage ambiguity). Validation does
+ * not require the lifecycle to be complete. Never throws for expected
+ * failures: an unloadable or absent project is reported as problems.
+ */
+export function validateProject(options = {}) {
+    try {
+        const project = loadProject(options);
+        const { nodes, edges } = project.graph;
+        return {
+            ok: true,
+            problems: [],
+            summary: {
+                nodes: nodes.length,
+                edges: edges.length,
+                lineages: deriveLineages(nodes, edges).lineages.length,
+                revision: graphRevision({ nodes, edges }),
+            },
+        };
+    }
+    catch (error) {
+        if (!(error instanceof PactwrightError))
+            throw error;
+        return { ok: false, problems: error.problems };
+    }
+}

package/dist/validation.d.ts

@@ -0,0 +1,24 @@
+import type { Problem } from "./errors.js";
+/**
+ * Collects problems for one file. Every `expect*` helper records a problem
+ * and returns `undefined` on failure so parsers can keep going and report
+ * everything wrong with a file in one pass.
+ */
+export declare class Checker {
+    readonly path: string;
+    readonly problems: Problem[];
+    constructor(path: string);
+    fail(code: string, message: string): undefined;
+    get ok(): boolean;
+}
+export type Unknown = unknown;
+export type UnknownRecord = Record<string, unknown>;
+export declare function isRecord(value: unknown): value is UnknownRecord;
+export declare function expectRecord(c: Checker, value: unknown, label: string): UnknownRecord | undefined;
+export declare function expectString(c: Checker, value: unknown, label: string): string | undefined;
+export declare function expectInteger(c: Checker, value: unknown, label: string): number | undefined;
+export declare function expectBoolean(c: Checker, value: unknown, label: string): boolean | undefined;
+export declare function expectEnum<T extends string>(c: Checker, value: unknown, label: string, allowed: readonly T[]): T | undefined;
+export declare function expectVersion(c: Checker, value: unknown, label: string, expected: number): void;
+export declare function requireKeys(c: Checker, record: UnknownRecord, label: string, keys: readonly string[]): void;
+export declare function rejectUnknownKeys(c: Checker, record: UnknownRecord, label: string, allowed: readonly string[]): void;