context-probe 0.1.0

package/dist/src/core/scaffold-architecture-orchestration.js

@@ -0,0 +1,36 @@
+import YAML from "yaml";
+import { parseCodebase } from "../analyzers/code.js";
+import { clampConfidence } from "./response.js";
+import { buildArchitectureLayerBalances } from "./scaffold-architecture-balances.js";
+import { buildArchitectureScaffoldDrafts } from "./scaffold-architecture-drafts.js";
+import { buildArchitectureScaffoldLayers } from "./scaffold-architecture-layers.js";
+import { buildArchitectureConstraints, inferLayerOrder } from "./scaffold-architecture-ordering.js";
+import { averageLayerConfidence, groupSourceFiles, mergeEvidence, mergeUnknowns, } from "./scaffold-shared.js";
+export async function scaffoldArchitectureConstraints(options) {
+    const codebase = await parseCodebase(options.repoRoot);
+    const grouped = groupSourceFiles(codebase);
+    if (grouped.length === 0) {
+        throw new Error("No scorable source files were found to scaffold architecture constraints.");
+    }
+    const orderedGroups = inferLayerOrder(codebase, grouped);
+    const constraints = buildArchitectureConstraints(orderedGroups);
+    const balances = buildArchitectureLayerBalances(codebase, orderedGroups);
+    const layers = buildArchitectureScaffoldLayers(orderedGroups, constraints, balances);
+    const drafts = buildArchitectureScaffoldDrafts(codebase, constraints);
+    const result = {
+        constraints,
+        yaml: YAML.stringify(constraints),
+        layers,
+        drafts,
+    };
+    const confidence = clampConfidence(averageLayerConfidence(layers));
+    return {
+        result,
+        confidence,
+        evidence: mergeEvidence(layers),
+        unknowns: mergeUnknowns(layers, [
+            "Complexity metadata is not scaffolded by default; add it explicitly when stable observations are available.",
+        ]),
+        diagnostics: [`Scaffolded ${layers.length} layer candidate(s).`],
+    };
+}

package/dist/src/core/scaffold-architecture-ordering.d.ts

@@ -0,0 +1,4 @@
+import type { ArchitectureConstraints, CodebaseAnalysis } from "./contracts.js";
+import { type SourceGroup } from "./scaffold-shared.js";
+export declare function inferLayerOrder(codebase: CodebaseAnalysis, groups: SourceGroup[]): SourceGroup[];
+export declare function buildArchitectureConstraints(groups: SourceGroup[]): ArchitectureConstraints;

package/dist/src/core/scaffold-architecture-ordering.js

@@ -0,0 +1,55 @@
+import { inferGroupDisplayName, LAYER_PRIORITY_HINTS, makeUniqueNames, normalizeName, } from "./scaffold-shared.js";
+export function inferLayerOrder(codebase, groups) {
+    const fileToGroup = new Map();
+    for (const group of groups) {
+        for (const filePath of group.files) {
+            fileToGroup.set(filePath, group.key);
+        }
+    }
+    const incoming = new Map();
+    const outgoing = new Map();
+    for (const group of groups) {
+        incoming.set(group.key, 0);
+        outgoing.set(group.key, 0);
+    }
+    for (const dependency of codebase.dependencies) {
+        if (dependency.targetKind !== "file") {
+            continue;
+        }
+        const sourceGroup = fileToGroup.get(dependency.source);
+        const targetGroup = fileToGroup.get(dependency.target);
+        if (!sourceGroup || !targetGroup || sourceGroup === targetGroup) {
+            continue;
+        }
+        outgoing.set(sourceGroup, (outgoing.get(sourceGroup) ?? 0) + 1);
+        incoming.set(targetGroup, (incoming.get(targetGroup) ?? 0) + 1);
+    }
+    return [...groups].sort((left, right) => {
+        const leftHint = LAYER_PRIORITY_HINTS.get(normalizeName(inferGroupDisplayName(left)).replace(/\s+/gu, "_"));
+        const rightHint = LAYER_PRIORITY_HINTS.get(normalizeName(inferGroupDisplayName(right)).replace(/\s+/gu, "_"));
+        const leftPriority = leftHint ?? 100;
+        const rightPriority = rightHint ?? 100;
+        if (leftPriority !== rightPriority) {
+            return leftPriority - rightPriority;
+        }
+        const leftBalance = (outgoing.get(left.key) ?? 0) - (incoming.get(left.key) ?? 0);
+        const rightBalance = (outgoing.get(right.key) ?? 0) - (incoming.get(right.key) ?? 0);
+        if (leftBalance !== rightBalance) {
+            return leftBalance - rightBalance;
+        }
+        return left.key.localeCompare(right.key);
+    });
+}
+export function buildArchitectureConstraints(groups) {
+    const orderedNames = makeUniqueNames(groups.map((group) => inferGroupDisplayName(group)));
+    const layers = groups.map((group, index) => ({
+        name: orderedNames[index] ?? `Layer${index + 1}`,
+        rank: index,
+        globs: group.pathGlobs,
+    }));
+    return {
+        version: "1.0",
+        direction: "inward",
+        layers,
+    };
+}

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

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

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

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

package/dist/src/core/scaffold-domain-aggregates-candidates.d.ts

@@ -0,0 +1,4 @@
+import type { DomainAggregateCandidate } from "./contracts.js";
+import type { ContextCandidateEntry } from "./scaffold-domain-contexts.js";
+import type { DocsBundle } from "./scaffold-domain-docs.js";
+export declare function buildAggregateCandidates(contextCandidates: ContextCandidateEntry[], docsBundle: DocsBundle | undefined): DomainAggregateCandidate[];

package/dist/src/core/scaffold-domain-aggregates-candidates.js

@@ -0,0 +1,8 @@
+import { deduplicateAggregateCandidates } from "./scaffold-domain-aggregates-dedupe.js";
+import { createExplicitAggregateCandidates } from "./scaffold-domain-aggregates-explicit.js";
+import { createInferredAggregateCandidates } from "./scaffold-domain-aggregates-inferred.js";
+export function buildAggregateCandidates(contextCandidates, docsBundle) {
+    const explicitAggregates = createExplicitAggregateCandidates(contextCandidates, docsBundle?.glossary.fragments);
+    const inferredAggregates = createInferredAggregateCandidates(contextCandidates, docsBundle);
+    return deduplicateAggregateCandidates([...explicitAggregates, ...inferredAggregates]);
+}

package/dist/src/core/scaffold-domain-aggregates-core.d.ts

@@ -0,0 +1 @@
+export { buildAggregateCandidates } from "./scaffold-domain-aggregates-candidates.js";

package/dist/src/core/scaffold-domain-aggregates-core.js

@@ -0,0 +1 @@
+export { buildAggregateCandidates } from "./scaffold-domain-aggregates-candidates.js";

package/dist/src/core/scaffold-domain-aggregates-dedupe.d.ts

@@ -0,0 +1,2 @@
+import type { DomainAggregateCandidate } from "./contracts.js";
+export declare function deduplicateAggregateCandidates(candidates: DomainAggregateCandidate[]): DomainAggregateCandidate[];

package/dist/src/core/scaffold-domain-aggregates-dedupe.js

@@ -0,0 +1,18 @@
+import { normalizeName } from "./scaffold-domain-aggregates-shared.js";
+export function deduplicateAggregateCandidates(candidates) {
+    const deduped = new Map();
+    for (const candidate of candidates) {
+        const key = `${candidate.definition.context}:${normalizeName(candidate.definition.name)}`;
+        const current = deduped.get(key);
+        if (!current || current.confidence < candidate.confidence) {
+            deduped.set(key, candidate);
+        }
+    }
+    return Array.from(deduped.values()).sort((left, right) => {
+        const contextComparison = left.definition.context.localeCompare(right.definition.context);
+        if (contextComparison !== 0) {
+            return contextComparison;
+        }
+        return left.definition.name.localeCompare(right.definition.name);
+    });
+}

package/dist/src/core/scaffold-domain-aggregates-explicit.d.ts

@@ -0,0 +1,4 @@
+import type { DomainAggregateCandidate } from "./contracts.js";
+import type { ContextCandidateEntry } from "./scaffold-domain-contexts.js";
+import type { GlossaryExtractionResult } from "./scaffold-domain-docs.js";
+export declare function createExplicitAggregateCandidates(contextCandidates: ContextCandidateEntry[], fragments: GlossaryExtractionResult["fragments"] | undefined): DomainAggregateCandidate[];

package/dist/src/core/scaffold-domain-aggregates-explicit.js

@@ -0,0 +1,43 @@
+import { clampConfidence, toEvidence } from "./response.js";
+import { isNoisyAggregateLabel, normalizeName, sanitizeAggregateAliases, toPascalCase, } from "./scaffold-domain-aggregates-shared.js";
+function countContextMentions(name, fragments) {
+    if (!fragments) {
+        return 0;
+    }
+    const normalizedName = normalizeName(name);
+    return fragments.filter((fragment) => normalizeName(fragment.text).includes(normalizedName)).length;
+}
+export function createExplicitAggregateCandidates(contextCandidates, fragments) {
+    const aggregateCandidates = [];
+    for (const entry of contextCandidates) {
+        const aggregateFiles = entry.group.files.filter((filePath) => filePath.toLowerCase().includes("aggregate"));
+        for (const filePath of aggregateFiles) {
+            const fileName = filePath.split("/").pop() ?? filePath;
+            const rawName = toPascalCase(fileName);
+            const name = rawName === "Aggregate" ? `${entry.candidate.definition.name}Aggregate` : rawName;
+            const baseName = name.replace(/Aggregate$/u, "");
+            if (isNoisyAggregateLabel(name) || isNoisyAggregateLabel(baseName)) {
+                continue;
+            }
+            const aliases = sanitizeAggregateAliases(name, [baseName, entry.candidate.definition.name]);
+            const mentionCount = countContextMentions(name, fragments) + countContextMentions(baseName, fragments);
+            const confidence = clampConfidence(0.8 + (mentionCount > 0 ? 0.08 : 0));
+            aggregateCandidates.push({
+                definition: {
+                    name,
+                    context: entry.candidate.definition.name,
+                    ...(aliases.length > 0 ? { aliases } : {}),
+                },
+                confidence,
+                evidence: [
+                    toEvidence(`${name} was inferred from ${filePath}.`, {
+                        context: entry.candidate.definition.name,
+                        path: filePath,
+                    }, undefined, confidence),
+                ],
+                unknowns: [],
+            });
+        }
+    }
+    return aggregateCandidates;
+}

package/dist/src/core/scaffold-domain-aggregates-inferred.d.ts

@@ -0,0 +1,4 @@
+import type { DomainAggregateCandidate } from "./contracts.js";
+import type { ContextCandidateEntry } from "./scaffold-domain-contexts.js";
+import type { DocsBundle } from "./scaffold-domain-docs.js";
+export declare function createInferredAggregateCandidates(contextCandidates: ContextCandidateEntry[], docsBundle: DocsBundle | undefined): DomainAggregateCandidate[];

package/dist/src/core/scaffold-domain-aggregates-inferred.js

@@ -0,0 +1,117 @@
+import { buildFragmentContextMentions, collectTermContexts } from "./boundary-fitness.js";
+import { clampConfidence, toEvidence } from "./response.js";
+import { hasContractOccurrence, hasInternalOccurrence, isNoisyAggregateLabel, normalizeName, STOPWORD_AGGREGATE_TERMS, sanitizeAggregateAliases, tokenizeAggregateLabel, toPascalCase, } from "./scaffold-domain-aggregates-shared.js";
+const AGGREGATE_CONTEXT_MARKERS = new Set([
+    "app",
+    "application",
+    "contracts",
+    "core",
+    "domain",
+    "foundation",
+    "kernel",
+    "model",
+    "service",
+    "services",
+    "usecase",
+    "usecases",
+]);
+function isAggregateEligibleContext(entry) {
+    const contextName = normalizeName(entry.candidate.definition.name);
+    const segment = normalizeName(entry.group.segment ?? "");
+    const basePath = normalizeName(entry.group.basePath);
+    const pathSegment = entry.group.basePath.split("/").at(-1) ?? "";
+    const normalizedPathSegment = normalizeName(pathSegment);
+    return Array.from(AGGREGATE_CONTEXT_MARKERS).some((marker) => contextName === marker ||
+        segment === marker ||
+        normalizedPathSegment === marker ||
+        basePath.includes(`/${marker}/`) ||
+        basePath.endsWith(`/${marker}`));
+}
+function termLooksLikeAggregateCandidate(term) {
+    const normalized = term.canonicalTerm.trim();
+    if (normalized.length === 0) {
+        return false;
+    }
+    if (isNoisyAggregateLabel(normalized)) {
+        return false;
+    }
+    return !STOPWORD_AGGREGATE_TERMS.some((pattern) => pattern.test(normalized));
+}
+function countTermSupport(term, rules, invariants) {
+    const normalizedTerm = normalizeName(term.canonicalTerm);
+    return [...rules, ...invariants].filter((entry) => {
+        if (normalizeName(entry.statement).includes(normalizedTerm)) {
+            return true;
+        }
+        return (entry.relatedTerms ?? []).some((relatedTerm) => normalizeName(relatedTerm) === normalizedTerm);
+    }).length;
+}
+export function createInferredAggregateCandidates(contextCandidates, docsBundle) {
+    if (!docsBundle) {
+        return [];
+    }
+    const model = {
+        version: "1.0",
+        contexts: contextCandidates.map((entry) => entry.candidate.definition),
+    };
+    const contextEntryByName = new Map(contextCandidates.map((entry) => [entry.candidate.definition.name, entry]));
+    const contextByName = new Map(model.contexts.map((context) => [context.name, context]));
+    const linkByTermId = new Map(docsBundle.termLinks.map((link) => [link.termId, link]));
+    const fragmentContextMentions = buildFragmentContextMentions(docsBundle.glossary.fragments, model);
+    const candidates = [];
+    for (const term of docsBundle.glossary.terms) {
+        if (!termLooksLikeAggregateCandidate(term)) {
+            continue;
+        }
+        const link = linkByTermId.get(term.termId);
+        const contexts = collectTermContexts(term, link, fragmentContextMentions, model);
+        if (contexts.length !== 1) {
+            continue;
+        }
+        const contextName = contexts[0];
+        if (!contextName) {
+            continue;
+        }
+        const context = contextByName.get(contextName);
+        if (!context || hasContractOccurrence(link, context) || !hasInternalOccurrence(link, context)) {
+            continue;
+        }
+        const supportCount = countTermSupport(term, docsBundle.rules.rules, docsBundle.invariants.invariants);
+        const contextEntry = contextEntryByName.get(contextName);
+        if (!contextEntry || !isAggregateEligibleContext(contextEntry)) {
+            continue;
+        }
+        if (supportCount === 0) {
+            continue;
+        }
+        const supportScore = supportCount + (link?.coverage.codeHits ?? 0);
+        const tokenCount = tokenizeAggregateLabel(term.canonicalTerm).length;
+        if (tokenCount <= 1 && supportScore < 3) {
+            continue;
+        }
+        const name = toPascalCase(term.canonicalTerm);
+        const aliases = sanitizeAggregateAliases(name, [term.canonicalTerm, ...term.aliases]);
+        const confidence = clampConfidence(0.58 +
+            Math.min(0.15, supportCount * 0.05) +
+            ((link?.coverage.codeHits ?? 0) > 0 ? 0.08 : 0) +
+            (term.collision ? -0.08 : 0));
+        candidates.push({
+            definition: {
+                name,
+                context: contextName,
+                ...(aliases.length > 0 ? { aliases } : {}),
+            },
+            confidence,
+            evidence: [
+                toEvidence(`${name} was inferred from a localized term in ${contextName}.`, {
+                    context: contextName,
+                    term: term.canonicalTerm,
+                    codeHits: link?.coverage.codeHits ?? 0,
+                    supportCount,
+                }, [term.termId], confidence),
+            ],
+            unknowns: ["The aggregate name is inferred from localized document terms and should be reviewed."],
+        });
+    }
+    return candidates;
+}

package/dist/src/core/scaffold-domain-aggregates-shared.d.ts

@@ -0,0 +1,23 @@
+export declare const STOPWORD_AGGREGATE_TERMS: RegExp[];
+export declare function normalizeName(value: string): string;
+export declare function tokenizeAggregateLabel(value: string): string[];
+export declare function isNoisyAggregateLabel(value: string): boolean;
+export declare function toPascalCase(value: string): string;
+export declare function sanitizeAggregateAliases(name: string, aliases: string[]): string[];
+export declare function hasContractOccurrence(termLink: {
+    occurrences?: Array<{
+        kind: string;
+        path: string;
+    }>;
+} | undefined, context: {
+    contractGlobs?: string[];
+}): boolean;
+export declare function hasInternalOccurrence(termLink: {
+    occurrences?: Array<{
+        kind: string;
+        path: string;
+    }>;
+} | undefined, context: {
+    internalGlobs?: string[];
+    pathGlobs?: string[];
+}): boolean;

package/dist/src/core/scaffold-domain-aggregates-shared.js

@@ -0,0 +1,91 @@
+import { matchGlobs } from "./io.js";
+export const STOPWORD_AGGREGATE_TERMS = [/context$/i, /contract$/i, /service$/i, /handler$/i, /controller$/i];
+const NOISY_SINGLE_TOKEN_TERMS = new Set([
+    "codex",
+    "declaration",
+    "declarations",
+    "index",
+    "indexes",
+    "boundary",
+    "boundaries",
+    "modified",
+    "missing",
+    "requires",
+    "escalation",
+]);
+const NOISY_MULTI_TOKEN_TERMS = new Set(["diff", "patch", "branch", "worktree", "commit"]);
+function unique(values) {
+    return Array.from(new Set(values));
+}
+export function normalizeName(value) {
+    return value.trim().toLowerCase();
+}
+function normalizeAggregateLabel(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/gu, " ")
+        .replace(/\s+/gu, " ")
+        .trim();
+}
+export function tokenizeAggregateLabel(value) {
+    return normalizeAggregateLabel(value)
+        .split(" ")
+        .map((segment) => segment.trim())
+        .filter((segment) => segment.length > 0);
+}
+export function isNoisyAggregateLabel(value) {
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+        return true;
+    }
+    if (/[\s]*cp\b|\bgit\b|\bmv\b|\brm\b/i.test(trimmed)) {
+        return true;
+    }
+    if (/[/\\=:<>|`$]/u.test(trimmed) || /\.env\b/i.test(trimmed)) {
+        return true;
+    }
+    if (/^[A-Z0-9_]+$/u.test(trimmed)) {
+        return true;
+    }
+    if (!/[a-z]/u.test(trimmed) && /[A-Z]/u.test(trimmed) && trimmed.length <= 12) {
+        return true;
+    }
+    const tokens = tokenizeAggregateLabel(trimmed);
+    if (tokens.length === 0) {
+        return true;
+    }
+    if (tokens.length === 1) {
+        return NOISY_SINGLE_TOKEN_TERMS.has(tokens[0] ?? "");
+    }
+    return tokens.some((token) => NOISY_MULTI_TOKEN_TERMS.has(token));
+}
+export function toPascalCase(value) {
+    const normalized = value
+        .replace(/\.[^.]+$/u, "")
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .replace(/[^a-zA-Z0-9]+/g, " ")
+        .trim();
+    if (!normalized) {
+        return "Generated";
+    }
+    return normalized
+        .split(/\s+/u)
+        .filter(Boolean)
+        .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
+        .join("");
+}
+export function sanitizeAggregateAliases(name, aliases) {
+    const normalizedName = normalizeAggregateLabel(name);
+    return unique(aliases
+        .map((alias) => alias.trim())
+        .filter((alias) => alias.length > 0 && normalizeAggregateLabel(alias) !== normalizedName && !isNoisyAggregateLabel(alias)));
+}
+export function hasContractOccurrence(termLink, context) {
+    return (termLink?.occurrences ?? []).some((occurrence) => occurrence.kind === "code" && matchGlobs(occurrence.path, context.contractGlobs ?? []));
+}
+export function hasInternalOccurrence(termLink, context) {
+    return (termLink?.occurrences ?? []).some((occurrence) => occurrence.kind === "code" &&
+        (matchGlobs(occurrence.path, context.internalGlobs ?? []) ||
+            matchGlobs(occurrence.path, context.pathGlobs ?? [])));
+}

package/dist/src/core/scaffold-domain-aggregates.d.ts

@@ -0,0 +1 @@
+export { buildAggregateCandidates } from "./scaffold-domain-aggregates-core.js";

package/dist/src/core/scaffold-domain-aggregates.js

@@ -0,0 +1 @@
+export { buildAggregateCandidates } from "./scaffold-domain-aggregates-core.js";

package/dist/src/core/scaffold-domain-context-candidates.d.ts

@@ -0,0 +1,5 @@
+import type { DomainContextCandidate } from "./contracts.js";
+import type { GlossaryExtractionResult } from "./scaffold-domain-docs.js";
+import type { SourceGroup } from "./scaffold-types.js";
+export declare function scoreContextNameAffinity(candidateName: string, fallbackName: string): number;
+export declare function buildContextCandidate(group: SourceGroup, name: string, fragments: GlossaryExtractionResult["fragments"] | undefined): DomainContextCandidate;

package/dist/src/core/scaffold-domain-context-candidates.js

@@ -0,0 +1,65 @@
+import { clampConfidence, toEvidence } from "./response.js";
+import { normalizeName } from "./scaffold-naming.js";
+import { CONTRACT_MARKERS, INTERNAL_MARKERS } from "./scaffold-source-group-constants.js";
+import { collectMarkerGlobs } from "./scaffold-source-groups.js";
+const NAME_AFFINITY_STOPWORDS = new Set(["and", "or", "the", "of"]);
+function tokenizePascalLikeName(value) {
+    return value
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .split(/[^A-Za-z0-9]+/u)
+        .map((segment) => normalizeName(segment))
+        .filter((segment) => segment.length > 0 && !NAME_AFFINITY_STOPWORDS.has(segment));
+}
+function scoreNameAffinity(candidateName, fallbackName) {
+    const candidateTokens = new Set(tokenizePascalLikeName(candidateName));
+    const fallbackTokens = tokenizePascalLikeName(fallbackName);
+    return fallbackTokens.filter((token) => candidateTokens.has(token)).length;
+}
+export function scoreContextNameAffinity(candidateName, fallbackName) {
+    return scoreNameAffinity(candidateName, fallbackName);
+}
+function countContextMentions(name, fragments) {
+    if (!fragments) {
+        return 0;
+    }
+    const normalizedName = normalizeName(name);
+    return fragments.filter((fragment) => normalizeName(fragment.text).includes(normalizedName)).length;
+}
+export function buildContextCandidate(group, name, fragments) {
+    const pathGlobs = group.pathGlobs;
+    const contractGlobs = collectMarkerGlobs(group, CONTRACT_MARKERS);
+    const internalGlobs = collectMarkerGlobs(group, INTERNAL_MARKERS);
+    const docsMentions = countContextMentions(name, fragments);
+    const confidence = clampConfidence(0.55 +
+        (group.heuristicSplit ? 0.08 : group.segment ? 0.12 : 0.05) +
+        (group.files.length >= 2 ? 0.08 : 0) +
+        (contractGlobs.length > 0 ? 0.08 : 0) +
+        (internalGlobs.length > 0 ? 0.08 : 0) +
+        (docsMentions > 0 ? 0.08 : 0));
+    const groupScope = group.heuristicSplit && (group.origins?.length ?? 0) > 1
+        ? `${group.origins?.length ?? 0} source buckets`
+        : group.basePath || "repository root";
+    const definition = {
+        name,
+        pathGlobs,
+        ...(contractGlobs.length > 0 ? { contractGlobs } : {}),
+        ...(internalGlobs.length > 0 ? { internalGlobs } : {}),
+    };
+    return {
+        definition,
+        confidence,
+        evidence: [
+            toEvidence(`${name} was inferred from ${group.files.length} source file(s) under ${groupScope}.`, {
+                group: group.basePath || ".",
+                ...(group.origins && group.origins.length > 0 ? { origins: group.origins } : {}),
+                files: group.files.slice(0, 5),
+                pathGlobs,
+            }, undefined, confidence),
+        ],
+        unknowns: group.heuristicSplit
+            ? ["This context was split from a broad infrastructure bucket by heuristic and should be reviewed."]
+            : group.segment
+                ? []
+                : ["Root-level source files were grouped into a single context by heuristic."],
+    };
+}

package/dist/src/core/scaffold-domain-context-naming.d.ts

@@ -0,0 +1,8 @@
+import type { Fragment, GlossaryTerm, TermTraceLink } from "./contracts.js";
+import type { SourceGroup } from "./scaffold-types.js";
+export interface DocsContextNamingInput {
+    fragments: Fragment[];
+    terms: GlossaryTerm[];
+    termLinks: TermTraceLink[];
+}
+export declare function inferDocsDrivenContextName(group: SourceGroup, fallbackName: string, docsInput: DocsContextNamingInput | undefined): string | undefined;

package/dist/src/core/scaffold-domain-context-naming.js

@@ -0,0 +1,117 @@
+import { isNoisyAggregateLabel } from "./scaffold-domain-aggregates-shared.js";
+import { normalizeName, toPascalCase } from "./scaffold-naming.js";
+const DOCS_HEADING_NOISE_TOKENS = new Set([
+    "appendix",
+    "diagram",
+    "diagrams",
+    "mermaid",
+    "guide",
+    "guides",
+    "reference",
+    "references",
+    "index",
+    "example",
+    "examples",
+    "setup",
+    "installation",
+    "usage",
+]);
+function cleanHeadingLabel(value) {
+    return value
+        .replace(/^#+\s*/u, "")
+        .replace(/`/gu, "")
+        .replace(/\b(context|module|layer)\b/giu, "")
+        .replace(/[^A-Za-z0-9]+/gu, " ")
+        .replace(/\s+/gu, " ")
+        .trim();
+}
+function isUsefulHeadingLabel(value) {
+    const normalized = cleanHeadingLabel(value);
+    if (normalized.length < 4) {
+        return false;
+    }
+    const tokenCount = normalized.split(/\s+/u).filter(Boolean).length;
+    if (tokenCount === 0 || tokenCount > 4) {
+        return false;
+    }
+    const lowered = normalizeName(normalized);
+    if (new Set(["docs", "glossary", "rules", "invariants", "architecture", "overview"]).has(lowered)) {
+        return false;
+    }
+    const tokens = lowered.split(/\s+/u).filter(Boolean);
+    return !tokens.some((token) => DOCS_HEADING_NOISE_TOKENS.has(token));
+}
+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" && isUsefulHeadingLabel(fragment.text)) {
+                currentHeading = cleanHeadingLabel(fragment.text);
+            }
+            if (currentHeading) {
+                headingByFragmentId.set(fragment.fragmentId, currentHeading);
+            }
+        }
+    }
+    return headingByFragmentId;
+}
+function hasLocalizedCodeOccurrence(link, group) {
+    return (link.occurrences ?? []).some((occurrence) => occurrence.kind === "code" && group.files.includes(occurrence.path));
+}
+export function inferDocsDrivenContextName(group, fallbackName, docsInput) {
+    if (!docsInput) {
+        return undefined;
+    }
+    const headingByFragmentId = buildHeadingByFragmentId(docsInput.fragments);
+    const termById = new Map(docsInput.terms.map((term) => [term.termId, term]));
+    const scores = new Map();
+    for (const link of docsInput.termLinks) {
+        if (!hasLocalizedCodeOccurrence(link, group)) {
+            continue;
+        }
+        const term = termById.get(link.termId);
+        if (!term) {
+            continue;
+        }
+        if (isNoisyAggregateLabel(term.canonicalTerm)) {
+            continue;
+        }
+        const contribution = Math.max(2, link.coverage.codeHits || 0);
+        for (const fragmentId of term.fragmentIds) {
+            const heading = headingByFragmentId.get(fragmentId);
+            if (!heading) {
+                continue;
+            }
+            const candidate = toPascalCase(heading);
+            if (candidate.length === 0 || normalizeName(candidate) === normalizeName(fallbackName)) {
+                continue;
+            }
+            scores.set(candidate, (scores.get(candidate) ?? 0) + contribution);
+        }
+    }
+    const ranked = Array.from(scores.entries()).sort((left, right) => {
+        if (right[1] !== left[1]) {
+            return right[1] - left[1];
+        }
+        return left[0].localeCompare(right[0]);
+    });
+    const [best, next] = ranked;
+    if (!best) {
+        return undefined;
+    }
+    if (best[1] < 2) {
+        return undefined;
+    }
+    if (next && next[1] === best[1]) {
+        return undefined;
+    }
+    return best[0];
+}

package/dist/src/core/scaffold-domain-contexts.d.ts

@@ -0,0 +1,11 @@
+import type { parseCodebase } from "../analyzers/code.js";
+import type { DomainContextCandidate } from "./contracts.js";
+import { type DocsContextNamingInput } from "./scaffold-domain-context-naming.js";
+import { type SourceGroup } from "./scaffold-shared.js";
+type ParsedCodebase = Awaited<ReturnType<typeof parseCodebase>>;
+export interface ContextCandidateEntry {
+    group: SourceGroup;
+    candidate: DomainContextCandidate;
+}
+export declare function buildContextCandidates(codebase: ParsedCodebase, docsInput: DocsContextNamingInput | undefined): ContextCandidateEntry[];
+export {};