onto-mcp 0.3.0

package/dist/core-runtime/readers/brownfield-builder.js

@@ -0,0 +1,150 @@
+import { sourceKey } from "./types.js";
+/**
+ * Build BrownfieldContext + BrownfieldDetail from scan results.
+ *
+ * Pure function: no I/O, no side effects.
+ *
+ * BrownfieldContext contains Tier 1+2 items (for Build Spec Section 7).
+ * BrownfieldDetail contains Tier 3 (full scan results with anchors).
+ * detail_anchor links Tier 1+2 items to their Tier 3 detail sections.
+ */
+export function buildBrownfield(scopeId, scanResults) {
+    const related_files = [];
+    const module_dependencies = [];
+    const api_contracts = [];
+    const db_schemas = [];
+    const config_env = [];
+    const sections = [];
+    for (const result of scanResults) {
+        const srcKey = sourceKey(result.source);
+        const srcLabel = result.source.description ?? srcKey;
+        // ── Files → related_files ──
+        for (const file of result.files) {
+            if (file.category === "source" || file.category === "config" || file.category === "schema" || file.category === "test") {
+                const anchor = makeAnchor(srcKey, file.path);
+                related_files.push({
+                    path: file.path,
+                    role: file.category === "test"
+                        ? `test (${srcLabel})`
+                        : `${file.language ?? file.category} (${srcLabel})`,
+                    detail_anchor: anchor,
+                });
+                sections.push({
+                    anchor,
+                    source: srcLabel,
+                    title: file.path,
+                    content: `- 카테고리: ${file.category}\n- 언어: ${file.language ?? "N/A"}\n- 크기: ${file.size_bytes} bytes`,
+                });
+            }
+        }
+        // ── Dependency graph → module_dependencies ──
+        const seenDeps = new Set();
+        for (const edge of result.dependency_graph) {
+            const depKey = `${edge.from}→${edge.to}`;
+            if (seenDeps.has(depKey))
+                continue;
+            seenDeps.add(depKey);
+            const anchor = makeAnchor(srcKey, `dep-${edge.from}-${edge.to}`);
+            module_dependencies.push({
+                module: edge.from,
+                depends_on: edge.to,
+                detail_anchor: anchor,
+            });
+            sections.push({
+                anchor,
+                source: srcLabel,
+                title: `${edge.from} → ${edge.to}`,
+                content: `- 종류: ${edge.kind}\n- 출처 파일: ${edge.from}`,
+            });
+        }
+        // ── API patterns → api_contracts ──
+        for (const api of result.api_patterns) {
+            const anchor = makeAnchor(srcKey, `api-${api.method}-${api.path}-${api.file}-L${api.line}`);
+            api_contracts.push({
+                endpoint: api.path,
+                method: api.method,
+                description: `${api.file}:${api.line}`,
+                detail_anchor: anchor,
+            });
+            sections.push({
+                anchor,
+                source: srcLabel,
+                title: `${api.method} ${api.path}`,
+                content: `- 파일: ${api.file}\n- 라인: ${api.line}`,
+            });
+        }
+        // ── Schema patterns → db_schemas ──
+        for (const schema of result.schema_patterns) {
+            const anchor = makeAnchor(srcKey, `schema-${schema.table}-${schema.file}-L${schema.line}`);
+            db_schemas.push({
+                table: schema.table,
+                columns: schema.columns,
+                detail_anchor: anchor,
+            });
+            sections.push({
+                anchor,
+                source: srcLabel,
+                title: schema.table,
+                content: `- 파일: ${schema.file}\n- 라인: ${schema.line}\n- 컬럼: ${schema.columns}`,
+            });
+        }
+        // ── Config patterns → config_env ──
+        for (const cfg of result.config_patterns) {
+            const anchor = makeAnchor(srcKey, `config-${cfg.key}-${cfg.file}-L${cfg.line}`);
+            config_env.push({
+                key: cfg.key,
+                description: `${cfg.source_type} (${cfg.file}:${cfg.line})`,
+                detail_anchor: anchor,
+            });
+            sections.push({
+                anchor,
+                source: srcLabel,
+                title: cfg.key,
+                content: `- 타입: ${cfg.source_type}\n- 파일: ${cfg.file}\n- 라인: ${cfg.line}`,
+            });
+        }
+        // ── Doc structures → detail sections only (no BrownfieldContext field) ──
+        for (const doc of result.doc_structure) {
+            const anchor = makeAnchor(srcKey, `doc-${doc.file}`);
+            const parts = [`- 형식: ${doc.format}`];
+            if (doc.headings)
+                parts.push(`- 제목: ${doc.headings.join(", ")}`);
+            if (doc.top_level_keys)
+                parts.push(`- 키: ${doc.top_level_keys.join(", ")}`);
+            if (doc.item_counts) {
+                const counts = Object.entries(doc.item_counts).map(([k, v]) => `${k}: ${v}`).join(", ");
+                parts.push(`- 항목 수: ${counts}`);
+            }
+            sections.push({
+                anchor,
+                source: srcLabel,
+                title: doc.file,
+                content: parts.join("\n"),
+            });
+        }
+    }
+    return {
+        context: {
+            related_files,
+            module_dependencies,
+            api_contracts: api_contracts.length > 0 ? api_contracts : undefined,
+            db_schemas: db_schemas.length > 0 ? db_schemas : undefined,
+            config_env: config_env.length > 0 ? config_env : undefined,
+        },
+        detail: {
+            scope_id: scopeId,
+            sections,
+        },
+    };
+}
+// ─── Anchor generation ───
+function makeAnchor(srcKey, suffix) {
+    return sanitizeAnchor(`${srcKey}-${suffix}`);
+}
+function sanitizeAnchor(raw) {
+    return raw
+        .toLowerCase()
+        .replace(/[^a-z0-9가-힣_-]/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+}

package/dist/core-runtime/readers/brownfield-builder.test.js

@@ -0,0 +1,136 @@
+import { describe, it, expect } from "vitest";
+import { buildBrownfield } from "./brownfield-builder.js";
+function makeScanResult(overrides = {}) {
+    return {
+        source: { type: "add-dir", path: "/test" },
+        scanned_at: "2026-03-09T00:00:00Z",
+        files: [],
+        content_hashes: {},
+        dependency_graph: [],
+        api_patterns: [],
+        schema_patterns: [],
+        config_patterns: [],
+        doc_structure: [],
+        ...overrides,
+    };
+}
+describe("buildBrownfield", () => {
+    it("returns empty context and detail for empty scan results", () => {
+        const { context, detail } = buildBrownfield("SC-TEST", []);
+        expect(context.related_files).toEqual([]);
+        expect(context.module_dependencies).toEqual([]);
+        expect(detail.sections).toEqual([]);
+        expect(detail.scope_id).toBe("SC-TEST");
+    });
+    it("maps files to related_files with detail_anchor", () => {
+        const result = makeScanResult({
+            files: [
+                { path: "src/app.ts", category: "source", language: "typescript", size_bytes: 100 },
+            ],
+        });
+        const { context, detail } = buildBrownfield("SC-TEST", [result]);
+        expect(context.related_files).toHaveLength(1);
+        expect(context.related_files[0].path).toBe("src/app.ts");
+        expect(context.related_files[0].detail_anchor).toBeTruthy();
+        // detail has matching section
+        const anchor = context.related_files[0].detail_anchor;
+        expect(detail.sections.some(s => s.anchor === anchor)).toBe(true);
+    });
+    it("maps dependency_graph to module_dependencies", () => {
+        const result = makeScanResult({
+            dependency_graph: [
+                { from: "app.ts", to: "./utils", kind: "import" },
+            ],
+        });
+        const { context } = buildBrownfield("SC-TEST", [result]);
+        expect(context.module_dependencies).toHaveLength(1);
+        expect(context.module_dependencies[0].module).toBe("app.ts");
+        expect(context.module_dependencies[0].depends_on).toBe("./utils");
+    });
+    it("maps api_patterns to api_contracts", () => {
+        const result = makeScanResult({
+            api_patterns: [
+                { file: "Controller.java", method: "GET", path: "/api/users", line: 10 },
+            ],
+        });
+        const { context } = buildBrownfield("SC-TEST", [result]);
+        expect(context.api_contracts).toHaveLength(1);
+        expect(context.api_contracts[0].endpoint).toBe("/api/users");
+    });
+    it("maps schema_patterns to db_schemas", () => {
+        const result = makeScanResult({
+            schema_patterns: [
+                { file: "V1.sql", table: "users", columns: "id, name", line: 1 },
+            ],
+        });
+        const { context } = buildBrownfield("SC-TEST", [result]);
+        expect(context.db_schemas).toHaveLength(1);
+        expect(context.db_schemas[0].table).toBe("users");
+    });
+    it("maps config_patterns to config_env", () => {
+        const result = makeScanResult({
+            config_patterns: [
+                { file: ".env", key: "DB_URL", source_type: "dotenv", line: 1 },
+            ],
+        });
+        const { context } = buildBrownfield("SC-TEST", [result]);
+        expect(context.config_env).toHaveLength(1);
+        expect(context.config_env[0].key).toBe("DB_URL");
+    });
+    it("deduplicates dependency edges", () => {
+        const result = makeScanResult({
+            dependency_graph: [
+                { from: "a.ts", to: "b", kind: "import" },
+                { from: "a.ts", to: "b", kind: "import" },
+            ],
+        });
+        const { context } = buildBrownfield("SC-TEST", [result]);
+        expect(context.module_dependencies).toHaveLength(1);
+    });
+    it("merges multiple scan results", () => {
+        const r1 = makeScanResult({
+            source: { type: "add-dir", path: "/project1" },
+            files: [{ path: "a.ts", category: "source", language: "typescript", size_bytes: 50 }],
+        });
+        const r2 = makeScanResult({
+            source: { type: "add-dir", path: "/project2" },
+            files: [{ path: "b.java", category: "source", language: "java", size_bytes: 80 }],
+        });
+        const { context, detail } = buildBrownfield("SC-TEST", [r1, r2]);
+        expect(context.related_files).toHaveLength(2);
+        expect(detail.sections.length).toBeGreaterThanOrEqual(2);
+    });
+    it("generates sanitized anchors", () => {
+        const result = makeScanResult({
+            files: [{ path: "src/모듈/컴포넌트.tsx", category: "source", language: "typescript", size_bytes: 100 }],
+        });
+        const { context } = buildBrownfield("SC-TEST", [result]);
+        const anchor = context.related_files[0].detail_anchor;
+        // anchor should not contain special characters that break markdown links
+        expect(anchor).not.toMatch(/[<>[\]{}()|\\^`"']/);
+    });
+    it("omits optional fields when empty", () => {
+        const { context } = buildBrownfield("SC-TEST", [makeScanResult()]);
+        expect(context.api_contracts).toBeUndefined();
+        expect(context.db_schemas).toBeUndefined();
+        expect(context.config_env).toBeUndefined();
+    });
+    it("includes test category files in related_files with test role", () => {
+        const result = makeScanResult({
+            files: [
+                { path: "src/app.ts", category: "source", language: "typescript", size_bytes: 100 },
+                { path: "src/app.test.ts", category: "test", language: "typescript", size_bytes: 80 },
+            ],
+        });
+        const { context, detail } = buildBrownfield("SC-TEST", [result]);
+        expect(context.related_files).toHaveLength(2);
+        const testFile = context.related_files.find(f => f.path === "src/app.test.ts");
+        expect(testFile).toBeDefined();
+        expect(testFile.role).toMatch(/^test \(/);
+        expect(testFile.detail_anchor).toBeTruthy();
+        const sourceFile = context.related_files.find(f => f.path === "src/app.ts");
+        expect(sourceFile.role).not.toMatch(/^test \(/);
+        // detail section exists for the test file
+        expect(detail.sections.some(s => s.anchor === testFile.detail_anchor)).toBe(true);
+    });
+});

package/dist/core-runtime/readers/code-chunk-collector.js

@@ -0,0 +1,53 @@
+/**
+ * 6관점 통합 코드 청크 수집 오케스트레이션.
+ *
+ * viewpoint-collectors.ts의 6개 수집 함수를 호출하고,
+ * 결과를 RelevantCodeChunks 구조로 조합한다.
+ */
+import { collectSemantics, collectDependency, collectLogic, collectStructure, collectPragmatics, collectEvolution, } from "./viewpoint-collectors.js";
+// ─── Main ───
+export function collectRelevantChunks(resolved, ontologyResult, scanResult, keywords, options) {
+    const defaultMax = options?.maxChunksPerViewpoint ?? 10;
+    function getMax(vp) {
+        const override = options?.viewpointOverrides?.[vp];
+        if (override?.enabled === false)
+            return 0;
+        return override?.maxChunks ?? defaultMax;
+    }
+    const by_viewpoint = {
+        semantics: collectSemantics(resolved, getMax("semantics")),
+        dependency: collectDependency(resolved, scanResult.dependency_graph, getMax("dependency")),
+        logic: collectLogic(ontologyResult, resolved, getMax("logic")),
+        structure: collectStructure(resolved, scanResult.files, scanResult.schema_patterns, scanResult.config_patterns, getMax("structure")),
+        pragmatics: collectPragmatics(ontologyResult.matched_entities, scanResult.api_patterns, resolved, getMax("pragmatics")),
+        evolution: collectEvolution(resolved, scanResult.files, scanResult.schema_patterns, getMax("evolution")),
+    };
+    // 중복 파일은 토큰 추정에서 1회만 카운트
+    const uniqueFiles = new Set();
+    let totalChunks = 0;
+    const viewpoint_counts = {};
+    for (const [vp, chunks] of Object.entries(by_viewpoint)) {
+        viewpoint_counts[vp] = chunks.length;
+        totalChunks += chunks.length;
+        for (const c of chunks) {
+            if (c.file_path)
+                uniqueFiles.add(c.file_path);
+        }
+    }
+    const unresolvedCount = resolved.filter((r) => r.resolution_method === "unresolved").length;
+    return {
+        by_viewpoint,
+        coverage_gaps: [], // 에이전트가 채움
+        ontology_result: ontologyResult,
+        total_chunks: totalChunks,
+        total_tokens_estimate: uniqueFiles.size * 500, // 파일당 ~500 토큰 추정
+        search_confidence: {
+            method: "ontology",
+            ontology_match_count: ontologyResult.matched_entities.length,
+            unresolved_count: unresolvedCount,
+            keywords_used: keywords,
+            viewpoint_counts,
+            ...(unresolvedCount > 0 ? { warning: `${unresolvedCount}건의 source_code가 파일로 해석되지 않았습니다` } : {}),
+        },
+    };
+}

package/dist/core-runtime/readers/code-chunk-collector.test.js

@@ -0,0 +1,136 @@
+import { describe, it, expect } from "vitest";
+import { collectRelevantChunks } from "./code-chunk-collector.js";
+// ─── Fixtures ───
+const RESOLVED = [
+    { reference: "TrialLectureCommandServiceImpl.create()", resolved_files: ["src/TrialLectureCommandServiceImpl.java"], resolution_method: "filename" },
+    { reference: "UnknownService.call()", resolved_files: [], resolution_method: "unresolved" },
+];
+const ONTOLOGY_RESULT = {
+    matched_entities: ["TrialLesson", "Ticket"],
+    code_locations: [{ reference: "TrialLectureCommandServiceImpl.create()", context: "Action TRIAL-1", entity: "TrialLesson" }],
+    db_tables: ["GT_CLASS"],
+    related_actions: [{ id: "TRIAL-1", display_name: "체험 수업 생성", source_code: "TrialLectureCommandServiceImpl.create()" }],
+    related_transitions: [],
+    value_filters: [{ entity: "TrialLesson", column: "CITY", value: "PODO_TRIAL", description: "체험 수업" }],
+    total_glossary_count: 2,
+};
+const SCAN_RESULT = {
+    source: { type: "add-dir", path: "./src" },
+    scanned_at: new Date().toISOString(),
+    files: [
+        { path: "src/TrialLectureCommandServiceImpl.java", category: "source", language: "java", size_bytes: 2000 },
+        { path: "src/LectureController.java", category: "source", language: "java", size_bytes: 1500 },
+        { path: "test/TrialLectureTest.java", category: "test", language: "java", size_bytes: 1000 },
+        { path: "schema/GT_CLASS.sql", category: "schema", language: "sql", size_bytes: 500 },
+    ],
+    content_hashes: {},
+    dependency_graph: [
+        { from: "src/LectureController.java", to: "src/TrialLectureCommandServiceImpl.java", kind: "import" },
+    ],
+    api_patterns: [
+        { file: "src/LectureController.java", method: "GET", path: "/trial/list", line: 30 },
+    ],
+    schema_patterns: [
+        { file: "schema/GT_CLASS.sql", table: "GT_CLASS", columns: "id, city, status", line: 1 },
+    ],
+    config_patterns: [],
+    doc_structure: [],
+};
+// ─── Tests ───
+describe("collectRelevantChunks", () => {
+    it("6관점 모두에서 결과를 생성한다", () => {
+        const result = collectRelevantChunks(RESOLVED, ONTOLOGY_RESULT, SCAN_RESULT, ["체험", "수업"]);
+        expect(result.by_viewpoint.semantics.length).toBeGreaterThan(0);
+        expect(result.by_viewpoint.dependency.length).toBeGreaterThan(0);
+        expect(result.coverage_gaps).toEqual([]); // 에이전트가 채움
+        expect(result.search_confidence.method).toBe("ontology");
+    });
+    it("total_chunks는 6관점 합계이다", () => {
+        const result = collectRelevantChunks(RESOLVED, ONTOLOGY_RESULT, SCAN_RESULT, ["체험"]);
+        const sum = Object.values(result.by_viewpoint).reduce((acc, chunks) => acc + chunks.length, 0);
+        expect(result.total_chunks).toBe(sum);
+    });
+    it("unresolved_count를 정확히 기록한다", () => {
+        const result = collectRelevantChunks(RESOLVED, ONTOLOGY_RESULT, SCAN_RESULT, ["체험"]);
+        expect(result.search_confidence.unresolved_count).toBe(1); // UnknownService
+    });
+    it("viewpoint_counts가 관점별 청크 수를 기록한다", () => {
+        const result = collectRelevantChunks(RESOLVED, ONTOLOGY_RESULT, SCAN_RESULT, ["체험"]);
+        for (const [vp, count] of Object.entries(result.search_confidence.viewpoint_counts)) {
+            expect(count).toBe(result.by_viewpoint[vp].length);
+        }
+    });
+    it("viewpointOverrides로 특정 관점을 비활성화할 수 있다", () => {
+        const result = collectRelevantChunks(RESOLVED, ONTOLOGY_RESULT, SCAN_RESULT, ["체험"], {
+            viewpointOverrides: { evolution: { enabled: false } },
+        });
+        expect(result.by_viewpoint.evolution).toEqual([]);
+    });
+    it("maxChunksPerViewpoint로 관점당 상한을 제어한다", () => {
+        const result = collectRelevantChunks(RESOLVED, ONTOLOGY_RESULT, SCAN_RESULT, ["체험"], {
+            maxChunksPerViewpoint: 1,
+        });
+        for (const chunks of Object.values(result.by_viewpoint)) {
+            expect(chunks.length).toBeLessThanOrEqual(1);
+        }
+    });
+    it("value_filters가 logic 관점에 반영된다", () => {
+        const result = collectRelevantChunks(RESOLVED, ONTOLOGY_RESULT, SCAN_RESULT, ["체험"]);
+        const logicContexts = result.by_viewpoint.logic.map((c) => c.context);
+        expect(logicContexts.some((ctx) => ctx.includes("PODO_TRIAL"))).toBe(true);
+    });
+    it("keywords_used가 기록된다", () => {
+        const result = collectRelevantChunks(RESOLVED, ONTOLOGY_RESULT, SCAN_RESULT, ["체험", "수업"]);
+        expect(result.search_confidence.keywords_used).toEqual(["체험", "수업"]);
+    });
+    it("guard_note가 있는 action이 logic 관점에 반영된다", () => {
+        const withGuard = {
+            ...ONTOLOGY_RESULT,
+            related_actions: [{
+                    id: "TRIAL-1",
+                    display_name: "체험 수업 생성",
+                    source_code: "TrialLectureCommandServiceImpl.create()",
+                    guard_note: "체험 수업은 1회만 가능",
+                }],
+        };
+        const result = collectRelevantChunks(RESOLVED, withGuard, SCAN_RESULT, ["체험"]);
+        const logicChunks = result.by_viewpoint.logic;
+        expect(logicChunks.some((c) => c.context.includes("체험 수업은 1회만 가능"))).toBe(true);
+        // guard_note가 있는 청크는 실제 파일 경로를 가져야 함
+        const guardChunk = logicChunks.find((c) => c.context.includes("체험 수업은 1회만 가능"));
+        expect(guardChunk?.file_path).toBe("src/TrialLectureCommandServiceImpl.java");
+    });
+    it("preconditions가 있는 action이 logic 관점에 반영된다", () => {
+        const withPreconditions = {
+            ...ONTOLOGY_RESULT,
+            related_actions: [{
+                    id: "TRIAL-1",
+                    display_name: "체험 수업 생성",
+                    source_code: "TrialLectureCommandServiceImpl.create()",
+                    preconditions: [{ check: "학생이 체험 수업을 받은 적 없음" }],
+                }],
+        };
+        const result = collectRelevantChunks(RESOLVED, withPreconditions, SCAN_RESULT, ["체험"]);
+        const logicChunks = result.by_viewpoint.logic;
+        expect(logicChunks.some((c) => c.context.includes("학생이 체험 수업을 받은 적 없음"))).toBe(true);
+    });
+    it("value_filters의 search_hint가 file_path가 아닌 별도 필드에 저장된다", () => {
+        const result = collectRelevantChunks(RESOLVED, ONTOLOGY_RESULT, SCAN_RESULT, ["체험"]);
+        const vfChunks = result.by_viewpoint.logic.filter((c) => c.search_hint);
+        expect(vfChunks.length).toBeGreaterThan(0);
+        for (const c of vfChunks) {
+            expect(c.file_path).toBeUndefined(); // file_path 없이 search_hint만 사용
+            expect(c.search_hint).toMatch(/^grep:/);
+        }
+    });
+    it("search_hint만 있는 청크는 토큰 추정에서 제외된다", () => {
+        const result = collectRelevantChunks(RESOLVED, ONTOLOGY_RESULT, SCAN_RESULT, ["체험"]);
+        // 빈 file_path는 uniqueFiles에 포함되지 않으므로 토큰 추정에 영향 없음
+        const allFilePaths = Object.values(result.by_viewpoint)
+            .flat()
+            .map((c) => c.file_path)
+            .filter((fp) => fp !== undefined);
+        const uniqueFiles = new Set(allFilePaths);
+        expect(result.total_tokens_estimate).toBe(uniqueFiles.size * 500);
+    });
+});