@weftlet/toolkit 0.0.0-stage → 0.1.1

package/dist/extraction/static.js

@@ -0,0 +1,322 @@
+// Modified for standalone extraction; see docs/extraction-manifest.json.
+import { randomUUID } from 'node:crypto';
+import { withCommittedTree } from "../repository/committed-tree.js";
+import { copyFile, mkdir, readFile, rename, stat, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { matchesRepositoryGlob } from "../repository/glob.js";
+import { runProcess } from "../infrastructure/process.js";
+import { sha256, stableJson } from "../infrastructure/util.js";
+export class ScipTypeScriptIndexer {
+    config;
+    storageRoot;
+    constructor(config, storageRoot) {
+        this.config = config;
+        this.storageRoot = storageRoot;
+    }
+    async index(context) {
+        const require = createRequire(import.meta.url);
+        const destination = join(this.storageRoot, 'scip', `${context.snapshotId}.scip`);
+        await mkdir(join(this.storageRoot, 'scip'), { recursive: true });
+        const temporary = `${destination}.${randomUUID()}.tmp`;
+        const command = this.config.command === 'bundled-scip-typescript' ? process.execPath : this.config.command;
+        const args = this.config.command === 'bundled-scip-typescript'
+            ? [
+                require.resolve('@sourcegraph/scip-typescript'),
+                ...this.config.args,
+                '--output',
+                temporary,
+            ]
+            : this.config.args;
+        await withCommittedTree(context.repositoryRoot, context.commitSha, async (worktreeRoot) => {
+            await runProcess(command, args, worktreeRoot, {
+                ...process.env,
+                NODE_OPTIONS: process.env.NODE_OPTIONS ?? '--max-old-space-size=8192',
+            });
+            const source = this.config.command === 'bundled-scip-typescript'
+                ? temporary
+                : join(worktreeRoot, 'index.scip');
+            await stat(source);
+            if (source !== temporary)
+                await copyFile(source, temporary);
+            // SCIP embeds this disposable checkout in metadata and inferred-type hover text.
+            // Store the normalized artifact itself so its digest still authenticates its bytes.
+            await writeFile(temporary, normalizeScipCheckout(await readFile(temporary), worktreeRoot));
+        });
+        await rename(temporary, destination);
+        return {
+            path: destination,
+            digest: sha256(await readFile(destination)),
+            mode: 'full',
+            version: this.config.version,
+        };
+    }
+}
+function loadScipRuntime() {
+    const require = createRequire(import.meta.url);
+    const main = require.resolve('@sourcegraph/scip-typescript');
+    return require(join(dirname(main), 'scip.js'));
+}
+export function normalizeScipCheckout(bytes, checkoutRoot) {
+    const runtime = loadScipRuntime();
+    const roots = [pathToFileURL(checkoutRoot).href, checkoutRoot.replace(/\\/g, '/'), checkoutRoot];
+    const normalize = (value) => {
+        for (const root of roots) {
+            if (value === root)
+                return 'file:///context-graph/repository';
+            value = value.split(`${root}/`).join('file:///context-graph/repository/');
+            value = value.split(`${root}\\`).join('file:///context-graph/repository/');
+        }
+        return value;
+    };
+    const index = runtime.scip.Index.deserializeBinary(bytes);
+    if (index.metadata)
+        index.metadata.project_root = normalize(index.metadata.project_root);
+    for (const symbol of [
+        ...index.documents.flatMap((document) => document.symbols),
+        ...index.external_symbols,
+    ]) {
+        symbol.documentation = symbol.documentation.map(normalize);
+    }
+    return index.serializeBinary();
+}
+export class ScipSymbolExtractor {
+    repository;
+    index;
+    identity = { id: 'scip-symbol-extractor', version: '1.0.0' };
+    constructor(repository, index) {
+        this.repository = repository;
+        this.index = index;
+    }
+    async extract(context) {
+        const parsed = loadScipRuntime().scip.Index.deserializeBinary(await readFile(this.index.path));
+        const symbols = new Map();
+        for (const document of parsed.documents) {
+            const path = document.relative_path.replace(/\\/g, '/');
+            const content = await this.repository.readFileAt(context.commitSha, path);
+            const digest = sha256(content);
+            const component = {
+                id: `component:file:${path}`,
+                kind: (/\.(spec|test)\.[^.]+$/i.test(path) ? 'Evidence' : 'Component'),
+                label: path,
+            };
+            for (const occurrence of document.occurrences) {
+                if (!occurrence.symbol || occurrence.symbol.startsWith('local '))
+                    continue;
+                const definition = (occurrence.symbol_roles & 1) === 1;
+                const sites = symbols.get(occurrence.symbol) ?? {
+                    definitions: new Map(),
+                    references: new Map(),
+                };
+                symbols.set(occurrence.symbol, sites);
+                const target = definition ? sites.definitions : sites.references;
+                if (target.has(path))
+                    continue;
+                target.set(path, {
+                    path,
+                    line: (occurrence.range[0] ?? 0) + 1,
+                    digest,
+                    component,
+                });
+            }
+        }
+        const facts = [];
+        for (const [symbolText, sites] of [...symbols.entries()].sort(([left], [right]) => left.localeCompare(right))) {
+            const definitionPaths = new Set(sites.definitions.keys());
+            const downstream = [...sites.references.values()].filter((site) => !definitionPaths.has(site.path));
+            if (sites.definitions.size === 0 || downstream.length === 0)
+                continue;
+            const symbol = {
+                id: `symbol:scip:${sha256(symbolText)}`,
+                kind: 'Contract',
+                label: symbolText,
+                attributes: { scipIndexDigest: this.index.digest },
+            };
+            const relationships = [
+                ...[...sites.definitions.values()].map((site) => ({ site, definition: true })),
+                ...downstream.map((site) => ({ site, definition: false })),
+            ];
+            for (const { site, definition } of relationships) {
+                const relation = definition ? 'definition' : 'reference';
+                const provenance = {
+                    path: site.path,
+                    startLine: site.line,
+                    endLine: site.line,
+                    digest: site.digest,
+                    commitSha: context.commitSha,
+                };
+                facts.push({
+                    id: sha256(stableJson({ relation, path: site.path, symbol: symbolText, provenance })),
+                    subject: site.component,
+                    predicate: definition ? 'contains' : 'consumes',
+                    object: symbol,
+                    provenance,
+                    extractor: this.identity,
+                    confidence: 1,
+                    snapshotId: context.snapshotId,
+                });
+            }
+        }
+        return facts;
+    }
+}
+export class RepositoryFileExtractor {
+    repository;
+    roots;
+    scipDigest;
+    identity = { id: 'repository-file-extractor', version: '1.0.0' };
+    constructor(repository, roots, scipDigest) {
+        this.repository = repository;
+        this.roots = roots;
+        this.scipDigest = scipDigest;
+    }
+    async extract(context) {
+        const paths = await this.repository.listFilesAt(context.commitSha, this.roots);
+        const facts = [];
+        const project = {
+            id: `project:${context.repositoryId}`,
+            kind: 'Project',
+            label: context.repositoryId,
+        };
+        for (const path of paths) {
+            if (!/\.(ts|tsx|js|mjs|cjs|json|prisma|ya?ml)$/i.test(path))
+                continue;
+            const content = await this.repository.readFileAt(context.commitSha, path);
+            const digest = sha256(content);
+            const component = {
+                id: `component:file:${path}`,
+                kind: (/\.(spec|test)\.[^.]+$/i.test(path) ? 'Evidence' : 'Component'),
+                label: path,
+                attributes: { scipIndexDigest: this.scipDigest },
+            };
+            const provenance = {
+                path,
+                startLine: 1,
+                endLine: Math.max(1, content.split('\n').length),
+                digest,
+                commitSha: context.commitSha,
+            };
+            facts.push({
+                id: sha256(stableJson({ project, component, provenance })),
+                subject: project,
+                predicate: 'contains',
+                object: component,
+                provenance,
+                extractor: this.identity,
+                confidence: 1,
+                snapshotId: context.snapshotId,
+            });
+            const lines = content.split('\n');
+            for (const [index, line] of lines.entries()) {
+                const imported = line.match(/(?:from\s+|import\s*\()['"]([^'"]+)['"]/)?.[1];
+                if (!imported)
+                    continue;
+                const contract = {
+                    id: `contract:module:${imported}`,
+                    kind: 'Contract',
+                    label: imported,
+                };
+                const importProvenance = { ...provenance, startLine: index + 1, endLine: index + 1 };
+                facts.push({
+                    id: sha256(stableJson({ component, imported, importProvenance })),
+                    subject: component,
+                    predicate: 'consumes',
+                    object: contract,
+                    provenance: importProvenance,
+                    extractor: this.identity,
+                    confidence: 1,
+                    snapshotId: context.snapshotId,
+                });
+            }
+        }
+        return facts;
+    }
+}
+export class RepositoryContractExtractor {
+    repository;
+    patterns;
+    consumerRoots;
+    aliases;
+    identity = { id: 'repository-contract-extractor', version: '1.1.0' };
+    constructor(repository, patterns, consumerRoots, aliases = {}) {
+        this.repository = repository;
+        this.patterns = patterns;
+        this.consumerRoots = consumerRoots;
+        this.aliases = aliases;
+    }
+    async extract(context) {
+        if (this.patterns.length === 0)
+            return [];
+        const paths = (await this.repository.listAllFilesAt(context.commitSha)).filter((path) => this.patterns.some((pattern) => matchesRepositoryGlob(path, pattern)));
+        const packageManifests = (await this.repository.listAllFilesAt(context.commitSha)).filter((path) => path.endsWith('package.json'));
+        const facts = [];
+        for (const path of paths) {
+            const content = await this.repository.readFileAt(context.commitSha, path);
+            const provenance = {
+                path,
+                startLine: 1,
+                endLine: Math.max(1, content.split('\n').length),
+                digest: sha256(content),
+                commitSha: context.commitSha,
+            };
+            const contract = {
+                id: `contract:file:${path}`,
+                kind: 'Contract',
+                label: path,
+            };
+            const source = {
+                id: `evidence:contract-file:${path}`,
+                kind: 'Evidence',
+                label: path,
+            };
+            facts.push({
+                id: sha256(stableJson({ source, contract, provenance })),
+                subject: source,
+                predicate: 'contains',
+                object: contract,
+                provenance,
+                extractor: this.identity,
+                confidence: 1,
+                snapshotId: context.snapshotId,
+            });
+            const needles = [path, ...(this.aliases[path] ?? [])];
+            const manifest = packageManifests
+                .filter((candidate) => path.startsWith(candidate.slice(0, -'package.json'.length)))
+                .sort((left, right) => right.length - left.length)[0];
+            if (manifest) {
+                const parsed = JSON.parse(await this.repository.readFileAt(context.commitSha, manifest));
+                if (typeof parsed.name === 'string' && parsed.name.startsWith('@')) {
+                    needles.push(parsed.name);
+                }
+            }
+            const matches = await this.repository.findTextAt(context.commitSha, needles, this.consumerRoots);
+            for (const match of matches.filter((candidate) => candidate.path !== path && candidate.path !== manifest)) {
+                const consumerContent = await this.repository.readFileAt(context.commitSha, match.path);
+                const consumerProvenance = {
+                    path: match.path,
+                    startLine: match.line,
+                    endLine: match.line,
+                    digest: sha256(consumerContent),
+                    commitSha: context.commitSha,
+                };
+                const consumer = {
+                    id: `component:file:${match.path}`,
+                    kind: 'Component',
+                    label: match.path,
+                };
+                facts.push({
+                    id: sha256(stableJson({ consumer, contract, consumerProvenance })),
+                    subject: consumer,
+                    predicate: 'consumes',
+                    object: contract,
+                    provenance: consumerProvenance,
+                    extractor: this.identity,
+                    confidence: 1,
+                    snapshotId: context.snapshotId,
+                });
+            }
+        }
+        return facts;
+    }
+}

package/dist/extraction/telemetry.d.ts

@@ -0,0 +1,19 @@
+import type { ExtractionContext, RuntimeEvidenceProvider, RuntimeTraceReference } from "@weftlet/core";
+import type { ContextGraphConfig } from "../configuration/config.js";
+export declare class OtlpJsonRuntimeEvidenceProvider implements RuntimeEvidenceProvider {
+    private readonly patterns;
+    private readonly now;
+    private readonly policy;
+    constructor(patterns: readonly string[], policy?: ContextGraphConfig['runtimeEvidencePolicy'], now?: () => Date);
+    collect(context: ExtractionContext): Promise<readonly RuntimeTraceReference[]>;
+}
+export declare function captureValidationTrace(outputPath: string, options: {
+    readonly serviceName: string;
+    readonly serviceVersion: string;
+    readonly capability: string;
+    readonly operation?: string;
+    readonly environment: string;
+    readonly serviceInstanceId?: string;
+    readonly backendUrl?: string;
+    readonly run: () => Promise<void>;
+}): Promise<void>;

package/dist/extraction/telemetry.js

@@ -0,0 +1,259 @@
+// Modified for standalone extraction; see docs/extraction-manifest.json.
+import { mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { dirname, join, relative, resolve } from 'node:path';
+import { trace } from '@opentelemetry/api';
+import { resourceFromAttributes } from '@opentelemetry/resources';
+import { BasicTracerProvider, InMemorySpanExporter, SimpleSpanProcessor, } from '@opentelemetry/sdk-trace-base';
+import { sha256 } from "../infrastructure/util.js";
+function attribute(attributes, key) {
+    return attributes?.find((candidate) => candidate.key === key)?.value.stringValue;
+}
+async function expandPatterns(root, patterns) {
+    const files = [];
+    for (const pattern of patterns) {
+        const normalized = pattern.replace(/\\/g, '/');
+        const wildcard = normalized.indexOf('*');
+        const directory = resolve(root, wildcard >= 0 ? normalized.slice(0, wildcard) : dirname(normalized));
+        const suffix = wildcard >= 0 ? normalized.slice(normalized.lastIndexOf('*') + 1) : normalized;
+        try {
+            for (const entry of await readdir(directory, { withFileTypes: true })) {
+                const path = join(directory, entry.name);
+                if (entry.isFile() && path.replace(/\\/g, '/').endsWith(suffix))
+                    files.push(path);
+            }
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    return files.sort();
+}
+export class OtlpJsonRuntimeEvidenceProvider {
+    patterns;
+    now;
+    policy;
+    constructor(patterns, policy = undefined, now = () => new Date()) {
+        this.patterns = patterns;
+        this.now = now;
+        this.policy = policy ?? {
+            retentionDays: 14,
+            maxReferences: 500,
+            maxSourceBytes: 5 * 1024 * 1024,
+            requireEnvironment: false,
+            requireServiceInstance: false,
+            capabilityKeys: ['context.graph.capability'],
+            operationKeys: ['context.graph.operation'],
+        };
+    }
+    async collect(context) {
+        const references = [];
+        const paths = await expandPatterns(context.repositoryRoot, this.patterns);
+        if (paths.length > this.policy.maxReferences) {
+            throw new Error(`Runtime evidence matched ${paths.length} sources, exceeding the ${this.policy.maxReferences}-reference cap`);
+        }
+        let cumulativeSourceBytes = 0;
+        for (const path of paths) {
+            const sourcePath = relative(context.repositoryRoot, path).replace(/\\/g, '/');
+            const sourceBytes = (await stat(path)).size;
+            if (sourceBytes > this.policy.maxSourceBytes) {
+                throw new Error(`Runtime evidence source exceeds ${this.policy.maxSourceBytes} bytes: ${sourcePath}`);
+            }
+            cumulativeSourceBytes += sourceBytes;
+            if (cumulativeSourceBytes > this.policy.maxSourceBytes) {
+                throw new Error(`Runtime evidence sources exceed the cumulative ${this.policy.maxSourceBytes}-byte cap`);
+            }
+        }
+        let expandedReferenceCount = 0;
+        for (const path of paths) {
+            const sourcePath = relative(context.repositoryRoot, path).replace(/\\/g, '/');
+            const content = await readFile(path, 'utf8');
+            const document = JSON.parse(content);
+            const sourceDigest = sha256(content);
+            for (const resourceSpan of document.resourceSpans ?? []) {
+                const resourceAttributes = resourceSpan.resource?.attributes;
+                const configuredServiceName = attribute(resourceAttributes, 'service.name');
+                const serviceName = configuredServiceName ?? 'unknown';
+                const serviceVersion = attribute(resourceAttributes, 'service.version') ?? '';
+                const environment = attribute(resourceAttributes, 'deployment.environment.name');
+                const serviceInstanceId = attribute(resourceAttributes, 'service.instance.id');
+                for (const scope of resourceSpan.scopeSpans ?? []) {
+                    for (const span of scope.spans ?? []) {
+                        expandedReferenceCount += 1;
+                        if (expandedReferenceCount > this.policy.maxReferences) {
+                            throw new Error(`Runtime evidence expands beyond the ${this.policy.maxReferences}-reference cap`);
+                        }
+                        const capability = this.policy.capabilityKeys
+                            .map((key) => attribute(span.attributes, key))
+                            .find(Boolean);
+                        const operation = this.policy.operationKeys
+                            .map((key) => attribute(span.attributes, key))
+                            .find(Boolean);
+                        const observedAt = parseUnixNano(span.endTimeUnixNano ?? span.startTimeUnixNano);
+                        const ageMs = observedAt ? this.now().getTime() - observedAt.getTime() : undefined;
+                        const retentionMs = this.policy.retentionDays * 24 * 60 * 60 * 1000;
+                        const reason = serviceVersion !== context.commitSha
+                            ? 'service.version does not match snapshot commit SHA'
+                            : !configuredServiceName
+                                ? 'service.name is required by runtime evidence policy'
+                                : this.policy.allowedServiceNames &&
+                                    !this.policy.allowedServiceNames.includes(configuredServiceName)
+                                    ? 'service.name is not allowed by runtime evidence policy'
+                                    : this.policy.requireEnvironment && !environment
+                                        ? 'deployment.environment.name is required by runtime evidence policy'
+                                        : environment &&
+                                            this.policy.allowedEnvironments &&
+                                            !this.policy.allowedEnvironments.includes(environment)
+                                            ? 'deployment.environment.name is not allowed by runtime evidence policy'
+                                            : this.policy.requireServiceInstance && !serviceInstanceId
+                                                ? 'service.instance.id is required by runtime evidence policy'
+                                                : !validOtelId(span.traceId, 32) || !validOtelId(span.spanId, 16)
+                                                    ? 'runtime evidence trace/span identity is missing or invalid'
+                                                    : !observedAt
+                                                        ? 'runtime evidence timestamp is missing or invalid'
+                                                        : !capability
+                                                            ? 'runtime evidence capability is required'
+                                                            : !operation
+                                                                ? 'runtime evidence operation is required'
+                                                                : ageMs !== undefined && ageMs < 0
+                                                                    ? 'runtime evidence timestamp is in the future'
+                                                                    : ageMs !== undefined && ageMs > retentionMs
+                                                                        ? `runtime evidence is outside the ${this.policy.retentionDays}-day retention window`
+                                                                        : undefined;
+                        references.push({
+                            traceId: span.traceId,
+                            spanId: span.spanId,
+                            serviceName,
+                            serviceVersion,
+                            capability,
+                            operation,
+                            environment,
+                            serviceInstanceId,
+                            observedAt: observedAt?.toISOString(),
+                            sourcePath,
+                            sourceDigest,
+                            accepted: reason === undefined,
+                            reason,
+                        });
+                    }
+                }
+            }
+        }
+        const unique = new Map();
+        for (const reference of references) {
+            const key = `${reference.traceId}:${reference.spanId}`;
+            const existing = unique.get(key);
+            if (!existing || preferRuntimeReference(reference, existing) < 0) {
+                unique.set(key, reference);
+            }
+        }
+        return [...unique.values()].sort(preferRuntimeReference).slice(0, this.policy.maxReferences);
+    }
+}
+function validOtelId(value, length) {
+    return new RegExp(`^[a-f0-9]{${length}}$`, 'i').test(value) && !/^0+$/.test(value);
+}
+function preferRuntimeReference(left, right) {
+    return (Number(right.accepted) - Number(left.accepted) ||
+        (right.observedAt ?? '').localeCompare(left.observedAt ?? '') ||
+        left.sourcePath.localeCompare(right.sourcePath) ||
+        left.traceId.localeCompare(right.traceId) ||
+        left.spanId.localeCompare(right.spanId));
+}
+function parseUnixNano(value) {
+    if (!value || !/^\d+$/.test(value))
+        return undefined;
+    const milliseconds = Number(BigInt(value) / 1000000n);
+    if (!Number.isFinite(milliseconds))
+        return undefined;
+    const parsed = new Date(milliseconds);
+    return Number.isNaN(parsed.getTime()) ? undefined : parsed;
+}
+export async function captureValidationTrace(outputPath, options) {
+    const exporter = new InMemorySpanExporter();
+    const provider = new BasicTracerProvider({
+        resource: resourceFromAttributes({
+            'service.name': options.serviceName,
+            'service.version': options.serviceVersion,
+            'deployment.environment.name': options.environment,
+        }),
+        spanProcessors: [new SimpleSpanProcessor(exporter)],
+    });
+    const tracer = provider.getTracer('context-graph-validation', '1.0.0');
+    const span = tracer.startSpan(options.operation ?? 'context-graph.validation', {
+        attributes: {
+            'context.graph.capability': options.capability,
+            'context.graph.operation': options.operation ?? 'context-graph.validation',
+        },
+    });
+    try {
+        await options.run();
+    }
+    catch (error) {
+        span.recordException(error);
+        throw error;
+    }
+    finally {
+        span.end();
+        await provider.forceFlush();
+    }
+    const spans = exporter.getFinishedSpans();
+    const document = {
+        resourceSpans: [
+            {
+                resource: {
+                    attributes: [
+                        { key: 'service.name', value: { stringValue: options.serviceName } },
+                        { key: 'service.version', value: { stringValue: options.serviceVersion } },
+                        {
+                            key: 'service.instance.id',
+                            value: { stringValue: options.serviceInstanceId ?? 'context-graph-validation' },
+                        },
+                        {
+                            key: 'deployment.environment.name',
+                            value: { stringValue: options.environment },
+                        },
+                    ],
+                },
+                scopeSpans: [
+                    {
+                        spans: spans.map((finished) => ({
+                            traceId: finished.spanContext().traceId,
+                            spanId: finished.spanContext().spanId,
+                            name: finished.name,
+                            startTimeUnixNano: hrTimeToUnixNano(finished.startTime),
+                            endTimeUnixNano: hrTimeToUnixNano(finished.endTime),
+                            attributes: [
+                                {
+                                    key: 'context.graph.capability',
+                                    value: { stringValue: options.capability },
+                                },
+                                {
+                                    key: 'context.graph.operation',
+                                    value: { stringValue: options.operation ?? finished.name },
+                                },
+                            ],
+                        })),
+                    },
+                ],
+            },
+        ],
+    };
+    await mkdir(dirname(outputPath), { recursive: true });
+    const serialized = `${JSON.stringify(document, null, 2)}\n`;
+    await writeFile(outputPath, serialized, 'utf8');
+    if (options.backendUrl) {
+        const response = await fetch(options.backendUrl, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: serialized,
+        });
+        if (!response.ok) {
+            throw new Error(`OTLP backend rejected validation trace with HTTP ${response.status}`);
+        }
+    }
+    trace.disable();
+}
+function hrTimeToUnixNano(value) {
+    return (BigInt(value[0]) * 1000000000n + BigInt(value[1])).toString();
+}

package/dist/governance/governance.d.ts

@@ -0,0 +1,60 @@
+import type { GraphSnapshot } from "@weftlet/core";
+export interface ArchitecturePolicy {
+    schemaVersion: 1;
+    roots: string[];
+    modules: {
+        id: string;
+        path: string;
+        domain: string;
+        layer: string;
+        adapter?: boolean;
+    }[];
+    contracts?: {
+        path: string;
+        owner: string;
+    }[];
+    rules: {
+        id: string;
+        kind: 'forbidden-import' | 'no-cycles' | 'contract-owner';
+        from?: string;
+        to?: string;
+        approved: boolean;
+        approvalRef?: string;
+        transitive?: boolean;
+    }[];
+    advisory: {
+        maxLines: number;
+        maxComplexity: number;
+        duplicateMinTokens: number;
+    };
+    baseline?: {
+        fingerprint: string;
+        approvalRef: string;
+        reason: string;
+    }[];
+    exceptions?: {
+        fingerprint: string;
+        ruleId: string;
+        from: string;
+        to: string;
+        expires: string;
+        approvalRef: string;
+        reason: string;
+    }[];
+}
+export interface GovernanceFinding {
+    category: 'rule-violation' | 'extraction-gap' | 'infrastructure-failure' | 'advisory';
+    ruleId: string;
+    from: string;
+    to: string;
+    message: string;
+    fingerprint: string;
+    disposition: 'new' | 'baseline' | 'exception';
+}
+export declare function analyzeArchitecture(root: string, policy: ArchitecturePolicy, policyPath?: string): Promise<{
+    policyPath: string;
+    inputDigest: string;
+    snapshot: GraphSnapshot;
+    findings: GovernanceFinding[];
+    passed: boolean;
+}>;