context-probe 0.1.0

package/dist/src/core/scaffold-source-groups.js

@@ -0,0 +1,123 @@
+import path from "node:path";
+import { classifySubgroup, findSourceRootIndex, inferGroupOrigin } from "./scaffold-source-group-classification.js";
+import { mergeMonorepoEquivalentGroups } from "./scaffold-source-group-merge.js";
+import { normalizeSegmentKey } from "./scaffold-source-group-naming.js";
+export { LAYER_PRIORITY_HINTS } from "./scaffold-source-group-constants.js";
+export { inferGroupDisplayName, inferGroupNames } from "./scaffold-source-group-naming.js";
+export function groupSourceFiles(codebase) {
+    const groups = new Map();
+    for (const filePath of codebase.scorableSourceFiles) {
+        const parts = filePath.split("/");
+        if (parts.length === 0) {
+            continue;
+        }
+        let key = "__root__";
+        let basePath = "";
+        let sourceRoot;
+        let segment;
+        let heuristicSplit = false;
+        let origins = [];
+        let pathGlobs = [filePath];
+        const sourceRootIndex = findSourceRootIndex(parts);
+        if (sourceRootIndex >= 0) {
+            const rootName = parts[sourceRootIndex];
+            if (!rootName) {
+                continue;
+            }
+            sourceRoot = rootName;
+            const prefix = parts.slice(0, sourceRootIndex).join("/");
+            const segmentName = parts[sourceRootIndex + 1];
+            basePath = prefix ? `${prefix}/${sourceRoot}` : sourceRoot;
+            if (segmentName && !path.extname(segmentName)) {
+                segment = segmentName;
+                basePath = `${basePath}/${segment}`;
+                key = basePath;
+                pathGlobs = [`${basePath}/**`];
+            }
+            else {
+                key = `${basePath}/__root__`;
+            }
+        }
+        else if (parts.length >= 2) {
+            const segmentName = parts[0];
+            if (!segmentName) {
+                continue;
+            }
+            segment = segmentName;
+            basePath = segment;
+            key = segment;
+            pathGlobs = [`${basePath}/**`];
+        }
+        const classifiedSegment = classifySubgroup(segment, filePath, basePath);
+        if (classifiedSegment) {
+            key = `__heuristic__/${normalizeSegmentKey(classifiedSegment)}`;
+            segment = classifiedSegment;
+            heuristicSplit = true;
+            origins = [inferGroupOrigin(basePath, sourceRoot, filePath)];
+            basePath = origins[0] ?? "";
+            pathGlobs = [filePath];
+        }
+        const group = groups.get(key) ?? {
+            key,
+            basePath,
+            ...(sourceRoot ? { sourceRoot } : {}),
+            ...(segment ? { segment } : {}),
+            ...(heuristicSplit ? { heuristicSplit: true } : {}),
+            ...(origins.length > 0 ? { origins } : {}),
+            pathGlobs,
+            files: [],
+        };
+        group.files.push(filePath);
+        if (heuristicSplit) {
+            group.heuristicSplit = true;
+            for (const origin of origins) {
+                if (!(group.origins ?? []).includes(origin)) {
+                    group.origins = [...(group.origins ?? []), origin];
+                }
+            }
+        }
+        for (const glob of pathGlobs) {
+            if (!group.pathGlobs.includes(glob)) {
+                group.pathGlobs.push(glob);
+            }
+        }
+        groups.set(key, group);
+    }
+    return mergeMonorepoEquivalentGroups(Array.from(groups.values()))
+        .map((group) => ({ ...group, files: group.files.sort(), pathGlobs: group.pathGlobs.sort() }))
+        .sort((left, right) => left.key.localeCompare(right.key));
+}
+export function collectMarkerGlobs(group, markers) {
+    const globs = new Set();
+    const markerFiles = new Set();
+    for (const filePath of group.files) {
+        const matchingOrigin = group.origins
+            ?.slice()
+            .sort((left, right) => right.length - left.length)
+            .find((origin) => filePath.startsWith(`${origin}/`)) ?? group.basePath;
+        const relative = matchingOrigin && filePath.startsWith(`${matchingOrigin}/`)
+            ? filePath.slice(matchingOrigin.length + 1)
+            : group.basePath && filePath.startsWith(`${group.basePath}/`)
+                ? filePath.slice(group.basePath.length + 1)
+                : filePath;
+        const relativeParts = relative.split("/");
+        for (const segment of relativeParts.slice(0, -1)) {
+            if (markers.has(segment.toLowerCase())) {
+                if (matchingOrigin) {
+                    globs.add(`${matchingOrigin}/${segment}/**`);
+                }
+                else if (group.basePath) {
+                    globs.add(`${group.basePath}/${segment}/**`);
+                }
+                else {
+                    globs.add(`${segment}/**`);
+                }
+            }
+        }
+        const baseName = path.basename(filePath, path.extname(filePath)).toLowerCase();
+        if (Array.from(markers).some((marker) => baseName.includes(marker))) {
+            markerFiles.add(filePath);
+        }
+    }
+    return globs.size > 0 ? Array.from(globs).sort() : Array.from(markerFiles).sort();
+}

package/dist/src/core/scaffold-types.d.ts

@@ -0,0 +1,30 @@
+import type { ArchitectureLayerCandidate, CodebaseAnalysis, DomainContextCandidate, Evidence, ExtractionBackend, ExtractionProviderName, ReviewResolutionLog } from "./contracts.js";
+export interface ExtractionOptions {
+    root: string;
+    cwd: string;
+    extractor?: ExtractionBackend;
+    provider?: ExtractionProviderName;
+    providerCommand?: string;
+    promptProfile?: string;
+    fallback?: "heuristic" | "none";
+    reviewLog?: ReviewResolutionLog;
+    applyReviewLog?: boolean;
+}
+export interface SourceGroup {
+    key: string;
+    basePath: string;
+    sourceRoot?: string;
+    segment?: string;
+    heuristicSplit?: boolean;
+    origins?: string[];
+    pathGlobs: string[];
+    files: string[];
+}
+export interface ScaffoldComputation<T> {
+    result: T;
+    confidence: number;
+    evidence: Evidence[];
+    unknowns: string[];
+    diagnostics: string[];
+}
+export type { ArchitectureLayerCandidate, CodebaseAnalysis, DomainContextCandidate };

package/dist/src/core/scaffold-types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/core/scaffold.d.ts

@@ -0,0 +1,2 @@
+export { scaffoldArchitectureConstraints } from "./scaffold-architecture.js";
+export { scaffoldDomainModel } from "./scaffold-domain.js";

package/dist/src/core/scaffold.js

@@ -0,0 +1,2 @@
+export { scaffoldArchitectureConstraints } from "./scaffold-architecture.js";
+export { scaffoldDomainModel } from "./scaffold-domain.js";

package/dist/src/core/scoring-shared.d.ts

@@ -0,0 +1,12 @@
+import type { BoundaryLeakFinding, MetricScore } from "./contracts.js";
+import { average, clamp01 } from "./shared-utils.js";
+export declare function computeLeakRatio(leaks: BoundaryLeakFinding[], applicableReferences: number): number;
+export declare function toMetricScore(metricId: string, value: number, components: Record<string, number>, evidenceRefs: string[], confidence: number, unknowns: string[]): MetricScore;
+export { average, clamp01 };
+export declare function weightedAverage(entries: Array<{
+    value: number | undefined;
+    weight: number;
+}>, fallback: number): number;
+export declare function dedupeEvidence<T extends {
+    evidenceId: string;
+}>(items: T[]): T[];

package/dist/src/core/scoring-shared.js

@@ -0,0 +1,39 @@
+import { average, clamp01 } from "./shared-utils.js";
+export function computeLeakRatio(leaks, applicableReferences) {
+    if (applicableReferences === 0) {
+        return 0;
+    }
+    return leaks.length / applicableReferences;
+}
+export function toMetricScore(metricId, value, components, evidenceRefs, confidence, unknowns) {
+    return {
+        metricId,
+        value,
+        components,
+        confidence,
+        evidenceRefs,
+        unknowns,
+    };
+}
+export { average, clamp01 };
+export function weightedAverage(entries, fallback) {
+    const observed = entries.filter((entry) => entry.value !== undefined && Number.isFinite(entry.value));
+    if (observed.length === 0) {
+        return fallback;
+    }
+    const totalWeight = observed.reduce((sum, entry) => sum + entry.weight, 0);
+    if (totalWeight <= 0) {
+        return fallback;
+    }
+    return observed.reduce((sum, entry) => sum + (entry.value ?? 0) * entry.weight, 0) / totalWeight;
+}
+export function dedupeEvidence(items) {
+    const seen = new Set();
+    return items.filter((item) => {
+        if (seen.has(item.evidenceId)) {
+            return false;
+        }
+        seen.add(item.evidenceId);
+        return true;
+    });
+}

package/dist/src/core/scoring.d.ts

@@ -0,0 +1,2 @@
+export { computeArchitectureScores } from "./architecture-scoring.js";
+export { computeDomainDesignScores } from "./domain-design-scoring.js";

package/dist/src/core/scoring.js

@@ -0,0 +1,2 @@
+export { computeArchitectureScores } from "./architecture-scoring.js";
+export { computeDomainDesignScores } from "./domain-design-scoring.js";

package/dist/src/core/shadow-rollout-gate-reasons.d.ts

@@ -0,0 +1,8 @@
+import type { DomainDesignShadowRolloutGateAggregate } from "./contracts.js";
+export declare function evaluateGateReasons(aggregate: DomainDesignShadowRolloutGateAggregate, observationCount: number, options?: {
+    requireManifestPaths?: boolean;
+    hasMissingVersionedManifestPath?: boolean;
+    minObservationCount?: number;
+    insufficientObservationReason?: string;
+}): string[];
+export declare const SHADOW_ROLLOUT_GATE_CATEGORY_MIN_OBSERVATIONS = 3;

package/dist/src/core/shadow-rollout-gate-reasons.js

@@ -0,0 +1,22 @@
+import { SHADOW_ROLLOUT_MIN_CATEGORY_REPO_OBSERVATIONS, SHADOW_ROLLOUT_MIN_REAL_REPO_OBSERVATIONS, } from "./shadow-rollout-summary.js";
+const SHADOW_ROLLOUT_MAX_WEIGHTED_AVERAGE_DELTA = 0.05;
+const SHADOW_ROLLOUT_MAX_DELTA_RANGE = 0.15;
+export function evaluateGateReasons(aggregate, observationCount, options) {
+    const reasons = [];
+    const minObservationCount = options?.minObservationCount ?? SHADOW_ROLLOUT_MIN_REAL_REPO_OBSERVATIONS;
+    const insufficientObservationReason = options?.insufficientObservationReason ?? "insufficient_real_repo_observations";
+    if (observationCount < minObservationCount) {
+        reasons.push(insufficientObservationReason);
+    }
+    if (options?.requireManifestPaths && options.hasMissingVersionedManifestPath) {
+        reasons.push("missing_versioned_manifest_path");
+    }
+    if (aggregate.deltaRange > SHADOW_ROLLOUT_MAX_DELTA_RANGE) {
+        reasons.push("real_repo_delta_range_above_threshold");
+    }
+    if (Math.abs(aggregate.weightedAverageDelta) > SHADOW_ROLLOUT_MAX_WEIGHTED_AVERAGE_DELTA) {
+        reasons.push("real_repo_weighted_average_delta_above_threshold");
+    }
+    return reasons;
+}
+export const SHADOW_ROLLOUT_GATE_CATEGORY_MIN_OBSERVATIONS = SHADOW_ROLLOUT_MIN_CATEGORY_REPO_OBSERVATIONS;

package/dist/src/core/shadow-rollout-gate-summary.d.ts

@@ -0,0 +1,2 @@
+import type { DomainDesignShadowRolloutGateAggregate, DomainDesignShadowRolloutGateObservation } from "./contracts.js";
+export declare function summarizeGateObservations(observations: DomainDesignShadowRolloutGateObservation[]): DomainDesignShadowRolloutGateAggregate;

package/dist/src/core/shadow-rollout-gate-summary.js

@@ -0,0 +1,36 @@
+export function summarizeGateObservations(observations) {
+    if (observations.length === 0) {
+        return {
+            repoCount: 0,
+            averageDelta: 0,
+            weightedAverageDelta: 0,
+            medianDelta: 0,
+            minDelta: 0,
+            maxDelta: 0,
+            deltaRange: 0,
+            positiveDeltaCount: 0,
+            negativeDeltaCount: 0,
+        };
+    }
+    const deltas = observations.map((entry) => entry.delta).sort((left, right) => left - right);
+    const totalRelevantCommits = observations.reduce((sum, entry) => sum + entry.relevantCommitCount, 0);
+    const weightedDeltaTotal = observations.reduce((sum, entry) => sum + entry.delta * entry.relevantCommitCount, 0);
+    const averageDelta = observations.reduce((sum, entry) => sum + entry.delta, 0) / observations.length;
+    const middleIndex = Math.floor(deltas.length / 2);
+    const medianDelta = deltas.length % 2 === 0
+        ? ((deltas[middleIndex - 1] ?? 0) + (deltas[middleIndex] ?? 0)) / 2
+        : (deltas[middleIndex] ?? 0);
+    const minDelta = deltas[0] ?? 0;
+    const maxDelta = deltas.at(-1) ?? 0;
+    return {
+        repoCount: observations.length,
+        averageDelta,
+        weightedAverageDelta: totalRelevantCommits === 0 ? averageDelta : weightedDeltaTotal / totalRelevantCommits,
+        medianDelta,
+        minDelta,
+        maxDelta,
+        deltaRange: maxDelta - minDelta,
+        positiveDeltaCount: observations.filter((entry) => entry.delta > 0).length,
+        negativeDeltaCount: observations.filter((entry) => entry.delta < 0).length,
+    };
+}

package/dist/src/core/shadow-rollout-gate.d.ts

@@ -0,0 +1,2 @@
+import type { DomainDesignShadowRolloutGateEvaluation, DomainDesignShadowRolloutGateObservation } from "./contracts.js";
+export declare function evaluateShadowRolloutGate(observations: DomainDesignShadowRolloutGateObservation[]): DomainDesignShadowRolloutGateEvaluation;

package/dist/src/core/shadow-rollout-gate.js

@@ -0,0 +1,50 @@
+import { evaluateGateReasons, SHADOW_ROLLOUT_GATE_CATEGORY_MIN_OBSERVATIONS } from "./shadow-rollout-gate-reasons.js";
+import { summarizeGateObservations } from "./shadow-rollout-gate-summary.js";
+export function evaluateShadowRolloutGate(observations) {
+    const overall = summarizeGateObservations(observations);
+    const repoOwnedCount = observations.filter((entry) => entry.modelSource === "repo_owned").length;
+    const versionedManifestCount = observations.filter((entry) => entry.modelSource === "versioned_manifest").length;
+    const categories = Array.from(observations
+        .reduce((groups, observation) => {
+        const current = groups.get(observation.category) ?? [];
+        current.push(observation);
+        groups.set(observation.category, current);
+        return groups;
+    }, new Map())
+        .entries())
+        .map(([category, categoryObservations]) => ({
+        category,
+        repoIds: categoryObservations.map((entry) => entry.repoId),
+        summary: summarizeGateObservations(categoryObservations),
+        gate: (() => {
+            const summary = summarizeGateObservations(categoryObservations);
+            const reasons = evaluateGateReasons(summary, categoryObservations.length, {
+                requireManifestPaths: true,
+                hasMissingVersionedManifestPath: categoryObservations.some((entry) => entry.modelSource === "versioned_manifest" && !entry.modelPath),
+                minObservationCount: SHADOW_ROLLOUT_GATE_CATEGORY_MIN_OBSERVATIONS,
+                insufficientObservationReason: "insufficient_category_observations",
+            });
+            return {
+                reasons,
+                replacementVerdict: reasons.length === 0 ? "go" : "no_go",
+                rolloutDisposition: reasons.length === 0 ? "replace" : "shadow_only",
+            };
+        })(),
+    }))
+        .sort((left, right) => left.category.localeCompare(right.category));
+    const reasons = evaluateGateReasons(overall, observations.length, {
+        requireManifestPaths: true,
+        hasMissingVersionedManifestPath: observations.some((entry) => entry.modelSource === "versioned_manifest" && !entry.modelPath),
+    });
+    return {
+        observations,
+        repoCount: observations.length,
+        repoOwnedCount,
+        versionedManifestCount,
+        overall,
+        categories,
+        reasons,
+        replacementVerdict: reasons.length === 0 ? "go" : "no_go",
+        rolloutDisposition: reasons.length === 0 ? "replace" : "shadow_only",
+    };
+}

package/dist/src/core/shadow-rollout-registry.d.ts

@@ -0,0 +1,5 @@
+import type { DomainDesignShadowRolloutBatchObservation, DomainDesignShadowRolloutGateObservation, DomainDesignShadowRolloutRegistry } from "./contracts.js";
+export declare function inferShadowRolloutModelSource(modelPath: string): "repo_owned" | "versioned_manifest";
+export declare function loadShadowRolloutRegistry(registryPath: string): Promise<DomainDesignShadowRolloutRegistry>;
+export declare function registryToGateObservations(registry: DomainDesignShadowRolloutRegistry, registryPath: string): DomainDesignShadowRolloutGateObservation[];
+export declare function batchToGateObservations(observations: DomainDesignShadowRolloutBatchObservation[]): DomainDesignShadowRolloutGateObservation[];

package/dist/src/core/shadow-rollout-registry.js

@@ -0,0 +1,31 @@
+import path from "node:path";
+import { readDataFile } from "./io.js";
+export function inferShadowRolloutModelSource(modelPath) {
+    return modelPath.includes(`${path.sep}fixtures${path.sep}validation${path.sep}shadow-rollout${path.sep}`)
+        ? "versioned_manifest"
+        : "repo_owned";
+}
+export async function loadShadowRolloutRegistry(registryPath) {
+    return readDataFile(registryPath);
+}
+export function registryToGateObservations(registry, registryPath) {
+    const registryDirectory = path.dirname(registryPath);
+    return registry.repos.map((entry) => ({
+        repoId: entry.repoId,
+        category: entry.category,
+        modelSource: entry.modelSource,
+        ...(entry.manifestPath ? { modelPath: path.resolve(registryDirectory, entry.manifestPath) } : {}),
+        relevantCommitCount: entry.observation.relevantCommitCount,
+        delta: entry.observation.delta,
+    }));
+}
+export function batchToGateObservations(observations) {
+    return observations.map((entry) => ({
+        repoId: entry.repoId,
+        category: entry.category,
+        modelSource: entry.modelSource,
+        modelPath: entry.modelPath,
+        relevantCommitCount: entry.relevantCommitCount,
+        delta: entry.policyDelta,
+    }));
+}

package/dist/src/core/shadow-rollout-summary.d.ts

@@ -0,0 +1,4 @@
+import type { DomainDesignShadowRolloutBatchAggregate, DomainDesignShadowRolloutBatchObservation } from "./contracts.js";
+export declare const SHADOW_ROLLOUT_MIN_REAL_REPO_OBSERVATIONS = 4;
+export declare const SHADOW_ROLLOUT_MIN_CATEGORY_REPO_OBSERVATIONS = 3;
+export declare function summarizeShadowRolloutBatchObservations(observations: DomainDesignShadowRolloutBatchObservation[]): DomainDesignShadowRolloutBatchAggregate;

package/dist/src/core/shadow-rollout-summary.js

@@ -0,0 +1,39 @@
+export const SHADOW_ROLLOUT_MIN_REAL_REPO_OBSERVATIONS = 4;
+export const SHADOW_ROLLOUT_MIN_CATEGORY_REPO_OBSERVATIONS = 3;
+export function summarizeShadowRolloutBatchObservations(observations) {
+    if (observations.length === 0) {
+        return {
+            repoCount: 0,
+            averageDelta: 0,
+            weightedAverageDelta: 0,
+            minDelta: 0,
+            maxDelta: 0,
+            deltaRange: 0,
+            driftCounts: {
+                aligned: 0,
+                candidateHigher: 0,
+                candidateLower: 0,
+            },
+        };
+    }
+    const deltas = observations.map((entry) => entry.policyDelta).sort((left, right) => left - right);
+    const totalRelevantCommits = observations.reduce((sum, entry) => sum + entry.relevantCommitCount, 0);
+    const weightedDeltaTotal = observations.reduce((sum, entry) => sum + entry.policyDelta * entry.relevantCommitCount, 0);
+    const averageDelta = observations.reduce((sum, entry) => sum + entry.policyDelta, 0) / observations.length;
+    const weightedAverageDelta = totalRelevantCommits === 0 ? averageDelta : weightedDeltaTotal / totalRelevantCommits;
+    const minDelta = deltas[0] ?? 0;
+    const maxDelta = deltas.at(-1) ?? 0;
+    return {
+        repoCount: observations.length,
+        averageDelta,
+        weightedAverageDelta,
+        minDelta,
+        maxDelta,
+        deltaRange: maxDelta - minDelta,
+        driftCounts: {
+            aligned: observations.filter((entry) => entry.driftCategory === "aligned").length,
+            candidateHigher: observations.filter((entry) => entry.driftCategory === "candidate_higher").length,
+            candidateLower: observations.filter((entry) => entry.driftCategory === "candidate_lower").length,
+        },
+    };
+}

package/dist/src/core/shadow-rollout.d.ts

@@ -0,0 +1,3 @@
+export { evaluateShadowRolloutGate } from "./shadow-rollout-gate.js";
+export { batchToGateObservations, inferShadowRolloutModelSource, loadShadowRolloutRegistry, registryToGateObservations, } from "./shadow-rollout-registry.js";
+export { summarizeShadowRolloutBatchObservations } from "./shadow-rollout-summary.js";

package/dist/src/core/shadow-rollout.js

@@ -0,0 +1,3 @@
+export { evaluateShadowRolloutGate } from "./shadow-rollout-gate.js";
+export { batchToGateObservations, inferShadowRolloutModelSource, loadShadowRolloutRegistry, registryToGateObservations, } from "./shadow-rollout-registry.js";
+export { summarizeShadowRolloutBatchObservations } from "./shadow-rollout-summary.js";

package/dist/src/core/shared-utils.d.ts

@@ -0,0 +1,4 @@
+export declare function clamp01Finite(value: number): number;
+export declare function clamp01(value: number): number;
+export declare function average(values: number[], fallback: number): number;
+export declare function unique<T>(values: T[]): T[];

package/dist/src/core/shared-utils.js

@@ -0,0 +1,15 @@
+export function clamp01Finite(value) {
+    return Math.max(0, Math.min(1, Number.isFinite(value) ? value : 0));
+}
+export function clamp01(value) {
+    return Math.max(0, Math.min(1, value));
+}
+export function average(values, fallback) {
+    if (values.length === 0) {
+        return fallback;
+    }
+    return values.reduce((sum, value) => sum + value, 0) / values.length;
+}
+export function unique(values) {
+    return Array.from(new Set(values));
+}

package/dist/src/core/trace.d.ts

@@ -0,0 +1,14 @@
+import type { DomainModel, GlossaryTerm, ModelCodeLink, TermTraceLink } from "./contracts.js";
+export declare function buildTermTraceLinks(options: {
+    docsRoot: string;
+    repoRoot?: string;
+    terms: GlossaryTerm[];
+    codeFiles?: string[];
+    onProgress?: (update: {
+        phase: "start" | "heartbeat" | "complete";
+        message: string;
+        elapsedMs?: number;
+    }) => void;
+    progressIntervalMs?: number;
+}): Promise<TermTraceLink[]>;
+export declare function buildModelCodeLinks(model: DomainModel, filePaths: string[]): ModelCodeLink[];

package/dist/src/core/trace.js

@@ -0,0 +1,118 @@
+import path from "node:path";
+import { normalizeDocuments } from "./artifacts.js";
+import { isSourceFile, listFiles, matchGlobs, readText, relativePath } from "./io.js";
+function countOccurrences(text, query) {
+    if (!query) {
+        return 0;
+    }
+    return text.toLowerCase().split(query.toLowerCase()).length - 1;
+}
+function formatDuration(ms) {
+    if (ms < 1000) {
+        return `${ms}ms`;
+    }
+    const seconds = ms / 1000;
+    if (seconds < 60) {
+        return `${seconds.toFixed(1)}s`;
+    }
+    const minutes = Math.floor(seconds / 60);
+    const remainingSeconds = Math.round(seconds % 60);
+    return `${minutes}m${remainingSeconds.toString().padStart(2, "0")}s`;
+}
+export async function buildTermTraceLinks(options) {
+    const startedAt = Date.now();
+    const fragments = await normalizeDocuments(options.docsRoot);
+    const codeFiles = options.repoRoot
+        ? (options.codeFiles ?? (await listFiles(options.repoRoot)).filter((filePath) => isSourceFile(filePath)))
+        : [];
+    const progressIntervalMs = options.progressIntervalMs ?? 5000;
+    let lastProgressAt = startedAt;
+    options.onProgress?.({
+        phase: "start",
+        message: `Preparing trace links for ${options.terms.length} term(s) across ${codeFiles.length} code file(s).`,
+    });
+    const codeContents = await Promise.all(codeFiles.map(async (filePath) => ({
+        path: options.repoRoot && path.isAbsolute(filePath)
+            ? relativePath(options.repoRoot, filePath)
+            : options.repoRoot
+                ? filePath
+                : filePath,
+        content: options.repoRoot && !path.isAbsolute(filePath)
+            ? await readText(path.join(options.repoRoot, filePath))
+            : await readText(filePath),
+    })));
+    const links = options.terms.map((term, index) => {
+        const queries = Array.from(new Set([term.canonicalTerm, ...(term.aliases ?? [])].filter(Boolean)));
+        if (Date.now() - lastProgressAt >= progressIntervalMs) {
+            lastProgressAt = Date.now();
+            const processedTerms = Math.max(index, 1);
+            const elapsedMs = lastProgressAt - startedAt;
+            const termsPerSecond = processedTerms / Math.max(elapsedMs / 1000, 0.001);
+            const remainingTerms = Math.max(options.terms.length - index, 0);
+            const etaMs = remainingTerms > 0 ? Math.round((remainingTerms / termsPerSecond) * 1000) : 0;
+            options.onProgress?.({
+                phase: "heartbeat",
+                message: `Trace linking is still running: processed ${index}/${options.terms.length} term(s) at ${termsPerSecond.toFixed(1)} term(s)/s, ETA ${formatDuration(etaMs)}.`,
+                elapsedMs,
+            });
+        }
+        const occurrences = [];
+        for (const fragment of fragments) {
+            const matchCount = queries.reduce((sum, query) => sum + countOccurrences(fragment.text, query), 0);
+            if (matchCount > 0 || term.fragmentIds.includes(fragment.fragmentId)) {
+                occurrences.push({
+                    kind: "document",
+                    path: fragment.path,
+                    fragmentId: fragment.fragmentId,
+                    matchCount: Math.max(matchCount, term.fragmentIds.includes(fragment.fragmentId) ? 1 : 0),
+                });
+            }
+        }
+        for (const codeFile of codeContents) {
+            const matchCount = queries.reduce((sum, query) => sum + countOccurrences(codeFile.content, query), 0);
+            if (matchCount > 0) {
+                occurrences.push({
+                    kind: "code",
+                    path: codeFile.path,
+                    matchCount,
+                });
+            }
+        }
+        const documentHits = occurrences.filter((occurrence) => occurrence.kind === "document").length;
+        const codeHits = occurrences.filter((occurrence) => occurrence.kind === "code").length;
+        return {
+            termId: term.termId,
+            canonicalTerm: term.canonicalTerm,
+            occurrences,
+            coverage: {
+                documentHits,
+                codeHits,
+            },
+            confidence: Math.min(1, term.confidence * (documentHits + codeHits > 0 ? 1 : 0.7)),
+        };
+    });
+    options.onProgress?.({
+        phase: "complete",
+        message: `Trace linking completed for ${options.terms.length} term(s) across ${codeFiles.length} code file(s).`,
+        elapsedMs: Date.now() - startedAt,
+    });
+    return links;
+}
+export function buildModelCodeLinks(model, filePaths) {
+    return model.contexts.map((context) => {
+        const files = filePaths.filter((filePath) => matchGlobs(filePath, context.pathGlobs));
+        const contract = files.filter((filePath) => matchGlobs(filePath, context.contractGlobs)).length;
+        const internal = files.filter((filePath) => matchGlobs(filePath, context.internalGlobs)).length;
+        const unclassified = Math.max(0, files.length - contract - internal);
+        return {
+            context: context.name,
+            files,
+            counts: {
+                contract,
+                internal,
+                unclassified,
+            },
+            coverage: files.length === 0 ? 0 : (contract + internal) / files.length,
+        };
+    });
+}

package/dist/src/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./commands.js";
+export * from "./core/contracts.js";
+export * from "./core/formula.js";
+export * from "./core/policy.js";
+export * from "./core/report.js";
+export * from "./core/scoring.js";
+export * from "./packs/index.js";

package/dist/src/index.js

@@ -0,0 +1,7 @@
+export * from "./commands.js";
+export * from "./core/contracts.js";
+export * from "./core/formula.js";
+export * from "./core/policy.js";
+export * from "./core/report.js";
+export * from "./core/scoring.js";
+export * from "./packs/index.js";

package/dist/src/packs/index.d.ts

@@ -0,0 +1,2 @@
+import type { DomainPack } from "../core/contracts.js";
+export declare const DOMAIN_PACKS: DomainPack[];