@pghoya2956/livemap 1.1.0 → 1.2.0

package/src/lib/judgments.mjs

@@ -0,0 +1,128 @@
+// 판정 파일: 에이전트 세션이 과거 작업 문서의 뜻을 판정해 적는 map/judgments/<작업 폴더>.json을 읽고 원문과 대조한다.
+// 엔진은 읽기만 한다(원문과 판정 파일을 고치지 않고 LLM·네트워크를 부르지 않는다). 줄 번호는 근거로 쓰지 않는다.
+//
+// 필드: schema 1, task(파일 이름과 같은 작업 폴더), by agent·human, planFile(작업 폴더 기준 md), lines[{ at, as definition·ignore, id }],
+//       questions.none { at } 또는 questions.items[{ id, state open·resolved, at }], note. 그 밖의 키는 무시한다(체크 여부·장부 상태·단계는 판정 대상이 아니다).
+// 근거 조각 at { file 프로젝트 기준 경로, text 한 줄 안의 20 코드 포인트 이상 조각 }:
+//   조각을 가진 줄이 하나면 확인(ok), 0개면 stale(원문이 바뀜), 둘 이상이면 invalid. 정의·질문 판정은 그 줄에 id가 있어야 한다.
+// 파일 모양이 틀리면(JSON·스키마·폴더·planFile) 파일 전체를 적용하지 않고, 근거 조각이 틀린 항목은 그 항목만 적용하지 않는다.
+export const JUDGMENTS_DIR = 'map/judgments';
+export const TEXT_MIN = 20;
+const BY = ['agent', 'human'];
+const AS = ['definition', 'ignore'];
+const STATES = ['open', 'resolved'];
+const LABEL = '판정 파일';
+
+const isObj = (x) => x !== null && typeof x === 'object' && !Array.isArray(x);
+const nonEmpty = (s) => typeof s === 'string' && s.trim().length > 0;
+// 프로젝트 안 상대 경로만 받는다
+const safeRel = (p) => nonEmpty(p) && !p.startsWith('/') && !/^[A-Za-z]:/.test(p) && !p.split(/[\\/]/).includes('..');
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+// 줄에 번호가 따로 있는지: 앞뒤가 영숫자(앞은 하이픈 포함)가 아니다. DEC-1은 DEC-12에 맞지 않는다
+export const hasId = (line, id) => new RegExp(`(^|[^A-Za-z0-9-])${escapeRe(id)}(?![A-Za-z0-9])`).test(line);
+
+// 근거 조각 대조: { state: 'ok'|'stale'|'invalid', file, line?, lines?, reason? }
+export function locate(fs, at, id, linesOf) {
+  if (!isObj(at) || !safeRel(at.file) || typeof at.text !== 'string') return { state: 'invalid', file: isObj(at) && typeof at.file === 'string' ? at.file : null, reason: '근거 조각 at은 { file: 프로젝트 기준 경로, text: 문자열 }' };
+  const { file, text } = at;
+  if (/[\r\n]/.test(text)) return { state: 'invalid', file, reason: `근거 조각이 여러 줄: ${file}` };
+  if ([...text].length < TEXT_MIN) return { state: 'invalid', file, reason: `근거 조각이 ${TEXT_MIN}자 미만: ${file}` };
+  if (!fs.has(file) || fs.isDir(file)) return { state: 'invalid', file, reason: `근거 파일 없음: ${file}` };
+  const lines = linesOf(file);
+  const hits = [];
+  lines.forEach((l, i) => { if (l.includes(text)) hits.push(i + 1); });
+  if (!hits.length) return { state: 'stale', file, reason: `근거 조각을 가진 줄이 원문에 없음: ${file}` };
+  if (hits.length > 1) return { state: 'invalid', file, lines: hits, reason: `근거 조각을 가진 줄이 ${hits.length}개: ${file}` };
+  if (id != null && !hasId(lines[hits[0] - 1], id)) return { state: 'invalid', file, lines: hits, reason: `근거 줄에 번호 ${id} 없음: ${file}:${hits[0]}` };
+  return { state: 'ok', file, line: hits[0] };
+}
+
+// 파일 모양 검사: 문제 문장 목록
+function shapeProblems(j, stem) {
+  const out = [];
+  if (j.schema !== 1) out.push('schema는 1');
+  if (j.task !== stem) out.push(`task는 파일 이름과 같은 작업 폴더 이름(${stem})`);
+  if (!BY.includes(j.by)) out.push(`by는 ${BY.join('·')}`);
+  if (j.planFile != null && !(safeRel(j.planFile) && j.planFile.endsWith('.md'))) out.push('planFile은 작업 폴더 기준 md 경로');
+  if (j.note != null && typeof j.note !== 'string') out.push('note는 문장');
+  if (j.lines != null) {
+    if (!Array.isArray(j.lines)) out.push('lines는 배열');
+    else j.lines.forEach((e, i) => {
+      if (!isObj(e)) { out.push(`lines[${i}]는 객체`); return; }
+      if (!AS.includes(e.as)) out.push(`lines[${i}].as는 ${AS.join('·')}`);
+      if (e.as === 'definition' && !nonEmpty(e.id)) out.push(`lines[${i}]: definition은 id 필수`);
+      if (e.id != null && !nonEmpty(e.id)) out.push(`lines[${i}].id는 문자열`);
+    });
+  }
+  if (j.questions != null) {
+    const q = j.questions;
+    if (!isObj(q)) out.push('questions는 객체');
+    else {
+      if (q.none != null && q.items != null) out.push('questions.none과 questions.items는 함께 쓰지 않는다');
+      if (q.none != null && !isObj(q.none)) out.push('questions.none은 { at }');
+      if (q.items != null) {
+        if (!Array.isArray(q.items)) out.push('questions.items는 배열');
+        else q.items.forEach((e, i) => {
+          if (!isObj(e)) { out.push(`questions.items[${i}]는 객체`); return; }
+          if (!nonEmpty(e.id)) out.push(`questions.items[${i}].id는 원문 표기 문자열`);
+          if (!STATES.includes(e.state)) out.push(`questions.items[${i}].state는 ${STATES.join('·')}`);
+        });
+      }
+    }
+  }
+  return out;
+}
+
+// 판정 파일을 모두 읽는다. taskNames: 작업 폴더 이름 집합, tasksDir: 설정 tasks.dir.
+// 돌려주는 값: { byTask: Map(작업 → 판정), issues: [[level, code, message, detail]] }
+//   판정 { file, task, by, note, planFile, lines[{ as, id, at, loc }], none { at, loc }|null, items[{ id, state, at, loc }], counts { applied, stale, invalid } }
+export function readJudgments(fs, taskNames, tasksDir) {
+  const byTask = new Map();
+  const issues = [];
+  if (!fs.isDir(JUDGMENTS_DIR)) return { byTask, issues };
+  const cache = new Map();
+  const linesOf = (rel) => { if (!cache.has(rel)) cache.set(rel, fs.read(rel).split(/\r?\n/)); return cache.get(rel); };
+  const excerpt = (file, line) => (linesOf(file)[line - 1] ?? '').trim();
+  for (const name of fs.ls(JUDGMENTS_DIR).filter((n) => n.endsWith('.json')).sort()) {
+    const file = `${JUDGMENTS_DIR}/${name}`;
+    if (fs.isDir(file)) continue;
+    const stem = name.slice(0, -'.json'.length);
+    const subject = { kind: 'judgment', id: stem };
+    const self = { file, line: null };
+    const invalid = (message, anchors = []) => issues.push(['error', 'judgment.invalid', message, { subject, anchors: [self, ...anchors] }]);
+    let j;
+    try { j = JSON.parse(fs.read(file)); } catch (e) { invalid(`JSON으로 읽지 못함(${e.message}): ${file}`); continue; }
+    if (!isObj(j)) { invalid(`판정 파일은 JSON 객체: ${file}`); continue; }
+    const shape = shapeProblems(j, stem);
+    if (shape.length) { for (const s of shape) invalid(`스키마 위반(${s}): ${file}`); continue; }
+    if (!taskNames.has(stem)) { invalid(`판정 대상 작업 폴더 없음: ${tasksDir}/${stem}`); continue; }
+    const base = `${tasksDir}/${stem}`;
+    if (j.planFile != null && (!fs.has(`${base}/${j.planFile}`) || fs.isDir(`${base}/${j.planFile}`))) { invalid(`planFile 없음: ${base}/${j.planFile}`); continue; }
+
+    const counts = { applied: j.planFile != null ? 1 : 0, stale: 0, invalid: 0 };
+    // 근거 조각 대조와 항목별 이슈. draftOf: stale 초안에 실을 판정 항목 모양(at: null)
+    const check = (at, id, draftOf) => {
+      const loc = locate(fs, at, id, linesOf);
+      if (loc.state === 'ok') counts.applied += 1;
+      else if (loc.state === 'invalid') {
+        counts.invalid += 1;
+        const anchors = loc.lines ? loc.lines.map((l) => ({ file: loc.file, line: l, excerpt: excerpt(loc.file, l) })) : loc.file && fs.has(loc.file) && !fs.isDir(loc.file) ? [{ file: loc.file, line: null }] : [];
+        invalid(loc.reason, anchors);
+      } else {
+        counts.stale += 1;
+        // 사라진 조각의 판정이 id를 가지면 같은 파일에서 그 id를 가진 줄이 후보
+        loc.candidates = id != null ? linesOf(loc.file).map((l, i) => [l, i + 1]).filter(([l]) => hasId(l, id)).map(([, n]) => ({ file: loc.file, line: n, excerpt: excerpt(loc.file, n) })) : [];
+        issues.push(['warn', 'judgment.stale', loc.reason, { subject, anchors: [self, { file: loc.file, line: null }], judgmentDraft: { task: stem, ...draftOf, candidates: loc.candidates } }]);
+      }
+      return loc;
+    };
+    const lines = (j.lines || []).map((e) => ({ as: e.as, id: e.id ?? null, at: e.at, loc: check(e.at, e.as === 'definition' ? e.id : null, { lines: [{ at: null, as: e.as, id: e.id ?? null }] }) }));
+    const q = j.questions || {};
+    const none = q.none != null ? { at: q.none.at, loc: check(q.none.at, null, { questions: { none: { at: null } } }) } : null;
+    const items = (q.items || []).map((e) => ({ id: e.id, state: e.state, at: e.at, loc: check(e.at, e.id, { questions: { items: [{ id: e.id, state: e.state, at: null }] } }) }));
+    byTask.set(stem, { file, task: stem, by: j.by, note: j.note ?? null, planFile: j.planFile ?? null, lines, none, items, counts });
+  }
+  return { byTask, issues };
+}
+
+export const JUDGMENT_LABEL = LABEL;

package/src/lib/literals.mjs

@@ -0,0 +1,103 @@
+// 경로 리터럴: 글자에서 따옴표·백틱 바로 뒤가 /api/인 문자열을 뽑아 정규화하고 API 노드 경로에 대응한다.
+// 접두어는 참조 bff 어댑터와 같이 고정이다. 따옴표 없이 주석에 쓴 경로와 변수로 조립한 경로는 잡히지 않는다.
+//   정규화: ? 뒤를 자른다. 경로 조각 전체가 ${…}면 :param. 조각 중간에서 ${…}가 시작하면 앞 글자까지 남기고 열린 끝(open)
+//   대응:   조각 수가 같고 각 조각이 같거나 한쪽이 :이름이면 맞다. 열린 끝은 앞부분이 맞으면 맞다(마지막 조각은 앞 글자 일치)
+export const API_PREFIX = '/api/';
+const QUOTES = new Set(["'", '"', '`']);
+
+// 템플릿 리터럴 본문을 조각으로 나눈다: 글자는 문자열, ${…}는 { expr } (중첩 괄호·안쪽 문자열을 건너뛴다)
+function templateParts(raw) {
+  const parts = [];
+  let text = '';
+  for (let i = 0; i < raw.length; i += 1) {
+    if (raw[i] === '\\') { text += raw.slice(i, i + 2); i += 1; continue; }
+    if (raw[i] === '$' && raw[i + 1] === '{') {
+      let depth = 1, j = i + 2, quote = null;
+      for (; j < raw.length && depth > 0; j += 1) {
+        const ch = raw[j];
+        if (quote) { if (ch === '\\') j += 1; else if (ch === quote) quote = null; continue; }
+        if (QUOTES.has(ch)) quote = ch;
+        else if (ch === '{') depth += 1;
+        else if (ch === '}') depth -= 1;
+      }
+      if (text) parts.push(text);
+      parts.push({ expr: raw.slice(i + 2, j - 1) });
+      text = '';
+      i = j - 1;
+      continue;
+    }
+    text += raw[i];
+  }
+  if (text) parts.push(text);
+  return parts;
+}
+
+// 따옴표 안 글자(따옴표 제외) → { path, open? }. 백틱이 아니면 ${를 글자로 본다
+export function normalizeApiLiteral(raw, template = true) {
+  const parts = template ? templateParts(raw) : [raw];
+  const segs = [];
+  let cur = [], open = false;
+  const flush = () => { segs.push(cur); cur = []; };
+  outer: for (const p of parts) {
+    if (typeof p !== 'string') { cur.push(p); continue; }
+    for (const ch of p) {
+      if (ch === '?' || ch === '#') break outer;
+      if (ch === '/') flush(); else cur.push(ch);
+    }
+  }
+  flush();
+  // segs[0]은 첫 / 앞의 빈 조각
+  const out = [];
+  for (const seg of segs.slice(1)) {
+    const exprs = seg.filter((x) => typeof x !== 'string');
+    if (!exprs.length) { out.push(seg.join('')); continue; }
+    if (seg.length === 1) { out.push(':param'); continue; }
+    const at = seg.findIndex((x) => typeof x !== 'string');
+    out.push(seg.slice(0, at).join(''));
+    open = true;
+    break;
+  }
+  while (!open && out.length > 1 && out[out.length - 1] === '') out.pop();
+  const path = '/' + out.join('/');
+  return open ? { path, open: true } : { path };
+}
+
+// 글자에서 리터럴을 뽑는다: [{ path, open?, line }]. startLine은 text 첫 줄의 줄 번호
+export function extractApiLiterals(text, startLine = 1) {
+  const out = [];
+  let line = startLine;
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i];
+    if (ch === '\n') { line += 1; continue; }
+    if (!QUOTES.has(ch) || !text.startsWith(API_PREFIX, i + 1)) continue;
+    // 닫는 따옴표까지(백틱은 ${…} 안을 건너뛴다). 작은·큰따옴표는 줄을 넘지 않는다
+    let j = i + 1, depth = 0;
+    for (; j < text.length; j += 1) {
+      const c = text[j];
+      if (c === '\\') { j += 1; continue; }
+      if (ch === '`') {
+        if (c === '$' && text[j + 1] === '{') { depth += 1; j += 1; continue; }
+        if (depth > 0) { if (c === '{') depth += 1; else if (c === '}') depth -= 1; continue; }
+      } else if (c === '\n') break;
+      if (c === ch && depth === 0) break;
+    }
+    if (j >= text.length || text[j] !== ch) continue;
+    const raw = text.slice(i + 1, j);
+    out.push({ ...normalizeApiLiteral(raw, ch === '`'), line });
+    for (let k = i + 1; k < j; k += 1) if (text[k] === '\n') line += 1;
+    i = j;
+  }
+  return out;
+}
+
+// API 노드 id("METHOD /api/x" 또는 "/api/x")의 경로
+export const apiPathOf = (id) => String(id).replace(/^[A-Z]+\s+(?=\/)/, '');
+
+const segMatch = (a, b) => a === b || a.startsWith(':') || b.startsWith(':');
+export function matchesApi(lit, apiId) {
+  const a = lit.path.split('/'), b = apiPathOf(apiId).split('/');
+  if (!lit.open) return a.length === b.length && a.every((s, i) => segMatch(s, b[i]));
+  if (b.length < a.length) return false;
+  const last = a.length - 1;
+  return a.every((s, i) => (i < last ? segMatch(s, b[i]) : segMatch(s, b[i]) || b[i].startsWith(s)));
+}

package/src/lib/md-blocks.mjs

@@ -0,0 +1,113 @@
+// md 블록 읽개: 마크다운 파일 하나를 줄 번호와 함께 블록으로 나눈다. 뜻(결정·계획 항목·질문)은 정하지 않는다.
+// 블록 { type, line, path } — path는 감싼 제목 [{ level, text, line }](제목 블록은 자기 자신 포함)
+//   heading { level, text }
+//   item    { indent, marker, checkbox(' '|'x'|'X'|null), checked(true|false|null), text(체크박스 뒤 글자), head }
+//   row     { cells, header(바로 아래가 구분 행), table(파일 안 표 번호, 1부터), head(첫 칸 머리 번호) }
+//   text    { text } — 제목·목록·표가 아닌 빈 줄 아닌 줄
+// 백틱·물결 코드 펜스(앞 공백 셋까지, 닫는 펜스는 같은 글자·같거나 긴 길이) 안 줄과 표 구분 행은 블록을 만들지 않는다. CRLF를 받는다.
+// 머리 번호 head { id, bold, struck, rest }: 앞뒤 **·__를 벗기고 ~~ 취소선이면 struck. id 모양이 계획 항목인지 결정인지는 부르는 쪽이 정한다.
+//
+// 경계: 이 모듈은 줄 단위 블록까지만 만든다. 절 이름으로 역할을 정하거나(잔여 질문 절, 결정 절) 항목 속성(`키: 값`)을 해석하는
+// 2단 파서는 이 블록 위에 올린다(작업 어댑터의 식별자 줄 문법, 뒤의 md 속성 파서). 인라인 링크·강조 해석, 들여쓴 코드 블록,
+// HTML 블록, setext 제목은 다루지 않는다.
+
+const FENCE = /^ {0,3}(`{3,}|~{3,})(.*)$/;
+const HEADING = /^ {0,3}(#{1,6})[ \t]+(.*?)(?:[ \t]+#+)?[ \t]*$/;
+const EMPTY_HEADING = /^ {0,3}(#{1,6})[ \t]*$/;
+const ITEM = /^([ \t]*)([-*+]|\d{1,9}[.)])(?:[ \t]+(.*))?$/;
+const CHECKBOX = /^\[( |x|X)\](?:[ \t]+(.*)|)$/;
+const DELIM = /^\s*\|?\s*:?-+:?\s*(\|\s*:?-+:?\s*)*\|?\s*$/;
+const ID = /^[A-Z][A-Za-z0-9]*(?:-[A-Za-z0-9]+)+/;
+const WRAP = /^(\*\*|__|~~)/;
+
+const indentOf = (s) => [...s].reduce((n, ch) => n + (ch === '\t' ? 4 - (n % 4) : 1), 0);
+
+// 표 행 한 줄을 칸으로 나눈다. 앞뒤 파이프는 선택, 백슬래시로 이스케이프한 파이프는 칸 안 글자
+export function splitCells(line) {
+  let s = line.trim();
+  if (s.startsWith('|')) s = s.slice(1);
+  if (s.endsWith('|') && !s.endsWith('\\|')) s = s.slice(0, -1);
+  const cells = [];
+  let cur = '';
+  for (let i = 0; i < s.length; i += 1) {
+    if (s[i] === '\\' && s[i + 1] === '|') { cur += '|'; i += 1; }
+    else if (s[i] === '|') { cells.push(cur.trim()); cur = ''; }
+    else cur += s[i];
+  }
+  cells.push(cur.trim());
+  return cells;
+}
+
+// 글자 머리의 번호: 앞 **·__·~~를 벗기고 번호 모양 낱말을 찾는다. 번호 바로 뒤의 닫는 표시도 벗겨 rest에 남기지 않는다
+export function headId(text) {
+  let s = String(text ?? '').trimStart();
+  let bold = false, struck = false;
+  const opened = [];
+  for (let m = s.match(WRAP); m; m = s.match(WRAP)) {
+    if (m[1] === '~~') struck = true; else bold = true;
+    opened.push(m[1]);
+    s = s.slice(2);
+  }
+  const m = s.match(ID);
+  if (!m) return null;
+  let rest = s.slice(m[0].length);
+  // 여는 표시의 반대 순서로 닫는 표시를 지운다. 번호 바로 뒤에 없으면(**DEC-10 [확정]**: …) 뒤에서 처음 나오는 것 하나를 지운다
+  for (const w of opened.slice().reverse()) {
+    if (rest.startsWith(w)) rest = rest.slice(w.length);
+    else { const k = rest.indexOf(w); if (k >= 0) rest = rest.slice(0, k) + rest.slice(k + w.length); }
+  }
+  return { id: m[0], bold, struck, rest };
+}
+
+export function readBlocks(text) {
+  const lines = String(text ?? '').split(/\r?\n/);
+  const blocks = [];
+  let path = [];
+  let fence = null;
+  let table = 0, inTable = false, tableStart = 0;
+  for (let i = 0; i < lines.length; i += 1) {
+    const raw = lines[i];
+    const line = i + 1;
+    const f = raw.match(FENCE);
+    if (fence) {
+      if (f && f[1][0] === fence.ch && f[1].length >= fence.len && f[2].trim() === '') fence = null;
+      continue;
+    }
+    if (f && !(f[1][0] === '`' && f[2].includes('`'))) { fence = { ch: f[1][0], len: f[1].length }; inTable = false; continue; }
+    if (!raw.trim()) { inTable = false; continue; }
+
+    const h = raw.match(HEADING) || raw.match(EMPTY_HEADING);
+    if (h) {
+      const level = h[1].length;
+      const heading = { level, text: (h[2] ?? '').trim(), line };
+      path = [...path.filter((p) => p.level < level), heading];
+      blocks.push({ type: 'heading', line, level, text: heading.text, path });
+      inTable = false;
+      continue;
+    }
+    if (raw.trimStart().startsWith('|')) {
+      // 구분 행: 표 첫 행 바로 아래일 때만(그 행이 머리 행). 표 중간의 `| - | - |`는 대시 칸을 가진 행이다
+      if (DELIM.test(raw) && (!inTable || tableStart === line - 1)) {
+        const prev = blocks[blocks.length - 1];
+        if (inTable && prev?.type === 'row' && prev.line === line - 1) prev.header = true;
+        continue;
+      }
+      if (!inTable) { table += 1; inTable = true; tableStart = line; }
+      const cells = splitCells(raw);
+      blocks.push({ type: 'row', line, path, cells, header: false, table, head: headId(cells[0]) });
+      continue;
+    }
+    inTable = false;
+    const it = raw.match(ITEM);
+    if (it) {
+      const body = it[3] ?? '';
+      const cb = body.match(CHECKBOX);
+      const checkbox = cb ? cb[1] : null;
+      const itemText = cb ? (cb[2] ?? '') : body;
+      blocks.push({ type: 'item', line, path, indent: indentOf(it[1]), marker: it[2], checkbox, checked: checkbox === null ? null : checkbox !== ' ', text: itemText, head: headId(itemText) });
+      continue;
+    }
+    blocks.push({ type: 'text', line, path, text: raw.trim() });
+  }
+  return blocks;
+}

package/src/lib/reading.mjs

@@ -0,0 +1,55 @@
+// 읽기 상태: 수치마다 "어떻게 읽었나"를 싣는다. 못 읽은 값과 0을 가르고, 화면은 부분·낡음·모름을 "?"로 보인다.
+// 어댑터는 노드(g.add·g.get이 돌려준 것)에 setReading으로 필드별 상태를 적는다. 적지 않은 필드는 rule로 본다.
+//   props.reading      { 필드: 값 }
+//   props.readingNotes { 필드: 이유 문장 }  파일·줄이 들어갈 수 있어 개요 조각에는 싣지 않는다
+// 값: observed 생산자 구조화 출력·livemap 소유 형식, rule 규칙으로 읽고 후보 줄이 모두 읽힘, judged 판정 파일로 채움·고침,
+//     partial 안 읽힌 후보 줄·뜻 확인 필요, stale 판정 근거가 사라졌거나 검사 결과 뒤 코드 변경, unknown 소스 없음·형식 밖, none 셀 대상 없음
+export const READING_VALUES = ['observed', 'rule', 'judged', 'partial', 'stale', 'unknown', 'none'];
+const BAD = new Set(['partial', 'stale', 'unknown']);
+export const DEFAULT_READING = 'rule';
+
+export function setReading(node, field, value, note) {
+  if (!node || typeof node !== 'object' || !node.props) throw new Error('reading 대상은 그래프 노드');
+  if (typeof field !== 'string' || !field) throw new Error(`reading 필드는 빈 문자열이 아닌 이름: ${field}`);
+  if (!READING_VALUES.includes(value)) throw new Error(`reading 값은 ${READING_VALUES.join('·')}: ${value}`);
+  if (note !== undefined && typeof note !== 'string') throw new Error('reading 이유는 문자열');
+  node.props.reading = { ...(node.props.reading || {}), [field]: value };
+  const notes = { ...(node.props.readingNotes || {}) };
+  if (note) notes[field] = note; else delete notes[field];
+  node.props.readingNotes = notes;
+  return node;
+}
+
+// 노드(또는 props·파생 뷰처럼 reading을 가진 객체)의 필드 상태. 적지 않았으면 fallback
+export function readingOf(x, field, fallback = DEFAULT_READING) {
+  const r = x?.props ? x.props.reading : x?.reading;
+  return r?.[field] ?? fallback;
+}
+
+const norm = (v) => (READING_VALUES.includes(v) ? v : 'unknown');
+
+// 합계: none은 빼고, 하나라도 partial·stale·unknown이면 partial. 나머지는 judged > rule > observed 순으로 가장 약한 근거를 쓴다.
+// 구성 요소가 없으면 empty(기본 rule: 셀 대상이 없어 0을 규칙으로 읽은 것과 같다)
+export function combineReading(values, empty = DEFAULT_READING) {
+  const vs = values.map(norm).filter((v) => v !== 'none');
+  if (!vs.length) return empty;
+  if (vs.some((v) => BAD.has(v))) return 'partial';
+  if (vs.includes('judged')) return 'judged';
+  if (vs.includes('rule')) return 'rule';
+  return 'observed';
+}
+
+// 노드에 적힌 상태만 센다: values는 값별 건수(모든 값 키), fields는 '<종류>.<필드>'별 값 건수
+export function countReadings(nodes) {
+  const values = Object.fromEntries(READING_VALUES.map((v) => [v, 0]));
+  const fields = {};
+  for (const n of nodes) {
+    for (const [field, raw] of Object.entries(n.props?.reading || {})) {
+      const v = norm(raw);
+      values[v] += 1;
+      const f = (fields[`${n.kind}.${field}`] ||= {});
+      f[v] = (f[v] || 0) + 1;
+    }
+  }
+  return { values, fields };
+}

package/src/link.mjs

@@ -0,0 +1,76 @@
+// 연결 단계: 모든 어댑터가 끝난 뒤 화면 노드 apiLiterals를 API 노드에 대응해 calls 엣지와 matched를 채운다.
+// router는 bff보다 먼저 돌아 어댑터 안에서는 대응할 API 노드가 없다. 연결 단계는 adapters[]에 들지 않는다.
+//   router.unknown-api       리터럴 위치(파일·줄·경로)마다 한 건
+//   router.hookapi-redundant hookApi 키가 쓰인 화면의 연결이 모두 리터럴로도 나옴(쓰는 화면이 없는 키 포함), 키마다 한 건
+//   router.hookapi-only      hookApi 키로만 나오는 연결이 있음, 키마다 한 건
+// 화면 apis 읽기 상태: 모든 리터럴이 API 노드에 맞고 hookApi로만 붙은 연결이 없으면 rule, 아니면 partial.
+import { matchesApi } from './lib/literals.mjs';
+import { setReading } from './lib/reading.mjs';
+
+const CONFIG = 'map/config.json';
+const LIST_MAX = 3;
+const list = (xs) => xs.slice(0, LIST_MAX).join(', ') + (xs.length > LIST_MAX ? ` 외 ${xs.length - LIST_MAX}` : '');
+
+export function linkScreenApis(g, fs, cfg) {
+  const apis = g.of('api');
+  const screens = g.of('screen').filter((s) => s.props.apiLiterals !== undefined || s.props.hookApiKeys !== undefined);
+  const literalPairs = new Set();
+  const unknown = new Map(); // 파일:줄:경로 → { lit, screens }
+  const lineText = new Map();
+  const excerptOf = (file, line) => {
+    if (!lineText.has(file)) lineText.set(file, fs.has(file) ? fs.read(file).split('\n') : []);
+    return (lineText.get(file)[line - 1] ?? '').trim();
+  };
+
+  for (const s of screens) {
+    const lits = s.props.apiLiterals ?? [];
+    if (!Array.isArray(lits)) throw new Error(`화면 ${s.id}의 apiLiterals가 배열이 아님`);
+    for (const lit of lits) {
+      if (!lit || typeof lit.path !== 'string' || typeof lit.file !== 'string') throw new Error(`화면 ${s.id}의 apiLiterals 항목에 path·file 문자열이 없음`);
+      lit.matched = apis.filter((a) => matchesApi(lit, a.id)).map((a) => a.id);
+      for (const id of lit.matched) { g.link('screen', s.id, 'calls', 'api', id); literalPairs.add(`${s.id}\t${id}`); }
+      if (!lit.matched.length) {
+        const key = `${lit.file}:${lit.line}:${lit.path}${lit.open ? '…' : ''}`;
+        if (!unknown.has(key)) unknown.set(key, { lit, screens: [] });
+        unknown.get(key).screens.push(s.id);
+      }
+    }
+  }
+  for (const { lit, screens: ss } of unknown.values()) {
+    const shown = `${lit.path}${lit.open ? '…' : ''}`;
+    g.issue('warn', '화면→API', `${lit.file}:${lit.line} 리터럴 ${shown}에 맞는 API 노드 없음(화면 ${ss.length}: ${list(ss)})`, {
+      code: 'router.unknown-api',
+      subject: { kind: 'screen', id: ss[0] },
+      anchors: [{ file: lit.file, line: Number.isInteger(lit.line) && lit.line >= 1 ? lit.line : null, excerpt: excerptOf(lit.file, lit.line) }],
+    });
+  }
+
+  // hookApi 정리 경고: 키마다 그 키를 쓴 화면의 (화면, API) 연결이 리터럴로도 나왔는지 본다
+  const hookApi = cfg.router?.hookApi;
+  const hookOnly = new Map(); // 화면 → [API]
+  if (hookApi && typeof hookApi === 'object') {
+    const cfgText = fs.has(CONFIG) ? fs.read(CONFIG) : '';
+    for (const [key, api] of Object.entries(hookApi)) {
+      const users = screens.filter((s) => (s.props.hookApiKeys || []).includes(key)).map((s) => s.id);
+      const missing = users.filter((sid) => !literalPairs.has(`${sid}\t${api}`));
+      for (const sid of missing) hookOnly.set(sid, [...new Set([...(hookOnly.get(sid) || []), api])]);
+      const line = fs.lineOf(cfgText, `"${key}"`);
+      const detail = { subject: { kind: 'config', id: `router.hookApi.${key}` }, anchors: [{ file: CONFIG, line }] };
+      if (missing.length) {
+        g.issue('warn', 'hookApi', `${key}(${api}) 리터럴 없이 대응표로만 연결되는 화면 ${missing.length}: ${list(missing)}`, { code: 'router.hookapi-only', ...detail });
+      } else {
+        const why = users.length ? `리터럴로도 연결됨(화면 ${users.length})` : '쓰는 화면 없음';
+        g.issue('warn', 'hookApi', `${key}(${api}) ${why}, 설정에서 지워도 됨`, { code: 'router.hookapi-redundant', ...detail });
+      }
+    }
+  }
+
+  for (const s of screens) {
+    const bad = (s.props.apiLiterals || []).filter((l) => !l.matched.length).map((l) => `${l.path}${l.open ? '…' : ''}(${l.file}:${l.line})`);
+    const only = hookOnly.get(s.id) || [];
+    const notes = [];
+    if (bad.length) notes.push(`API 노드에 맞지 않는 리터럴 ${bad.length}: ${list(bad)}`);
+    if (only.length) notes.push(`hookApi로만 연결 ${only.length}: ${list(only)}`);
+    setReading(s, 'apis', notes.length ? 'partial' : 'rule', notes.length ? notes.join('; ') : undefined);
+  }
+}

package/src/reporters/node-results.mjs

@@ -0,0 +1,33 @@
+// Node 사용자 리포터(패키지 공개 경로): node --test의 test:pass·test:fail 이벤트를 파일별로 세어 결과 JSON 한 실행으로 낸다.
+//   node --test --test-reporter=@pghoya2956/livemap/src/reporters/node-results.mjs --test-reporter-destination=map/.out/node-results.json
+// Node v22.0.0 문서에 있는 이벤트 필드(file·details.type·skip·todo)만 쓴다. test:summary는 v22.0.0 문서에 없어 쓰지 않는다.
+// describe(details.type === 'suite')는 빼고, skip이 있으면 skipped, todo가 있으면 pending이다. 불러오기에 실패한 파일은
+// 파일 이름으로 test:fail 하나가 와서 실패 1이 된다. 루트는 러너의 작업 폴더이고, 루트 밖 파일은 빼고 그 수를 outsideRoot에 남긴다.
+// 러너 종료 코드는 리포터가 알 수 없어 exit는 null이다(livemap test-report가 채운다).
+import { emptyFile, gitStamp, RESULTS_SCHEMA, sortFiles, toRootPath } from '../results.mjs';
+
+const flag = (v) => v !== undefined && v !== null && v !== false;
+
+export default async function* nodeResults(source) {
+  const root = process.cwd();
+  const at = new Date().toISOString();
+  const { sha, dirtyPaths } = gitStamp(root);
+  const files = new Map();
+  const outside = new Set();
+  for await (const event of source) {
+    if (event.type !== 'test:pass' && event.type !== 'test:fail') continue;
+    const d = event.data || {};
+    if (d.details?.type === 'suite' || !d.file) continue;
+    const filePath = toRootPath(root, d.file);
+    if (!filePath) { outside.add(d.file); continue; }
+    if (!files.has(filePath)) files.set(filePath, emptyFile(filePath));
+    const f = files.get(filePath);
+    f.tests += 1;
+    if (flag(d.todo)) f.pending += 1;
+    else if (flag(d.skip)) f.skipped += 1;
+    else if (event.type === 'test:fail') f.failed += 1;
+    else f.passed += 1;
+  }
+  const run = { runner: 'node', source: null, sha, dirtyPaths, at, exit: null, outsideRoot: outside.size, files: sortFiles([...files.values()]) };
+  yield JSON.stringify({ schema: RESULTS_SCHEMA, runs: [run] }, null, 2) + '\n';
+}