context-probe 0.1.0

package/dist/src/core/domain-design-scoring-pilot.js

@@ -0,0 +1,57 @@
+import { persistenceCandidateToMetricComponents } from "./domain-design-scoring-support.js";
+export function resolveDomainPersistencePilot(input) {
+    const diagnostics = [];
+    const { metric, shadow, shadowLocalityConfidence, pilotPersistenceCategory, pilotGateEvaluation } = input;
+    if (!pilotPersistenceCategory) {
+        return { metric, diagnostics };
+    }
+    if (!pilotGateEvaluation) {
+        throw new Error("pilotPersistenceCategory requires pilotGateEvaluation");
+    }
+    const categoryGate = pilotGateEvaluation.categories.find((entry) => entry.category === pilotPersistenceCategory);
+    if (!categoryGate) {
+        throw new Error(`No shadow rollout category gate is registered for \`${pilotPersistenceCategory}\``);
+    }
+    const baselineElsValue = metric.value;
+    const persistenceCandidateValue = shadow?.localityModels.persistenceCandidate.localityScore ?? baselineElsValue;
+    const comparisonAvailable = (shadow?.localityModels.persistenceAnalysis.relevantCommitCount ?? 0) > 0 &&
+        (shadow?.localityModels.persistenceAnalysis.contextsSeen.length ?? 0) > 0;
+    const applied = comparisonAvailable && categoryGate.gate.rolloutDisposition === "replace";
+    const pilotFallbackMessage = "Persistence pilot fell back to baseline ELS because locality comparison data is unavailable.";
+    if (!comparisonAvailable) {
+        diagnostics.push(pilotFallbackMessage);
+        metric.unknowns = Array.from(new Set([...metric.unknowns, pilotFallbackMessage]));
+    }
+    if (applied && shadow) {
+        metric.value = persistenceCandidateValue;
+        metric.components = persistenceCandidateToMetricComponents(shadow.localityModels.persistenceCandidate);
+        metric.confidence = shadowLocalityConfidence > 0 ? shadowLocalityConfidence : metric.confidence;
+        metric.evidenceRefs = [];
+        metric.unknowns = Array.from(new Set([
+            ...metric.unknowns,
+            `ELS fully reflects persistence_candidate pilot output for category \`${pilotPersistenceCategory}\` and exposes persistence-derived locality metadata.`,
+        ]));
+    }
+    return {
+        metric,
+        diagnostics,
+        pilot: {
+            category: pilotPersistenceCategory,
+            applied,
+            localitySource: applied ? "persistence_candidate" : "els",
+            baselineElsValue,
+            persistenceCandidateValue,
+            effectiveElsValue: metric.value,
+            overallGate: {
+                reasons: pilotGateEvaluation.reasons,
+                replacementVerdict: pilotGateEvaluation.replacementVerdict,
+                rolloutDisposition: pilotGateEvaluation.rolloutDisposition,
+            },
+            categoryGate: {
+                reasons: categoryGate.gate.reasons,
+                replacementVerdict: categoryGate.gate.replacementVerdict,
+                rolloutDisposition: categoryGate.gate.rolloutDisposition,
+            },
+        },
+    };
+}

package/dist/src/core/domain-design-scoring-response-shared.d.ts

@@ -0,0 +1,20 @@
+import type { CommandResponse, DomainDesignScoreResult, Evidence, ProgressUpdate } from "./contracts.js";
+export declare function buildDomainDesignScoreResult(input: {
+    scores: DomainDesignScoreResult["metrics"];
+    leakFindings: DomainDesignScoreResult["leakFindings"];
+    history: DomainDesignScoreResult["history"];
+    contractUsage: {
+        applicableReferences: number;
+    };
+    shadow?: DomainDesignScoreResult["shadow"];
+    pilot?: DomainDesignScoreResult["pilot"];
+}): DomainDesignScoreResult;
+export declare function buildDomainDesignScoreResponseOptions(input: {
+    repoPath: string;
+    docsRoot?: string;
+    scores: DomainDesignScoreResult["metrics"];
+    diagnostics: string[];
+    progress: ProgressUpdate[];
+    unknowns: string[];
+    evidence: Evidence[];
+}): Partial<Omit<CommandResponse<DomainDesignScoreResult>, "result" | "version">>;

package/dist/src/core/domain-design-scoring-response-shared.js

@@ -0,0 +1,30 @@
+import { confidenceFromSignals, toProvenance } from "./response.js";
+import { dedupeEvidence } from "./scoring-shared.js";
+export function buildDomainDesignScoreResult(input) {
+    const { scores, leakFindings, history, contractUsage, shadow, pilot } = input;
+    return {
+        domainId: "domain_design",
+        metrics: scores,
+        leakFindings,
+        history,
+        crossContextReferences: contractUsage.applicableReferences,
+        ...(shadow ? { shadow } : {}),
+        ...(pilot ? { pilot } : {}),
+    };
+}
+export function buildDomainDesignScoreResponseOptions(input) {
+    const { repoPath, docsRoot, scores, diagnostics, progress, unknowns, evidence } = input;
+    const status = diagnostics.length > 0 ? "warning" : "ok";
+    return {
+        status,
+        evidence: dedupeEvidence(evidence),
+        confidence: confidenceFromSignals(scores.map((score) => score.confidence)),
+        unknowns: Array.from(new Set(unknowns)),
+        diagnostics,
+        progress,
+        provenance: [
+            toProvenance(repoPath, "domain_design"),
+            ...(docsRoot !== undefined ? [toProvenance(docsRoot, "domain_design_docs")] : []),
+        ],
+    };
+}

package/dist/src/core/domain-design-scoring-response.d.ts

@@ -0,0 +1,18 @@
+import type { CommandResponse, CommandResponseMeta, DomainDesignScoreResult, Evidence, ProgressUpdate } from "./contracts.js";
+export declare function buildDomainDesignScoreResponse(input: {
+    repoPath: string;
+    docsRoot?: string;
+    scores: DomainDesignScoreResult["metrics"];
+    leakFindings: DomainDesignScoreResult["leakFindings"];
+    history: DomainDesignScoreResult["history"];
+    contractUsage: {
+        applicableReferences: number;
+    };
+    shadow?: DomainDesignScoreResult["shadow"];
+    pilot?: DomainDesignScoreResult["pilot"];
+    diagnostics: string[];
+    progress: ProgressUpdate[];
+    unknowns: string[];
+    evidence: Evidence[];
+    meta?: CommandResponseMeta;
+}): CommandResponse<DomainDesignScoreResult>;

package/dist/src/core/domain-design-scoring-response.js

@@ -0,0 +1,27 @@
+import { buildDomainDesignScoreResponseOptions, buildDomainDesignScoreResult, } from "./domain-design-scoring-response-shared.js";
+import { createResponse } from "./response.js";
+export function buildDomainDesignScoreResponse(input) {
+    const { repoPath, docsRoot, scores, leakFindings, history, contractUsage, shadow, pilot, diagnostics, progress, unknowns, evidence, meta, } = input;
+    const responseOptions = {
+        repoPath,
+        scores,
+        diagnostics,
+        progress,
+        unknowns,
+        evidence,
+    };
+    if (docsRoot !== undefined) {
+        responseOptions.docsRoot = docsRoot;
+    }
+    return createResponse(buildDomainDesignScoreResult({
+        scores,
+        leakFindings,
+        history,
+        contractUsage,
+        shadow,
+        pilot,
+    }), {
+        ...buildDomainDesignScoreResponseOptions(responseOptions),
+        ...(meta ? { meta } : {}),
+    });
+}

package/dist/src/core/domain-design-scoring-support-drf.d.ts

@@ -0,0 +1,17 @@
+import type { Fragment, InvariantCandidate, RuleCandidate } from "./contracts.js";
+export declare function buildReviewItemsForCandidates(key: "rules" | "invariants", candidates: RuleCandidate[] | InvariantCandidate[], responseConfidence: number, responseUnknowns: string[]): import("./contracts.js").ReviewItem[];
+export declare function computeDrfComponents(fragments: Fragment[], rules: RuleCandidate[], invariants: InvariantCandidate[], reviewItemCount: number): {
+    SC: number;
+    RC: number;
+    IV: number;
+    RA: number;
+    proseFragments: number;
+    useCaseFragments: number;
+    signalFragments: number;
+    totalCandidates: number;
+};
+export declare function inspectDrfEvidenceQuality(fragments: Fragment[], rules: RuleCandidate[], invariants: InvariantCandidate[]): {
+    explicitUseCaseCount: number;
+    explicitRuleCount: number;
+    explicitInvariantCount: number;
+};

package/dist/src/core/domain-design-scoring-support-drf.js

@@ -0,0 +1,118 @@
+import { listReviewItems } from "./review.js";
+import { average, clamp01 } from "./scoring-shared.js";
+const USE_CASE_SIGNALS = [
+    /ユースケース/u,
+    /シナリオ/u,
+    /期待(?:される)?結果/u,
+    /受け入れ基準/u,
+    /利用者/u,
+    /\buse case\b/i,
+    /\bscenario\b/i,
+    /\bacceptance\b/i,
+];
+const CONSTRAINT_SIGNALS = [
+    /なければならない/u,
+    /べき/u,
+    /常に/u,
+    /一致/u,
+    /一意/u,
+    /整合/u,
+    /返(?:る|される)/u,
+    /欠落しない/u,
+    /再現可能/u,
+    /安定(?:する|している)/u,
+    /辿れる/u,
+    /反映(?:される|されている)/u,
+    /付与(?:される|されている)/u,
+    /表示(?:される|されている)/u,
+];
+const USE_CASE_HEADING_PATTERNS = [/\bcore use cases?\b/i, /\buse cases?\b/i, /ユースケース/u];
+const RULE_HEADING_PATTERNS = [/\bdecision rules?\b/i, /\brules?\b/i, /ルール/u];
+const INVARIANT_HEADING_PATTERNS = [/\bstrong invariants?\b/i, /\binvariants?\b/i, /不変条件/u];
+export function buildReviewItemsForCandidates(key, candidates, responseConfidence, responseUnknowns) {
+    return listReviewItems({
+        status: "ok",
+        result: {
+            [key]: candidates,
+        },
+        evidence: candidates.flatMap((candidate) => candidate.evidence),
+        confidence: responseConfidence,
+        unknowns: responseUnknowns,
+        diagnostics: [],
+        progress: [],
+        provenance: [],
+        version: "1.0",
+    });
+}
+export function computeDrfComponents(fragments, rules, invariants, reviewItemCount) {
+    const proseFragments = fragments.filter((fragment) => fragment.kind === "paragraph" && fragment.text.trim().length > 0);
+    const totalCandidates = rules.length + invariants.length;
+    const allCandidates = [...rules, ...invariants];
+    const coveredFragments = new Set(allCandidates.flatMap((candidate) => candidate.fragmentIds)).size;
+    const signalFragments = proseFragments.filter((fragment) => CONSTRAINT_SIGNALS.some((pattern) => pattern.test(fragment.text))).length;
+    const useCaseFragments = proseFragments.filter((fragment) => USE_CASE_SIGNALS.some((pattern) => pattern.test(fragment.text))).length;
+    const ambiguousCandidates = allCandidates.filter((candidate) => candidate.unknowns.length > 0).length;
+    const lowConfidenceCandidates = allCandidates.filter((candidate) => candidate.confidence < 0.75).length;
+    const ambiguityRate = totalCandidates === 0 ? 1 : ambiguousCandidates / totalCandidates;
+    const lowConfidenceRate = totalCandidates === 0 ? 1 : lowConfidenceCandidates / totalCandidates;
+    const reviewDensity = clamp01(reviewItemCount / Math.max(1, totalCandidates * 2));
+    const averageConfidence = average(allCandidates.map((candidate) => candidate.confidence), 0.45);
+    const SC = proseFragments.length === 0
+        ? 0
+        : clamp01((0.7 * useCaseFragments) / proseFragments.length + (0.3 * coveredFragments) / proseFragments.length);
+    const RC = signalFragments === 0 ? 0 : clamp01((coveredFragments / signalFragments) * (1 - 0.5 * ambiguityRate));
+    const IV = clamp01(0.6 * ambiguityRate + 0.4 * lowConfidenceRate);
+    const RA = clamp01((1 - reviewDensity) * 0.6 + averageConfidence * 0.4);
+    return {
+        SC,
+        RC,
+        IV,
+        RA,
+        proseFragments: proseFragments.length,
+        useCaseFragments,
+        signalFragments,
+        totalCandidates,
+    };
+}
+function headingMatches(heading, patterns) {
+    if (!heading) {
+        return false;
+    }
+    return patterns.some((pattern) => pattern.test(heading));
+}
+function buildHeadingByFragmentId(fragments) {
+    const byFile = new Map();
+    for (const fragment of fragments) {
+        const list = byFile.get(fragment.path) ?? [];
+        list.push(fragment);
+        byFile.set(fragment.path, list);
+    }
+    const headingByFragmentId = new Map();
+    for (const fragmentsInFile of byFile.values()) {
+        const ordered = [...fragmentsInFile].sort((left, right) => left.lineStart - right.lineStart);
+        let currentHeading;
+        for (const fragment of ordered) {
+            if (fragment.kind === "heading") {
+                currentHeading = fragment.text.replace(/^#+\s*/u, "").trim();
+            }
+            if (currentHeading) {
+                headingByFragmentId.set(fragment.fragmentId, currentHeading);
+            }
+        }
+    }
+    return headingByFragmentId;
+}
+function countAnchoredCandidates(candidates, headingByFragmentId, patterns) {
+    return candidates.filter((candidate) => candidate.fragmentIds.some((fragmentId) => headingMatches(headingByFragmentId.get(fragmentId), patterns))).length;
+}
+export function inspectDrfEvidenceQuality(fragments, rules, invariants) {
+    const headingByFragmentId = buildHeadingByFragmentId(fragments);
+    const explicitUseCaseCount = fragments.filter((fragment) => fragment.kind === "paragraph" &&
+        USE_CASE_SIGNALS.some((pattern) => pattern.test(fragment.text)) &&
+        headingMatches(headingByFragmentId.get(fragment.fragmentId), USE_CASE_HEADING_PATTERNS)).length;
+    return {
+        explicitUseCaseCount,
+        explicitRuleCount: countAnchoredCandidates(rules, headingByFragmentId, RULE_HEADING_PATTERNS),
+        explicitInvariantCount: countAnchoredCandidates(invariants, headingByFragmentId, INVARIANT_HEADING_PATTERNS),
+    };
+}

package/dist/src/core/domain-design-scoring-support-persistence.d.ts

@@ -0,0 +1,6 @@
+export declare function persistenceCandidateToMetricComponents(candidate: {
+    persistentCouplingPenalty: number;
+    clusterPenalty: number;
+    pairPenalty: number;
+    coherencePenalty: number;
+}): Record<string, number>;

package/dist/src/core/domain-design-scoring-support-persistence.js

@@ -0,0 +1,8 @@
+export function persistenceCandidateToMetricComponents(candidate) {
+    return {
+        persistentCouplingPenalty: candidate.persistentCouplingPenalty,
+        clusterPenalty: candidate.clusterPenalty,
+        pairPenalty: candidate.pairPenalty,
+        coherencePenalty: candidate.coherencePenalty,
+    };
+}

package/dist/src/core/domain-design-scoring-support-uli.d.ts

@@ -0,0 +1,12 @@
+import type { TermTraceLink } from "./contracts.js";
+export declare function computeUliComponents(terms: Array<{
+    termId: string;
+    count: number;
+    aliases: string[];
+    collision: boolean;
+}>, links: TermTraceLink[]): {
+    GC: number;
+    AE: number;
+    TC: number;
+    TL: number;
+};

package/dist/src/core/domain-design-scoring-support-uli.js

@@ -0,0 +1,31 @@
+function computeAliasEntropy(aliasesPerTerm, termCount) {
+    if (termCount === 0) {
+        return 1;
+    }
+    return Math.min(1, aliasesPerTerm / termCount);
+}
+export function computeUliComponents(terms, links) {
+    const totalTerms = terms.length;
+    if (totalTerms === 0) {
+        return {
+            GC: 0,
+            AE: 1,
+            TC: 1,
+            TL: 0,
+        };
+    }
+    const linkByTermId = new Map(links.map((link) => [link.termId, link]));
+    const glossaryCovered = terms.filter((term) => {
+        const link = linkByTermId.get(term.termId);
+        return term.count > 1 || (link?.coverage.codeHits ?? 0) > 0;
+    }).length;
+    const tracedTerms = links.filter((link) => link.coverage.documentHits > 0 && link.coverage.codeHits > 0).length;
+    const collisionTerms = terms.filter((term) => term.collision).length;
+    const aliasCount = terms.reduce((sum, term) => sum + term.aliases.length, 0);
+    return {
+        GC: glossaryCovered / totalTerms,
+        AE: computeAliasEntropy(aliasCount, totalTerms),
+        TC: collisionTerms / totalTerms,
+        TL: tracedTerms / totalTerms,
+    };
+}

package/dist/src/core/domain-design-scoring-support.d.ts

@@ -0,0 +1,3 @@
+export { buildReviewItemsForCandidates, computeDrfComponents, inspectDrfEvidenceQuality, } from "./domain-design-scoring-support-drf.js";
+export { persistenceCandidateToMetricComponents } from "./domain-design-scoring-support-persistence.js";
+export { computeUliComponents } from "./domain-design-scoring-support-uli.js";

package/dist/src/core/domain-design-scoring-support.js

@@ -0,0 +1,3 @@
+export { buildReviewItemsForCandidates, computeDrfComponents, inspectDrfEvidenceQuality, } from "./domain-design-scoring-support-drf.js";
+export { persistenceCandidateToMetricComponents } from "./domain-design-scoring-support-persistence.js";
+export { computeUliComponents } from "./domain-design-scoring-support-uli.js";

package/dist/src/core/domain-design-scoring.d.ts

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

package/dist/src/core/domain-design-scoring.js

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

package/dist/src/core/formula-parser-tokenize.d.ts

@@ -0,0 +1,14 @@
+export type Token = {
+    type: "number";
+    value: number;
+} | {
+    type: "identifier";
+    value: string;
+} | {
+    type: "operator";
+    value: "+" | "-" | "*" | "/";
+} | {
+    type: "paren";
+    value: "(" | ")";
+};
+export declare function tokenize(expression: string): Token[];

package/dist/src/core/formula-parser-tokenize.js

@@ -0,0 +1,58 @@
+export function tokenize(expression) {
+    const tokens = [];
+    let cursor = 0;
+    while (cursor < expression.length) {
+        const char = expression[cursor];
+        if (char === undefined) {
+            break;
+        }
+        if (char === " " || char === "\n" || char === "\t") {
+            cursor += 1;
+            continue;
+        }
+        if (char === "(" || char === ")") {
+            tokens.push({ type: "paren", value: char });
+            cursor += 1;
+            continue;
+        }
+        if (char === "+" || char === "-" || char === "*" || char === "/") {
+            tokens.push({ type: "operator", value: char });
+            cursor += 1;
+            continue;
+        }
+        if (/\d/.test(char)) {
+            const remaining = expression.slice(cursor);
+            const match = /^\d+(?:\.\d*)?/u.exec(remaining);
+            const literal = match?.[0];
+            if (!literal) {
+                throw new Error(`Invalid numeric literal in formula: ${expression}`);
+            }
+            cursor += literal.length;
+            if (expression[cursor] === ".") {
+                throw new Error(`Invalid numeric literal in formula: ${expression}`);
+            }
+            const numericValue = Number(literal);
+            if (!Number.isFinite(numericValue)) {
+                throw new Error(`Invalid numeric literal in formula: ${expression}`);
+            }
+            tokens.push({ type: "number", value: numericValue });
+            continue;
+        }
+        if (/[A-Za-z_]/.test(char)) {
+            let identifier = char;
+            cursor += 1;
+            while (cursor < expression.length && /[A-Za-z0-9_]/.test(expression[cursor] ?? "")) {
+                const nextChar = expression[cursor];
+                if (!nextChar) {
+                    break;
+                }
+                identifier += nextChar;
+                cursor += 1;
+            }
+            tokens.push({ type: "identifier", value: identifier });
+            continue;
+        }
+        throw new Error(`Unsupported character "${char}" in formula: ${expression}`);
+    }
+    return tokens;
+}

package/dist/src/core/formula-parser.d.ts

@@ -0,0 +1 @@
+export declare function evaluateFormula(expression: string, variables: Record<string, number>): number;

package/dist/src/core/formula-parser.js

@@ -0,0 +1,91 @@
+import { tokenize } from "./formula-parser-tokenize.js";
+class FormulaParser {
+    expression;
+    variables;
+    tokens;
+    index = 0;
+    constructor(expression, variables) {
+        this.expression = expression;
+        this.variables = variables;
+        this.tokens = tokenize(expression);
+    }
+    parse() {
+        const value = this.parseExpression();
+        if (this.index < this.tokens.length) {
+            throw new Error(`Unexpected token at end of expression: ${this.expression}`);
+        }
+        return this.ensureFinite(value);
+    }
+    parseExpression() {
+        let value = this.parseTerm();
+        while (this.peekOperator("+") || this.peekOperator("-")) {
+            const token = this.consume();
+            if (!token || token.type !== "operator") {
+                throw new Error(`Expected operator in formula: ${this.expression}`);
+            }
+            const operator = token.value;
+            const right = this.parseTerm();
+            value = this.ensureFinite(operator === "+" ? value + right : value - right);
+        }
+        return value;
+    }
+    parseTerm() {
+        let value = this.parseFactor();
+        while (this.peekOperator("*") || this.peekOperator("/")) {
+            const token = this.consume();
+            if (!token || token.type !== "operator") {
+                throw new Error(`Expected operator in formula: ${this.expression}`);
+            }
+            const operator = token.value;
+            const right = this.parseFactor();
+            value = this.ensureFinite(operator === "*" ? value * right : value / right);
+        }
+        return value;
+    }
+    parseFactor() {
+        const token = this.consume();
+        if (!token) {
+            throw new Error(`Unexpected end of expression: ${this.expression}`);
+        }
+        if (token.type === "number") {
+            return token.value;
+        }
+        if (token.type === "identifier") {
+            const value = this.variables[token.value];
+            if (value === undefined || !Number.isFinite(value)) {
+                throw new Error(`Unknown identifier "${token.value}" in formula: ${this.expression}`);
+            }
+            return value;
+        }
+        if (token.type === "operator" && token.value === "-") {
+            return this.ensureFinite(-this.parseFactor());
+        }
+        if (token.type === "paren" && token.value === "(") {
+            const nested = this.parseExpression();
+            const next = this.consume();
+            if (!next || next.type !== "paren" || next.value !== ")") {
+                throw new Error(`Missing closing parenthesis in formula: ${this.expression}`);
+            }
+            return nested;
+        }
+        throw new Error(`Unexpected token in formula: ${JSON.stringify(token)}`);
+    }
+    ensureFinite(value) {
+        if (!Number.isFinite(value)) {
+            throw new Error(`Formula produced a non-finite result: ${this.expression}`);
+        }
+        return value;
+    }
+    peekOperator(operator) {
+        const token = this.tokens[this.index];
+        return token?.type === "operator" && token.value === operator;
+    }
+    consume() {
+        const token = this.tokens[this.index];
+        this.index += 1;
+        return token;
+    }
+}
+export function evaluateFormula(expression, variables) {
+    return new FormulaParser(expression, variables).parse();
+}

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

@@ -0,0 +1 @@
+export { evaluateFormula } from "./formula-parser.js";

package/dist/src/core/formula.js

@@ -0,0 +1 @@
+export { evaluateFormula } from "./formula-parser.js";

package/dist/src/core/history-locality.d.ts

@@ -0,0 +1,5 @@
+import type { CochangeAnalysis, CochangeCommit, DomainModel } from "./contracts.js";
+import { type HistoryObservationQuality } from "./history-shared.js";
+export declare function evaluateEvolutionLocalityObservationQuality(commits: CochangeCommit[], model: DomainModel): HistoryObservationQuality;
+export declare function scoreEvolutionLocality(commits: CochangeCommit[], model: DomainModel): CochangeAnalysis;
+export declare function computeEvolutionLocalityScore(analysis: CochangeAnalysis): number;

package/dist/src/core/history-locality.js

@@ -0,0 +1,48 @@
+import { buildHistoryObservationQuality, clamp01, contextualizeCommits, unique, } from "./history-shared.js";
+export function evaluateEvolutionLocalityObservationQuality(commits, model) {
+    const contextualized = contextualizeCommits(commits, model);
+    const contextsSeen = unique(contextualized.flatMap((commit) => commit.contexts)).sort();
+    return buildHistoryObservationQuality({
+        relevantCommitCount: contextualized.length,
+        contextsSeen,
+    });
+}
+export function scoreEvolutionLocality(commits, model) {
+    const relevant = contextualizeCommits(commits, model);
+    if (relevant.length === 0) {
+        return {
+            commits: [],
+            crossContextCommits: 0,
+            localCommits: 0,
+            averageContextsPerCommit: 0,
+            surpriseCouplingRatio: 0,
+            crossContextChangeLocality: 0,
+            featureScatter: 0,
+            contextsSeen: [],
+        };
+    }
+    const crossContextCommits = relevant.filter((entry) => entry.contexts.length > 1).length;
+    const localCommits = relevant.length - crossContextCommits;
+    const totalContextTouches = relevant.reduce((sum, entry) => sum + entry.contexts.length, 0);
+    const averageContextsPerCommit = totalContextTouches / relevant.length;
+    const contextsSeen = unique(relevant.flatMap((entry) => entry.contexts)).sort();
+    const maxContexts = Math.max(1, contextsSeen.length);
+    const featureScatter = maxContexts <= 1 ? 0 : Math.min(1, (averageContextsPerCommit - 1) / (maxContexts - 1));
+    const surpriseCouplingRatio = crossContextCommits / relevant.length;
+    const crossContextChangeLocality = localCommits / relevant.length;
+    return {
+        commits,
+        crossContextCommits,
+        localCommits,
+        averageContextsPerCommit,
+        surpriseCouplingRatio,
+        crossContextChangeLocality,
+        featureScatter,
+        contextsSeen,
+    };
+}
+export function computeEvolutionLocalityScore(analysis) {
+    return clamp01(0.4 * analysis.crossContextChangeLocality +
+        0.3 * (1 - analysis.featureScatter) +
+        0.3 * (1 - analysis.surpriseCouplingRatio));
+}

package/dist/src/core/history-normalization.d.ts

@@ -0,0 +1,13 @@
+import type { CochangeCommit, PolicyConfig } from "./contracts.js";
+export interface NormalizeHistoryOptions {
+    includePathGlobs?: string[];
+    onProgress?: (event: {
+        phase: "start" | "heartbeat" | "complete" | "error";
+        elapsedMs: number;
+        observedCommitCount: number;
+        emittedCommitCount: number;
+        includePathGlobCount: number;
+    }) => void;
+    progressIntervalMs?: number;
+}
+export declare function normalizeHistory(repoPath: string, policyConfig: PolicyConfig, profileName: string, options?: NormalizeHistoryOptions): Promise<CochangeCommit[]>;