context-probe 0.1.0

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

@@ -0,0 +1,75 @@
+import { buildContextCandidate, scoreContextNameAffinity } from "./scaffold-domain-context-candidates.js";
+import { inferDocsDrivenContextName } from "./scaffold-domain-context-naming.js";
+import { groupSourceFiles, inferGroupNames } from "./scaffold-shared.js";
+import { mergeSourceGroups } from "./scaffold-source-group-merge.js";
+export function buildContextCandidates(codebase, docsInput) {
+    const groups = groupSourceFiles(codebase);
+    if (groups.length === 0) {
+        throw new Error("No scorable source files were found to scaffold a domain model.");
+    }
+    const fallbackNames = inferGroupNames(groups);
+    const proposedNames = groups.map((group, index) => inferDocsDrivenContextName(group, fallbackNames[index] ?? "Context", docsInput));
+    const proposedNameOwners = new Map();
+    for (const [index, proposedName] of proposedNames.entries()) {
+        if (!proposedName) {
+            continue;
+        }
+        proposedNameOwners.set(proposedName, [...(proposedNameOwners.get(proposedName) ?? []), index]);
+    }
+    const acceptedDocsDrivenIndexes = new Set();
+    for (const [proposedName, ownerIndexes] of proposedNameOwners.entries()) {
+        if (ownerIndexes.length === 1) {
+            const onlyOwnerIndex = ownerIndexes[0];
+            if (onlyOwnerIndex !== undefined) {
+                acceptedDocsDrivenIndexes.add(onlyOwnerIndex);
+            }
+            continue;
+        }
+        const rankedOwners = ownerIndexes
+            .map((index) => ({
+            index,
+            affinity: scoreContextNameAffinity(proposedName, fallbackNames[index] ?? "Context"),
+        }))
+            .sort((left, right) => right.affinity - left.affinity || left.index - right.index);
+        const best = rankedOwners[0];
+        const next = rankedOwners[1];
+        if (!best || best.affinity === 0 || (next && next.affinity === best.affinity)) {
+            continue;
+        }
+        acceptedDocsDrivenIndexes.add(best.index);
+    }
+    const consumedIndexes = new Set();
+    const mergedEntries = [];
+    for (const [proposedName, ownerIndexes] of proposedNameOwners.entries()) {
+        const mergeableOwners = ownerIndexes.filter((index) => scoreContextNameAffinity(proposedName, fallbackNames[index] ?? "Context") > 0);
+        if (mergeableOwners.length < 2) {
+            continue;
+        }
+        for (const index of mergeableOwners) {
+            consumedIndexes.add(index);
+        }
+        const mergeGroups = mergeableOwners
+            .map((index) => groups[index])
+            .filter((group) => group !== undefined);
+        mergedEntries.push({
+            group: mergeSourceGroups(`__docs__/${proposedName}`, mergeGroups, { forceHeuristicSplit: true }),
+            name: proposedName,
+            order: Math.min(...mergeableOwners),
+        });
+    }
+    const entries = groups
+        .map((group, index) => ({
+        order: index,
+        group,
+        name: proposedNames[index] && acceptedDocsDrivenIndexes.has(index)
+            ? proposedNames[index]
+            : (fallbackNames[index] ?? "Context"),
+    }))
+        .filter((entry) => !consumedIndexes.has(entry.order))
+        .concat(mergedEntries)
+        .sort((left, right) => left.order - right.order);
+    return entries.map((entry) => ({
+        group: entry.group,
+        candidate: buildContextCandidate(entry.group, entry.name, docsInput?.fragments),
+    }));
+}

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

@@ -0,0 +1,17 @@
+import { extractGlossary, extractInvariants, extractRules } from "./document-extractors.js";
+import { type ExtractionOptions } from "./scaffold-shared.js";
+import { buildTermTraceLinks } from "./trace.js";
+export type GlossaryExtractionResult = Awaited<ReturnType<typeof extractGlossary>>;
+type RulesExtractionResult = Awaited<ReturnType<typeof extractRules>>;
+type InvariantsExtractionResult = Awaited<ReturnType<typeof extractInvariants>>;
+export interface DocsBundle {
+    glossary: GlossaryExtractionResult;
+    rules: RulesExtractionResult;
+    invariants: InvariantsExtractionResult;
+    termLinks: Awaited<ReturnType<typeof buildTermTraceLinks>>;
+}
+interface CodebaseFiles {
+    scorableSourceFiles: string[];
+}
+export declare function buildDocsBundle(repoRoot: string, docsRoot: string, codebase: CodebaseFiles, extractionOptions: ExtractionOptions | undefined): Promise<DocsBundle>;
+export {};

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

@@ -0,0 +1,18 @@
+import { extractGlossary, extractInvariants, extractRules } from "./document-extractors.js";
+import { createDefaultExtractionOptions } from "./scaffold-shared.js";
+import { buildTermTraceLinks } from "./trace.js";
+export async function buildDocsBundle(repoRoot, docsRoot, codebase, extractionOptions) {
+    const options = extractionOptions ?? createDefaultExtractionOptions(docsRoot, repoRoot);
+    const [glossary, rules, invariants] = await Promise.all([
+        extractGlossary(options),
+        extractRules(options),
+        extractInvariants(options),
+    ]);
+    const termLinks = await buildTermTraceLinks({
+        docsRoot,
+        repoRoot,
+        terms: glossary.terms,
+        codeFiles: codebase.scorableSourceFiles,
+    });
+    return { glossary, rules, invariants, termLinks };
+}

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

@@ -0,0 +1,7 @@
+import type { DomainModelScaffoldResult } from "./contracts.js";
+import { type ExtractionOptions, type ScaffoldComputation } from "./scaffold-shared.js";
+export declare function scaffoldDomainModel(options: {
+    repoRoot: string;
+    docsRoot?: string;
+    extractionOptions?: ExtractionOptions;
+}): Promise<ScaffoldComputation<DomainModelScaffoldResult>>;

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

@@ -0,0 +1,62 @@
+import YAML from "yaml";
+import { parseCodebase } from "../analyzers/code.js";
+import { clampConfidence } from "./response.js";
+import { buildAggregateCandidates } from "./scaffold-domain-aggregates.js";
+import { buildContextCandidates } from "./scaffold-domain-contexts.js";
+import { buildDocsBundle } from "./scaffold-domain-docs.js";
+import { averageConfidence, mergeEvidence, mergeUnknowns, unique, } from "./scaffold-shared.js";
+export async function scaffoldDomainModel(options) {
+    const codebase = await parseCodebase(options.repoRoot);
+    const docsBundle = options.docsRoot
+        ? await buildDocsBundle(options.repoRoot, options.docsRoot, codebase, options.extractionOptions)
+        : undefined;
+    const contextCandidates = buildContextCandidates(codebase, docsBundle
+        ? {
+            fragments: docsBundle.glossary.fragments,
+            terms: docsBundle.glossary.terms,
+            termLinks: docsBundle.termLinks,
+        }
+        : undefined);
+    const aggregateCandidates = buildAggregateCandidates(contextCandidates, docsBundle);
+    const model = {
+        version: "1.0",
+        contexts: contextCandidates.map((entry) => entry.candidate.definition),
+        ...(aggregateCandidates.length > 0
+            ? {
+                aggregates: aggregateCandidates.map((candidate) => candidate.definition),
+            }
+            : {}),
+    };
+    const result = {
+        model,
+        yaml: YAML.stringify(model),
+        contexts: contextCandidates.map((entry) => entry.candidate),
+        aggregates: aggregateCandidates,
+    };
+    const extractionSignals = docsBundle
+        ? [docsBundle.glossary.confidence, docsBundle.rules.confidence, docsBundle.invariants.confidence]
+        : [];
+    const confidence = clampConfidence(averageConfidence(contextCandidates, aggregateCandidates, extractionSignals));
+    const unknowns = mergeUnknowns([...contextCandidates.map((entry) => entry.candidate), ...aggregateCandidates], [
+        ...(docsBundle
+            ? [...docsBundle.glossary.unknowns, ...docsBundle.rules.unknowns, ...docsBundle.invariants.unknowns]
+            : ["No docs root was provided, so aggregate candidates rely on code structure only."]),
+        ...(aggregateCandidates.length === 0
+            ? ["No aggregate candidates were observed; review whether aggregates should be declared explicitly."]
+            : []),
+    ]);
+    const diagnostics = unique([
+        ...(docsBundle
+            ? [...docsBundle.glossary.diagnostics, ...docsBundle.rules.diagnostics, ...docsBundle.invariants.diagnostics]
+            : []),
+        `Scaffolded ${contextCandidates.length} context candidate(s).`,
+        `Scaffolded ${aggregateCandidates.length} aggregate candidate(s).`,
+    ].filter((entry) => entry.length > 0));
+    return {
+        result,
+        confidence,
+        evidence: mergeEvidence([...contextCandidates.map((entry) => entry.candidate), ...aggregateCandidates]),
+        unknowns,
+        diagnostics,
+    };
+}

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

@@ -0,0 +1,4 @@
+export declare function unique<T>(values: T[]): T[];
+export declare function normalizeName(value: string): string;
+export declare function toPascalCase(value: string): string;
+export declare function makeUniqueNames(names: string[]): string[];

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

@@ -0,0 +1,32 @@
+export function unique(values) {
+    return Array.from(new Set(values));
+}
+export function normalizeName(value) {
+    return value.trim().toLowerCase();
+}
+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 makeUniqueNames(names) {
+    const counts = new Map();
+    return names.map((name) => {
+        const count = counts.get(name) ?? 0;
+        counts.set(name, count + 1);
+        if (count === 0) {
+            return name;
+        }
+        return `${name}${count + 1}`;
+    });
+}

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

@@ -0,0 +1,2 @@
+import type { ExtractionOptions } from "./scaffold-types.js";
+export declare function createDefaultExtractionOptions(docsRoot: string, repoRoot: string): ExtractionOptions;

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

@@ -0,0 +1,10 @@
+export function createDefaultExtractionOptions(docsRoot, repoRoot) {
+    return {
+        root: docsRoot,
+        cwd: repoRoot,
+        extractor: "heuristic",
+        promptProfile: "default",
+        fallback: "heuristic",
+        applyReviewLog: false,
+    };
+}

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

@@ -0,0 +1,5 @@
+export { averageConfidence, averageLayerConfidence, mergeEvidence, mergeUnknowns, } from "./scaffold-aggregation.js";
+export { makeUniqueNames, normalizeName, unique } from "./scaffold-naming.js";
+export { createDefaultExtractionOptions } from "./scaffold-options.js";
+export { groupSourceFiles, inferGroupDisplayName, inferGroupNames, LAYER_PRIORITY_HINTS, } from "./scaffold-source-groups.js";
+export type { ArchitectureLayerCandidate, CodebaseAnalysis, DomainContextCandidate, ExtractionOptions, ScaffoldComputation, SourceGroup, } from "./scaffold-types.js";

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

@@ -0,0 +1,4 @@
+export { averageConfidence, averageLayerConfidence, mergeEvidence, mergeUnknowns, } from "./scaffold-aggregation.js";
+export { makeUniqueNames, normalizeName, unique } from "./scaffold-naming.js";
+export { createDefaultExtractionOptions } from "./scaffold-options.js";
+export { groupSourceFiles, inferGroupDisplayName, inferGroupNames, LAYER_PRIORITY_HINTS, } from "./scaffold-source-groups.js";

package/dist/src/core/scaffold-source-group-classification.d.ts

@@ -0,0 +1,3 @@
+export declare function findSourceRootIndex(parts: string[]): number;
+export declare function classifySubgroup(segment: string | undefined, filePath: string, basePath: string): string | undefined;
+export declare function inferGroupOrigin(basePath: string, sourceRoot: string | undefined, filePath: string): string;

package/dist/src/core/scaffold-source-group-classification.js

@@ -0,0 +1,91 @@
+import path from "node:path";
+const SOURCE_ROOTS = new Set(["src", "lib", "app"]);
+const SUBGROUPABLE_SEGMENTS = new Set([
+    "adapters",
+    "adapter",
+    "services",
+    "service",
+    "server",
+    "project",
+    "bootstrap",
+    "evaluation",
+    "quality",
+    "mcp",
+    "interfaces",
+    "interface",
+]);
+const EXTRACTION_MARKERS = [
+    "extract",
+    "extractor",
+    "ingest",
+    "import",
+    "loader",
+    "load",
+    "parser",
+    "parse",
+    "sync",
+    "crawl",
+    "scrape",
+    "git",
+];
+const RUNTIME_MARKERS = [
+    "runtime",
+    "server",
+    "http",
+    "router",
+    "endpoint",
+    "socket",
+    "mcp",
+    "duckdb",
+    "sqlite",
+    "postgres",
+    "mysql",
+    "redis",
+    "cache",
+    "queue",
+    "store",
+    "storage",
+    "search",
+    "index",
+    "vector",
+    "embed",
+    "embedding",
+    "neo4j",
+    "graph",
+    "query",
+];
+const WORKSPACE_MARKERS = ["workspace", "project", "bootstrap", "registry", "config", "env", "setup"];
+const EVALUATION_MARKERS = ["evaluation", "quality", "benchmark", "review", "telemetry", "metric", "score", "eval"];
+export function findSourceRootIndex(parts) {
+    return parts.findIndex((part) => SOURCE_ROOTS.has(part ?? ""));
+}
+export function classifySubgroup(segment, filePath, basePath) {
+    if (!segment || !SUBGROUPABLE_SEGMENTS.has(segment.toLowerCase())) {
+        return undefined;
+    }
+    const relative = basePath && filePath.startsWith(`${basePath}/`) ? filePath.slice(basePath.length + 1) : path.basename(filePath);
+    const normalized = relative.toLowerCase();
+    if (EXTRACTION_MARKERS.some((marker) => normalized.includes(marker))) {
+        return "IngestAndExtraction";
+    }
+    if (WORKSPACE_MARKERS.some((marker) => normalized.includes(marker))) {
+        return "WorkspaceBootstrap";
+    }
+    if (EVALUATION_MARKERS.some((marker) => normalized.includes(marker))) {
+        return "EvaluationQuality";
+    }
+    if (RUNTIME_MARKERS.some((marker) => normalized.includes(marker))) {
+        return "RuntimeInfrastructure";
+    }
+    return undefined;
+}
+export function inferGroupOrigin(basePath, sourceRoot, filePath) {
+    if (basePath) {
+        return basePath;
+    }
+    if (sourceRoot) {
+        return sourceRoot;
+    }
+    const parts = filePath.split("/");
+    return parts.length > 1 ? (parts[0] ?? ".") : ".";
+}

package/dist/src/core/scaffold-source-group-constants.d.ts

@@ -0,0 +1,3 @@
+export declare const CONTRACT_MARKERS: Set<string>;
+export declare const LAYER_PRIORITY_HINTS: Map<string, number>;
+export declare const INTERNAL_MARKERS: Set<string>;

package/dist/src/core/scaffold-source-group-constants.js

@@ -0,0 +1,52 @@
+export const CONTRACT_MARKERS = new Set(["contract", "contracts", "api", "schema", "schemas", "dto", "dtos"]);
+export const LAYER_PRIORITY_HINTS = new Map([
+    ["domain", 0],
+    ["core", 0],
+    ["foundation", 0],
+    ["model", 0],
+    ["kernel", 0],
+    ["contracts", 0],
+    ["application", 1],
+    ["app", 1],
+    ["usecase", 1],
+    ["usecases", 1],
+    ["use_case", 1],
+    ["use_cases", 1],
+    ["service", 1],
+    ["services", 1],
+    ["domain_services", 1],
+    ["orchestration", 1],
+    ["adapter", 2],
+    ["adapters", 2],
+    ["extractor", 2],
+    ["extractors", 2],
+    ["ingestandextraction", 2],
+    ["interface", 2],
+    ["interfaces", 2],
+    ["delivery", 2],
+    ["presentation", 2],
+    ["ui", 2],
+    ["api", 2],
+    ["transport", 2],
+    ["server", 2],
+    ["mcp", 2],
+    ["infra", 3],
+    ["infrastructure", 3],
+    ["persistence", 3],
+    ["platform", 3],
+    ["runtime", 3],
+    ["runtimeinfrastructure", 3],
+    ["project", 4],
+    ["workspace", 4],
+    ["bootstrap", 4],
+    ["workspacebootstrap", 4],
+    ["evaluation", 5],
+    ["quality", 5],
+    ["evaluationquality", 5],
+    ["tooling", 6],
+    ["tools", 6],
+    ["scripts", 6],
+    ["test", 7],
+    ["tests", 7],
+]);
+export const INTERNAL_MARKERS = new Set(["internal", "impl", "private", "_internal"]);

package/dist/src/core/scaffold-source-group-merge.d.ts

@@ -0,0 +1,5 @@
+import type { SourceGroup } from "./scaffold-types.js";
+export declare function mergeSourceGroups(key: string, groups: SourceGroup[], options?: {
+    forceHeuristicSplit?: boolean;
+}): SourceGroup;
+export declare function mergeMonorepoEquivalentGroups(groups: SourceGroup[]): SourceGroup[];

package/dist/src/core/scaffold-source-group-merge.js

@@ -0,0 +1,56 @@
+import { inferGroupDisplayName, normalizeSegmentKey } from "./scaffold-source-group-naming.js";
+export function mergeSourceGroups(key, groups, options) {
+    const sourceRoots = Array.from(new Set(groups.map((group) => group.sourceRoot).filter((value) => value !== undefined)));
+    const segments = Array.from(new Set(groups.map((group) => group.segment).filter((value) => value !== undefined)));
+    const origins = Array.from(new Set(groups.flatMap((group) => group.origins && group.origins.length > 0 ? group.origins : group.basePath ? [group.basePath] : []))).sort();
+    const files = Array.from(new Set(groups.flatMap((group) => group.files))).sort();
+    const pathGlobs = Array.from(new Set(groups.flatMap((group) => group.pathGlobs))).sort();
+    return {
+        key,
+        basePath: origins[0] ?? groups[0]?.basePath ?? "",
+        ...(sourceRoots.length === 1 ? { sourceRoot: sourceRoots[0] } : {}),
+        ...(segments.length === 1 ? { segment: segments[0] } : {}),
+        heuristicSplit: Boolean(options?.forceHeuristicSplit) || groups.some((group) => group.heuristicSplit) || origins.length > 1,
+        ...(origins.length > 0 ? { origins } : {}),
+        pathGlobs,
+        files,
+    };
+}
+function shouldMergeMonorepoGroup(group) {
+    if (group.basePath.startsWith("packages/") || group.basePath.startsWith("apps/")) {
+        return true;
+    }
+    return Boolean(group.sourceRoot) || (group.origins?.length ?? 0) > 1;
+}
+export function mergeMonorepoEquivalentGroups(groups) {
+    const mergeableByDisplayName = new Map();
+    const passthrough = [];
+    for (const group of groups) {
+        if (!shouldMergeMonorepoGroup(group)) {
+            passthrough.push(group);
+            continue;
+        }
+        const displayName = inferGroupDisplayName(group);
+        const normalizedDisplayName = normalizeSegmentKey(displayName);
+        mergeableByDisplayName.set(normalizedDisplayName, [
+            ...(mergeableByDisplayName.get(normalizedDisplayName) ?? []),
+            group,
+        ]);
+    }
+    const merged = Array.from(mergeableByDisplayName.entries()).map(([normalizedDisplayName, matchingGroups]) => {
+        if (matchingGroups.length < 2) {
+            return matchingGroups[0];
+        }
+        const firstGroup = matchingGroups[0];
+        if (!firstGroup) {
+            return matchingGroups[0];
+        }
+        const preferredSegment = inferGroupDisplayName(firstGroup);
+        const mergedGroup = mergeSourceGroups(`__merged__/${normalizedDisplayName}`, matchingGroups);
+        return {
+            ...mergedGroup,
+            ...(matchingGroups.some((group) => group.segment) ? { segment: preferredSegment } : {}),
+        };
+    });
+    return [...passthrough, ...merged.filter((group) => group !== undefined)];
+}

package/dist/src/core/scaffold-source-group-naming.d.ts

@@ -0,0 +1,4 @@
+import type { SourceGroup } from "./scaffold-types.js";
+export declare function normalizeSegmentKey(value: string): string;
+export declare function inferGroupDisplayName(group: SourceGroup): string;
+export declare function inferGroupNames(groups: SourceGroup[]): string[];

package/dist/src/core/scaffold-source-group-naming.js

@@ -0,0 +1,66 @@
+import { makeUniqueNames, toPascalCase } from "./scaffold-naming.js";
+const SEGMENT_NAME_HINTS = new Map([
+    ["app", "App"],
+    ["api", "API"],
+    ["bootstrap", "Bootstrap"],
+    ["cli", "CLI"],
+    ["ci", "CI"],
+    ["contracts", "Contracts"],
+    ["contract", "Contracts"],
+    ["core", "Core"],
+    ["data", "Data"],
+    ["delivery", "Delivery"],
+    ["domain", "Domain"],
+    ["evaluation", "Evaluation"],
+    ["extractor", "Extractors"],
+    ["extractors", "Extractors"],
+    ["infra", "Infrastructure"],
+    ["infrastructure", "Infrastructure"],
+    ["interfaces", "Interfaces"],
+    ["interface", "Interfaces"],
+    ["kernel", "Kernel"],
+    ["lib", "Library"],
+    ["llm", "LLM"],
+    ["mcp", "MCP"],
+    ["model", "Model"],
+    ["presentation", "Presentation"],
+    ["project", "Project"],
+    ["quality", "Quality"],
+    ["qa", "QA"],
+    ["runtime", "Runtime"],
+    ["scripts", "Scripts"],
+    ["server", "Server"],
+    ["service", "Services"],
+    ["services", "Services"],
+    ["tests", "Tests"],
+    ["test", "Tests"],
+    ["tools", "Tools"],
+    ["tooling", "Tools"],
+    ["ui", "UI"],
+    ["usecase", "UseCases"],
+    ["usecases", "UseCases"],
+    ["use_case", "UseCases"],
+    ["use_cases", "UseCases"],
+    ["workspace", "Workspace"],
+]);
+export function normalizeSegmentKey(value) {
+    return toPascalCase(value).toLowerCase();
+}
+function inferScaffoldName(value) {
+    return SEGMENT_NAME_HINTS.get(normalizeSegmentKey(value)) ?? toPascalCase(value);
+}
+function inferRootGroupName(group) {
+    if (group.sourceRoot === "src" || group.sourceRoot === "app") {
+        return "Application";
+    }
+    if (group.sourceRoot === "lib") {
+        return "Library";
+    }
+    return "Root";
+}
+export function inferGroupDisplayName(group) {
+    return group.segment ? inferScaffoldName(group.segment) : inferRootGroupName(group);
+}
+export function inferGroupNames(groups) {
+    return makeUniqueNames(groups.map((group) => inferGroupDisplayName(group)));
+}

package/dist/src/core/scaffold-source-groups.d.ts

@@ -0,0 +1,5 @@
+import type { CodebaseAnalysis, SourceGroup } from "./scaffold-types.js";
+export { LAYER_PRIORITY_HINTS } from "./scaffold-source-group-constants.js";
+export { inferGroupDisplayName, inferGroupNames } from "./scaffold-source-group-naming.js";
+export declare function groupSourceFiles(codebase: CodebaseAnalysis): SourceGroup[];
+export declare function collectMarkerGlobs(group: SourceGroup, markers: Set<string>): string[];