weavatrix 0.2.12 → 0.2.14

package/src/analysis/allowed-test-runner.js

@@ -19,29 +19,40 @@ function packageManager(repoRoot) {
   return 'npm'
 }
 
-export function validateTestRequests(repoRoot, requests = []) {
-  const manifest = manifestAt(repoRoot)
-  if (!manifest) return {ok: false, reason: 'package.json is missing or unreadable', tests: []}
+function normalizeTestRequests(requests = []) {
   const tests = []
-  for (const request of requests.slice(0, 5)) {
+  for (const request of (Array.isArray(requests) ? requests : []).slice(0, 5)) {
     const script = String(request?.script || '')
     const args = Array.isArray(request?.args) ? request.args.slice(0, 40).map(String) : []
     if (!SAFE_SCRIPT.test(script)) return {ok: false, reason: `script ${script || '(missing)'} is outside the test/check/verify allowlist`, tests}
-    if (!Object.hasOwn(manifest.scripts || {}, script)) return {ok: false, reason: `package.json has no script named ${script}`, tests}
     if (args.some((arg) => arg.length > 300 || UNSAFE_SHELL_ARG.test(arg))) return {ok: false, reason: `script ${script} has an invalid or shell-sensitive argument`, tests}
     tests.push({script, args})
   }
+  return {ok: true, tests}
+}
+
+export function validateTestRequests(repoRoot, requests = []) {
+  const normalized = normalizeTestRequests(requests)
+  if (!normalized.ok || !normalized.tests.length) return normalized
+  const manifest = manifestAt(repoRoot)
+  if (!manifest) return {ok: false, reason: 'package.json is missing or unreadable', tests: []}
+  for (const test of normalized.tests) {
+    if (!Object.hasOwn(manifest.scripts || {}, test.script)) return {ok: false, reason: `package.json has no script named ${test.script}`, tests: []}
+  }
+  const tests = normalized.tests
   return {ok: true, tests, packageManager: packageManager(repoRoot)}
 }
 
 export async function runAllowedTests(repoRoot, requests = [], {enabled = false, timeoutMs = 60_000} = {}) {
-  const checked = validateTestRequests(repoRoot, requests)
-  if (!checked.ok) return {state: 'BLOCKED', reason: checked.reason, results: []}
-  if (!checked.tests.length) return {state: 'NOT_REQUESTED', reason: 'no package scripts were requested', results: []}
+  const normalized = normalizeTestRequests(requests)
+  if (!normalized.ok) return {state: 'BLOCKED', reason: normalized.reason, results: []}
+  if (!normalized.tests.length) return {state: 'NOT_REQUESTED', reason: 'no package scripts were requested', plan: [], results: []}
   if (!enabled || process.env.WEAVATRIX_ALLOW_TEST_RUNS !== '1') return {
     state: 'DISABLED', reason: 'set WEAVATRIX_ALLOW_TEST_RUNS=1 and pass run_tests:true to execute allowlisted package scripts',
-    plan: checked.tests, results: [],
+    plan: normalized.tests, results: [],
   }
+  const checked = validateTestRequests(repoRoot, normalized.tests)
+  if (!checked.ok) return {state: 'BLOCKED', reason: checked.reason, results: []}
   const results = []
   const timeout = Math.max(1000, Math.min(300_000, Number(timeoutMs) || 60_000))
   for (const test of checked.tests) {

package/src/analysis/architecture/contract-graph.js

@@ -0,0 +1,119 @@
+import {architectureHash} from './contract-schema.js'
+
+export const isSymbolNode = (id) => String(id).includes('#')
+const endpointId = (value) => value && typeof value === 'object' ? String(value.id) : String(value ?? '')
+
+export function fileOfNode(id, byId) {
+    const node = byId.get(String(id))
+    if (node?.source_file) return String(node.source_file).replace(/\\/g, '/')
+    return String(id).split('#')[0].replace(/\\/g, '/')
+}
+
+export function componentForFile(file, components) {
+    const normalized = String(file || '').replace(/\\/g, '/')
+    let best = null
+    for (const component of components) for (const prefix of component.paths) {
+        if (normalized !== prefix && !normalized.startsWith(`${prefix}/`)) continue
+        if (!best || prefix.length > best.prefix.length) best = {id: component.id, prefix}
+    }
+    return best?.id || '(unmapped)'
+}
+
+export function relationKind(link) {
+    if (link.typeOnly === true) return 'type-only'
+    if (link.compileOnly === true) return 'compile-only'
+    return 'runtime'
+}
+
+export function runtimeFileGraph(graph) {
+    const byId = new Map((graph.nodes || []).map((node) => [String(node.id), node]))
+    const files = new Set((graph.nodes || []).filter((node) => !isSymbolNode(node.id)).map((node) => String(node.id)))
+    const adjacency = new Map([...files].map((file) => [file, new Set()]))
+    for (const link of graph.links || []) {
+        if (relationKind(link) !== 'runtime' || !['imports', 're_exports'].includes(link.relation) || link.barrelProxy === true) continue
+        const source = fileOfNode(endpointId(link.source), byId)
+        const target = fileOfNode(endpointId(link.target), byId)
+        if (source && target && source !== target && files.has(source) && files.has(target)) adjacency.get(source)?.add(target)
+    }
+    return adjacency
+}
+
+export function stronglyConnected(adjacency) {
+    let index = 0
+    const indexes = new Map(), low = new Map(), stack = [], onStack = new Set(), out = []
+    const visit = (node) => {
+        indexes.set(node, index); low.set(node, index); index++; stack.push(node); onStack.add(node)
+        for (const target of adjacency.get(node) || []) {
+            if (!indexes.has(target)) { visit(target); low.set(node, Math.min(low.get(node), low.get(target))) }
+            else if (onStack.has(target)) low.set(node, Math.min(low.get(node), indexes.get(target)))
+        }
+        if (low.get(node) !== indexes.get(node)) return
+        const component = []
+        while (stack.length) {
+            const value = stack.pop()
+            onStack.delete(value)
+            component.push(value)
+            if (value === node) break
+        }
+        if (component.length > 1 || adjacency.get(node)?.has(node)) out.push(component.sort())
+    }
+    for (const node of [...adjacency.keys()].sort()) if (!indexes.has(node)) visit(node)
+    return out.sort((a, b) => b.length - a.length || a[0].localeCompare(b[0]))
+}
+
+export function architectureViolation(ruleId, kind, evidence, current, target) {
+    const normalizedEvidence = String(evidence).replace(/:\d+(?=\b|$)/g, '')
+    const fingerprint = architectureHash({ruleId, kind, evidence: normalizedEvidence}).slice(0, 32)
+    return {fingerprint, ruleId, kind, evidence, ...(current != null ? {current} : {}), ...(target != null ? {target} : {})}
+}
+
+export const matchComponentSelector = (selector, value) => selector.includes('*') || selector.includes(value)
+
+export function collectComponentEdges(graph, contract) {
+    const nodes = Array.isArray(graph?.nodes) ? graph.nodes : []
+    const links = Array.isArray(graph?.links) ? graph.links : []
+    const byId = new Map(nodes.map((node) => [String(node.id), node]))
+    const componentEdges = new Map()
+    for (const link of links) {
+        if (!['imports', 're_exports', 'calls', 'references'].includes(link.relation) || link.barrelProxy === true) continue
+        const fromFile = fileOfNode(endpointId(link.source), byId)
+        const toFile = fileOfNode(endpointId(link.target), byId)
+        if (!fromFile || !toFile || fromFile === toFile) continue
+        const from = componentForFile(fromFile, contract.components)
+        const to = componentForFile(toFile, contract.components)
+        if (from === to) continue
+        const kind = relationKind(link)
+        const key = `${from}\0${to}\0${kind}`
+        const record = componentEdges.get(key) || {from, to, kind, count: 0, samples: []}
+        record.count++
+        if (record.samples.length < 5) record.samples.push(`${fromFile} -> ${toFile}`)
+        componentEdges.set(key, record)
+    }
+    return {nodes, links, byId, componentEdges}
+}
+
+export function collectComponentFitness(nodes, links, byId, contract) {
+    const stats = new Map(contract.components.map((component) => [component.id, {
+        files: new Set(), internalPairs: new Set(), boundaryPairs: new Set(),
+    }]))
+    for (const node of nodes.filter((item) => !isSymbolNode(item.id))) {
+        const file = String(node.source_file || node.id).replace(/\\/g, '/')
+        stats.get(componentForFile(file, contract.components))?.files.add(file)
+    }
+    const runtimePairs = new Set()
+    for (const link of links) {
+        if (relationKind(link) !== 'runtime' || !['imports', 're_exports', 'calls', 'references'].includes(link.relation) || link.barrelProxy === true) continue
+        const source = fileOfNode(endpointId(link.source), byId), target = fileOfNode(endpointId(link.target), byId)
+        if (!source || !target || source === target) continue
+        const pair = `${source}\0${target}`
+        if (runtimePairs.has(pair)) continue
+        runtimePairs.add(pair)
+        const from = componentForFile(source, contract.components), to = componentForFile(target, contract.components)
+        if (from === to) stats.get(from)?.internalPairs.add(pair)
+        else {
+            stats.get(from)?.boundaryPairs.add(pair)
+            stats.get(to)?.boundaryPairs.add(pair)
+        }
+    }
+    return stats
+}

package/src/analysis/architecture/contract-schema.js

@@ -0,0 +1,110 @@
+import {createHash} from 'node:crypto'
+
+export const ARCHITECTURE_CONTRACT_V = 1
+
+const RELATION_KIND = new Set(['runtime', 'type-only', 'compile-only', 'any'])
+const ACTION = new Set(['allow', 'forbid'])
+const ENFORCEMENT = new Set(['ratchet', 'strict', 'advisory'])
+
+export const safeArchitectureId = (value, fallback = '') => {
+    const text = String(value ?? '').trim()
+    return /^[a-z0-9][a-z0-9._:-]{0,127}$/i.test(text) ? text : fallback
+}
+
+export const architecturePathPrefix = (value) => {
+    const text = String(value ?? '').replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+|\/+$/g, '')
+    return text && !text.split('/').some((part) => !part || part === '.' || part === '..') ? text : null
+}
+
+export const finiteArchitectureBudget = (value, fallback = null) => {
+    const number = Number(value)
+    return Number.isFinite(number) && number >= 0 ? number : fallback
+}
+
+const stringList = (value, sanitize, cap = 100) => [...new Set((Array.isArray(value) ? value : [])
+    .slice(0, cap).map(sanitize).filter(Boolean))]
+
+const stable = (value) => Array.isArray(value)
+    ? `[${value.map(stable).join(',')}]`
+    : value && typeof value === 'object'
+        ? `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stable(value[key])}`).join(',')}}`
+        : JSON.stringify(value)
+
+export const architectureHash = (value) => createHash('sha256').update(stable(value)).digest('hex')
+
+function sanitizeComponent(value, index) {
+    const id = safeArchitectureId(value?.id, `component-${index + 1}`)
+    const paths = stringList(value?.paths ?? [value?.path], architecturePathPrefix, 64)
+    if (!paths.length) return null
+    return {id, name: String(value?.name || id).slice(0, 128), paths}
+}
+
+function sanitizeRule(value, index) {
+    const from = stringList(value?.from, (item) => item === '*' ? '*' : safeArchitectureId(item), 64)
+    const to = stringList(value?.to, (item) => item === '*' ? '*' : safeArchitectureId(item), 64)
+    if (!from.length || !to.length) return null
+    return {
+        id: safeArchitectureId(value?.id, `dependency-${index + 1}`),
+        action: ACTION.has(value?.action) ? value.action : 'forbid',
+        kinds: stringList(value?.kinds ?? ['runtime'], (kind) => RELATION_KIND.has(kind) ? kind : '', 4),
+        from,
+        to,
+        ...(value?.reason ? {reason: String(value.reason).slice(0, 300)} : {}),
+    }
+}
+
+function sanitizeException(value) {
+    const fingerprint = /^[a-f0-9]{16,64}$/i.test(String(value?.fingerprint || '')) ? String(value.fingerprint) : null
+    if (!fingerprint) return null
+    const expires = /^\d{4}-\d{2}-\d{2}$/.test(String(value?.expires || '')) ? String(value.expires) : null
+    return {fingerprint, reason: String(value?.reason || '').slice(0, 300), ...(expires ? {expires} : {})}
+}
+
+function normalizeBudgets(raw = {}) {
+    const budgets = {
+        runtimeCycles: finiteArchitectureBudget(raw.runtimeCycles),
+        maxFunctionLoc: finiteArchitectureBudget(raw.maxFunctionLoc),
+        maxFileLoc: finiteArchitectureBudget(raw.maxFileLoc),
+        maxCyclomatic: finiteArchitectureBudget(raw.maxCyclomatic),
+        maxParams: finiteArchitectureBudget(raw.maxParams),
+        maxRuntimeDependenciesPerComponent: finiteArchitectureBudget(raw.maxRuntimeDependenciesPerComponent),
+        maxModuleFiles: finiteArchitectureBudget(raw.maxModuleFiles),
+        minModuleCohesion: finiteArchitectureBudget(raw.minModuleCohesion),
+        maxModuleBoundaryRatio: finiteArchitectureBudget(raw.maxModuleBoundaryRatio),
+    }
+    for (const key of Object.keys(budgets)) if (budgets[key] == null) delete budgets[key]
+    return budgets
+}
+
+export function normalizeArchitectureContract(input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input)) throw new Error('architecture contract must be an object')
+    const components = (Array.isArray(input.components) ? input.components : [])
+        .slice(0, 200).map(sanitizeComponent).filter(Boolean)
+    const componentIds = new Set(components.map((item) => item.id))
+    const dependencyRules = (Array.isArray(input.dependencyRules) ? input.dependencyRules : [])
+        .slice(0, 500).map(sanitizeRule).filter(Boolean)
+        .filter((rule) => [...rule.from, ...rule.to].every((id) => id === '*' || componentIds.has(id)))
+    const baseline = input.ratchet?.baseline && typeof input.ratchet.baseline === 'object'
+        ? {
+            fingerprints: stringList(input.ratchet.baseline.fingerprints, (item) => /^[a-f0-9]{16,64}$/i.test(String(item)) ? String(item) : '', 5_000),
+            metrics: Object.fromEntries(Object.entries(input.ratchet.baseline.metrics || {}).slice(0, 500)
+                .map(([key, value]) => [safeArchitectureId(key), finiteArchitectureBudget(value)]).filter(([key, value]) => key && value != null)),
+        }
+        : {fingerprints: [], metrics: {}}
+    const contract = {
+        architectureContractV: ARCHITECTURE_CONTRACT_V,
+        name: String(input.name || 'Target architecture').slice(0, 128),
+        style: safeArchitectureId(input.style, 'custom'),
+        enforcement: ENFORCEMENT.has(input.enforcement) ? input.enforcement : 'ratchet',
+        components,
+        dependencyRules,
+        budgets: normalizeBudgets(input.budgets),
+        technologies: {
+            required: stringList(input.technologies?.required, (item) => safeArchitectureId(item), 100),
+            forbidden: stringList(input.technologies?.forbidden, (item) => safeArchitectureId(item), 100),
+        },
+        exceptions: (Array.isArray(input.exceptions) ? input.exceptions : []).slice(0, 500).map(sanitizeException).filter(Boolean),
+        ratchet: {baseline},
+    }
+    return {...contract, contractHash: architectureHash(contract)}
+}

package/src/analysis/architecture/contract-storage.js

@@ -0,0 +1,35 @@
+import {existsSync, readFileSync, writeFileSync, mkdirSync} from 'node:fs'
+import {dirname, join} from 'node:path'
+import {createRepoBoundary} from '../../repo-path.js'
+import {normalizeArchitectureContract} from './contract-schema.js'
+
+export const CONTRACT_PATHS = ['.weavatrix/architecture.json', '.weavatrix-architecture.json']
+
+const readContract = (path, source) => {
+    try {
+        return {contract: normalizeArchitectureContract(JSON.parse(readFileSync(path, 'utf8'))), source}
+    } catch (error) {
+        return {contract: null, source, error: error.message}
+    }
+}
+
+export function loadArchitectureContract(repoRoot, graphPath) {
+    const boundary = createRepoBoundary(repoRoot)
+    for (const relative of CONTRACT_PATHS) {
+        const resolved = boundary.resolve(relative)
+        if (resolved.ok && existsSync(resolved.path)) return readContract(resolved.path, relative)
+    }
+    const cached = graphPath ? join(dirname(graphPath), 'architecture.contract.json') : null
+    return cached && existsSync(cached)
+        ? readContract(cached, 'hosted-cache')
+        : {contract: null, source: null, error: null}
+}
+
+export function writeCachedArchitectureContract(graphPath, input) {
+    if (!graphPath) throw new Error('graph path is required for hosted contract cache')
+    const contract = normalizeArchitectureContract(input)
+    const path = join(dirname(graphPath), 'architecture.contract.json')
+    mkdirSync(dirname(path), {recursive: true})
+    writeFileSync(path, JSON.stringify(contract, null, 2), 'utf8')
+    return {path, contract}
+}

package/src/analysis/architecture/contract-verification.js

@@ -0,0 +1,168 @@
+import {
+    architectureHash,
+    architecturePathPrefix,
+    finiteArchitectureBudget,
+    normalizeArchitectureContract,
+} from './contract-schema.js'
+import {
+    architectureViolation as violation,
+    collectComponentEdges,
+    collectComponentFitness,
+    componentForFile,
+    fileOfNode,
+    isSymbolNode,
+    matchComponentSelector as matches,
+    runtimeFileGraph,
+    stronglyConnected,
+} from './contract-graph.js'
+
+function dependencyViolations(componentEdges, contract) {
+    const violations = []
+    for (const edge of componentEdges.values()) {
+        const applicable = contract.dependencyRules.filter((rule) =>
+            rule.kinds.some((kind) => kind === 'any' || kind === edge.kind) && matches(rule.from, edge.from))
+        for (const rule of applicable) if (rule.action === 'forbid' && matches(rule.to, edge.to)) {
+            violations.push(violation(rule.id, 'dependency', `${edge.from} -> ${edge.to} (${edge.kind})`, edge.count, 0))
+        }
+        const allowRules = applicable.filter((rule) => rule.action === 'allow')
+        if (allowRules.length && !allowRules.some((rule) => matches(rule.to, edge.to))) {
+            const ruleId = allowRules.map((rule) => rule.id).sort().join('+')
+            violations.push(violation(ruleId, 'dependency', `${edge.from} -> ${edge.to} (${edge.kind}; outside allow-list)`, edge.count, 0))
+        }
+    }
+    return violations
+}
+
+function componentBudgetViolations(componentEdges, stats, contract) {
+    const violations = []
+    const targetsByComponent = new Map()
+    for (const edge of componentEdges.values()) if (edge.kind === 'runtime') {
+        const targets = targetsByComponent.get(edge.from) || new Set()
+        targets.add(edge.to)
+        targetsByComponent.set(edge.from, targets)
+    }
+    if (contract.budgets.maxRuntimeDependenciesPerComponent != null) for (const [component, targets] of targetsByComponent) {
+        if (targets.size > contract.budgets.maxRuntimeDependenciesPerComponent) violations.push(violation(
+            'budget.maxRuntimeDependenciesPerComponent', 'budget', `${component} runtime dependencies`, targets.size,
+            contract.budgets.maxRuntimeDependenciesPerComponent,
+        ))
+    }
+    for (const [component, item] of stats) {
+        const internal = item.internalPairs.size, boundary = item.boundaryPairs.size
+        const cohesion = internal + boundary ? internal / (internal + boundary) : 1
+        const boundaryRatio = internal + boundary ? boundary / (internal + boundary) : 0
+        if (contract.budgets.maxModuleFiles != null && item.files.size > contract.budgets.maxModuleFiles) {
+            violations.push(violation('budget.maxModuleFiles', 'budget', `${component} files`, item.files.size, contract.budgets.maxModuleFiles))
+        }
+        if (contract.budgets.minModuleCohesion != null && cohesion < contract.budgets.minModuleCohesion) {
+            violations.push(violation('budget.minModuleCohesion', 'budget', `${component} cohesion`, Number(cohesion.toFixed(4)), contract.budgets.minModuleCohesion))
+        }
+        if (contract.budgets.maxModuleBoundaryRatio != null && boundaryRatio > contract.budgets.maxModuleBoundaryRatio) {
+            violations.push(violation('budget.maxModuleBoundaryRatio', 'budget', `${component} boundary ratio`, Number(boundaryRatio.toFixed(4)), contract.budgets.maxModuleBoundaryRatio))
+        }
+    }
+    return violations
+}
+
+function codeBudgetViolations(nodes, byId, contract) {
+    const violations = []
+    for (const node of nodes) {
+        const loc = finiteArchitectureBudget(node?.complexity?.loc)
+        const cyclomatic = finiteArchitectureBudget(node?.complexity?.cyclomatic)
+        const params = finiteArchitectureBudget(node?.complexity?.params)
+        const evidence = `${node.source_file || fileOfNode(node.id, byId)}#${node.label || node.id}`
+        if (contract.budgets.maxFunctionLoc != null && loc != null && loc > contract.budgets.maxFunctionLoc) {
+            violations.push(violation('budget.maxFunctionLoc', 'budget', evidence, loc, contract.budgets.maxFunctionLoc))
+        }
+        if (contract.budgets.maxCyclomatic != null && cyclomatic != null && cyclomatic > contract.budgets.maxCyclomatic) {
+            violations.push(violation('budget.maxCyclomatic', 'budget', evidence, cyclomatic, contract.budgets.maxCyclomatic))
+        }
+        if (contract.budgets.maxParams != null && params != null && params > contract.budgets.maxParams) {
+            violations.push(violation('budget.maxParams', 'budget', evidence, params, contract.budgets.maxParams))
+        }
+    }
+    if (contract.budgets.maxFileLoc != null) for (const node of nodes.filter((item) => !isSymbolNode(item.id))) {
+        const file = String(node.source_file || node.id)
+        const physicalLoc = finiteArchitectureBudget(node.physical_loc)
+        if (physicalLoc != null && physicalLoc > contract.budgets.maxFileLoc) {
+            violations.push(violation('budget.maxFileLoc', 'budget', file, physicalLoc, contract.budgets.maxFileLoc))
+        }
+    }
+    return violations
+}
+
+function technologyViolations(contract, technologies) {
+    const techSet = new Set(technologies.map((item) => String(item ?? '').trim()).filter(Boolean))
+    const violations = []
+    for (const required of contract.technologies.required) if (!techSet.has(required)) {
+        violations.push(violation('technology.required', 'technology', `missing ${required}`))
+    }
+    for (const forbidden of contract.technologies.forbidden) if (techSet.has(forbidden)) {
+        violations.push(violation('technology.forbidden', 'technology', `forbidden ${forbidden}`))
+    }
+    return violations
+}
+
+const componentFitnessMetrics = (stats) => Object.fromEntries([...stats].map(([component, item]) => {
+    const internal = item.internalPairs.size, boundary = item.boundaryPairs.size
+    return [component, {
+        files: item.files.size,
+        cohesion: internal + boundary ? Number((internal / (internal + boundary)).toFixed(4)) : 1,
+        boundaryRatio: internal + boundary ? Number((boundary / (internal + boundary)).toFixed(4)) : 0,
+    }]
+}))
+
+export function verifyArchitecture({graph, contract: rawContract, technologies = []}) {
+    const contract = rawContract?.contractHash ? rawContract : normalizeArchitectureContract(rawContract)
+    const {nodes, links, byId, componentEdges} = collectComponentEdges(graph, contract)
+    const stats = collectComponentFitness(nodes, links, byId, contract)
+    const runtimeCycles = stronglyConnected(runtimeFileGraph(graph))
+    const violations = [
+        ...dependencyViolations(componentEdges, contract),
+        ...componentBudgetViolations(componentEdges, stats, contract),
+        ...codeBudgetViolations(nodes, byId, contract),
+        ...technologyViolations(contract, technologies),
+    ]
+    if (contract.budgets.runtimeCycles != null && runtimeCycles.length > contract.budgets.runtimeCycles) {
+        violations.push(violation('budget.runtimeCycles', 'budget', `runtime cycles: ${runtimeCycles.length}`, runtimeCycles.length, contract.budgets.runtimeCycles))
+    }
+    const exceptions = new Set(contract.exceptions
+        .filter((item) => !item.expires || item.expires >= new Date().toISOString().slice(0, 10))
+        .map((item) => item.fingerprint))
+    const active = violations.filter((item) => !exceptions.has(item.fingerprint))
+    const baseline = new Set(contract.ratchet.baseline.fingerprints)
+    const current = new Set(active.map((item) => item.fingerprint))
+    const fresh = active.filter((item) => !baseline.has(item.fingerprint))
+    const existing = active.filter((item) => baseline.has(item.fingerprint))
+    const fixed = [...baseline].filter((fingerprint) => !current.has(fingerprint))
+    const status = contract.enforcement === 'advisory'
+        ? 'ADVISORY'
+        : contract.enforcement === 'strict' ? (active.length ? 'FAIL' : 'PASS') : (fresh.length ? 'FAIL' : 'PASS')
+    const result = {
+        architectureVerificationV: 1,
+        contractHash: contract.contractHash,
+        status,
+        enforcement: contract.enforcement,
+        metrics: {
+            runtimeCycles: runtimeCycles.length,
+            violations: active.length,
+            componentDependencies: componentEdges.size,
+            mappedComponents: contract.components.length,
+            componentFitness: componentFitnessMetrics(stats),
+        },
+        new: fresh,
+        existing,
+        fixed,
+        excepted: violations.filter((item) => exceptions.has(item.fingerprint)),
+        componentEdges: [...componentEdges.values()].sort((a, b) => a.from.localeCompare(b.from) || a.to.localeCompare(b.to) || a.kind.localeCompare(b.kind)),
+        runtimeCycles: runtimeCycles.slice(0, 100),
+    }
+    return {...result, verificationHash: architectureHash(result)}
+}
+
+export function contractForChange(contract, files = []) {
+    const normalized = (Array.isArray(files) ? files.slice(0, 200) : []).map(architecturePathPrefix).filter(Boolean)
+    const components = [...new Set(normalized.map((file) => componentForFile(file, contract.components)))]
+    const rules = contract.dependencyRules.filter((rule) => components.some((component) => matches(rule.from, component) || matches(rule.to, component)))
+    return {files: normalized, components, rules, budgets: contract.budgets, technologies: contract.technologies}
+}