@pghoya2956/livemap 1.1.0 → 1.2.0

package/src/adapters/testreport.mjs

@@ -1,24 +1,120 @@
-// 검사 결과 어댑터: 마지막 검사 실행의 JUnit XML(map/.out/junit.xml)을 읽는다. 기준 커밋이 main HEAD와 같을 때만 "최신 검증"으로 친다.
-// 리포트는 `npm run test:report`가 남긴다. 없으면 등급 A를 줄 수 없을 뿐 생성은 계속된다.
+// 검사 결과 어댑터: 결과 JSON(tests.report 폴더의 test-results.json)을 먼저 읽고, 없으면 JUnit(tests.report)과 옆 메타를 같은 해석기로 읽는다.
+// 둘 다 없으면 1.1.1 문구를 그대로 돌려준다(골든 1.0.1이 adapters[]·adapterNotes에서 위치로 비교한다).
+// 최신(DEC-18): 실행 sha가 git 어댑터의 HEAD와 같거나 조상이고, 그 뒤 커밋과 실행 때 바뀐 경로(dirtyPaths)가 문서 경로 밖을 건드리지 않으면 최신이다.
+// 문서 경로는 설정 키에서만 정한다: tasks.dir, wiki.index 폴더, semantic, roadmap.file, captures.site, deploy.manifest, map/judgments.
+// 검사 노드(id = 파일 경로)와 결과 filePath를 그대로 맞춘다. 결과가 없거나 파일별 결과가 없는 검사의 lastRun 읽기 상태는 unknown이다.
+import { posix } from 'node:path';
+import { parseJunit, readResults, resultsPath, totalsOf } from '../results.mjs';
+import { setReading } from '../lib/reading.mjs';
+
+const NO_REPORT = '검사 리포트 없음(npm run test:report 미실행)';
+const NO_HISTORY = '결과 커밋이 이력에 없음';
+
+export function docPaths(cfg) {
+  const wikiDir = cfg.wiki?.index ? posix.dirname(cfg.wiki.index) : null;
+  const paths = [
+    cfg.tasks?.dir,
+    // 위키 인덱스가 루트에 있으면 폴더 대신 그 파일만 문서 경로로 본다(루트 전체가 문서가 되지 않게)
+    wikiDir && wikiDir !== '.' ? wikiDir : cfg.wiki?.index,
+    cfg.semantic, cfg.roadmap?.file, cfg.captures?.site, cfg.deploy?.manifest, 'map/judgments',
+  ];
+  return [...new Set(paths.filter((p) => typeof p === 'string' && p).map((p) => p.replace(/^\.\//, '').replace(/\/+$/, '')))].filter((p) => p && p !== '.');
+}
+const inDocs = (docs, p) => { const x = String(p).replace(/\/+$/, ''); return docs.some((d) => x === d || x.startsWith(d + '/')); };
+
+// 실행 하나의 최신 여부와 낡은 이유
+function freshness(run, fs, cfg, head) {
+  if (!run.sha || !head || !fs.hasGit()) return { fresh: false, note: NO_HISTORY };
+  const sha = fs.git('rev-parse', '--verify', '--quiet', `${run.sha}^{commit}`);
+  if (!sha) return { fresh: false, note: NO_HISTORY };
+  if (sha !== head && fs.git('merge-base', sha, head) !== sha) return { fresh: false, note: '결과 커밋이 HEAD의 조상이 아님' };
+  const docs = docPaths(cfg);
+  if (sha !== head) {
+    const n = Number(fs.git('rev-list', '--count', `${sha}..${head}`, '--', '.', ...docs.map((d) => `:(exclude)${d}`)) || 0);
+    if (n > 0) return { fresh: false, note: `결과 커밋 뒤 문서 경로 밖 변경 커밋 ${n}` };
+  }
+  // JUnit 메타처럼 dirtyPaths가 없는 실행은 이 조건을 건너뛴다
+  if (Array.isArray(run.dirtyPaths)) {
+    const out = run.dirtyPaths.filter((p) => !inDocs(docs, p));
+    if (out.length) return { fresh: false, note: `실행 때 문서 경로 밖 변경 ${out.length}(${out.slice(0, 3).join(', ')}${out.length > 3 ? ' …' : ''})` };
+  }
+  return { fresh: true, note: null };
+}
+
+const failedOf = (run) => (run.totals || totalsOf(run.files || [])).failed;
+// 개요 신호: 최신 실행 중 실패가 있거나 exit가 0이 아니면 fail, 모두 최신이고 실패 0이면 ok, 최신이 아닌 실행이 있으면 stale, 실행이 없으면 none
+export function testSignal(runs) {
+  if (!runs.length) return 'none';
+  const fresh = runs.filter((r) => r.fresh);
+  if (fresh.some((r) => failedOf(r) > 0 || (typeof r.exit === 'number' && r.exit !== 0))) return 'fail';
+  return fresh.length === runs.length ? 'ok' : 'stale';
+}
+
 export default function testreport(g, fs, cfg) {
   const rel = cfg.tests.report;
-  if (!fs.has(rel)) return '검사 리포트 없음(npm run test:report 미실행)';
-  const xml = fs.read(rel);
-  const suites = [...xml.matchAll(/<testsuite\b([^>]*)>/g)].map((m) => Object.fromEntries([...m[1].matchAll(/(\w+)="([^"]*)"/g)].map((a) => [a[1], a[2]])));
-  const total = suites.reduce((n, s) => n + Number(s.tests || 0), 0);
-  const failures = suites.reduce((n, s) => n + Number(s.failures || 0) + Number(s.errors || 0), 0);
-  const skipped = suites.reduce((n, s) => n + Number(s.skipped || 0), 0);
-  const metaFile = rel.replace(/\.xml$/, '.json');
-  const meta = fs.has(metaFile) ? JSON.parse(fs.read(metaFile)) : {};
+  const tests = g.of('test');
   const head = g.get('deploy', 'head')?.props.full || null;
-  // suite가 하나도 없는 리포트(러너가 파일을 못 찾은 경우 등)는 통과 근거가 아니다.
-  const fresh = total > 0 && !!(meta.sha && head && meta.sha === head);
-  g.add('testreport', 'last', '마지막 검사', { total, failures, skipped, sha: meta.sha || null, at: meta.at || null, fresh, files: suites.map((s) => s.name) }, { file: rel, line: 1, rule: 'testreport:junit' });
-  // 검사 파일 노드에 통과 여부를 붙인다(파일명 기준 매칭)
-  for (const s of suites) {
-    const t = g.of('test').find((x) => s.name && (s.name.includes(x.label) || s.name.includes(x.id)));
-    if (t) { t.props.lastRun = { passed: Number(s.failures || 0) + Number(s.errors || 0) === 0, tests: Number(s.tests || 0), fresh }; }
+  const unknownAll = (note) => { for (const t of tests) setReading(t, 'lastRun', 'unknown', note); };
+  const resRel = resultsPath(cfg);
+  let runs;
+  let perFile = true;
+  if (fs.has(resRel)) {
+    try { runs = readResults(fs.abs(resRel)).runs; } catch (e) { unknownAll('결과 JSON을 읽지 못함'); return String(e.message).replace(fs.abs(resRel), resRel); }
+    if (!runs.length) { unknownAll('결과 JSON에 실행이 없음'); return '결과 JSON에 실행이 없음'; }
+  } else if (rel && fs.has(rel)) {
+    const metaFile = rel.replace(/\.xml$/, '.json');
+    let meta = {};
+    try { meta = fs.has(metaFile) ? JSON.parse(fs.read(metaFile)) : {}; } catch { meta = {}; }
+    const parsed = parseJunit(fs.read(rel), fs.ROOT);
+    // 메타에는 dirtyPaths가 없다(1.x 메타 모양)
+    runs = [{ runner: 'junit', source: rel, sha: meta.sha || null, at: meta.at || parsed.at || null, exit: typeof meta.exit === 'number' ? meta.exit : null, files: parsed.files, totals: parsed.totals }];
+    perFile = parsed.files.length > 0;
+  } else {
+    unknownAll('검사 결과 없음');
+    return NO_REPORT;
+  }
+
+  const judged = runs.map((run) => ({ ...run, ...freshness(run, fs, cfg, head) }));
+  // 파일마다 결과 하나: 최신 실행을 먼저, 같으면 나중 시각
+  const byFile = new Map();
+  for (const run of judged) {
+    for (const f of run.files || []) {
+      const cur = byFile.get(f.filePath);
+      const better = !cur || (run.fresh && !cur.run.fresh) || (run.fresh === cur.run.fresh && String(run.at || '') > String(cur.run.at || ''));
+      if (better) byFile.set(f.filePath, { run, file: f });
+    }
+  }
+  for (const t of tests) {
+    const hit = byFile.get(t.id);
+    if (!hit) { setReading(t, 'lastRun', 'unknown', perFile ? '결과에 이 검사 파일이 없음' : 'JUnit에 파일(file 속성)이 없어 파일별 결과 없음'); continue; }
+    const { run, file } = hit;
+    t.props.lastRun = {
+      passed: file.failed === 0, tests: file.tests, failed: file.failed, skipped: file.skipped, pending: file.pending,
+      ...(file.flaky !== undefined ? { flaky: file.flaky } : {}),
+      runner: run.runner, sha: run.sha || null, at: run.at || null, fresh: run.fresh, tags: file.tags || [],
+    };
+    t.props.runCount = file.tests;
+    if (run.fresh) {
+      t.props.count = file.tests;
+      setReading(t, 'count', 'observed');
+      setReading(t, 'lastRun', 'observed');
+    } else {
+      setReading(t, 'lastRun', 'stale', run.note);
+    }
+  }
+
+  const totals = judged.reduce((s, r) => { const x = r.totals || totalsOf(r.files || []); s.tests += x.tests; s.failed += x.failed; s.skipped += x.skipped; return s; }, { tests: 0, failed: 0, skipped: 0 });
+  const latest = judged.slice().sort((a, b) => String(b.at || '').localeCompare(String(a.at || '')))[0];
+  const signal = testSignal(judged);
+  g.add('testreport', 'last', '마지막 검사', {
+    total: totals.tests, failures: totals.failed, skipped: totals.skipped, sha: latest.sha || null, at: latest.at || null,
+    fresh: judged.every((r) => r.fresh), files: [...byFile.keys()].sort(), signal,
+    runs: judged.map((r) => ({ runner: r.runner, source: r.source ?? null, sha: r.sha || null, at: r.at || null, exit: r.exit ?? null, fresh: r.fresh })),
+  }, { file: fs.has(resRel) ? resRel : rel, line: 1, rule: fs.has(resRel) ? 'testreport:results' : 'testreport:junit' });
+  if (totals.tests === 0) return '리포트에 검사가 없음(러너 인자·경로 확인)';
+  if (signal === 'fail') {
+    const failed = judged.filter((r) => r.fresh).reduce((n, r) => n + failedOf(r), 0);
+    return failed ? `실패 ${failed}건` : `실행 종료 코드 ${judged.find((r) => r.fresh && typeof r.exit === 'number' && r.exit !== 0).exit}`;
   }
-  if (total === 0) return '리포트에 검사가 없음(러너 인자·경로 확인)';
-  return failures ? `실패 ${failures}건` : null;
+  return null;
 }

package/src/adapters/tests.mjs

@@ -1,4 +1,5 @@
 import { join } from 'node:path';
+import { setReading } from '../lib/reading.mjs';
 // 검사 어댑터: tests/ 파일에서 test 노드를 만들고, 파일 안의 goto('/…')·'/api/…' 문자열로 screen·api를 덮는(covers) 엣지를 잇는다.
 export default function tests(g, fs, cfg) {
   const c = cfg.tests;
@@ -19,8 +20,11 @@ export default function tests(g, fs, cfg) {
     const own = fs.read(f);
     const t = [...closure(f)].map(fs.read).join('\n');
     const count = (own.match(/^\s*(?:test|it)\(/gm) || []).length;
+    // 제목이 ${ 를 가진 템플릿 문자열이면 반복문으로 여러 번 등록될 수 있어 줄 수가 실제 개수보다 작을 수 있다.
+    const templated = own.split('\n').flatMap((line, i) => (/^\s*(?:test|it)\(\s*`[^`]*\$\{/.test(line) ? [i + 1] : []));
     const id = f;
-    g.add('test', id, f.replace(`${c.dir}/`, '').replace(/\.(test|spec)\.mjs$/, ''), { kind: f.endsWith('.spec.mjs') ? 'e2e' : 'unit', count, gated: gate.test(own) }, { file: f, line: 1, rule: 'tests:test(|it(' });
+    const node = g.add('test', id, f.replace(`${c.dir}/`, '').replace(/\.(test|spec)\.mjs$/, ''), { kind: f.endsWith('.spec.mjs') ? 'e2e' : 'unit', count, gated: gate.test(own) }, { file: f, line: 1, rule: 'tests:test(|it(' });
+    if (templated.length) setReading(node, 'count', 'partial', `제목이 템플릿 문자열인 호출(${f}:${templated.join(',')})은 반복 등록이면 실제 개수가 더 많다`);
     for (const s of g.of('screen')) {
       const goto = s.id.replace(/:\w+/g, '');
       if ((goto.length > 1 && t.includes(`goto('${goto}`)) || (s.id === '/' && t.includes("goto('/')"))) g.link('test', id, 'covers', 'screen', s.id);

package/src/check.mjs

@@ -1,56 +1,124 @@
 // 검증: 생성물 바이트 비교가 아니라 뜻(여정)과 사실(코드)의 정합을 본다.
 // error → CI 실패. warn → 화면에 뜨는 경고와 같은 것들.
-export function check(d, cfg) {
+// 문제마다 이슈 계약 코드(docs/issue-codes.md)를 붙인다. 문구(msg)와 순서는 1.1.1 텍스트 출력 그대로다.
+import { problem } from './lib/issues.mjs';
+
+// derive가 만든 완성 문장을 코드로 가른다. 맞는 규칙이 없으면 마지막 대체 코드
+const STEP_WARNING = [[/^라우트 없음/, 'step.route-missing'], [/^참조 미해결/, 'step.ref-unresolved'], [/^장면은 동작인데/, 'step.screen-not-live'], [/^장면은 \S+인데 화면은 동작/, 'step.screen-live-early'], [/관측 근거 없음/, 'step.no-evidence'], [/^확인 필요/, 'step.review-stale']];
+const ROADMAP_PROBLEM = [[/^장면 없음/, 'roadmap.scene-missing'], [/^작업 폴더 없음/, 'roadmap.task-missing'], [/^선행 항목 없음/, 'roadmap.dep-missing'], [/^알 수 없는 상태/, 'roadmap.unknown-status'], [/^마일스톤 없음/, 'roadmap.milestone-missing']];
+const MILESTONE_PROBLEM = [[/: id 없음$/, 'milestone.no-id'], [/^마일스톤 id 중복/, 'milestone.duplicate-id'], [/: 알 수 없는 상태 /, 'milestone.unknown-status'], [/: 날짜 형식 /, 'milestone.bad-date']];
+const MILESTONE_WARNING = [[/: 완료인데 미완료 항목/, 'milestone.done-open-items'], [/: 항목이 모두 완료인데 상태/, 'milestone.all-items-done'], [/: 진행 항목이 있는데 상태/, 'milestone.running-items'], [/: 묶인 항목 없음$/, 'milestone.no-items'], [/: 완료일과 상태가 맞지 않음$/, 'milestone.completed-on-mismatch']];
+const pick = (rules, text, fallback) => rules.find(([re]) => re.test(text))?.[1] || fallback;
+
+// 이슈 계약 모양의 문제 목록: { level, code, msg, subject, anchors, resolutions }
+export function checkProblems(d, cfg) {
   const out = [];
-  const err = (msg) => out.push({ level: 'error', msg });
-  const warn = (msg) => out.push({ level: 'warn', msg });
+  const err = (code, msg, extra) => out.push(problem('error', code, msg, extra));
+  const warn = (code, msg, extra) => out.push(problem('warn', code, msg, extra));
+  const subj = (kind, id) => ({ subject: { kind, id: String(id) } });
 
-  for (const a of d.adapters) if (a.status === 'failed') err(`어댑터 실패 ${a.name}: ${a.error}`);
+  for (const a of d.adapters) if (a.status === 'failed') err('adapter.failed', `어댑터 실패 ${a.name}: ${a.error}`, subj('adapter', a.name));
   const counts = { screen: d.summary.routes, api: d.summary.apis, function: d.summary.dbFunctions, test: d.tests.length, task: d.tasks.length, decision: d.decisions.length };
-  for (const [k, floor] of Object.entries(cfg.floors || {})) if ((counts[k] ?? 0) < floor) err(`바닥값 미달 ${k}: ${counts[k] ?? 0} < ${floor} (스캐너가 깨졌을 가능성)`);
+  for (const [k, floor] of Object.entries(cfg.floors || {})) if ((counts[k] ?? 0) < floor) err('floor.below', `바닥값 미달 ${k}: ${counts[k] ?? 0} < ${floor} (스캐너가 깨졌을 가능성)`, subj('config', `floors.${k}`));
 
   const ids = new Set();
   for (const j of d.semantic.journeys) {
-    if (ids.has(j.id)) err(`여정 id 중복: ${j.id}`); ids.add(j.id);
-    if (!j.steps?.length) err(`여정에 장면 없음: ${j.id}`);
+    const js = subj('journey', j.id);
+    if (ids.has(j.id)) err('journey.duplicate-id', `여정 id 중복: ${j.id}`, js); ids.add(j.id);
+    if (!j.steps?.length) err('journey.no-steps', `여정에 장면 없음: ${j.id}`, js);
     const stepIds = new Set();
     for (const s of j.steps) {
-      if (stepIds.has(s.id)) err(`${j.title}: 장면 id 중복 ${s.id}`); stepIds.add(s.id);
-      if (!s.intent && s.status !== 'next') warn(`${j.title} › ${s.label}: intent 비어 있음`);
-      for (const w of s.warnings) (/라우트 없음|참조 미해결|장면은 동작인데|관측 근거 없음/.test(w) ? err : warn)(`${j.title} › ${s.label}: ${w}`);
-      if (!['live', 'mock', 'planned', 'next'].includes(s.status)) err(`${j.title} › ${s.label}: 알 수 없는 상태 ${s.status}`);
-      if (s.status === 'planned' && (s.screens || []).length) warn(`${j.title} › ${s.label}: planned 인데 화면이 있음(mock 이 맞는지 확인)`);
-      if (s.capture && !s.captureFile) warn(`${j.title} › ${s.label}: 캡처 파일 없음 ${s.capture}`);
+      const ss = subj('step', `${j.id}/${s.id}`);
+      if (stepIds.has(s.id)) err('step.duplicate-id', `${j.title}: 장면 id 중복 ${s.id}`, js); stepIds.add(s.id);
+      if (!s.intent && s.status !== 'next') warn('step.intent-empty', `${j.title} › ${s.label}: intent 비어 있음`, ss);
+      for (const w of s.warnings) (/라우트 없음|참조 미해결|장면은 동작인데|관측 근거 없음/.test(w) ? err : warn)(pick(STEP_WARNING, w, 'step.warning'), `${j.title} › ${s.label}: ${w}`, ss);
+      if (!['live', 'mock', 'planned', 'next'].includes(s.status)) err('step.unknown-status', `${j.title} › ${s.label}: 알 수 없는 상태 ${s.status}`, ss);
+      if (s.status === 'planned' && (s.screens || []).length) warn('step.planned-has-screen', `${j.title} › ${s.label}: planned 인데 화면이 있음(mock 이 맞는지 확인)`, ss);
+      if (s.capture && !s.captureFile) warn('step.capture-missing', `${j.title} › ${s.label}: 캡처 파일 없음 ${s.capture}`, ss);
     }
   }
   // 로드맵: 가리키는 장면·작업·선행 항목이 없거나 상태 어휘가 틀리면 오류. 진행 중인데 작업 폴더가 없으면 경고.
   const mids = new Set();
   for (const m of d.roadmap || []) {
-    if (mids.has(m.id)) err(`로드맵 id 중복: ${m.id}`); mids.add(m.id);
-    for (const p of m.problems) err(`로드맵 ${m.title}: ${p}`);
-    if (m.status === '진행' && !m.tasks.length) warn(`로드맵 ${m.title}: 진행인데 작업 폴더가 없음`);
+    const ms = subj('milestone', m.id);
+    if (mids.has(m.id)) err('roadmap.duplicate-id', `로드맵 id 중복: ${m.id}`, ms); mids.add(m.id);
+    for (const p of m.problems) err(pick(ROADMAP_PROBLEM, p, 'roadmap.problem'), `로드맵 ${m.title}: ${p}`, ms);
+    if (m.status === '진행' && !m.tasks.length) warn('roadmap.running-no-task', `로드맵 ${m.title}: 진행인데 작업 폴더가 없음`, ms);
   }
   // 마일스톤: 문장은 derive가 만든다. 마일스톤 절이 없으면 줄이 없다
-  for (const m of d.milestones || []) { for (const p of m.problems) err(p); for (const w of m.warnings) warn(w); }
+  for (const m of d.milestones || []) {
+    const rs = subj('release', m.id);
+    for (const p of m.problems) err(pick(MILESTONE_PROBLEM, p, 'milestone.problem'), p, rs);
+    for (const w of m.warnings) warn(pick(MILESTONE_WARNING, w, 'milestone.warning'), w, rs);
+  }
   const running = (d.milestones || []).filter((m) => m.status === '진행');
-  if (running.length > 1) warn(`진행 마일스톤 ${running.length}개: ${running.map((m) => m.title).join(', ')}`);
+  if (running.length > 1) warn('milestone.multiple-running', `진행 마일스톤 ${running.length}개: ${running.map((m) => m.title).join(', ')}`);
   for (const m of d.roadmap || []) {
     if (m.status !== '진행') continue;
-    if ((d.milestones || []).length && !m.milestone) warn(`로드맵 ${m.title}: 진행인데 마일스톤 없음`);
+    const ms = subj('milestone', m.id);
+    if ((d.milestones || []).length && !m.milestone) warn('roadmap.running-no-milestone', `로드맵 ${m.title}: 진행인데 마일스톤 없음`, ms);
     const open = (m.deps || []).filter((x) => x.status !== '완료');
-    if (open.length) warn(`로드맵 ${m.title}: 진행인데 선행 미완 ${open.map((x) => x.title).join(', ')}`);
+    if (open.length) warn('roadmap.running-open-deps', `로드맵 ${m.title}: 진행인데 선행 미완 ${open.map((x) => x.title).join(', ')}`, ms);
   }
   // 배우 사전: 여정 배우, 여정과 다른 단계 배우가 사전 키에 없으면 경고(사전이 없는 프로젝트는 건너뜀)
   const actors = d.semantic.actors || {};
   if (Object.keys(actors).length) for (const j of d.semantic.journeys) {
-    if (j.actor && !(j.actor in actors)) warn(`${j.title}: 배우 사전에 없는 값 ${j.actor}`);
-    for (const s of j.steps) if (s.actor && s.actor !== j.actor && !(s.actor in actors)) warn(`${j.title} › ${s.label}: 배우 사전에 없는 값 ${s.actor}`);
+    if (j.actor && !(j.actor in actors)) warn('journey.actor-unknown', `${j.title}: 배우 사전에 없는 값 ${j.actor}`, subj('journey', j.id));
+    for (const s of j.steps) if (s.actor && s.actor !== j.actor && !(s.actor in actors)) warn('journey.actor-unknown', `${j.title} › ${s.label}: 배우 사전에 없는 값 ${s.actor}`, subj('step', `${j.id}/${s.id}`));
+  }
+  if (d.orphans.screens.length) warn('orphan.screens', `여정에 없는 화면 ${d.orphans.screens.length}: ${d.orphans.screens.join(', ')}`);
+  if (d.orphans.apis.length) warn('orphan.apis', `어느 화면도 부르지 않는 API ${d.orphans.apis.length}: ${d.orphans.apis.join(', ')}`);
+  if (d.orphans.tests.length) warn('orphan.tests', `라우트·API에 붙지 않는 검사 ${d.orphans.tests.length}: ${d.orphans.tests.join(', ')}`);
+  if (d.deploy && d.deploy.behind === null) warn('deploy.behind-unknown', '배포 sha가 main 이력에 없어 뒤처짐을 계산하지 못함', subj('deploy', 'homelab'));
+  // 어댑터가 g.issue로 낸 문제: 기존 검사 뒤에 그대로 싣는다. error는 종료 코드 1에 센다. 코드 없이 낸 문제는 adapter.issue
+  for (const i of d.issues || []) {
+    const p = problem(i.level, i.code || 'adapter.issue', `${i.label}: ${i.message}`, { subject: i.subject ?? null, anchors: i.anchors || [], resolutions: i.resolutions || [] });
+    if (i.judgmentDraft) p.judgmentDraft = i.judgmentDraft;
+    out.push(p);
   }
-  if (d.orphans.screens.length) warn(`여정에 없는 화면 ${d.orphans.screens.length}: ${d.orphans.screens.join(', ')}`);
-  if (d.orphans.apis.length) warn(`어느 화면도 부르지 않는 API ${d.orphans.apis.length}: ${d.orphans.apis.join(', ')}`);
-  if (d.orphans.tests.length) warn(`라우트·API에 붙지 않는 검사 ${d.orphans.tests.length}: ${d.orphans.tests.join(', ')}`);
-  if (d.deploy && d.deploy.behind === null) warn('배포 sha가 main 이력에 없어 뒤처짐을 계산하지 못함');
-  // 어댑터가 g.issue로 낸 문제: 기존 검사 뒤에 그대로 싣는다. error는 종료 코드 1에 센다.
-  for (const i of d.issues || []) (i.level === 'error' ? err : warn)(`${i.label}: ${i.message}`);
   return out;
 }
+
+// 1.1.1 모양({ level, msg })의 문제 목록. 텍스트 출력과 기존 호출자가 쓴다
+export function check(d, cfg) {
+  return checkProblems(d, cfg).map(({ level, msg }) => ({ level, msg }));
+}
+
+// check --staged: 커밋 전 훅이 쓰는 고르기. 대상은 스테이징된 tasks.dir 안 작업 폴더 파일·장부(tasks.index)와 map/judgments/*.json이다.
+// 대상 파일에 걸린 tasks.*·judgment.* 문제만 오류로 센다. 걸림은 문제 대상(작업·장부·판정 파일)이 스테이징된 작업 폴더·판정 파일이거나
+// 근거 줄이 스테이징된 대상 파일에 있는 것이다. 대상이 단계(여정 refs)인 문제는 고칠 곳이 여정 파일이라 세지 않는다.
+const STAGED_PREFIXES = ['tasks.', 'judgment.'];
+const STAGED_SUBJECTS = ['task', 'ledger', 'judgment'];
+const JUDGMENT_FILE = /^map\/judgments\/([^/]+)\.json$/;
+const taskFolderOf = (path, dir) => { if (!dir || !path.startsWith(`${dir}/`)) return null; const m = path.slice(dir.length + 1).match(/^(\d{8}-[^/]+)\//); return m ? m[1] : null; };
+
+export function stagedTargets(paths, cfg) {
+  const dir = cfg?.tasks?.dir ? cfg.tasks.dir.replace(/^\.\//, '').replace(/\/+$/, '') : null;
+  const index = cfg?.tasks?.index ? cfg.tasks.index.replace(/^\.\//, '') : null;
+  return paths.filter((p) => taskFolderOf(p, dir) || (index && p === index) || JUDGMENT_FILE.test(p));
+}
+
+export function stagedProblems(problems, paths, cfg) {
+  const targets = stagedTargets(paths, cfg);
+  const dir = cfg?.tasks?.dir ? cfg.tasks.dir.replace(/^\.\//, '').replace(/\/+$/, '') : null;
+  const files = new Set(targets);
+  const folders = new Set(targets.map((p) => taskFolderOf(p, dir)).filter(Boolean));
+  const judged = new Set(targets.map((p) => p.match(JUDGMENT_FILE)?.[1]).filter(Boolean));
+  return problems.filter((p) => STAGED_PREFIXES.some((x) => p.code.startsWith(x)) && STAGED_SUBJECTS.includes(p.subject?.kind) && (
+    p.anchors.some((a) => files.has(a.file))
+    || (p.subject.kind === 'task' && folders.has(p.subject.id))
+    || (p.subject.kind === 'judgment' && (judged.has(p.subject.id) || folders.has(p.subject.id)))
+  )).map((p) => ({ ...p, level: 'error' }));
+}
+
+// 훅 출력: 문제마다 코드·문구, 처리, 근거 줄, 판정 초안. 받은 에이전트 세션이 판정 파일을 쓰거나 원문을 고친다
+export function stagedText(problems) {
+  const lines = [];
+  for (const p of problems) {
+    lines.push(`✗ ${p.code} ${p.msg}`);
+    if (p.resolutions.length) lines.push(`  처리: ${p.resolutions.join('·')}`);
+    for (const a of p.anchors) lines.push(`  근거: ${a.file}${a.line ? `:${a.line}` : ''}${a.excerpt ? ` ${a.excerpt}` : ''}`);
+    if (p.judgmentDraft) lines.push(`  판정 초안(judgmentDraft): ${JSON.stringify(p.judgmentDraft)}`);
+  }
+  return lines;
+}

package/src/cli.mjs

@@ -1,10 +1,13 @@
 // 프로젝트 상황판 CLI. 의존성 없음(Node 22). 명령 진입은 bin/livemap.mjs가 main(argv)를 부른다.
 //   livemap build   [--root .] [--out map/.out]       저장소 스캔 → graph.json·data.json·overview.json
-//   livemap check   [--root .]                         검증(바닥값·라우트 존재·상태 모순·참조 미해결·어댑터 실패) → exit 1이면 실패
+//   livemap check   [--root .] [--json] [--strict]     검증(바닥값·라우트 존재·상태 모순·참조 미해결·어댑터 실패) → exit 1이면 실패
+//                                                      --json은 stdout에 이슈 계약 JSON만, --strict는 tasks.*·judgment.* 경고도 오류로 센다
+//                  [--staged]                          커밋 전 훅: 스테이징된 작업 문서·판정 파일에 걸린 tasks.*·judgment.*만 오류로 센다(git 없음·대상 없음 0)
 //   livemap serve   [--port 4180] [--static <dir>]     loopback 서빙. 기본은 요청마다 재빌드(5초 캐시), --static은 export 폴더를 그대로 준다
 //   livemap export  <dir> [--out map/.out]             화면·서체·캡처·생성물을 /map/ 주소 배치 그대로 한 폴더에 모은다
-//   livemap init                                       없는 파일만 템플릿으로 만들고 .gitignore·npm 스크립트를 넣는다
-//   livemap test-report                                단위 검사를 JUnit으로 남긴다(config.tests.dir → config.tests.report)
+//   livemap init                                       없는 파일만 템플릿으로 만들고 .gitignore·npm 스크립트·커밋 전 훅(.githooks/pre-commit)을 넣는다
+//   livemap test-report [--import <파일> [--sha <커밋>]]  단위 검사를 JUnit과 결과 JSON(config.tests.report 폴더의 test-results.json)으로 남긴다.
+//                                                      --import는 러너를 돌리지 않고 livemap 리포터·Playwright JSON·JUnit 출력을 결과 JSON에 넣는다
 //   livemap --version
 import { mkdirSync, writeFileSync, existsSync, readFileSync } from 'node:fs';
 import { resolve, dirname, join } from 'node:path';
@@ -12,7 +15,10 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { Graph, runAdapter } from './lib/graph.mjs';
 import { makeFs } from './lib/util.mjs';
 import { derive, overviewSlice } from './derive.mjs';
-import { check } from './check.mjs';
+import { execFileSync } from 'node:child_process';
+import { checkProblems, stagedTargets, stagedProblems, stagedText } from './check.mjs';
+import { linkScreenApis } from './link.mjs';
+import { applyStrict, problemsJson, sortProblems, textLines } from './lib/issues.mjs';
 
 const here = dirname(fileURLToPath(import.meta.url));
 export const PKG_ROOT = resolve(here, '..');
@@ -50,7 +56,10 @@ export async function buildGraph(root = process.cwd()) {
     if (loaded.shadowed) shadowed.push(name);
     runAdapter(g, name, (g) => loaded.fn(g, fs, cfg));
   }
-  const sem = fs.has(cfg.semantic) ? JSON.parse(fs.read(cfg.semantic)) : { journeys: [] };
+  // 연결 단계: 모든 어댑터 뒤에 화면 리터럴을 API 노드에 잇는다. adapters[]에 들지 않고, 실패하면 오류 이슈로 남긴다
+  try { linkScreenApis(g, fs, cfg); } catch (e) { g.issue('error', '연결 단계', String(e?.message || e)); }
+  // 설정에 semantic 키가 없으면 여정 입력이 없는 것으로 본다(없는 키는 뺀다)
+  const sem = cfg.semantic && fs.has(cfg.semantic) ? JSON.parse(fs.read(cfg.semantic)) : { journeys: [] };
   const captureExists = (id) => (id && fs.has(`${capturesDir(cfg)}/${id}.jpg`) ? `${id}.jpg` : null);
   const data = derive(g, sem, cfg, { captureExists });
   return { g, cfg, sem, data, fs, shadowed };
@@ -76,11 +85,13 @@ export function engineMismatch(cfg) {
 
 const USAGE = `usage: livemap <command>
   build        [--root .] [--out map/.out]    저장소 스캔 → graph.json · data.json · overview.json
-  check        [--root .]                     정합 검사, 오류가 있으면 exit 1
+  check        [--root .] [--json] [--strict] 정합 검사, 오류가 있으면 exit 1(--json: 이슈 JSON만)
+  check --staged                              커밋 전 훅: 스테이징된 작업 문서·판정 파일의 문제만 오류로
   serve        [--port 4180] [--static <dir>] 로컬 뷰 http://127.0.0.1:<port>/map/
   export <dir> [--out map/.out]               화면·서체·캡처·생성물을 한 폴더에(먼저 build)
-  init                                        map/ 초안 파일·.gitignore·npm 스크립트
-  test-report                                 단위 검사를 JUnit 리포트로
+  init                                        map/ 초안 파일·.gitignore·npm 스크립트·커밋 전 훅
+  test-report                                 단위 검사를 JUnit 리포트와 결과 JSON으로
+  test-report --import <파일> [--sha <커밋>]  Playwright JSON·JUnit·livemap 리포터 출력을 결과 JSON에
   --version                                   엔진 버전`;
 
 function readConfig(root) {
@@ -91,6 +102,37 @@ function readConfig(root) {
 }
 
 // 명령을 실행하고 종료 코드를 돌려준다. serve는 서버를 띄우고 undefined를 돌려준다(프로세스가 계속 산다).
+// check --staged: 스테이징 목록(git diff --cached, 내용은 작업트리 기준)에 작업 문서·판정 파일이 없으면 빌드하지 않고 0
+const STAGED_FAIL = '원문을 식별자 줄 규칙대로 고치거나 map/judgments/<작업 폴더>.json에 판정을 적어 스테이징하고 다시 커밋한다. --no-verify로 넘기지 않는다';
+async function checkStaged(root, cfg, json) {
+  let paths;
+  try {
+    const out = execFileSync('git', ['-C', root, 'diff', '--cached', '--name-only', '--relative', '--no-renames', '-z'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    paths = out.split('\0').filter(Boolean);
+  } catch {
+    if (json) process.stdout.write(JSON.stringify(problemsJson([], VERSION), null, 2) + '\n');
+    else console.log('map check --staged: git 저장소 아님, 건너뜀');
+    return 0;
+  }
+  const targets = stagedTargets(paths, cfg);
+  if (!targets.length) {
+    if (json) process.stdout.write(JSON.stringify(problemsJson([], VERSION), null, 2) + '\n');
+    else console.log('map check --staged: 대상 없음');
+    return 0;
+  }
+  // 빌드 중 어댑터가 찍는 줄은 훅 출력에 섞지 않는다
+  const log = console.log;
+  console.log = (...a) => console.error(...a);
+  let built;
+  try { built = await buildGraph(root); } finally { console.log = log; }
+  const problems = sortProblems(stagedProblems(checkProblems(built.data, built.cfg), paths, built.cfg));
+  if (json) { process.stdout.write(JSON.stringify(problemsJson(problems, VERSION), null, 2) + '\n'); return problems.length ? 1 : 0; }
+  if (!problems.length) { console.log(`map check --staged: 통과 (대상 파일 ${targets.length})`); return 0; }
+  for (const line of stagedText(problems)) console.log(line);
+  console.log(`map check --staged: 오류 ${problems.length} (스테이징된 작업 문서·판정 파일의 tasks.*·judgment.* 문제). ${STAGED_FAIL}`);
+  return 1;
+}
+
 export async function main(argv = []) {
   const cmd = argv[0] || 'build';
   const opt = (k, d) => { const i = argv.indexOf(`--${k}`); return i >= 0 ? argv[i + 1] : d; };
@@ -121,12 +163,24 @@ export async function main(argv = []) {
     for (const a of bad) console.log(`  ${a.status === 'failed' ? '✗' : '△'} ${a.name}: ${a.error}`);
     return 0;
   }
+  if (cmd === 'check' && argv.includes('--staged')) return checkStaged(root, cfg, argv.includes('--json'));
   if (cmd === 'check') {
-    const { data, cfg: c, shadowed } = await buildGraph(root);
-    notifyShadow(shadowed);
-    const problems = check(data, c);
-    for (const p of problems) console.log(`${p.level === 'error' ? '✗' : '△'} ${p.msg}`);
+    const json = argv.includes('--json');
+    // --json: stdout에는 JSON만. 빌드 중 어댑터가 찍는 줄과 가림 알림은 stderr로 보낸다
+    const log = console.log;
+    if (json) console.log = (...a) => console.error(...a);
+    let built;
+    try { built = await buildGraph(root); } finally { console.log = log; }
+    const { data, cfg: c, shadowed } = built;
+    if (json) for (const n of shadowed) console.error(`프로젝트 어댑터가 참조 어댑터를 가림: ${n}`);
+    else notifyShadow(shadowed);
+    const problems = applyStrict(checkProblems(data, c), argv.includes('--strict'));
     const errors = problems.filter((p) => p.level === 'error').length;
+    if (json) {
+      process.stdout.write(JSON.stringify(problemsJson(problems, VERSION), null, 2) + '\n');
+      return errors ? 1 : 0;
+    }
+    for (const line of textLines(problems)) console.log(line);
     console.log(errors ? `map check: 오류 ${errors}` : `map check: 통과 (경고 ${problems.length})`);
     return errors ? 1 : 0;
   }
@@ -149,7 +203,8 @@ export async function main(argv = []) {
     return exportSite({ root, out, captures: resolve(root, capturesDir(cfg)), target: resolve(process.cwd(), target) });
   }
   if (cmd === 'test-report') {
-    const { testReport } = await import('./test-report.mjs');
+    const { testReport, importReport } = await import('./test-report.mjs');
+    if (argv.includes('--import')) return importReport({ root, cfg, file: opt('import'), sha: opt('sha') });
     return testReport({ root, cfg });
   }
   return 2;