elanous 0.2.15 → 0.2.16

package/scripts/ci-public-export-import-gate.ts

@@ -0,0 +1,154 @@
+/**
+ * Public export import guard — a file the public export includes must not statically import
+ * a module the export excludes. 0.2.15 shipped that break: src/decisions/proact-meter.ts
+ * imported src/directives/directive-index (exclude `src/directives/directive-index*`) and the
+ * export-check PWA build failed.
+ *
+ *   bun scripts/ci-public-export-import-gate.ts --changed-files a b …   # exit 1 on a hit · 0 when clean
+ *
+ * Only string-literal specifiers are resolved. Non-literal specifiers (createRequire with a
+ * concatenated string, and the like) are counted as unseen — this check cannot see them.
+ * The public PWA build itself stays on the release export-check run; it is not run here.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, posix, resolve } from 'node:path';
+type ExportSelectors = {
+  loadExportConfig: (root: string, file?: string) => { readonly include: readonly string[]; readonly exclude: readonly string[]; readonly replace: Readonly<Record<string, string>> };
+  selectExportFiles: (tracked: readonly string[], config: { readonly include: readonly string[]; readonly exclude: readonly string[]; readonly replace: Readonly<Record<string, string>> }) => string[];
+};
+
+/**
+ * scripts/public-export.ts `loadExportConfig` (line 123) and `selectExportFiles` (line 140).
+ * Imported on call, not at load: that module imports typescript, and a tree that has not
+ * installed it must still be able to load this gate and report why it could not measure.
+ */
+async function exportSelectors(): Promise<ExportSelectors> {
+  return import('./public-export.js');
+}
+
+export interface ExportImportHit {
+  readonly file: string;
+  readonly line: number;
+  readonly target: string;
+}
+
+export interface ExportImportCheck {
+  readonly measured: boolean;
+  readonly hits: readonly ExportImportHit[];
+  readonly unseen: number;
+  readonly detail?: string;
+}
+
+const CODE_FILE = /\.(?:[cm]?[jt]sx?)$/;
+const FROM_CLAUSE = /\b(?:import|export)\s+(?:type\s+)?(?:[^'"\n;]*?\s+from\s+)?(['"])([^'"\n]+)\1/g;
+const DYNAMIC_IMPORT = /\bimport\s*\(\s*(['"])([^'"\n]+)\1/g;
+const NON_LITERAL_IMPORT = /\b(?:import|require|createRequire)\s*\(\s*(?!['"`])/g;
+
+function trackedFiles(root: string): string[] | undefined {
+  const run = spawnSync('git', ['ls-files', '-z'], { cwd: root, encoding: 'utf-8', timeout: 60_000, maxBuffer: 64 * 1024 * 1024 });
+  if (run.status !== 0) return undefined;
+  return String(run.stdout).split('\0').filter(Boolean);
+}
+
+/** Specifier resolved against the importer's directory, then mapped onto a repo-relative path. */
+function resolveSpecifier(importer: string, specifier: string): string | undefined {
+  if (!specifier.startsWith('.')) return undefined;
+  const raw = posix.normalize(posix.join(posix.dirname(importer), specifier));
+  return raw.startsWith('../') ? undefined : raw;
+}
+
+function candidatePaths(resolved: string): string[] {
+  const ext = posix.extname(resolved);
+  const bases = ext === '.js' || ext === '.jsx' || ext === '.mjs' || ext === '.cjs'
+    ? [resolved.slice(0, -ext.length) + '.ts', resolved.slice(0, -ext.length) + '.tsx', resolved]
+    : [resolved];
+  const out: string[] = [];
+  for (const base of bases) {
+    out.push(base);
+    if (!posix.extname(base)) {
+      out.push(`${base}.ts`, `${base}.tsx`, `${base}.js`, `${base}.mjs`);
+      out.push(posix.join(base, 'index.ts'), posix.join(base, 'index.tsx'), posix.join(base, 'index.js'));
+    }
+  }
+  return out;
+}
+
+function lineOf(text: string, index: number): number {
+  let line = 1;
+  for (let i = 0; i < index && i < text.length; i++) if (text[i] === '\n') line++;
+  return line;
+}
+
+/**
+ * Changed files that the public manifest includes, scanned for a literal import of a tracked
+ * module that the same manifest leaves out. `unseen` counts non-literal import/require calls.
+ */
+export async function exportImportCheck(changedFiles: readonly string[], root: string): Promise<ExportImportCheck> {
+  const tracked = trackedFiles(root);
+  if (!tracked) return { measured: false, hits: [], unseen: 0, detail: 'git ls-files 실패' };
+  let included: Set<string>;
+  try {
+    const { loadExportConfig, selectExportFiles } = await exportSelectors();
+    included = new Set(selectExportFiles(tracked, loadExportConfig(root)));
+  } catch (error) {
+    return { measured: false, hits: [], unseen: 0, detail: error instanceof Error ? error.message : '매니페스트를 못 읽었다' };
+  }
+  const trackedSet = new Set(tracked);
+  const hits: ExportImportHit[] = [];
+  let unseen = 0;
+  for (const file of changedFiles) {
+    if (!included.has(file) || !CODE_FILE.test(file)) continue;
+    const abs = join(root, file);
+    if (!existsSync(abs)) continue;
+    let text: string;
+    try { text = readFileSync(abs, 'utf8'); } catch { continue; }
+    const seen = new Set<string>();
+    const consider = (index: number, specifier: string) => {
+      const resolvedSpec = resolveSpecifier(file, specifier);
+      if (!resolvedSpec) return;
+      const target = candidatePaths(resolvedSpec).find((candidate) => trackedSet.has(candidate));
+      if (!target || included.has(target)) return;
+      const key = `${index}\0${target}`;
+      if (seen.has(key)) return;
+      seen.add(key);
+      hits.push({ file, line: lineOf(text, index), target });
+    };
+    for (const pattern of [FROM_CLAUSE, DYNAMIC_IMPORT]) {
+      pattern.lastIndex = 0;
+      for (const match of text.matchAll(pattern)) consider(match.index ?? 0, match[2] ?? '');
+    }
+    NON_LITERAL_IMPORT.lastIndex = 0;
+    unseen += [...text.matchAll(NON_LITERAL_IMPORT)].length;
+  }
+  return { measured: true, hits, unseen };
+}
+
+/** Gate form: 1 on a hit, 0 when clean. An unmeasured check blocks only when a changed file is included. */
+export async function runPublicExportImportGate(io: { args: readonly string[]; cwd: string; log: (line: string) => void; error: (line: string) => void }): Promise<number> {
+  const at = io.args.indexOf('--changed-files');
+  const files = at >= 0 ? io.args.slice(at + 1).filter((arg) => !arg.startsWith('--')) : [];
+  if (files.length === 0) return 0;
+  let result: ExportImportCheck;
+  try { result = await exportImportCheck(files, io.cwd); }
+  catch { result = { measured: false, hits: [], unseen: 0, detail: '검사 실행 실패' }; }
+  if (!result.measured) {
+    let publicFiles = files;
+    try {
+      const { loadExportConfig, selectExportFiles } = await exportSelectors();
+      publicFiles = selectExportFiles(files, loadExportConfig(io.cwd));
+    } catch { publicFiles = files; }
+    if (publicFiles.length === 0) { io.log('⚠ public-export-import: 못 쟀다 — 공개 대상 변경 없음'); return 0; }
+    io.error(`✗ public-export-import: 못 쟀다 — 막는다(${result.detail ?? '?'})`);
+    return 1;
+  }
+  if (result.unseen > 0) io.log(`⚠ public-export-import: 비리터럴 지정자 ${result.unseen}곳은 못 봄`);
+  if (result.hits.length === 0) return 0;
+  io.error(`✗ public-export-import: 공개 파일이 공개 내보내기에서 제외된 모듈을 import 한다 (${result.hits.length}곳) — 공개본 빌드가 여기서 깨진다:`);
+  for (const hit of result.hits) io.error(`   ${hit.file}:${hit.line} → ${hit.target}`);
+  return 1;
+}
+
+if (import.meta.main) {
+  process.exit(await runPublicExportImportGate({ args: process.argv.slice(2), cwd: resolve(import.meta.dir, '..'), log: console.log, error: console.error }));
+}

package/scripts/ci-test-interference-gate.ts

@@ -2,6 +2,7 @@
 import {
   detectTestInterference,
   formatIsolatedFailureSummary,
+  runBunTest,
   type InterferenceReport,
   type TestRunner,
 } from './detect-test-interference.js';
@@ -11,6 +12,8 @@ const TEST_FILE = /\.test\.tsx?$/;
 
 export type TestInterferenceGateIo = {
   args?: readonly string[];
+  /** Landing tree. `bun test` of the changed files runs here, not in process.cwd(). */
+  cwd?: string;
   log?: (message: string) => void;
   detect?: (files: readonly string[], runner?: TestRunner) => Promise<InterferenceReport>;
   runner?: TestRunner;
@@ -36,6 +39,7 @@ export function selectedTestFiles(files: readonly string[]): string[] {
 export async function runTestInterferenceGate(io: TestInterferenceGateIo = {}): Promise<number> {
   const args = io.args ?? process.argv.slice(2);
   const log = io.log ?? console.log;
+  const cwd = io.cwd ?? process.cwd();
   const changed = parseChangedFiles(args);
   const tests = selectedTestFiles(changed ?? []);
   if (tests.length < 2) {
@@ -48,7 +52,7 @@ export async function runTestInterferenceGate(io: TestInterferenceGateIo = {}):
   const capNotice = omitted > 0 ? ` · 상한 ${MAX_INSPECTED_TEST_FILES}개 적용, ${omitted}개 미검사.` : '';
   let report: InterferenceReport;
   try {
-    report = await (io.detect ?? detectTestInterference)(inspected, io.runner);
+    report = await (io.detect ?? detectTestInterference)(inspected, io.runner ?? ((files) => runBunTest(files, undefined, cwd)));
   } catch {
     log(`[test-interference-gate] 경고: 측정 불가 — 판정기 실행 실패, 간섭 없음으로 처리하지 않음.${capNotice}`);
     return 0;

package/scripts/ci-typecheck-changed.ts

@@ -15,9 +15,18 @@ import {
 import { debug } from '../src/debug/log.js';
 import { tscEnv } from '../src/typecheck-ratchet.js';
 
+/** Inherited GIT_DIR / GIT_WORK_TREE would make `--cwd <other tree>` still read the launcher's repo. */
+function gitEnv(base: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+  const env = { ...base };
+  delete env.GIT_DIR;
+  delete env.GIT_WORK_TREE;
+  delete env.GIT_COMMON_DIR;
+  return env;
+}
+
 /** git 조회용 — 명령 실패는 호출자가 빈 출력과 구분할 수 있게 전파한다. */
-function sh(cmd: string): string {
-  return execSync(cmd, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+function sh(cmd: string, cwd = process.cwd()): string {
+  return execSync(cmd, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], cwd, env: gitEnv() });
 }
 
 export type TscRun = { out: string; ran: boolean; why?: string };
@@ -59,13 +68,15 @@ export type ChangedTsFiles = {
   failures?: { command: string; why: string }[];
 };
 
-/** 선택한 base와 파일 수를 함께 보존한다. 0개도 base 기준 관측값이다. */
-export function changedTsFiles(run = sh, env: NodeJS.ProcessEnv = process.env): ChangedTsFiles {
+/** 선택한 base와 파일 수를 함께 보존한다. 0개도 base 기준 관측값이다.
+ *  `cwd` 는 착지 트리다 — `pr land --cwd` 가 프로세스 cwd 가 아니라 그 트리를 재게 한다. */
+export function changedTsFiles(run: (cmd: string) => string = sh, env: NodeJS.ProcessEnv = process.env, cwd = process.cwd(), baseRef?: string): ChangedTsFiles {
   let base: string;
   let baseSource: string;
-  if (env.TSC_BASE_REF) {
-    base = env.TSC_BASE_REF;
-    baseSource = 'TSC_BASE_REF';
+  const pinned = baseRef ?? env.TSC_BASE_REF;
+  if (pinned) {
+    base = pinned;
+    baseSource = baseRef ? 'baseRef' : 'TSC_BASE_REF';
   } else if (env.GITHUB_BASE_REF) {
     base = `origin/${env.GITHUB_BASE_REF}`;
     baseSource = 'GITHUB_BASE_REF';
@@ -108,8 +119,10 @@ export function changedTsFiles(run = sh, env: NodeJS.ProcessEnv = process.env):
         if (!file) continue;
         const ts = /\.tsx?$/.test(file);
         // A deleted .ts is not a compile candidate, so it must not count as «should have been collected».
-        if (!ts || existsSync(file)) diffFiles.add(file);
-        if (ts && existsSync(file)) files.add(file);
+        // existsSync is bound to the landing tree — process.cwd() would count the launcher's files.
+        const present = existsSync(join(cwd, file));
+        if (!ts || present) diffFiles.add(file);
+        if (ts && present) files.add(file);
       }
     } catch (cause) {
       failures.push({ command, why: cause instanceof Error ? cause.message : String(cause) });
@@ -766,7 +779,7 @@ export function readMergeBaseDiagnostics(base: string, command: string, cwd = pr
   const workspace = mkdtempSync(join(tmpdir(), 'ci-typecheck-baseline-'));
   const worktree = join(workspace, 'base');
   try {
-    execFileSync('git', ['worktree', 'add', '--detach', worktree, base], { cwd, stdio: 'pipe' });
+    execFileSync('git', ['worktree', 'add', '--detach', worktree, base], { cwd, stdio: 'pipe', env: gitEnv() });
     const modules = join(cwd, 'node_modules');
     if (!existsSync(modules)) return { unavailable: `기준 worktree 의존성을 재사용할 수 없다(${modules} 없음)` };
     symlinkSync(modules, join(worktree, 'node_modules'));
@@ -780,7 +793,7 @@ export function readMergeBaseDiagnostics(base: string, command: string, cwd = pr
   } catch (error) {
     return { unavailable: error instanceof Error ? error.message : String(error) };
   } finally {
-    try { execFileSync('git', ['worktree', 'remove', '--force', worktree], { cwd, stdio: 'pipe' }); }
+    try { execFileSync('git', ['worktree', 'remove', '--force', worktree], { cwd, stdio: 'pipe', env: gitEnv() }); }
     catch { /* acquisition failure is rendered by the caller */ }
     rmSync(workspace, { recursive: true, force: true });
   }
@@ -792,6 +805,10 @@ export type GateIo = {
   literalUnionMembers?: (changed: ReadonlySet<string>, base: string) => LiteralUnionMember[] | LiteralUnionMemberCheck;
   readBaselineDiagnostics?: (base: string, command: string) => BaselineDiagnostics;
   runTscCmd: (cmd: string) => TscRun;
+  /** Landing tree. Git, existsSync, tsc, and the test baseline are measured here — not in process.cwd(). */
+  cwd?: string;
+  /** Explicit base revision. Same rule as TSC_BASE_REF, without reading the process environment. */
+  baseRef?: string;
   log: (message: string) => void;
   warn: (message: string) => void;
   error: (message: string) => void;
@@ -861,8 +878,10 @@ function inspectTscResult(tsc: TscRun, changed: ReadonlySet<string>, baseline: R
 }
 
 export function runGate(io: Partial<GateIo> = {}): void {
-  const { changedTsFiles: getChanged = changedTsFiles, runTscCmd = (cmd: string) => runTsc(cmd), log = (message: string) => console.log(message), warn = (message: string) => console.warn(message), error = (message: string) => console.error(message), exit = ((code: number) => process.exit(code)) as GateIo['exit'] } = io;
-  const readBaselineDiagnostics = io.readBaselineDiagnostics ?? ((base: string, command: string) => readMergeBaseDiagnostics(base, command));
+  const cwd = io.cwd ?? process.cwd();
+  const defaultChanged = () => changedTsFiles((cmd) => sh(cmd, cwd), process.env, cwd, io.baseRef);
+  const { changedTsFiles: getChanged = defaultChanged, runTscCmd = (cmd: string) => runTsc(cmd, ((command, options) => execSync(command, { ...options, cwd, env: gitEnv() })) as typeof execSync), log = (message: string) => console.log(message), warn = (message: string) => console.warn(message), error = (message: string) => console.error(message), exit = ((code: number) => process.exit(code)) as GateIo['exit'] } = io;
+  const readBaselineDiagnostics = io.readBaselineDiagnostics ?? ((base: string, command: string) => readMergeBaseDiagnostics(base, command, cwd));
   // Set 주입은 기존 테스트 심이며 기준 revision이 없다. 실제 ChangedTsFiles 경로만 Git 관측을 요구한다.
   const requiredExportFields = io.requiredExportFields ?? ((changed: ReadonlySet<string>, base: string) => base === 'injected test seam'
     ? { fields: [], removedSymbols: [], parameterIncreases: [] }
@@ -966,8 +985,8 @@ export function runGate(io: Partial<GateIo> = {}): void {
   }, { level: 'info' });
   log(`[tsc-gate] root 설정 범위 ${rootScope.size}개 관측 (apps/pwa/** 제외).`);
   if (runsPwa) log(`[tsc-gate] PWA 설정 범위 ${pwaScope.size}개 관측.`);
-  const tscBin = existsSync('node_modules/.bin/tsc') ? 'node_modules/.bin/tsc' : 'npx tsc';
-  const baseline = readTestTypecheckBaseline(process.cwd());
+  const tscBin = existsSync(join(cwd, 'node_modules/.bin/tsc')) ? 'node_modules/.bin/tsc' : 'npx tsc';
+  const baseline = readTestTypecheckBaseline(cwd);
   const rootCommand = `${tscBin} --noEmit -p ${TYPECHECK_GATE_CONFIG}`;
   const pwaCommand = `${tscBin} --noEmit -p apps/pwa/tsconfig.json`;
   const pwaEnvCommand = `${tscBin} --noEmit -p tsconfig.pwa-env.json`;

package/scripts/docs/doc-rot.ts

@@ -0,0 +1,164 @@
+#!/usr/bin/env bun
+// DOC-ROT① — 내부 매뉴얼(내부 문서 `*`)의 명령·저장소 경로를 실제와 대조한다.
+//   bun scripts/docs/doc-rot.ts [--json] [files…]      (기본 = 내부 문서 `*`)
+// 명령 판정은 scripts/docs-cli-check.ts 의 checkCommands 만 쓴다(같은 판정을 다시 짜지 않는다).
+// 경로 판정은 인라인 코드 안의 src/ · scripts/ · docs/ · graphs/ · test/ 가 repoRoot 에 있는지다.
+// ⛔ --help 를 못 잰 명령은 unmeasured 로 따로 센다 — «없다»로 세지 않는다.
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { join, relative, resolve } from 'node:path';
+import {
+  checkCommands,
+  extractElanousCommands,
+  type Finding,
+  type HelpRunner,
+} from '../docs-cli-check.js';
+
+const REPO = resolve(import.meta.dir, '../..');
+const PATH_ROOTS = ['src/', 'scripts/', 'docs/', 'graphs/', 'test/'] as const;
+const PASSTHROUGH_COMMANDS = new Set(['gh', 'git']);
+
+export interface MissingPath { line: number; path: string }
+export interface DocRotFinding extends Omit<Finding, 'kind'> {
+  kind: Finding['kind'] | 'passthrough' | 'globalFlag' | 'intentional';
+}
+export interface DocRotFile {
+  file: string;
+  commands: DocRotFinding[];
+  missingPaths: MissingPath[];
+}
+export interface DocRotTotals {
+  files: number;
+  staleFiles: number;
+  missingPaths: number;
+  badCommands: number;
+  unmeasured: number;
+  passthrough: number;
+  globalFlag: number;
+  intentional: number;
+}
+export interface DocRotReport {
+  files: DocRotFile[];
+  totals: DocRotTotals;
+}
+
+export interface ScanDocRotInput {
+  files: readonly string[];
+  repoRoot: string;
+  help?: HelpRunner;
+  read?: (file: string) => string;
+}
+
+/** 인라인 코드에서 저장소 경로를 뽑는다. 줄번호 꼬리(`:12`)는 떼고, glob(`*`)은 건너뛴다. */
+export function extractRepoPaths(text: string): MissingPath[] {
+  const out: MissingPath[] = [];
+  const seen = new Set<string>();
+  for (const m of text.matchAll(/`([^`\n]+)`/g)) {
+    const raw = m[1]!;
+    if (raw.includes('*')) continue;
+    if (!PATH_ROOTS.some((root) => raw.startsWith(root))) continue;
+    const path = raw.replace(/:\d+$/, '');
+    if (!PATH_ROOTS.some((root) => path.startsWith(root)) || path.endsWith('/')) continue;
+    const line = text.slice(0, m.index ?? 0).split('\n').length;
+    const key = `${line}\0${path}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push({ line, path });
+  }
+  return out;
+}
+
+/** 파일마다 명령 findings(checkCommands 재사용)와 없는 경로를 센다. */
+export function scanDocRot(input: ScanDocRotInput): DocRotReport {
+  const read = input.read ?? ((file: string) => readFileSync(file, 'utf8'));
+  const texts = input.files.map((file) => ({ file, text: read(file) }));
+  const help: HelpRunner = input.help ?? ((args) => {
+    const result = spawnSync('bun', ['bin/elanous.mjs', '--test', ...args, '--help'], {
+      cwd: input.repoRoot, encoding: 'utf8', timeout: 60_000, env: { ...process.env, NO_COLOR: '1' },
+    });
+    return { ok: result.status === 0, out: `${result.stdout ?? ''}\n${result.stderr ?? ''}` };
+  });
+  let commandRoot: ReturnType<HelpRunner> | undefined;
+  const cachedHelp: HelpRunner = (args) => {
+    if (args.length === 0) return commandRoot ??= help(args);
+    return help(args);
+  };
+  const checked = texts.map(({ file, text }) => {
+    const label = relative(input.repoRoot, file) || file;
+    return { file: label, text, commands: checkCommands(extractElanousCommands(label, text), cachedHelp) };
+  });
+  const hasUnknownFlag = checked.some(({ commands }) => commands.some((finding) => finding.kind === 'unknown-flag'));
+  // A separate lookup measures root Options; a failure must not mean "no global flags".
+  const rootOptionsHelp = hasUnknownFlag ? help([]) : commandRoot;
+  const rootOptions = rootOptionsHelp?.ok ? (rootOptionsHelp.out.split(/\nOptions:\s*\n/)[1] ?? '').split(/\n\S[^\n]*:\s*\n/)[0]! : '';
+  const globalFlags = new Set([...rootOptions.matchAll(/^\s+(?:-\w,\s*)?(--[a-z][a-z0-9-]*)\b/gm)].map((match) => match[1]!));
+  const files: DocRotFile[] = checked.map(({ file, text, commands }) => {
+    const lines = text.split('\n');
+    const classified: DocRotFinding[] = commands.map((finding) => {
+      if (finding.kind !== 'unmeasured' && (lines[finding.ref.line - 1] ?? '').includes('⛔')) return { ...finding, kind: 'intentional' };
+      if (finding.kind !== 'unknown-flag') return finding;
+      if (PASSTHROUGH_COMMANDS.has(finding.ref.cmd)) return { ...finding, kind: 'passthrough' };
+      if (!rootOptionsHelp?.ok) return { ...finding, kind: 'unmeasured' };
+      const flag = /^--[a-z][a-z0-9-]*/.exec(finding.detail)?.[0];
+      if (flag && globalFlags.has(flag)) return { ...finding, kind: 'globalFlag' };
+      return finding;
+    });
+    const missingPaths = extractRepoPaths(text).filter((entry) => !existsSync(join(input.repoRoot, entry.path)));
+    return { file, commands: classified, missingPaths };
+  });
+  const isBad = (finding: DocRotFinding) => finding.kind === 'unknown-command' || finding.kind === 'unknown-subcommand' || finding.kind === 'unknown-flag';
+  const count = (kind: DocRotFinding['kind']) => files.reduce((sum, file) => sum + file.commands.filter((finding) => finding.kind === kind).length, 0);
+  const totals: DocRotTotals = {
+    files: files.length,
+    staleFiles: files.filter((file) => file.missingPaths.length > 0 || file.commands.some(isBad)).length,
+    missingPaths: files.reduce((sum, file) => sum + file.missingPaths.length, 0),
+    badCommands: files.reduce((sum, file) => sum + file.commands.filter(isBad).length, 0),
+    unmeasured: count('unmeasured'),
+    passthrough: count('passthrough'),
+    globalFlag: count('globalFlag'),
+    intentional: count('intentional'),
+  };
+  return { files, totals };
+}
+
+export function defaultManualFiles(repoRoot: string = REPO): string[] {
+  return readdirSync(join(repoRoot, 'docs', 'manual'))
+    .filter((name) => name.endsWith('.md'))
+    .sort()
+    .map((name) => join(repoRoot, 'docs', 'manual', name));
+}
+
+function renderTable(report: DocRotReport): string {
+  const lines = [
+    `doc-rot — 매뉴얼 ${report.totals.files} · 낡은 파일 ${report.totals.staleFiles} · 없는 경로 ${report.totals.missingPaths} · 깨진 명령 ${report.totals.badCommands} · 못 잰 명령 ${report.totals.unmeasured} · 통과 래퍼 ${report.totals.passthrough} · 전역 옵션 ${report.totals.globalFlag} · 의도적 예시 ${report.totals.intentional}`,
+  ];
+  for (const file of report.files) {
+    for (const finding of file.commands) lines.push(`  ${finding.kind}  ${file.file}:${finding.ref.line}  ${finding.detail}`);
+    for (const missing of file.missingPaths) lines.push(`  missing-path  ${file.file}:${missing.line}  ${missing.path}`);
+  }
+  return lines.join('\n');
+}
+
+if (import.meta.main) {
+  try {
+    const { registerStandaloneLogSink } = await import('../../src/domains/standalone-log-sink.js');
+    await registerStandaloneLogSink('doc-rot');
+  } catch { /* fail-open — 관측 배선 실패가 측정을 막지 않는다 */ }
+  const { debug } = await import('../../src/debug/log.js');
+  const json = process.argv.includes('--json');
+  const args = process.argv.slice(2).filter((arg) => arg !== '--json');
+  const files = args.length ? args.map((arg) => resolve(arg)) : defaultManualFiles();
+  const report = scanDocRot({ files, repoRoot: REPO });
+  debug.log('docs.rot', 'scanned', {
+    files: report.totals.files,
+    staleFiles: report.totals.staleFiles,
+    missingPaths: report.totals.missingPaths,
+    badCommands: report.totals.badCommands,
+    unmeasured: report.totals.unmeasured,
+    passthrough: report.totals.passthrough,
+    globalFlag: report.totals.globalFlag,
+    intentional: report.totals.intentional,
+  });
+  console.log(json ? JSON.stringify(report) : renderTable(report));
+  process.exit(report.totals.badCommands + report.totals.missingPaths > 0 ? 1 : 0);
+}

package/scripts/docs/generate-graph-anatomy.ts

@@ -6,8 +6,10 @@
  *   노드 종류 = src/graph-kinds/registry.ts (HARNESS_CORE_KINDS · WORKFLOW_CORE_KINDS · listNodeKinds)
  *   그래프     = graphs/ YAML 을 src/self-implement/graph-yaml.ts 의 loadGraphTemplates · edgeMapOf 가 읽는다
  *
- * renderGraphAnatomy 는 순수하다 — 파일을 쓰지 않고 process.cwd() 를 읽지 않는다.
- * 뿌리·커밋·시각은 인자로만 받는다. main 만 내부 문서 `graph-anatomy` 에 쓴다.
+ * renderGraphAnatomy · diffAnatomy 는 순수하다 — 파일을 쓰지 않고 process.cwd() 를 읽지 않는다.
+ * 뿌리·커밋·시각은 인자로만 받는다. 쓰기는 main 만 한다.
+ * main: `--out <path>` (기본 내부 문서 `graph-anatomy`) 와 같은 이름 `.json` 옆 파일.
+ * git 트리가 아니면 죽지 않고 `commit: (설치본 v<package.json version>)`.
  */
 
 import { execFileSync } from 'node:child_process';
@@ -35,6 +37,22 @@ export interface RenderGraphAnatomyInput {
   readonly generatedAt: string;
 }
 
+/** `<out>.json` 옆 파일. graphs 값은 graph_id → nodeId 목록. */
+export interface AnatomySnapshot {
+  readonly generatedAt: string;
+  readonly commit: string;
+  readonly graphs: Readonly<Record<string, readonly string[]>>;
+}
+
+export interface AnatomyDiff {
+  readonly addedGraphs: readonly string[];
+  readonly removedGraphs: readonly string[];
+  /** `graph_id/nodeId` */
+  readonly addedNodes: readonly string[];
+  /** `graph_id/nodeId` */
+  readonly removedNodes: readonly string[];
+}
+
 export interface ScannedGraphDir {
   /** graphsRoot 기준 상대 경로. 뿌리 자신은 '.' */
   readonly dir: string;
@@ -165,6 +183,58 @@ function graphIdPaths(graphsRoot: string, dir: string): ReadonlyMap<string, stri
   return paths;
 }
 
+function sortedIds(ids: Iterable<string>): string[] {
+  return [...ids].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
+
+/** 순수. 어제 판과 오늘 판의 그래프·노드 차이. 파일을 읽거나 쓰지 않는다. */
+export function diffAnatomy(prev: AnatomySnapshot, next: AnatomySnapshot): AnatomyDiff {
+  const prevIds = new Set(Object.keys(prev.graphs));
+  const nextIds = new Set(Object.keys(next.graphs));
+  const addedGraphs = sortedIds([...nextIds].filter((id) => !prevIds.has(id)));
+  const removedGraphs = sortedIds([...prevIds].filter((id) => !nextIds.has(id)));
+  const addedNodes: string[] = [];
+  const removedNodes: string[] = [];
+  // A graph that appears or disappears contributes all of its nodes, so the node list never hides them (ACP must-fix).
+  for (const id of sortedIds([...new Set([...prevIds, ...nextIds])])) {
+    const before = new Set(prev.graphs[id] ?? []);
+    const after = new Set(next.graphs[id] ?? []);
+    for (const nodeId of sortedIds([...after].filter((node) => !before.has(node)))) addedNodes.push(`${id}/${nodeId}`);
+    for (const nodeId of sortedIds([...before].filter((node) => !after.has(node)))) removedNodes.push(`${id}/${nodeId}`);
+  }
+  return { addedGraphs, removedGraphs, addedNodes, removedNodes };
+}
+
+/** 머리(`# Graph anatomy` 와 생성물 경고) 바로 아래. 파일을 쓰지 않는다. */
+export function renderYesterdaySection(prev: AnatomySnapshot | null, next: AnatomySnapshot): string {
+  if (prev === null) return ['## 어제 대비', '', '이전 판 없음(첫 생성)', ''].join('\n');
+  const diff = diffAnatomy(prev, next);
+  const lines = ['## 어제 대비', ''];
+  const changed = diff.addedGraphs.length + diff.removedGraphs.length + diff.addedNodes.length + diff.removedNodes.length;
+  if (changed === 0) {
+    lines.push('변화 없음', '');
+    return lines.join('\n');
+  }
+  for (const id of diff.addedGraphs) lines.push(`+ ${id}`);
+  for (const id of diff.removedGraphs) lines.push(`- ${id}`);
+  for (const node of diff.addedNodes) lines.push(`+ ${node}`);
+  for (const node of diff.removedNodes) lines.push(`- ${node}`);
+  lines.push('');
+  return lines.join('\n');
+}
+
+function snapshotOf(scanned: readonly ScannedGraphDir[], commit: string, generatedAt: string): AnatomySnapshot {
+  const graphs: Record<string, string[]> = {};
+  for (const { result } of scanned) {
+    for (const template of Object.values(result.templates)) {
+      const ids = template.nodes.map((node) => node.nodeId);
+      const prev = graphs[template.graphId];
+      graphs[template.graphId] = prev === undefined ? ids : [...prev, ...ids.filter((id) => !prev.includes(id))];
+    }
+  }
+  return { generatedAt, commit, graphs };
+}
+
 function kindRows(entries: readonly NodeKindEntry[]): string[] {
   return [...entries]
     .sort((a, b) => (a.graph < b.graph ? -1 : a.graph > b.graph ? 1 : a.kind < b.kind ? -1 : a.kind > b.kind ? 1 : 0))
@@ -179,7 +249,7 @@ function issueLines(label: string, issues: readonly GraphParseIssue[]): string[]
 /**
  * 마크다운 한 장. 파일을 쓰지 않는다. graphsRoot · commit · generatedAt 만 읽는다.
  */
-export function renderGraphAnatomy(input: RenderGraphAnatomyInput): string {
+export function renderGraphAnatomy(input: RenderGraphAnatomyInput, yesterday?: string): string {
   const scanned = scanGraphDirs(input.graphsRoot);
   const templates: { dir: string; fileLabel: string; template: GraphTemplateSpec }[] = [];
   for (const { dir, result } of scanned) {
@@ -207,6 +277,7 @@ export function renderGraphAnatomy(input: RenderGraphAnatomyInput): string {
     `- scannedDirs: ${scanned.length}`,
     `- templates: ${templates.length}`,
     '',
+    ...(yesterday === undefined ? [] : [yesterday.trimEnd(), '']),
     '## 표 1 노드 종류',
     '',
     '원천: `src/graph-kinds/registry.ts` — `HARNESS_CORE_KINDS` · `WORKFLOW_CORE_KINDS` · `listNodeKinds()`.',
@@ -292,23 +363,74 @@ function repoRootFromHere(): string {
   return join(dirname(fileURLToPath(import.meta.url)), '..', '..');
 }
 
-function readCommit(repoRoot: string): string {
-  return execFileSync('git', ['rev-parse', 'HEAD'], { cwd: repoRoot, encoding: 'utf8' }).trim();
+/** git 트리가 아니면 죽지 않는다. 설치본은 package.json version 으로 적는다. */
+export function readCommit(repoRoot: string): string {
+  try {
+    return execFileSync('git', ['rev-parse', 'HEAD'], { cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+  } catch {
+    let version = 'unknown';
+    try {
+      const raw = JSON.parse(readFileSync(join(repoRoot, 'package.json'), 'utf8')) as { version?: unknown };
+      if (typeof raw.version === 'string' && raw.version.length > 0) version = raw.version;
+    } catch { /* 설치본인데 package.json 도 없으면 unknown */ }
+    return `(설치본 v${version})`;
+  }
 }
 
 export function defaultOutputPath(repoRoot: string): string {
   return join(repoRoot, 'docs', 'generated', 'graph-anatomy.md');
 }
 
+/** 옆 파일 이름. `a.md` → `a.md.json`. */
+export function snapshotPathOf(out: string): string {
+  return `${out}.json`;
+}
+
+function isSnapshot(value: unknown): value is AnatomySnapshot {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const record = value as Record<string, unknown>;
+  if (typeof record.generatedAt !== 'string' || typeof record.commit !== 'string') return false;
+  if (!record.graphs || typeof record.graphs !== 'object' || Array.isArray(record.graphs)) return false;
+  return Object.values(record.graphs as Record<string, unknown>).every((nodes) => Array.isArray(nodes) && nodes.every((node) => typeof node === 'string'));
+}
+
+/** 쓰기 전의 옆 파일. 없거나 깨졌으면 null(첫 생성). 파일을 쓰지 않는다. */
+export function readPreviousSnapshot(out: string): AnatomySnapshot | null {
+  const path = snapshotPathOf(out);
+  if (!existsSync(path)) return null;
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'));
+    return isSnapshot(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function parseFlag(argv: readonly string[], name: string): string | undefined {
+  const index = argv.indexOf(name);
+  const value = index >= 0 ? argv[index + 1] : undefined;
+  if (index >= 0 && (value === undefined || value.startsWith('--'))) throw new Error(`${name} 에는 경로가 필요하다`);
+  return value;
+}
+
+export function parseOutArg(argv: readonly string[], fallback: string): string {
+  return parseFlag(argv, '--out') ?? fallback;
+}
+
 function main(): void {
   const repoRoot = repoRootFromHere();
-  const graphsRoot = join(repoRoot, 'graphs');
+  const argv = process.argv.slice(2);
+  const graphsRoot = parseFlag(argv, '--graphs') ?? join(repoRoot, 'graphs');
   const generatedAt = new Date().toISOString();
-  const commit = readCommit(repoRoot);
-  const markdown = renderGraphAnatomy({ graphsRoot, commit, generatedAt });
-  const out = defaultOutputPath(repoRoot);
+  const commit = readCommit(parseFlag(argv, '--repo') ?? repoRoot);
+  const out = parseOutArg(argv, defaultOutputPath(repoRoot));
+  const scanned = scanGraphDirs(graphsRoot);
+  const next = snapshotOf(scanned, commit, generatedAt);
+  const prev = readPreviousSnapshot(out);
+  const markdown = renderGraphAnatomy({ graphsRoot, commit, generatedAt }, renderYesterdaySection(prev, next));
   mkdirSync(dirname(out), { recursive: true });
   writeFileSync(out, markdown);
+  writeFileSync(snapshotPathOf(out), `${JSON.stringify(next, null, 2)}\n`);
   process.stdout.write(`${out}\n`);
 }