onto-mcp 0.3.0

package/dist/core-runtime/readers/review-log.test.js

@@ -0,0 +1,313 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { collectReviewLogs, computeProgressiveness } from "./review-log.js";
+// ─── Test fixtures ───
+const PROJECT_ROOT = "/mock/project";
+function makeExecResult(overrides = {}) {
+    return {
+        session_id: "20260413-aaa00001",
+        session_root: "/mock/.onto/review/20260413-aaa00001",
+        execution_realization: "subagent",
+        host_runtime: "codex",
+        review_mode: "full",
+        execution_status: "completed",
+        execution_started_at: "2026-04-13T10:00:00+09:00",
+        execution_completed_at: "2026-04-13T10:01:48+09:00",
+        total_duration_ms: 107745,
+        planned_lens_ids: ["logic", "structure", "axiology"],
+        participating_lens_ids: ["logic", "structure", "axiology"],
+        degraded_lens_ids: [],
+        excluded_lens_ids: [],
+        executed_lens_count: 3,
+        synthesis_executed: true,
+        deliberation_status: null,
+        halt_reason: null,
+        error_log_path: "error-log.md",
+        lens_execution_results: [
+            {
+                unit_id: "logic",
+                unit_kind: "lens",
+                packet_path: "prompt-packets/logic.prompt.md",
+                output_path: "round1/logic.md",
+                status: "completed",
+                started_at: "2026-04-13T10:00:00+09:00",
+                completed_at: "2026-04-13T10:00:32+09:00",
+                duration_ms: 32517,
+                timestamp_provenance: "runner_wallclock",
+                failure_message: null,
+            },
+            {
+                unit_id: "structure",
+                unit_kind: "lens",
+                packet_path: "prompt-packets/structure.prompt.md",
+                output_path: "round1/structure.md",
+                status: "completed",
+                started_at: "2026-04-13T10:00:00+09:00",
+                completed_at: "2026-04-13T10:00:36+09:00",
+                duration_ms: 36342,
+                timestamp_provenance: "runner_wallclock",
+                failure_message: null,
+            },
+            {
+                unit_id: "axiology",
+                unit_kind: "lens",
+                packet_path: "prompt-packets/axiology.prompt.md",
+                output_path: "round1/axiology.md",
+                status: "completed",
+                started_at: "2026-04-13T10:00:00+09:00",
+                completed_at: "2026-04-13T10:00:33+09:00",
+                duration_ms: 32791,
+                failure_message: null,
+            },
+        ],
+        synthesize_execution_result: {
+            unit_id: "synthesize",
+            unit_kind: "synthesize",
+            packet_path: "prompt-packets/synthesize.runtime.prompt.md",
+            output_path: "synthesis.md",
+            status: "completed",
+            started_at: "2026-04-13T10:01:06+09:00",
+            completed_at: "2026-04-13T10:01:48+09:00",
+            duration_ms: 42000,
+            timestamp_provenance: "runner_wallclock",
+            failure_message: null,
+        },
+        ...overrides,
+    };
+}
+function makeReviewRecord(overrides = {}) {
+    return {
+        review_record_id: "20260413-aaa00001",
+        session_id: "20260413-aaa00001",
+        entrypoint: "review",
+        record_status: "completed",
+        created_at: "2026-04-13T10:00:00+09:00",
+        updated_at: "2026-04-13T10:01:48+09:00",
+        request_text: "design doc 검토",
+        review_target_scope_ref: "binding.yaml",
+        ...overrides,
+    };
+}
+function makeBinding(refs = ["/mock/project/.onto/processes/evolve.md"]) {
+    return {
+        resolved_target_scope: {
+            kind: "file",
+            resolved_refs: refs,
+        },
+    };
+}
+function yamlStringify(obj) {
+    // vitest 환경에서는 yaml 패키지 대신 간단한 변환 사용
+    const { stringify } = require("yaml");
+    return stringify(obj);
+}
+// ─── Temp dir setup ───
+let testDir;
+function setupReviewDir() {
+    testDir = join(tmpdir(), `review-log-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    mkdirSync(testDir, { recursive: true });
+    return testDir;
+}
+function createSession(reviewRoot, sessionId, execOverrides = {}, recordOverrides = {}, bindingRefs = ["/mock/project/.onto/processes/evolve.md"]) {
+    const sessionDir = join(reviewRoot, sessionId);
+    mkdirSync(sessionDir, { recursive: true });
+    writeFileSync(join(sessionDir, "execution-result.yaml"), yamlStringify(makeExecResult({ session_id: sessionId, ...execOverrides })));
+    writeFileSync(join(sessionDir, "review-record.yaml"), yamlStringify(makeReviewRecord({ session_id: sessionId, review_record_id: sessionId, ...recordOverrides })));
+    writeFileSync(join(sessionDir, "binding.yaml"), yamlStringify(makeBinding(bindingRefs)));
+}
+// ─── Tests ───
+describe("review-log", () => {
+    beforeEach(() => {
+        setupReviewDir();
+    });
+    afterEach(() => {
+        if (testDir) {
+            rmSync(testDir, { recursive: true, force: true });
+        }
+    });
+    describe("collectReviewLogs", () => {
+        it("빈 디렉터리에서 빈 summary 를 반환한다", () => {
+            const result = collectReviewLogs(testDir, PROJECT_ROOT);
+            expect(result.total_sessions).toBe(0);
+            expect(result.entries).toHaveLength(0);
+            expect(result.progressiveness).toHaveLength(0);
+        });
+        it("존재하지 않는 경로에서 빈 summary 를 반환한다", () => {
+            const result = collectReviewLogs("/nonexistent/path", PROJECT_ROOT);
+            expect(result.total_sessions).toBe(0);
+        });
+        it("단일 세션을 수집한다", () => {
+            createSession(testDir, "20260413-aaa00001");
+            const result = collectReviewLogs(testDir, PROJECT_ROOT);
+            expect(result.total_sessions).toBe(1);
+            expect(result.entries).toHaveLength(1);
+            const entry = result.entries[0];
+            expect(entry.session_id).toBe("20260413-aaa00001");
+            expect(entry.review_mode).toBe("full");
+            expect(entry.execution_status).toBe("completed");
+            expect(entry.total_duration_ms).toBe(107745);
+            expect(entry.lens_count).toBe(3);
+            expect(entry.participating_lens_ids).toEqual(["logic", "structure", "axiology"]);
+            expect(entry.request_text).toBe("design doc 검토");
+        });
+        it("per-lens duration 을 정확히 수집한다", () => {
+            createSession(testDir, "20260413-aaa00001");
+            const result = collectReviewLogs(testDir, PROJECT_ROOT);
+            const entry = result.entries[0];
+            expect(entry.per_lens_duration).toHaveLength(3);
+            const logic = entry.per_lens_duration.find((d) => d.lens_id === "logic");
+            expect(logic).toBeDefined();
+            expect(logic.duration_ms).toBe(32517);
+            expect(logic.provenance).toBe("runner_wallclock");
+        });
+        it("provenance summary 를 정확히 산출한다", () => {
+            createSession(testDir, "20260413-aaa00001");
+            const result = collectReviewLogs(testDir, PROJECT_ROOT);
+            const prov = result.entries[0].provenance_summary;
+            // logic + structure = 2 runner_wallclock, axiology = unknown (provenance 없음), synth = 1 runner_wallclock
+            expect(prov.runner_wallclock).toBe(3);
+            expect(prov.unknown).toBe(1); // axiology 는 provenance 필드 없음
+        });
+        it("synthesis duration 을 수집한다", () => {
+            createSession(testDir, "20260413-aaa00001");
+            const result = collectReviewLogs(testDir, PROJECT_ROOT);
+            expect(result.entries[0].synthesis_duration_ms).toBe(42000);
+        });
+        it("synthesis 가 없는 세션을 처리한다", () => {
+            createSession(testDir, "20260413-aaa00001", {
+                synthesis_executed: false,
+                synthesize_execution_result: null,
+            });
+            const result = collectReviewLogs(testDir, PROJECT_ROOT);
+            expect(result.entries[0].synthesis_duration_ms).toBeNull();
+        });
+        it("여러 세션을 시간순 정렬한다", () => {
+            createSession(testDir, "20260413-bbb00002", {}, {
+                created_at: "2026-04-13T12:00:00+09:00",
+            });
+            createSession(testDir, "20260413-aaa00001", {}, {
+                created_at: "2026-04-13T10:00:00+09:00",
+            });
+            const result = collectReviewLogs(testDir, PROJECT_ROOT);
+            expect(result.entries).toHaveLength(2);
+            expect(result.entries[0].session_id).toBe("20260413-aaa00001");
+            expect(result.entries[1].session_id).toBe("20260413-bbb00002");
+        });
+        it("target refs 를 프로젝트 루트 기준으로 정규화한다", () => {
+            createSession(testDir, "20260413-aaa00001", {}, {}, ["/mock/project/.onto/processes/evolve.md"]);
+            const result = collectReviewLogs(testDir, "/mock/project");
+            expect(result.entries[0].review_target_refs).toEqual([".onto/processes/evolve.md"]);
+        });
+        it("execution-result.yaml 없는 세션은 건너뛴다", () => {
+            // execution-result.yaml 없이 디렉터리만 생성
+            const sessionDir = join(testDir, "20260413-ccc00003");
+            mkdirSync(sessionDir, { recursive: true });
+            writeFileSync(join(sessionDir, "review-record.yaml"), yamlStringify(makeReviewRecord()));
+            const result = collectReviewLogs(testDir, PROJECT_ROOT);
+            expect(result.total_sessions).toBe(0);
+        });
+        it("total_duration_ms 전체 합산을 반환한다", () => {
+            createSession(testDir, "20260413-aaa00001", { total_duration_ms: 50000 }, {
+                created_at: "2026-04-13T10:00:00+09:00",
+            });
+            createSession(testDir, "20260413-bbb00002", { total_duration_ms: 30000 }, {
+                created_at: "2026-04-13T11:00:00+09:00",
+            });
+            const result = collectReviewLogs(testDir, PROJECT_ROOT);
+            expect(result.total_duration_ms).toBe(80000);
+        });
+    });
+    describe("computeProgressiveness", () => {
+        it("세션 2건 미만 그룹은 제외한다", () => {
+            const entries = [
+                makeLogEntry("s1", ["fileA.md"], 100000, "2026-04-13T10:00:00+09:00"),
+            ];
+            const metrics = computeProgressiveness(entries);
+            expect(metrics).toHaveLength(0);
+        });
+        it("동일 대상 2회 review 시 점진성 metric 을 산출한다", () => {
+            const entries = [
+                makeLogEntry("s1", ["fileA.md"], 100000, "2026-04-13T10:00:00+09:00"),
+                makeLogEntry("s2", ["fileA.md"], 70000, "2026-04-13T12:00:00+09:00"),
+            ];
+            const metrics = computeProgressiveness(entries);
+            expect(metrics).toHaveLength(1);
+            const m = metrics[0];
+            expect(m.session_count).toBe(2);
+            expect(m.first_duration_ms).toBe(100000);
+            expect(m.latest_duration_ms).toBe(70000);
+            expect(m.duration_delta_ms).toBe(-30000);
+            expect(m.duration_delta_ratio).toBe(-0.3);
+            expect(m.avg_duration_ms).toBe(85000);
+        });
+        it("동일 대상 3회 review 시 첫/마지막 비교 metric 을 산출한다", () => {
+            const entries = [
+                makeLogEntry("s1", ["fileA.md"], 100000, "2026-04-13T10:00:00+09:00"),
+                makeLogEntry("s2", ["fileA.md"], 80000, "2026-04-13T12:00:00+09:00"),
+                makeLogEntry("s3", ["fileA.md"], 60000, "2026-04-13T14:00:00+09:00"),
+            ];
+            const metrics = computeProgressiveness(entries);
+            expect(metrics[0].session_count).toBe(3);
+            expect(metrics[0].duration_delta_ms).toBe(-40000);
+            expect(metrics[0].duration_delta_ratio).toBe(-0.4);
+        });
+        it("서로 다른 대상은 별도 그룹으로 분리한다", () => {
+            const entries = [
+                makeLogEntry("s1", ["fileA.md"], 100000, "2026-04-13T10:00:00+09:00"),
+                makeLogEntry("s2", ["fileA.md"], 70000, "2026-04-13T12:00:00+09:00"),
+                makeLogEntry("s3", ["fileB.md"], 90000, "2026-04-13T11:00:00+09:00"),
+                makeLogEntry("s4", ["fileB.md"], 85000, "2026-04-13T13:00:00+09:00"),
+            ];
+            const metrics = computeProgressiveness(entries);
+            expect(metrics).toHaveLength(2);
+        });
+        it("target refs 순서가 달라도 동일 그룹으로 합친다", () => {
+            const entries = [
+                makeLogEntry("s1", ["fileB.md", "fileA.md"], 100000, "2026-04-13T10:00:00+09:00"),
+                makeLogEntry("s2", ["fileA.md", "fileB.md"], 70000, "2026-04-13T12:00:00+09:00"),
+            ];
+            const metrics = computeProgressiveness(entries);
+            expect(metrics).toHaveLength(1);
+            expect(metrics[0].session_count).toBe(2);
+        });
+        it("target refs 가 빈 세션은 그룹에서 제외한다", () => {
+            const entries = [
+                makeLogEntry("s1", [], 100000, "2026-04-13T10:00:00+09:00"),
+                makeLogEntry("s2", [], 70000, "2026-04-13T12:00:00+09:00"),
+            ];
+            const metrics = computeProgressiveness(entries);
+            expect(metrics).toHaveLength(0);
+        });
+        it("시간이 증가한 경우 양수 delta 를 반환한다", () => {
+            const entries = [
+                makeLogEntry("s1", ["fileA.md"], 50000, "2026-04-13T10:00:00+09:00"),
+                makeLogEntry("s2", ["fileA.md"], 80000, "2026-04-13T12:00:00+09:00"),
+            ];
+            const metrics = computeProgressiveness(entries);
+            expect(metrics[0].duration_delta_ms).toBe(30000);
+            expect(metrics[0].duration_delta_ratio).toBe(0.6);
+        });
+    });
+});
+// ─── Test helper ───
+function makeLogEntry(session_id, target_refs, total_duration_ms, created_at) {
+    return {
+        session_id,
+        created_at,
+        review_target_refs: target_refs,
+        request_text: "test review",
+        review_mode: "full",
+        execution_realization: "subagent",
+        host_runtime: "codex",
+        execution_status: "completed",
+        total_duration_ms,
+        lens_count: 9,
+        participating_lens_ids: ["logic"],
+        degraded_lens_ids: [],
+        per_lens_duration: [],
+        synthesis_duration_ms: null,
+        provenance_summary: { runner_wallclock: 0, coordinator_derived: 0, batch_fallback: 0, unknown: 0 },
+    };
+}

package/dist/core-runtime/readers/scan-local.js

@@ -0,0 +1,102 @@
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { contentHash } from "../scope-runtime/hash.js";
+import { getLogger } from "../logger.js";
+import { walkDirectory, computeDirectoryHashFromMap, normalizePath } from "./file-utils.js";
+import { detectPatterns } from "./patterns/index.js";
+import { sourceKey, emptyScanResult } from "./types.js";
+/**
+ * Scan a local file or directory and produce a ScanResult.
+ *
+ * Pure I/O function: reads file system, no network calls.
+ * For single files, wraps the file as a 1-item scan.
+ * For directories, walks the tree respecting .gitignore and exclusion rules.
+ */
+export function scanLocal(source) {
+    const fullPath = normalizePath(source.path);
+    let stat;
+    try {
+        stat = statSync(fullPath);
+    }
+    catch {
+        return emptyScanResult(source);
+    }
+    if (stat.isFile()) {
+        return scanSingleFile(source, fullPath);
+    }
+    return scanDirectory(source, fullPath);
+}
+export function scanDirectory(source, rootPath) {
+    const files = walkDirectory(rootPath);
+    const deps = [];
+    const apis = [];
+    const schemas = [];
+    const configs = [];
+    const docs = [];
+    const contentHashMap = new Map();
+    for (const file of files) {
+        const absPath = join(rootPath, file.path);
+        let content;
+        try {
+            content = readFileSync(absPath, "utf-8");
+        }
+        catch (error) {
+            getLogger().debug("scanDirectory: failed to read file", { path: absPath, error });
+            contentHashMap.set(file.path, "unreadable");
+            continue;
+        }
+        contentHashMap.set(file.path, contentHash(content));
+        const patterns = detectPatterns(content, file.path);
+        deps.push(...patterns.deps);
+        apis.push(...patterns.apis);
+        schemas.push(...patterns.schemas);
+        configs.push(...patterns.configs);
+        docs.push(...patterns.docs);
+    }
+    const dirHash = computeDirectoryHashFromMap(contentHashMap);
+    return {
+        source,
+        scanned_at: new Date().toISOString(),
+        files,
+        content_hashes: { [sourceKey(source)]: dirHash },
+        dependency_graph: deps,
+        api_patterns: apis,
+        schema_patterns: schemas,
+        config_patterns: configs,
+        doc_structure: docs,
+    };
+}
+function scanSingleFile(source, filePath) {
+    let content;
+    try {
+        content = readFileSync(filePath, "utf-8");
+    }
+    catch {
+        return emptyScanResult(source);
+    }
+    const hash = contentHash(content);
+    const fileName = filePath.split("/").pop() ?? filePath;
+    let sizeBytes = content.length;
+    try {
+        sizeBytes = statSync(filePath).size;
+    }
+    catch { /* use content.length as fallback */ }
+    const fileEntry = {
+        path: fileName,
+        category: "other",
+        language: undefined,
+        size_bytes: sizeBytes,
+    };
+    const patterns = detectPatterns(content, fileName);
+    return {
+        source,
+        scanned_at: new Date().toISOString(),
+        files: [fileEntry],
+        content_hashes: { [sourceKey(source)]: hash },
+        dependency_graph: patterns.deps,
+        api_patterns: patterns.apis,
+        schema_patterns: patterns.schemas,
+        config_patterns: patterns.configs,
+        doc_structure: patterns.docs,
+    };
+}

package/dist/core-runtime/readers/scan-local.test.js

@@ -0,0 +1,102 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { scanLocal } from "./scan-local.js";
+const TMP = join(import.meta.dirname ?? ".", ".tmp-scanlocal-test");
+beforeEach(() => mkdirSync(TMP, { recursive: true }));
+afterEach(() => rmSync(TMP, { recursive: true, force: true }));
+describe("scanLocal", () => {
+    // Depends on patterns/ module (deferred — code parser infrastructure not yet absorbed)
+    it.skip("scans a directory and returns ScanResult", () => {
+        writeFileSync(join(TMP, "app.ts"), 'import { foo } from "./foo";\nconst x = process.env.API_KEY;');
+        writeFileSync(join(TMP, "foo.ts"), "export const foo = 1;");
+        const result = scanLocal({ type: "add-dir", path: TMP });
+        expect(result.files.length).toBeGreaterThanOrEqual(2);
+        expect(result.dependency_graph.length).toBeGreaterThan(0);
+        expect(result.config_patterns.length).toBeGreaterThan(0);
+        expect(Object.keys(result.content_hashes).length).toBe(1);
+    });
+    // Depends on patterns/ module (deferred)
+    it.skip("scans a single file", () => {
+        const filePath = join(TMP, "single.ts");
+        writeFileSync(filePath, 'import { bar } from "bar";');
+        const result = scanLocal({ type: "add-dir", path: filePath });
+        expect(result.files).toHaveLength(1);
+        expect(result.dependency_graph).toHaveLength(1);
+    });
+    it("returns empty for non-existent path", () => {
+        const result = scanLocal({ type: "add-dir", path: join(TMP, "nope") });
+        expect(result.files).toEqual([]);
+        expect(result.dependency_graph).toEqual([]);
+    });
+    it("excludes .git and node_modules", () => {
+        mkdirSync(join(TMP, ".git"), { recursive: true });
+        writeFileSync(join(TMP, ".git", "config"), "git");
+        mkdirSync(join(TMP, "node_modules", "pkg"), { recursive: true });
+        writeFileSync(join(TMP, "node_modules", "pkg", "index.js"), "code");
+        writeFileSync(join(TMP, "app.ts"), "const a = 1;");
+        const result = scanLocal({ type: "add-dir", path: TMP });
+        expect(result.files.map(f => f.path)).toEqual(["app.ts"]);
+    });
+    // Depends on patterns/ module (deferred)
+    it.skip("detects API patterns in Java file", () => {
+        writeFileSync(join(TMP, "Controller.java"), '@GetMapping("/api/users")\npublic List<User> getUsers() {}');
+        const result = scanLocal({ type: "add-dir", path: TMP });
+        expect(result.api_patterns.length).toBeGreaterThan(0);
+        expect(result.api_patterns[0].method).toBe("GET");
+    });
+    // Depends on patterns/ module (deferred)
+    it.skip("detects schema patterns", () => {
+        writeFileSync(join(TMP, "V1__init.sql"), "CREATE TABLE users (\n  id BIGINT PRIMARY KEY\n);");
+        const result = scanLocal({ type: "add-dir", path: TMP });
+        expect(result.schema_patterns.length).toBeGreaterThan(0);
+        expect(result.schema_patterns[0].table).toBe("users");
+    });
+    it("produces consistent hashes", () => {
+        writeFileSync(join(TMP, "a.ts"), "const a = 1;");
+        const r1 = scanLocal({ type: "add-dir", path: TMP });
+        const r2 = scanLocal({ type: "add-dir", path: TMP });
+        expect(Object.keys(r1.content_hashes)[0]).toBe(Object.keys(r2.content_hashes)[0]);
+    });
+    // ─── W-A-76: ontology-absent path (r−) fallback grounding surface ───
+    //
+    // scan-local 이 ontology YAML 부재 시 review lens 에게 제공하는 최소 grounding 재료를
+    // 검증한다. files 와 content_hashes 는 patterns/ 모듈 미이전과 독립적으로 산출되어야
+    // r− 경로의 기준선 grounding 을 보장한다.
+    describe("W-A-76 r− fallback grounding", () => {
+        it("ontology YAML 이 전혀 없어도 files 배열에 직접 파일들을 나열한다", () => {
+            writeFileSync(join(TMP, "README.md"), "# project\n");
+            writeFileSync(join(TMP, "service.ts"), "export const x = 1;\n");
+            writeFileSync(join(TMP, "config.yaml"), "key: value\n");
+            const result = scanLocal({ type: "add-dir", path: TMP });
+            // lens 가 grounding 에 쓸 수 있는 최소 signal: 파일 경로 + content_hash
+            const paths = result.files.map((f) => f.path).sort();
+            expect(paths).toEqual(["README.md", "config.yaml", "service.ts"]);
+            expect(Object.keys(result.content_hashes).length).toBe(1);
+        });
+        it("code-mapping.yaml / behavior.yaml / model.yaml 이 존재해도 scan-local 자체는 ontology 를 consume 하지 않는다", () => {
+            // r− 경로는 scan-local 을 사용하는데, scan-local 은 ontology 구조를 해석하지 않고
+            // 파일만 나열한다. 이것이 r− 경로의 grounding 한계를 구조적으로 보장한다.
+            writeFileSync(join(TMP, "code-mapping.yaml"), "glossary: []\n");
+            writeFileSync(join(TMP, "behavior.yaml"), "actions: []\n");
+            writeFileSync(join(TMP, "model.yaml"), "entities: []\n");
+            writeFileSync(join(TMP, "service.ts"), "export const x = 1;\n");
+            const result = scanLocal({ type: "add-dir", path: TMP });
+            // ontology YAML 들은 단순 파일로만 등장. matched_entities 같은 구조화된 산출 없음.
+            const paths = result.files.map((f) => f.path).sort();
+            expect(paths).toContain("code-mapping.yaml");
+            expect(paths).toContain("behavior.yaml");
+            expect(paths).toContain("model.yaml");
+            expect(paths).toContain("service.ts");
+            // scan-local 은 OntologyQueryResult 를 반환하지 않음 — 형식 자체가 다름.
+            expect("matched_entities" in result).toBe(false);
+        });
+        it("빈 디렉터리도 r− fallback 의 적법한 baseline 을 반환한다 (files=[], 해시 구조 유지)", () => {
+            const result = scanLocal({ type: "add-dir", path: TMP });
+            expect(result.files).toEqual([]);
+            // 디렉터리 스캔은 빈 해시 맵이라도 content_hashes 키를 하나 둔다 (source key).
+            expect(Object.keys(result.content_hashes).length).toBe(1);
+            // lens 는 이 baseline 에서 "대상 비어있음" 을 판단할 수 있다.
+        });
+    });
+});

package/dist/core-runtime/readers/scan-tarball.js

@@ -0,0 +1,121 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { execSync } from "node:child_process";
+import { scanLocal } from "./scan-local.js";
+/**
+ * Resolve GitHub token: GITHUB_TOKEN env var first, then `gh auth token` fallback.
+ */
+export function resolveGitHubToken() {
+    if (process.env.GITHUB_TOKEN) {
+        return process.env.GITHUB_TOKEN;
+    }
+    try {
+        return execSync("gh auth token", { timeout: 5_000, stdio: "pipe" }).toString().trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Download a GitHub tarball and scan its contents.
+ *
+ * Uses Node.js built-in `fetch` to download the tarball, extracts to a temp
+ * directory with `tar xzf`, then delegates to scanLocal().
+ * Temp directory is always cleaned up.
+ *
+ * Returns either a ScanResult or a ScanError.
+ */
+export async function scanTarball(source, etag, cachedHash) {
+    const tmpDir = mkdtempSync(join(tmpdir(), "sprint-kit-tarball-"));
+    try {
+        // Extract org/repo from URL
+        const match = source.url.match(/github\.com\/([^/]+\/[^/]+)/);
+        if (!match) {
+            return {
+                source,
+                error_type: "parse",
+                message: `Invalid GitHub URL: ${source.url}`,
+            };
+        }
+        const repoPath = match[1].replace(/\.git$/, "");
+        // Validate repoPath to prevent injection into URL
+        if (!/^[\w.-]+\/[\w.-]+$/.test(repoPath)) {
+            return {
+                source,
+                error_type: "parse",
+                message: `Invalid repository path: ${repoPath}`,
+            };
+        }
+        // Build request headers
+        const headers = {
+            Accept: "application/vnd.github+json",
+            "User-Agent": "sprint-kit",
+        };
+        const token = resolveGitHubToken();
+        if (token) {
+            headers["Authorization"] = `Bearer ${token}`;
+        }
+        if (etag) {
+            headers["If-None-Match"] = etag;
+        }
+        // Download tarball via fetch
+        let response;
+        try {
+            response = await fetch(`https://api.github.com/repos/${repoPath}/tarball/HEAD`, {
+                headers,
+                signal: AbortSignal.timeout(120_000),
+            });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (msg.includes("TimeoutError") || msg.includes("abort") || msg.includes("timeout")) {
+                return { source, error_type: "timeout", message: `Timeout downloading ${repoPath}: ${msg}` };
+            }
+            return { source, error_type: "network", message: `Failed to download ${repoPath}: ${msg}` };
+        }
+        // Handle 304 Not Modified (ETag cache hit)
+        if (response.status === 304 && cachedHash) {
+            return { skipped: true, source, cached_hash: cachedHash };
+        }
+        // Handle HTTP error responses
+        if (!response.ok) {
+            if (response.status === 401 || response.status === 403) {
+                const rateLimitRemaining = response.headers.get("X-RateLimit-Remaining");
+                if (rateLimitRemaining === "0") {
+                    return { source, error_type: "auth", message: `GitHub API rate limit exceeded for ${repoPath}. GITHUB_TOKEN 환경변수를 설정하세요.` };
+                }
+                return { source, error_type: "auth", message: `Authentication failed for ${repoPath}: HTTP ${response.status}. Private 레포라면 GITHUB_TOKEN 환경변수를 설정하세요.` };
+            }
+            if (response.status === 404) {
+                return { source, error_type: "not_found", message: `Repository not found: ${repoPath}` };
+            }
+            return { source, error_type: "network", message: `Failed to download ${repoPath}: HTTP ${response.status}` };
+        }
+        // Capture ETag for cache update
+        const responseEtag = response.headers.get("ETag") ?? undefined;
+        // Write tarball to temp file and extract
+        const arrayBuffer = await response.arrayBuffer();
+        const tarballPath = join(tmpDir, "tarball.tar.gz");
+        writeFileSync(tarballPath, Buffer.from(arrayBuffer));
+        execSync("tar xzf tarball.tar.gz --strip-components=1", {
+            cwd: tmpDir,
+            timeout: 120_000,
+            stdio: "pipe",
+        });
+        // Scan the extracted directory
+        const localSource = { type: "add-dir", path: tmpDir, description: source.description };
+        const result = scanLocal(localSource);
+        // Return with original source entry + ETag
+        return { ...result, source, response_etag: responseEtag };
+    }
+    finally {
+        // Always clean up
+        try {
+            rmSync(tmpDir, { recursive: true, force: true });
+        }
+        catch {
+            // Best effort cleanup
+        }
+    }
+}