@pghoya2956/livemap 1.0.0

package/src/derive.mjs

@@ -0,0 +1,161 @@
+// 파생: 그래프(코드 사실) + 여정 파일(뜻)을 합쳐 화면이 읽는 뷰 모델을 만든다. 화면은 여기서 만든 것만 그린다.
+const ROADMAP_STATUS = ['완료', '진행', '다음', '대기', '이후'];
+const RANK = { live: 0, partial: 1, mixed: 1, mock: 2, planned: 3, next: 4, static: 5 };
+
+export function derive(g, sem, cfg, { captureExists }) {
+  const screens = g.of('screen'), apis = g.of('api'), fns = g.of('function'), tests = g.of('test'), commits = g.of('commit').sort((a, b) => b.props.date.localeCompare(a.props.date));
+  const tasks = g.of('task'), decisions = g.of('decision').filter((d) => d.props.kind === 'wiki'), specDefs = g.of('decision').filter((d) => d.props.kind !== 'wiki');
+  const head = g.get('deploy', 'head')?.props || null;
+  const homelab = g.get('deploy', 'homelab')?.props || null;
+  const report = g.get('testreport', 'last')?.props || null;
+  const short = (t) => t.split('.').pop();
+  const testsOf = (kind, id) => g.in(kind, id, 'covers').map((t) => t.label);
+  const testsPassedFresh = (kind, id) => g.in(kind, id, 'covers').some((t) => t.props.lastRun?.passed && t.props.lastRun?.fresh);
+
+  // ---- 화면·API·함수 뷰 ----
+  const screenView = screens.map((s) => ({
+    path: s.id, component: s.props.component, file: s.props.file, guarded: s.props.guarded, source: s.props.source, mockVia: s.props.mockVia, fixedVia: s.props.fixedVia || [], files: s.props.files,
+    apis: g.out('screen', s.id, 'calls').map((a) => a.id), tests: testsOf('screen', s.id), last: s.props.last, src: s.src,
+    steps: [],
+  }));
+  const apiView = apis.map((a) => ({ path: a.id, method: a.props.method || '?', calls: a.props.calls || [], tests: testsOf('api', a.id), src: a.src, declared: !!a.src }));
+  const fnView = fns.map((f) => ({ name: f.id, usedByApi: g.in('function', f.id, 'invokes').length > 0, tables: g.out('function', f.id, 'touches').map((t) => t.label), tests: testsOf('function', f.id), migration: f.props.migration || null, src: f.src }));
+  const migView = g.of('migration').map((m) => ({ file: m.id, tables: m.props.tables.map(short), functions: m.props.functions.map(short), grants: m.props.grants, rls: m.props.rls, last: m.props.last }));
+  const testView = tests.map((t) => ({ file: t.id, label: t.label, kind: t.props.kind, count: t.props.count, gated: t.props.gated, lastRun: t.props.lastRun || null }));
+
+  // ---- 여정 해석 ----
+  const byPath = Object.fromEntries(screenView.map((s) => [s.path, s]));
+  const apiByPath = Object.fromEntries(apiView.map((a) => [a.path, a]));
+  const decisionBySlug = Object.fromEntries(decisions.map((d) => [d.id, d]));
+  const defBy = Object.fromEntries(specDefs.map((d) => [d.id, { task: g.in('decision', d.id, 'defines')[0]?.id || null, file: d.props.file, done: d.props.done }]));
+  const resolveRef = (ref) => { const m = ref.match(/^((?:DEC|PN|P\d)-\d+)/i); return m ? defBy[m[1].toUpperCase()] || null : null; };
+  const journeys = (sem.journeys || []).map((j) => {
+    const steps = j.steps.map((st) => {
+      const actor = st.actor || j.actor;
+      const screenNodes = (st.screens || []).map((p) => byPath[p] ? { path: p, source: byPath[p].source, file: byPath[p].file, tests: byPath[p].tests, last: byPath[p].last, mockVia: byPath[p].mockVia, fixedVia: byPath[p].fixedVia } : { path: p, source: 'missing' });
+      const apiSet = new Set(st.apis || []);
+      for (const p of st.screens || []) for (const a of byPath[p]?.apis || []) apiSet.add(a);
+      const apiNodes = [...apiSet].map((p) => apiByPath[p] ? { path: p, method: apiByPath[p].method, calls: apiByPath[p].calls, tests: apiByPath[p].tests } : { path: p, method: '?', calls: [], tests: [], missing: true });
+      const fnNames = [...new Set(apiNodes.flatMap((a) => a.calls.filter((c) => !c.startsWith('auth:'))))];
+      const functionNodes = fnNames.map((n) => ({ name: n, tables: fnView.find((f) => f.name === n)?.tables || [], tests: testsOf('function', n) }));
+      const testFiles = [...new Set([...screenNodes.flatMap((x) => x.tests || []), ...apiNodes.flatMap((x) => x.tests || []), ...functionNodes.flatMap((x) => x.tests || [])])];
+      const refNodes = (st.refs || []).map((r) => ({ ref: r, ...(resolveRef(r) || {}), wiki: decisionBySlug[r] ? { title: decisionBySlug[r].label, file: decisionBySlug[r].props.file, status: decisionBySlug[r].props.status } : null }));
+      const taskNames = [...new Set(refNodes.map((r) => r.task).filter(Boolean))];
+      const warnings = [];
+      for (const n of screenNodes) {
+        if (n.source === 'missing') warnings.push(`라우트 없음: ${n.path}`);
+        else if (st.status === 'live' && n.source !== 'live') warnings.push(`장면은 동작인데 화면은 ${n.source}: ${n.path}`);
+        else if ((st.status === 'planned' || st.status === 'next') && n.source === 'live') warnings.push(`장면은 ${st.status}인데 화면은 동작: ${n.path}`);
+      }
+      for (const r of refNodes) if (/^(DEC|PN|P\d)-/i.test(r.ref) && !r.task) warnings.push(`참조 미해결: ${r.ref}`);
+      // 등급: D 주장 / C 관측 / B 검사 존재 / A 최신 커밋에서 통과
+      const observed = screenNodes.length > 0 && screenNodes.every((n) => n.source === 'live');
+      const covered = observed && testFiles.length > 0;
+      const verified = covered && (screenNodes.some((n) => testsPassedFresh('screen', n.path)) || apiNodes.some((a) => !a.missing && testsPassedFresh('api', a.path)) || functionNodes.some((f) => testsPassedFresh('function', f.name)));
+      const grade = st.status !== 'live' ? null : verified ? 'A' : covered ? 'B' : observed ? 'C' : 'D';
+      if (grade === 'D') warnings.push('동작 주장에 관측 근거 없음');
+      // 신선도: 장면 확인일보다 화면 파일이 나중에 바뀌었으면 확인 필요
+      const changedAfter = st.reviewedAt ? screenNodes.filter((n) => n.last && n.last.date > st.reviewedAt).map((n) => n.path) : [];
+      if (changedAfter.length) warnings.push(`확인 필요: ${st.reviewedAt} 뒤 화면 변경 ${changedAfter.join(', ')}`);
+      const recentCommits = [...new Map(screenNodes.flatMap((n) => g.in('screen', n.path, 'changes')).map((c) => [c.id, c])).values()].sort((a, b) => b.props.date.localeCompare(a.props.date)).slice(0, 5).map((c) => ({ sha: c.id, date: c.props.date, subject: c.label }));
+      const captureFile = captureExists(st.capture);
+      for (const n of screenNodes) if (byPath[n.path]) byPath[n.path].steps.push({ journey: j.id, step: st.id, label: `${j.title} › ${st.label}` });
+      return { ...st, actor, screenNodes, apiNodes, functionNodes, testFiles, refNodes, taskNames, warnings, grade, captureFile, recentCommits };
+    });
+    const sts = steps.map((s) => s.status);
+    const status = sts.every((s) => s === 'live') ? 'live' : sts.some((s) => s === 'live') ? 'partial' : sts.slice().sort((a, b) => RANK[a] - RANK[b])[0];
+    const counts = Object.fromEntries(['live', 'mock', 'planned', 'next'].map((k) => [k, sts.filter((s) => s === k).length]));
+    return { ...j, steps, status, counts, taskNames: [...new Set(steps.flatMap((s) => s.taskNames))], warnings: steps.reduce((n, s) => n + s.warnings.length, 0) };
+  });
+
+  // ---- 고아·커버리지 ----
+  const inJourney = new Set(journeys.flatMap((j) => j.steps.flatMap((s) => s.screens || [])));
+  const calledApis = new Set(screenView.flatMap((s) => s.apis).concat(journeys.flatMap((j) => j.steps.flatMap((s) => s.apis || []))));
+  const orphans = {
+    screens: screenView.filter((s) => !inJourney.has(s.path)).map((s) => s.path),
+    apis: apiView.filter((a) => !calledApis.has(a.path)).map((a) => a.path),
+    functions: fnView.filter((f) => !f.usedByApi).map((f) => f.name),
+    tests: testView.filter((t) => !g.out('test', t.file, 'covers').length).map((t) => t.label),
+  };
+  const coverage = { screens: { inJourney: screenView.length - orphans.screens.length, total: screenView.length } };
+
+  // ---- 커밋 영향 ----
+  const commitView = commits.map((c) => {
+    const routes = g.out('commit', c.id, 'changes').filter((n) => n.kind === 'screen').map((n) => n.id);
+    const js = [...new Map(routes.flatMap((p) => byPath[p]?.steps || []).map((x) => [x.journey + '/' + x.step, x])).values()];
+    return { sha: c.id, date: c.props.date, author: c.props.author, subject: c.label, files: c.props.files, areas: c.props.areas, runtime: c.props.runtime, routes, journeys: js, touchesApi: g.out('commit', c.id, 'changes').some((n) => n.kind === 'api'), touchesDb: g.out('commit', c.id, 'changes').some((n) => n.kind === 'migration') };
+  });
+  const areaCounts = {};
+  for (const c of commitView) for (const a of c.areas) areaCounts[a] = (areaCounts[a] || 0) + 1;
+
+  // ---- 작업·장부·결정 ----
+  const taskView = tasks.map((t) => ({ name: t.id, title: t.label, ...t.props, journeys: journeys.filter((j) => j.taskNames.includes(t.id)).map((j) => ({ id: j.id, title: j.title, status: j.status, steps: j.steps.filter((s) => s.taskNames.includes(t.id)).map((s) => s.label) })) })).sort((a, b) => b.name.localeCompare(a.name));
+  const ledger = { running: g.of('ledger').filter((l) => l.props.state === 'running').map((l) => ({ work: l.label, owner: l.props.owner, done: l.props.done })), waiting: g.of('ledger').filter((l) => l.props.state !== 'running').map((l) => ({ work: l.label, state: l.props.status, resume: l.props.resume, done: l.props.state === 'done' })) };
+  const decisionView = decisions.map((d) => ({ slug: d.id, title: d.label, file: d.props.file, status: d.props.status, summary: d.props.summary, refs: journeys.reduce((n, j) => n + j.steps.filter((s) => s.refNodes.some((r) => r.wiki && r.wiki.file === d.props.file)).length, 0) }));
+  // ---- 로드맵: 항목 순서대로 장면 상태·작업 단계를 붙인다. 해석 실패는 check가 오류로 막는다 ----
+  const stepByRef = Object.fromEntries(journeys.flatMap((j) => j.steps.map((s) => [`${j.id}/${s.id}`, { journey: j.id, step: s.id, label: `${j.title} › ${s.label}`, status: s.status, grade: s.grade, fixed: s.screenNodes.some((n) => (n.fixedVia || []).length) }])));
+  const milestones = g.of('milestone').sort((a, b) => a.props.order - b.props.order);
+  const milestoneIds = new Set(milestones.map((m) => m.id));
+  const roadmap = milestones.map((m) => {
+    const p = m.props;
+    const scenes = p.scenes.map((r) => stepByRef[r] ? { ref: r, ...stepByRef[r] } : { ref: r, missing: true });
+    const trackedTasks = p.tasks.map((name) => { const t = taskView.find((x) => x.name === name); return t ? { name, title: t.title, stage: t.stage, status: t.status, pnDone: t.pnDone, pnOpen: t.pnOpen } : { name, missing: true }; });
+    const problems = [...scenes.filter((s) => s.missing).map((s) => `장면 없음: ${s.ref}`), ...trackedTasks.filter((t) => t.missing).map((t) => `작업 폴더 없음: ${t.name}`), ...p.deps.filter((d) => !milestoneIds.has(d)).map((d) => `선행 항목 없음: ${d}`)];
+    if (!ROADMAP_STATUS.includes(p.status)) problems.push(`알 수 없는 상태: ${p.status || '(비어 있음)'}`);
+    const live = scenes.filter((s) => s.status === 'live').length;
+    return { id: m.id, order: p.order, title: m.label, status: p.status, mode: p.mode, goal: p.goal, waitingOn: p.waitingOn, done: p.done, deps: p.deps.map((d) => ({ id: d, title: milestones.find((x) => x.id === d)?.label || d, status: milestones.find((x) => x.id === d)?.props.status || null })), scenes, tasks: trackedTasks, progress: { live, total: scenes.length, fixed: scenes.filter((s) => s.fixed).length }, problems, src: m.src };
+  });
+
+  const plans = taskView.filter((t) => t.pnDone + t.pnOpen > 0).map((t) => ({ task: t.name, title: t.title, done: t.pnDone, open: t.pnOpen, oq: t.oq }));
+
+  const summary = {
+    routes: screenView.length, liveRoutes: screenView.filter((s) => s.source === 'live').length, mockRoutes: screenView.filter((s) => s.source === 'mock' || s.source === 'mixed').length, fixedRoutes: screenView.filter((s) => s.fixedVia.length).length,
+    apis: apiView.length, dbFunctions: fnView.length, dbTables: g.of('table').length, tests: testView.reduce((n, t) => n + t.count, 0), e2e: testView.filter((t) => t.kind === 'e2e').reduce((n, t) => n + t.count, 0),
+    pnDone: plans.reduce((n, p) => n + p.done, 0), pnOpen: plans.reduce((n, p) => n + p.open, 0), oq: plans.reduce((n, p) => n + p.oq, 0),
+    commits: commitView.length, warnings: journeys.reduce((n, j) => n + j.warnings, 0), orphans: Object.values(orphans).reduce((n, a) => n + a.length, 0),
+    stepsLive: journeys.reduce((n, j) => n + j.counts.live, 0), stepsTotal: journeys.reduce((n, j) => n + j.steps.length, 0),
+    grades: Object.fromEntries(['A', 'B', 'C', 'D'].map((k) => [k, journeys.reduce((n, j) => n + j.steps.filter((s) => s.grade === k).length, 0)])),
+  };
+
+  return {
+    schemaVersion: 1, generatedAt: new Date().toISOString(), project: sem.project || cfg.project, head, deploy: homelab, testreport: report,
+    adapters: g.toJSON().adapters, semantic: { actors: sem.actors || {}, statusLegend: sem.statusLegend || {}, journeys },
+    summary, orphans, coverage, tasks: taskView, roadmap, ledger, decisions: decisionView, plans, commits: commitView, areaCounts,
+    screens: screenView, apis: apiView, functions: fnView, migrations: migView, tests: testView,
+  };
+}
+
+// 첫 화면 전용 조각: 시스템 식별자(경로·파일·sha)를 뺀다. 개요는 이것만 받는다.
+export function overviewSlice(d) {
+  const A = d.semantic.actors;
+  const lastRun = d.testreport ? { fresh: d.testreport.fresh, failures: d.testreport.failures, total: d.testreport.total, at: d.testreport.at } : null;
+  return {
+    generatedAt: d.generatedAt, project: d.project, headDate: d.head?.date || null,
+    line: summaryLine(d),
+    journeys: d.semantic.journeys.map((j) => ({ id: j.id, title: j.title, actor: A[j.actor] || j.actor, lane: j.lane, status: j.status, warnings: j.warnings, steps: j.steps.map((s) => ({ id: s.id, label: s.label, status: s.status, grade: s.grade, warn: s.warnings.length > 0 })) })),
+    running: d.ledger.running.map((r) => ({ work: r.work, owner: r.owner })),
+    roadmap: d.roadmap.filter((m) => m.status !== '완료').slice(0, 4).map((m) => ({ id: m.id, title: m.title, status: m.status, mode: m.mode, live: m.progress.live, total: m.progress.total, waiting: !!m.waitingOn })),
+    roadmapDone: d.roadmap.filter((m) => m.status === '완료').length, roadmapTotal: d.roadmap.length,
+    waiting: d.ledger.waiting.filter((w) => !w.done).map((w) => ({ work: w.work, state: (w.state || '').split('(')[0] })),
+    tasks: d.tasks.filter((t) => t.status !== '폐기' && t.status !== '기록').slice().sort((a, b) => (a.status === '진행' ? -1 : 1) - (b.status === '진행' ? -1 : 1) || b.recentCommits - a.recentCommits).slice(0, 6).map((t) => ({ id: t.name, title: t.title, stage: t.stage, status: t.status, pnDone: t.pnDone, pnOpen: t.pnOpen, oq: t.oq })),
+    signals: {
+      deploy: d.deploy ? (d.deploy.behindRuntime === 0 ? 'ok' : d.deploy.behindRuntime === null ? 'unknown' : 'behind') : 'unknown', deployBehind: d.deploy?.behindRuntime ?? null,
+      tests: lastRun ? (lastRun.failures ? 'fail' : lastRun.fresh ? 'ok' : 'stale') : 'none', lastRun,
+      adapters: d.adapters.some((a) => a.status === 'failed') ? 'fail' : d.adapters.some((a) => a.status === 'partial') ? 'partial' : 'ok', adapterNotes: d.adapters.filter((a) => a.status !== 'ok').map((a) => `${a.name}: ${a.error}`),
+      warnings: d.summary.warnings, orphans: d.summary.orphans, gated: d.tests.filter((t) => t.gated).reduce((n, t) => n + t.count, 0),
+    },
+    counts: { stepsLive: d.summary.stepsLive, stepsTotal: d.summary.stepsTotal, screensLive: d.summary.liveRoutes, screensFixed: d.summary.fixedRoutes, screens: d.summary.routes, apis: d.summary.apis, functions: d.summary.dbFunctions, tests: d.summary.tests, pnDone: d.summary.pnDone, pnTotal: d.summary.pnDone + d.summary.pnOpen, oq: d.summary.oq, decisions: d.decisions.filter((x) => x.status === 'current').length, proposed: d.decisions.filter((x) => x.status === 'proposed').length, grades: d.summary.grades },
+    areas: Object.entries(d.areaCounts).sort((a, b) => b[1] - a[1]).slice(0, 6),
+    recent: d.commits.filter((c) => c.journeys.length).slice(0, 6).map((c) => ({ date: c.date, subject: c.subject, scenes: c.journeys.map((x) => x.label) })),
+    openQuestions: d.plans.filter((p) => p.oq).map((p) => ({ title: p.title, oq: p.oq })),
+  };
+}
+
+export function summaryLine(d) {
+  const s = d.summary;
+  const next = (d.roadmap || []).find((m) => m.status === '진행')?.title || (d.roadmap || []).find((m) => m.status === '다음')?.title || d.ledger.running[0]?.work || d.ledger.waiting.find((w) => !w.done && /대기/.test(w.state || ''))?.work || '';
+  const parts = [`장면 ${s.stepsLive}/${s.stepsTotal} 동작`, `화면 ${s.liveRoutes}/${s.routes} 실데이터`, ...(s.fixedRoutes ? [`하드코딩 표시 ${s.fixedRoutes}`] : []), `14일 커밋 ${s.commits}`];
+  if (d.deploy && d.deploy.behindRuntime > 0) parts.push(`미배포 ${d.deploy.behindRuntime}`);
+  if (s.warnings) parts.push(`경고 ${s.warnings}`);
+  return `${parts.join(' · ')}${next ? ` · 다음: ${next.replace(/\*\*/g, '').replace(/\[([^\]]+)\]\([^)]+\)/g, '$1').slice(0, 40)}` : ''}`;
+}

package/src/init.mjs

@@ -0,0 +1,70 @@
+// livemap init: 없는 파일만 템플릿으로 만들고 .gitignore 줄과 npm 스크립트를 넣는다. 다시 실행하면 아무것도 바꾸지 않는다.
+import { existsSync, mkdirSync, copyFileSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export const INIT_FILES = [
+  ['templates/config.json', 'map/config.json'],
+  ['templates/journeys.json', 'map/semantic/journeys.json'],
+  ['templates/README.md', 'map/README.md'],
+  ['templates/captures-README.md', 'map/captures/README.md'],
+];
+export const IGNORE_LINE = 'map/.out/';
+export const BUDGET_SCRIPT = 'playwright test --config node_modules/@pghoya2956/livemap/budget/playwright.config.mjs';
+export const SCRIPTS = {
+  map: 'livemap build',
+  'map:check': 'livemap check',
+  'map:serve': 'livemap serve',
+  'map:export': 'livemap export map/.out/site',
+  'test:report': 'livemap test-report',
+};
+
+const hasPlaywright = (root, pkg) => existsSync(join(root, 'node_modules/@playwright/test/package.json'))
+  || Boolean(pkg?.devDependencies?.['@playwright/test'] || pkg?.dependencies?.['@playwright/test']);
+
+export function init({ root, pkgRoot }) {
+  const created = [];
+  const kept = [];
+  for (const [from, to] of INIT_FILES) {
+    const dst = join(root, to);
+    if (existsSync(dst)) continue;
+    mkdirSync(dirname(dst), { recursive: true });
+    copyFileSync(join(pkgRoot, from), dst);
+    created.push(to);
+  }
+
+  const ignore = join(root, '.gitignore');
+  const ignoreText = existsSync(ignore) ? readFileSync(ignore, 'utf8') : '';
+  if (!ignoreText.split(/\r?\n/).some((l) => l.trim() === IGNORE_LINE || l.trim() === `/${IGNORE_LINE}`)) {
+    writeFileSync(ignore, `${ignoreText}${ignoreText && !ignoreText.endsWith('\n') ? '\n' : ''}${IGNORE_LINE}\n`);
+    created.push(`.gitignore: ${IGNORE_LINE}`);
+  }
+
+  const pkgFile = join(root, 'package.json');
+  const notes = [];
+  if (!existsSync(pkgFile)) {
+    notes.push('package.json 없음: npm init 뒤 다시 실행하면 npm 스크립트를 넣는다');
+  } else {
+    const raw = readFileSync(pkgFile, 'utf8');
+    const pkg = JSON.parse(raw);
+    const want = { ...SCRIPTS };
+    if (hasPlaywright(root, pkg)) want['map:budget'] = BUDGET_SCRIPT;
+    else notes.push('@playwright/test 없음: 화면 예산 검사를 쓰려면 npm i -D -E @playwright/test@1.63.0 뒤 다시 livemap init');
+    const scripts = { ...(pkg.scripts || {}) };
+    let changed = false;
+    for (const [name, value] of Object.entries(want)) {
+      if (!(name in scripts)) { scripts[name] = value; created.push(`npm 스크립트 ${name}`); changed = true; }
+      else if (scripts[name] !== value) kept.push(`npm 스크립트 ${name}: 기존 값 유지("${scripts[name]}", 권장 "${value}")`);
+    }
+    if (changed) {
+      pkg.scripts = scripts;
+      const indent = raw.match(/^[ \t]+(?=")/m)?.[0] ?? '  ';
+      writeFileSync(pkgFile, JSON.stringify(pkg, null, indent) + (raw.endsWith('\n') ? '\n' : ''));
+    }
+  }
+
+  for (const c of created) console.log(`+ ${c}`);
+  for (const k of kept) console.log(`= ${k}`);
+  for (const n of notes) console.log(`! ${n}`);
+  if (!created.length) console.log('livemap init: 변경 없음');
+  return 0;
+}

package/src/lib/graph.mjs

@@ -0,0 +1,48 @@
+// 그래프 모델. 어댑터는 노드·엣지만 넣고, 화면은 파생 뷰만 읽는다.
+// 노드: { kind, id, label, props, src: { file, line, rule } }  엣지: { from, to, kind }
+export const NODE_KINDS = ['journey', 'step', 'screen', 'api', 'function', 'table', 'migration', 'test', 'commit', 'decision', 'task', 'ledger', 'deploy', 'testreport', 'milestone'];
+export const EDGE_KINDS = ['has_step', 'shows', 'uses', 'calls', 'invokes', 'touches', 'covers', 'changes', 'refs', 'defines', 'contains', 'tracks'];
+
+export class Graph {
+  constructor() { this.nodes = new Map(); this.edges = []; this.adapters = []; }
+  key(kind, id) { return `${kind}:${id}`; }
+  add(kind, id, label, props = {}, src = null) {
+    if (!NODE_KINDS.includes(kind)) throw new Error(`unknown node kind ${kind}`);
+    const k = this.key(kind, id);
+    const existing = this.nodes.get(k);
+    if (existing) { Object.assign(existing.props, props); if (src && !existing.src) existing.src = src; return existing; }
+    const node = { kind, id, label: label ?? id, props, src };
+    this.nodes.set(k, node);
+    return node;
+  }
+  link(fromKind, fromId, kind, toKind, toId) {
+    if (!EDGE_KINDS.includes(kind)) throw new Error(`unknown edge kind ${kind}`);
+    const from = this.key(fromKind, fromId), to = this.key(toKind, toId);
+    if (!this.edges.some((e) => e.from === from && e.to === to && e.kind === kind)) this.edges.push({ from, to, kind });
+  }
+  get(kind, id) { return this.nodes.get(this.key(kind, id)) || null; }
+  of(kind) { return [...this.nodes.values()].filter((n) => n.kind === kind); }
+  out(kind, id, edgeKind = null) {
+    const from = this.key(kind, id);
+    return this.edges.filter((e) => e.from === from && (!edgeKind || e.kind === edgeKind)).map((e) => this.nodes.get(e.to)).filter(Boolean);
+  }
+  in(kind, id, edgeKind = null) {
+    const to = this.key(kind, id);
+    return this.edges.filter((e) => e.to === to && (!edgeKind || e.kind === edgeKind)).map((e) => this.nodes.get(e.from)).filter(Boolean);
+  }
+  report(name, status, count, error = null) { this.adapters.push({ name, status, count, error }); }
+  toJSON() {
+    return { schemaVersion: 1, adapters: this.adapters, nodes: [...this.nodes.values()], edges: this.edges };
+  }
+}
+
+// 어댑터 실행 래퍼: 실패해도 그래프 생성이 멈추지 않고 failed로 기록된다(빈 표를 "없음"으로 오해하지 않게).
+export function runAdapter(graph, name, fn) {
+  const before = graph.nodes.size;
+  try {
+    const partial = fn(graph);
+    graph.report(name, partial ? 'partial' : 'ok', graph.nodes.size - before, partial || null);
+  } catch (e) {
+    graph.report(name, 'failed', graph.nodes.size - before, String(e.message || e));
+  }
+}

package/src/lib/util.mjs

@@ -0,0 +1,36 @@
+// 어댑터 공용 유틸. 파일 읽기·순회·git 호출을 한 곳에 둔다(테스트에서 ROOT를 바꿔 끼운다).
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { join } from 'node:path';
+
+export function makeFs(ROOT) {
+  const abs = (p) => join(ROOT, p);
+  const has = (p) => existsSync(abs(p));
+  const isDir = (p) => has(p) && statSync(abs(p)).isDirectory();
+  const read = (p) => readFileSync(abs(p), 'utf8');
+  const walk = (dir, pred, acc = []) => {
+    if (!isDir(dir)) return acc;
+    for (const name of readdirSync(abs(dir))) {
+      const rel = join(dir, name);
+      if (statSync(abs(rel)).isDirectory()) { if (name !== 'node_modules' && name !== '.git') walk(rel, pred, acc); }
+      else if (pred(rel)) acc.push(rel);
+    }
+    return acc;
+  };
+  const ls = (dir) => (isDir(dir) ? readdirSync(abs(dir)) : []);
+  let gitOk = null;
+  const git = (...a) => {
+    try { const out = execFileSync('git', ['-C', ROOT, ...a], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); gitOk = true; return out; }
+    catch { if (gitOk === null) gitOk = false; return ''; }
+  };
+  const lastCommit = (path) => {
+    const line = git('log', '-1', '--format=%h|%ad|%s', '--date=short', '--', path);
+    if (!line) return null;
+    const [sha, date, ...s] = line.split('|');
+    return { sha, date, subject: s.join('|') };
+  };
+  // main → origin/main → HEAD 순으로 존재하는 참조를 고른다(CI 체크아웃에는 로컬 main이 없을 수 있다).
+  const resolveRef = (name) => { for (const c of [name, `origin/${name}`, 'HEAD']) if (git('rev-parse', '--verify', '--quiet', c)) return c; return null; };
+  const lineOf = (text, needle) => { const i = text.indexOf(needle); return i < 0 ? null : text.slice(0, i).split('\n').length; };
+  return { ROOT, abs, has, isDir, read, walk, ls, git, lastCommit, lineOf, resolveRef, hasGit: () => { if (gitOk === null) git('rev-parse', 'HEAD'); return gitOk; } };
+}

package/src/serve.mjs

@@ -0,0 +1,106 @@
+// 로컬 뷰와 export. 127.0.0.1 전용.
+// 브라우저 주소 → 파일 배치는 locate() 하나가 정하고, serve(재빌드)·serve --static·export가 같은 배치를 쓴다.
+//   /map/  /map/map.css  /map/map.js  /map/fonts/*   → 화면 폴더(패키지 site/)
+//   /map/captures/<id>.jpg                           → 캡처 폴더(프로젝트 config.captures.site)
+//   /map/data/*.json                                 → 생성물 폴더(--out)
+import { createServer } from 'node:http';
+import { readFile, stat } from 'node:fs/promises';
+import { existsSync, mkdirSync, readdirSync, rmSync, statSync, copyFileSync, writeFileSync } from 'node:fs';
+import { join, extname, resolve, dirname, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const types = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript', '.css': 'text/css', '.json': 'application/json', '.jpg': 'image/jpeg', '.png': 'image/png', '.svg': 'image/svg+xml', '.woff2': 'font/woff2', '.txt': 'text/plain; charset=utf-8' };
+export const SITE = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'site');
+export const DATA_FILES = ['data.json', 'overview.json', 'graph.json'];
+export const EXPORT_MARK = '.livemap-export';
+export const CSP = "default-src 'self'; script-src 'self'; style-src 'self'; connect-src 'self'; img-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'self'";
+
+// 주소(/map/ 아래 경로)를 { kind, rel }로 푼다. 숨김 파일·경로 탈출은 null.
+export function locate(pathname) {
+  if (!pathname.startsWith('/map/')) return null;
+  let rel = pathname.slice('/map/'.length);
+  if (rel === '') rel = 'index.html';
+  let parts;
+  try { parts = rel.split('/').map((p) => decodeURIComponent(p)); } catch { return null; }
+  if (parts.some((p) => p === '' || p.startsWith('.') || /[\\/\0]/.test(p))) return null;
+  if (parts[0] === 'data') return parts.length === 2 ? { kind: 'data', rel: parts[1] } : null;
+  if (parts[0] === 'captures') return parts.length === 2 ? { kind: 'captures', rel: parts[1] } : null;
+  return { kind: 'site', rel: parts.join('/') };
+}
+
+const inside = (base, file) => file === base || file.startsWith(base.endsWith(sep) ? base : base + sep);
+
+// 배치 종류별 원본 폴더. 재빌드 서빙은 패키지·프로젝트·생성물 세 곳, static은 export 폴더 한 곳.
+export function sourcesFor({ static: dir, out, captures }) {
+  if (dir) return { site: dir, captures: join(dir, 'captures'), data: join(dir, 'data') };
+  return { site: SITE, captures, data: out };
+}
+
+export function serve({ root, out, port, build, captures, static: staticDir }) {
+  const src = sourcesFor({ static: staticDir, out, captures });
+  let last = 0;
+  const server = createServer(async (req, res) => {
+    const url = new URL(req.url, 'http://localhost');
+    const path = url.pathname;
+    if (path === '/' || path === '/map') { res.writeHead(302, { location: '/map/' }); return res.end(); }
+    // 배포 서빙과 같은 CSP를 걸어 인라인 스타일·스크립트 의존을 로컬에서 먼저 잡는다.
+    res.setHeader('content-security-policy', CSP);
+    const loc = locate(path);
+    if (!loc) { res.writeHead(path.startsWith('/map/') ? 403 : 404); return res.end('not found'); }
+    try {
+      if (loc.kind === 'data' && !staticDir && Date.now() - last > 5000) { await build(); last = Date.now(); }
+      const base = src[loc.kind];
+      const file = resolve(base, loc.rel);
+      if (!inside(base, file)) { res.writeHead(403); return res.end(); }
+      if (!(await stat(file)).isFile()) throw new Error('not a file');
+      const cache = loc.kind === 'data' ? 'no-store' : 'no-cache';
+      res.writeHead(200, { 'content-type': types[extname(file)] || 'application/octet-stream', 'cache-control': cache });
+      res.end(await readFile(file));
+    } catch {
+      res.writeHead(404); res.end('not found');
+    }
+  });
+  const label = staticDir ? `static ${staticDir}` : `root ${root}`;
+  server.listen(port, '127.0.0.1', () => console.log(`map serve → http://127.0.0.1:${port}/map/  (${label})`));
+  return server;
+}
+
+// 폴더 안 파일을 숨김 파일 빼고 상대 경로로 나열한다.
+function listFiles(dir, prefix = '') {
+  if (!existsSync(dir)) return [];
+  const acc = [];
+  for (const name of readdirSync(dir).sort()) {
+    if (name.startsWith('.')) continue;
+    const abs = join(dir, name);
+    const rel = prefix ? `${prefix}/${name}` : name;
+    if (statSync(abs).isDirectory()) acc.push(...listFiles(abs, rel));
+    else acc.push(rel);
+  }
+  return acc;
+}
+
+// export 폴더를 serve --static이 읽는 배치(locate의 역)로 만든다. 종료 코드를 돌려준다.
+export function exportSite({ out, captures, target }) {
+  const missing = DATA_FILES.filter((f) => !existsSync(join(out, f)));
+  if (missing.length) { console.error(`생성물 없음(${missing.join(', ')}): 먼저 livemap build --out ${out}`); return 2; }
+  if (existsSync(target)) {
+    if (!statSync(target).isDirectory()) { console.error(`export 대상이 폴더가 아님: ${target}`); return 2; }
+    const entries = readdirSync(target);
+    if (entries.length && !entries.includes(EXPORT_MARK)) {
+      console.error(`export 대상이 비어 있지 않고 이전 export 폴더도 아님(지우지 않음): ${target}`);
+      return 2;
+    }
+    rmSync(target, { recursive: true, force: true });
+  }
+  const dst = sourcesFor({ static: target });
+  const copies = [
+    ...listFiles(SITE).map((rel) => [join(SITE, rel), join(dst.site, rel)]),
+    ...listFiles(captures).filter((f) => !f.includes('/') && f.endsWith('.jpg')).map((f) => [join(captures, f), join(dst.captures, f)]),
+    ...DATA_FILES.map((f) => [join(out, f), join(dst.data, f)]),
+  ];
+  for (const [from, to] of copies) { mkdirSync(dirname(to), { recursive: true }); copyFileSync(from, to); }
+  writeFileSync(join(target, EXPORT_MARK), 'livemap export\n');
+  const caps = copies.filter(([, to]) => dirname(to) === dst.captures).length;
+  console.log(`map export → ${target}: 파일 ${copies.length} (캡처 ${caps})`);
+  return 0;
+}

package/src/test-report.mjs

@@ -0,0 +1,22 @@
+// 단위 검사를 JUnit 리포트로 남기고 기준 커밋·시각을 옆에 적는다. 상황판이 이 둘을 읽어 "최신 커밋에서 통과"(등급 A)를 판정한다.
+// 검사 폴더는 config.tests.dir, 리포트는 config.tests.report(메타는 같은 이름의 .json). 로컬 스택이 필요한 검사면 개발 머신에서 돌린다.
+import { spawnSync, execFileSync } from 'node:child_process';
+import { mkdirSync, writeFileSync, readdirSync, existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+export function testReport({ root, cfg }) {
+  const dir = cfg?.tests?.dir || 'tests';
+  const report = cfg?.tests?.report || 'map/.out/junit.xml';
+  const abs = (p) => resolve(root, p);
+  if (!existsSync(abs(dir))) { console.error(`검사 폴더 없음: ${dir} (config.tests.dir)`); return 2; }
+  mkdirSync(dirname(abs(report)), { recursive: true });
+  // Node 22.22는 디렉토리 인자를 검사 하나의 실패로 취급하므로 파일 목록을 넘긴다.
+  const files = readdirSync(abs(dir)).filter((f) => f.endsWith('.test.mjs')).map((f) => join(dir, f));
+  const r = spawnSync('node', ['--test', '--test-concurrency=1', '--test-reporter=junit', `--test-reporter-destination=${report}`, ...files], { stdio: 'inherit', cwd: root });
+  let sha = null;
+  try { sha = execFileSync('git', ['-C', root, 'rev-parse', 'HEAD'], { encoding: 'utf8' }).trim(); } catch { /* git 저장소가 아니면 기준 커밋 없음 */ }
+  const meta = report.replace(/\.xml$/, '.json');
+  writeFileSync(abs(meta), JSON.stringify({ sha, at: new Date().toISOString(), exit: r.status }, null, 2));
+  console.log(`test report → ${report} (sha ${sha ? sha.slice(0, 7) : '-'}, exit ${r.status})`);
+  return r.status ?? 1;
+}

package/templates/README.md

@@ -0,0 +1,29 @@
+# 프로젝트 상황판
+
+제품 오너가 코드를 읽지 않고 "어디까지 실제로 동작하나, 지금 무엇을 하나, 무엇이 바뀌었나"를 한 화면에서 보고, 여정 → 장면 → 화면·API·DB·검사·결정·작업으로 파고드는 뷰다. 엔진은 npm 패키지 `@pghoya2956/livemap`이고, 이 폴더에는 프로젝트 소유 파일만 둔다. 배포본 주소: `<배포 주소>/map/`. 실시간은 로컬 `npm run map:serve`.
+
+## 명령
+
+| 명령 | 하는 일 |
+|---|---|
+| `npm run map` | 저장소 스캔 → `map/.out/{graph,data,overview}.json` (git 제외) |
+| `npm run map:check` | 정합 검사. 오류면 exit 1(CI 게이트): 어댑터 실패·바닥값 미달·장면이 가리키는 라우트 없음·상태 모순·참조 미해결 |
+| `npm run map:serve` | `http://127.0.0.1:4180/map/` 로컬 뷰. 요청마다 재빌드(5초 캐시) |
+| `npm run map:budget` | 화면 예산 Playwright 검사 + 개요 스크린샷 `map/.out/overview-1440.png` |
+| `npm run map:export` | 배포용 한 폴더 `map/.out/site`(먼저 `npm run map`) |
+| `npm run test:report` | 단위 검사를 JUnit으로 남겨 장면 등급 A(최신 커밋에서 통과) 판정에 쓴다 |
+
+## 이 폴더
+
+| 파일 | 내용 |
+|---|---|
+| `config.json` | 어댑터 입력 경로·바닥값·화면 예산. `engine`은 엔진 major |
+| `semantic/journeys.json` | 손으로 유지하는 유일한 층: 배우·목표·장면. 장면 상태가 바뀌는 병합은 같은 커밋에서 이 파일을 고친다 |
+| `captures/*.jpg` | 장면 캡처 |
+| `adapters/<이름>.mjs` | 이 프로젝트만의 어댑터(선택). 참조 어댑터와 이름이 같으면 참조 어댑터를 가린다 |
+
+작성 안내·어댑터 계약·서빙 방법은 `node_modules/@pghoya2956/livemap/docs/`에 있다.
+
+## 업그레이드
+
+`npm i -D -E @pghoya2956/livemap@<버전>`을 커밋한다. major가 바뀌면 `docs/migrate.md`를 따른다.

package/templates/captures-README.md

@@ -0,0 +1 @@
+이 폴더에 장면 캡처(JPEG, 파일명 = `map/semantic/journeys.json`의 `capture` 값 + `.jpg`)를 둔다. 없으면 장면 카드가 빈 칸으로 그려진다. 위치는 `map/config.json`의 `captures.site`가 정한다.

package/templates/config.json

@@ -0,0 +1,18 @@
+{
+  "engine": 1,
+  "project": { "name": "프로젝트 이름", "host": "https://example.invalid" },
+  "adapters": ["router", "bff", "migrations", "tests", "wiki", "tasks", "roadmap", "git", "deploy", "testreport"],
+  "router": { "app": "web/src/App.tsx", "pagesDir": "web/src/pages", "localDirs": ["web/src/pages", "web/src/components"], "mockPattern": "/mock'", "fixedPattern": "/content/", "livePattern": "lib/queries", "hookApi": { "Session": "/api/session" } },
+  "bff": { "server": "app/server.mjs" },
+  "migrations": { "dir": "supabase/migrations" },
+  "tests": { "dir": "tests", "gatePattern": "ALLOW_DESTRUCTIVE", "report": "map/.out/junit.xml" },
+  "tasks": { "dir": "tasks", "index": "tasks/index.md" },
+  "roadmap": { "file": "tasks/roadmap.md" },
+  "wiki": { "index": ".agent/wiki/index.md", "sources": ".agent/wiki/sources.yaml" },
+  "git": { "branch": "main", "sinceDays": 14, "areas": [["web/", "화면"], ["app/", "서버"], ["supabase/", "DB"], ["tests/", "검사"], ["deploy/", "배포"], [".github/", "배포"], ["map/", "상황판"], ["tasks/", "문서"], [".md", "문서"]], "runtimePaths": ["web", "app", "supabase", "Dockerfile", "package.json"] },
+  "deploy": { "manifest": "deploy/k8s/app.yaml", "imagePattern": "image: ghcr\\.io/[^:]+:([0-9a-f]{40})" },
+  "semantic": "map/semantic/journeys.json",
+  "captures": { "site": "map/captures" },
+  "floors": { "screen": 1, "api": 1 },
+  "budget": { "viewport": [1440, 900], "maxPanels": 8, "maxRowsPerPanel": 6, "navItems": 5 }
+}

package/templates/journeys.json

@@ -0,0 +1,15 @@
+{
+  "project": { "name": "프로젝트 이름", "tagline": "한 줄 설명", "host": "https://example.invalid" },
+  "actors": { "user": "사용자", "staff": "운영자" },
+  "statusLegend": { "live": "실데이터로 동작", "mock": "화면만(목업 데이터)", "planned": "미착수(스펙 있음)", "next": "다음 스펙" },
+  "journeys": [
+    {
+      "id": "first", "title": "첫 여정(예시, 바꿔 쓴다)", "actor": "user", "lane": "사용자 여정",
+      "goal": "배우가 이루려는 목표 한 문장",
+      "steps": [
+        { "id": "start", "label": "첫 장면", "intent": "사용자가 원해서 하는 일", "status": "mock", "screens": ["/"], "capture": null, "refs": [], "reviewedAt": "2026-01-01" }
+      ]
+    }
+  ],
+  "captures": { "dir": "map/captures", "note": "장면 캡처(JPEG 720px). 화면이 바뀌면 같은 이름으로 다시 만든다." }
+}