@mafianacho/nacholens 0.0.0-stage → 0.3.0

package/src/review.js

@@ -0,0 +1,321 @@
+// Review layer: three read-only views derived from the model + change overlay.
+//   compare  (A3) before/after rows per use case
+//   intent   (C1) planner expectations checked against the model (met | unmet | unknown)
+//   impact   (C5) which other use cases a change can break, and whether tests mention them
+// Everything here is a pure function of its inputs (model, changes, intent, test files). Nothing is
+// guessed: an expectation without a mechanical check is `unknown`, an untestable claim stays that way.
+import { ignoreReason, COMPONENT_NOTE } from "./diff.js";
+
+const isObj = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const isStr = (v, max = 400) => typeof v === "string" && v.trim().length > 0 && v.length <= max;
+const stepKey = (u, s) => `${u}/${s}`;
+const pathOf = (st) => [st.from, ...(st.via ?? []), st.to];
+const evText = (st) => (st.evidence ?? []).slice(0, 2).map((e) => `${e.file}:${e.lines[0]}${e.lines[1] !== e.lines[0] ? "-" + e.lines[1] : ""}`).join(", ");
+
+/** ordered, consecutive-deduplicated list of the components a use case visits */
+export function usePath(model, uc) {
+  const out = [];
+  for (const st of uc.steps) for (const c of pathOf(st)) if (out[out.length - 1] !== c) out.push(c);
+  return out;
+}
+
+// ───────────────────────────── A3: before / after ─────────────────────────────
+
+const FLOW_FIELDS = ["kind", "from", "to", "label", "request", "response"];
+const flowSig = (st) => FLOW_FIELDS.map((k) => st[k] ?? "").join("\u0001") + "\u0001" + (st.via ?? []).join(",");
+const cell = (m, st) => ({
+  label: st.label, kind: st.kind, route: pathOf(st).map((c) => (m.components.find((x) => x.id === c)?.label ?? c).split("\n")[0]).join(" → "),
+  ...(st.request ? { request: st.request } : {}), ...(st.response ? { response: st.response } : {}),
+});
+
+/**
+ * Rows aligned by step id. With `beforeModel` (a model written against the base commit) the flow itself is
+ * compared; without it, the overlay decides: added = nothing before, removed = nothing after, modified = same flow,
+ * code changed (the old text is not known, and the row says so).
+ */
+export function buildCompare(model, changes = null, beforeModel = null) {
+  const cs = new Map((changes?.steps ?? []).map((s) => [stepKey(s.useCase, s.step), s]));
+  const mode = beforeModel ? "two-models" : "overlay";
+  const ids = [...model.useCases.map((u) => u.id), ...(beforeModel?.useCases ?? []).map((u) => u.id).filter((id) => !model.useCases.some((u) => u.id === id))];
+  const useCases = ids.map((id) => {
+    const a = model.useCases.find((u) => u.id === id), b = beforeModel ? beforeModel.useCases.find((u) => u.id === id) : a;
+    const A = a?.steps ?? [], B = b?.steps ?? [];
+    const rows = [];
+    if (beforeModel) {
+      const aIds = new Set(A.map((s) => s.id)), bIds = new Set(B.map((s) => s.id));
+      const commonB = B.filter((s) => aIds.has(s.id)).map((s) => s.id), commonA = A.filter((s) => bIds.has(s.id)).map((s) => s.id);
+      const orderMoved = new Set(commonA.filter((sid, i) => commonB[i] !== sid));
+      for (const sa of A) {
+        const sb = B.find((s) => s.id === sa.id);
+        const ch = cs.get(stepKey(id, sa.id));
+        if (!sb) { rows.push({ id: sa.id, status: "added", before: null, after: cell(model, sa), note: "This step is not in the model before the change." }); continue; }
+        const diffs = FLOW_FIELDS.filter((k) => (sa[k] ?? "") !== (sb[k] ?? "")).concat((sa.via ?? []).join(",") !== (sb.via ?? []).join(",") ? ["via"] : []);
+        const status = diffs.length ? "modified" : orderMoved.has(sa.id) ? "moved" : ch ? "modified" : "same";
+        rows.push({
+          id: sa.id, status, before: cell(beforeModel, sb), after: cell(model, sa),
+          ...(diffs.length ? { fields: diffs, note: `Changed fields: ${diffs.join(", ")}` } : orderMoved.has(sa.id) ? { note: "The step order changed." } : ch ? { note: ch.note } : {}),
+        });
+        // removed before-steps are inserted right after their nearest earlier common step
+        const idxB = B.findIndex((s) => s.id === sa.id);
+        for (let k = idxB + 1; k < B.length && !aIds.has(B[k].id); k++) rows.push({ id: B[k].id, status: "removed", before: cell(beforeModel, B[k]), after: null, note: "This step is not in the model after the change." });
+      }
+      // before-steps that open the use case, before any common step
+      const lead = [];
+      for (let k = 0; k < B.length && !aIds.has(B[k].id); k++) lead.push({ id: B[k].id, status: "removed", before: cell(beforeModel, B[k]), after: null, note: "This step is not in the model after the change." });
+      rows.unshift(...lead);
+    } else {
+      for (const st of A) {
+        const ch = cs.get(stepKey(id, st.id));
+        if (!ch) rows.push({ id: st.id, status: "same", before: cell(model, st), after: cell(model, st) });
+        else if (ch.change === "added") rows.push({ id: st.id, status: "added", before: null, after: cell(model, st), note: ch.note });
+        else if (ch.change === "removed") rows.push({ id: st.id, status: "removed", before: cell(model, st), after: null, note: ch.note });
+        else rows.push({ id: st.id, status: "modified", before: cell(model, st), after: cell(model, st), note: `${ch.note} (the model has no earlier version, so the flow is shown unchanged)`, codeOnly: true });
+      }
+    }
+    // overlay mode: the "before" path is the after path without the steps this work added
+    let pathBefore, pathAfter = a ? usePath(model, a) : [];
+    if (beforeModel) pathBefore = b ? usePath(beforeModel, b) : [];
+    else pathBefore = a ? usePath(model, { ...a, steps: a.steps.filter((s) => cs.get(stepKey(id, s.id))?.change !== "added") }) : [];
+    const changed = rows.filter((r) => r.status !== "same").length;
+    return {
+      id, title: (a ?? b).title, trigger: (a ?? b).trigger, state: !a ? "removed" : !b ? "added" : changed ? "changed" : "same",
+      pathBefore, pathAfter,
+      pathLabels: Object.fromEntries([...model.components, ...(beforeModel?.components ?? [])].map((c) => [c.id, c.label.split("\n")[0]])),
+      rows, changedRows: changed,
+    };
+  });
+  const sum = (st) => useCases.reduce((n, u) => n + u.rows.filter((r) => r.status === st).length, 0);
+  return { mode, useCases, summary: { useCases: useCases.filter((u) => u.state !== "same").length, added: sum("added"), removed: sum("removed"), modified: sum("modified"), moved: sum("moved") } };
+}
+
+// ───────────────────────────── C1: intent check ─────────────────────────────
+
+const CHECKS = ["step", "absent", "order"];
+const MATCH_KEYS = ["kind", "from", "to", "with", "table", "op", "text"];
+
+/** a matcher is a plain object; `text` is a list of alternatives joined by | (case-insensitive substring, no regex) */
+function validateMatcher(m, w, errors, model) {
+  if (!isObj(m)) return errors.push(`${w}: must be an object with at least one of kind/from/to/with/table/op/text`);
+  for (const k of Object.keys(m)) if (!MATCH_KEYS.includes(k)) errors.push(`${w}.${k}: unknown condition (${MATCH_KEYS.join("|")})`);
+  if (!MATCH_KEYS.some((k) => m[k] !== undefined)) errors.push(`${w}: has no condition`);
+  if (m.kind !== undefined && !["request", "response", "call", "internal"].includes(m.kind)) errors.push(`${w}.kind: request|response|call|internal`);
+  for (const k of ["from", "to", "with"]) if (m[k] !== undefined && !model.components.some((c) => c.id === m[k])) errors.push(`${w}.${k}: component not in the model (${m[k]})`);
+  if (m.op !== undefined && !["read", "insert", "update", "upsert", "delete"].includes(m.op)) errors.push(`${w}.op: read|insert|update|upsert|delete`);
+  if (m.table !== undefined && !isStr(m.table, 80)) errors.push(`${w}.table: 1-80 characters`);
+  if (m.text !== undefined && !isStr(m.text, 120)) errors.push(`${w}.text: 1-120 characters (separate alternatives with |)`);
+}
+
+export function validateIntent(intent, model) {
+  const errors = [];
+  if (!isObj(intent)) return ["intent: must be an object"];
+  if (intent.schemaVersion !== 1) errors.push("intent.schemaVersion: 1");
+  if (!isStr(intent.title, 160)) errors.push("intent.title: 1-160 characters (what the work set out to build)");
+  if (intent.source !== undefined && !isStr(intent.source, 300)) errors.push("intent.source: 1-300 characters (where the plan lives)");
+  if (!Array.isArray(intent.expectations) || intent.expectations.length === 0 || intent.expectations.length > 60) return [...errors, "intent.expectations: an array of 1-60 items"];
+  const seen = new Set();
+  intent.expectations.forEach((e, i) => {
+    const w = `intent.expectations[${i}]`;
+    if (!isObj(e)) return errors.push(`${w}: must be an object`);
+    if (!/^[a-z0-9][a-z0-9-]{0,40}$/.test(e.id ?? "")) errors.push(`${w}.id: lowercase letters, digits and - (1-41 characters)`);
+    else if (seen.has(e.id)) errors.push(`${w}.id: duplicate ${e.id}`);
+    seen.add(e.id);
+    if (!isStr(e.text, 300)) errors.push(`${w}.text: 1-300 characters (the planner's own words)`);
+    if (e.useCase !== undefined && !model.useCases.some((u) => u.id === e.useCase)) errors.push(`${w}.useCase: use case not in the model (${e.useCase})`);
+    if (e.check === undefined) return; // allowed: stays `unknown`
+    const c = e.check;
+    if (!isObj(c) || !CHECKS.includes(c.type)) return errors.push(`${w}.check.type: ${CHECKS.join("|")}`);
+    if (e.useCase === undefined) errors.push(`${w}.useCase: required when check is given`);
+    if (c.type === "order") {
+      for (const k of Object.keys(c)) if (!["type", "first", "then"].includes(k)) errors.push(`${w}.check.${k}: unknown field`);
+      validateMatcher(c.first, `${w}.check.first`, errors, model); validateMatcher(c.then, `${w}.check.then`, errors, model);
+    } else {
+      for (const k of Object.keys(c)) if (!["type", "match"].includes(k)) errors.push(`${w}.check.${k}: unknown field`);
+      validateMatcher(c.match, `${w}.check.match`, errors, model);
+    }
+  });
+  return errors;
+}
+
+function stepMatches(model, st, m) {
+  if (m.kind !== undefined && st.kind !== m.kind) return false;
+  if (m.from !== undefined && st.from !== m.from) return false;
+  if (m.to !== undefined && st.to !== m.to) return false;
+  if (m.with !== undefined && !pathOf(st).includes(m.with)) return false;
+  if (m.table !== undefined || m.op !== undefined) {
+    const hit = (st.data ?? []).some((d) => (m.table === undefined || d.table === m.table) && (m.op === undefined || d.op === m.op));
+    if (!hit) return false;
+  }
+  if (m.text !== undefined) {
+    const hay = [st.label, st.narration, st.request, st.response, ...(st.data ?? []).map((d) => `${d.table} ${(d.columns ?? []).join(" ")}`)].filter(Boolean).join(" ").toLowerCase();
+    if (!m.text.toLowerCase().split("|").map((t) => t.trim()).filter(Boolean).some((t) => hay.includes(t))) return false;
+  }
+  return true;
+}
+
+/**
+ * Status per expectation: met (the model shows it, with the steps as proof), unmet (the use case exists but the
+ * model shows no such step / the opposite), unknown (no mechanical check, or nothing to compare).
+ * `touched` marks expectations whose proof steps were changed by this work, so the planner re-reads them.
+ * `uncovered` = changed steps that no expectation points at (candidates for scope drift; a human decides).
+ */
+export function checkIntent(model, intent, changes = null) {
+  const cs = new Map((changes?.steps ?? []).map((s) => [stepKey(s.useCase, s.step), s]));
+  const proofOf = (uc, st) => ({ useCase: uc.id, step: st.id, label: st.label, evidence: evText(st), change: cs.get(stepKey(uc.id, st.id))?.change ?? null });
+  const results = intent.expectations.map((e) => {
+    const base = { id: e.id, text: e.text, ...(e.useCase ? { useCase: e.useCase } : {}) };
+    if (!e.check) return { ...base, status: "unknown", reason: "No automatic check. Add a check that names the model step that proves it, or have a person confirm it.", proof: [] };
+    const uc = model.useCases.find((u) => u.id === e.useCase);
+    const find = (m) => uc.steps.filter((s) => stepMatches(model, s, m));
+    let status, reason, proof = [];
+    if (e.check.type === "step") {
+      const hit = find(e.check.match);
+      status = hit.length ? "met" : "unmet"; proof = hit.map((s) => proofOf(uc, s));
+      reason = hit.length ? `${hit.length} matching ${hit.length === 1 ? "step" : "steps"}.` : "No step of this use case matches.";
+    } else if (e.check.type === "absent") {
+      const hit = find(e.check.match);
+      status = hit.length ? "unmet" : "met"; proof = hit.map((s) => proofOf(uc, s));
+      reason = hit.length ? "A step that should not exist is there." : "No step matches (as intended).";
+    } else {
+      const f = find(e.check.first), t = find(e.check.then);
+      const idx = (s) => uc.steps.indexOf(s);
+      if (!f.length || !t.length) {
+        status = "unmet"; proof = [...f, ...t].map((s) => proofOf(uc, s));
+        reason = `This use case has no ${!f.length ? "step that should come first" : "step that should come later"}.`;
+      } else if (f.some((a) => t.every((b) => idx(a) < idx(b)))) {
+        status = "met"; proof = [...f, ...t].map((s) => proofOf(uc, s)); reason = "The step that should come first comes before the later one.";
+      } else {
+        status = "unmet"; proof = [...f, ...t].map((s) => proofOf(uc, s)); reason = "The order is reversed, or the earlier step is missing.";
+      }
+    }
+    return { ...base, status, reason, proof, touched: proof.some((p) => p.change) };
+  });
+  const referenced = new Set(results.flatMap((r) => r.proof.map((p) => stepKey(p.useCase, p.step))));
+  // an expectation also claims its whole use case's changed steps when it has no check but names the use case
+  for (const e of intent.expectations) if (e.useCase && !e.check) for (const s of changes?.steps ?? []) if (s.useCase === e.useCase) referenced.add(stepKey(s.useCase, s.step));
+  const stepOf = (k) => { const [u, s] = k.split("/"); const uc = model.useCases.find((x) => x.id === u); return { uc, st: uc?.steps.find((x) => x.id === s) }; };
+  const uncovered = (changes?.steps ?? []).filter((s) => !referenced.has(stepKey(s.useCase, s.step))).map((s) => {
+    const { uc, st } = stepOf(stepKey(s.useCase, s.step));
+    return { useCase: s.useCase, step: s.step, label: st?.label ?? s.step, useCaseTitle: uc?.title ?? s.useCase, change: s.change, evidence: st ? evText(st) : "" };
+  });
+  const count = (k) => results.filter((r) => r.status === k).length;
+  return { title: intent.title, source: intent.source ?? null, results, uncovered, summary: { total: results.length, met: count("met"), unmet: count("unmet"), unknown: count("unknown"), touched: results.filter((r) => r.touched).length, uncovered: uncovered.length, changedSteps: (changes?.steps ?? []).length } };
+}
+
+// ───────────────────────────── C5: regression map ─────────────────────────────
+
+/**
+ * Other use cases that share something the change touched:
+ *  - table   a changed step reads/writes a table another use case also uses
+ *  - endpoint / part / wire   a changed detail item (own evidence changed) that a step of another use case passes
+ *  - component   a component whose own evidence (start-up/config) changed and the use case passes through it
+ * `direct` = the use case holds a changed step itself. Components that are merely endpoints of a changed step
+ * are NOT used as a link (every use case passes the API: that would flag everything).
+ */
+export function buildImpact(model, changes = null, tests = null) {
+  const csteps = changes?.steps ?? [];
+  const changedKeys = new Set(csteps.map((s) => stepKey(s.useCase, s.step)));
+  const info = new Map(model.useCases.map((u) => [u.id, { direct: [], reasons: [] }]));
+  const stepOf = (uid, sid) => model.useCases.find((u) => u.id === uid)?.steps.find((s) => s.id === sid);
+  for (const c of csteps) info.get(c.useCase)?.direct.push({ step: c.step, change: c.change, label: stepOf(c.useCase, c.step)?.label ?? c.step });
+
+  // what the changed steps touch
+  const touchedTables = new Map(), touchedEndpoints = new Map();
+  for (const c of csteps) {
+    const st = stepOf(c.useCase, c.step);
+    for (const d of st?.data ?? []) touchedTables.set(`${d.store}.${d.table}`, [...(touchedTables.get(`${d.store}.${d.table}`) ?? []), { useCase: c.useCase, step: c.step, op: d.op }]);
+    for (const e of st?.endpoints ?? []) touchedEndpoints.set(e, [...(touchedEndpoints.get(e) ?? []), { useCase: c.useCase, step: c.step }]);
+  }
+  const detailHits = new Map((changes?.details ?? []).map((d) => [`${d.component}|${d.kind}|${d.id}`, d]));
+  const strongComps = new Set((changes?.components ?? []).filter((c) => c.note.startsWith(COMPONENT_NOTE)).map((c) => c.id));
+
+  for (const u of model.useCases) {
+    const r = info.get(u.id);
+    for (const st of u.steps) {
+      const here = { useCase: u.id, step: st.id, label: st.label };
+      const own = changedKeys.has(stepKey(u.id, st.id)); // a changed step already explains its own parts, wires and endpoints
+      for (const d of st.data ?? []) {
+        const k = `${d.store}.${d.table}`;
+        const src = (touchedTables.get(k) ?? []).filter((x) => x.useCase !== u.id);
+        if (src.length) r.reasons.push({ kind: "table", ref: k, ...here, text: `Does ${d.op} on table ${k}, the same table as the changed ${src.map((x) => `${x.useCase}/${x.step} (${x.op})`).join(", ")}.` });
+        if (!own && detailHits.has(`${d.store}|table|${d.table}`)) r.reasons.push({ kind: "table", ref: k, ...here, text: `The definition (schema) evidence of table ${k} changed in this work.` });
+      }
+      for (const e of st.endpoints ?? []) {
+        const src = (touchedEndpoints.get(e) ?? []).filter((x) => x.useCase !== u.id);
+        if (src.length) r.reasons.push({ kind: "endpoint", ref: e, ...here, text: `Calls the external endpoint ${e}, the same call as the changed ${src.map((x) => `${x.useCase}/${x.step}`).join(", ")}.` });
+        const [c, id] = e.split("/");
+        if (!own && detailHits.has(`${c}|endpoint|${id}`)) r.reasons.push({ kind: "endpoint", ref: e, ...here, text: `The definition evidence of endpoint ${e} changed in this work.` });
+      }
+      const trace = st.trace ?? [];
+      trace.forEach((p, i) => {
+        const [c, id] = p.split("/");
+        if (!own && detailHits.has(`${c}|part|${id}`)) r.reasons.push({ kind: "part", ref: p, ...here, text: `Passes the part ${p}, whose evidence code changed in this work.` });
+        const nx = trace[i + 1];
+        if (!own && nx && nx.split("/")[0] === c && detailHits.has(`${c}|wire|${id}>${nx.split("/")[1]}`)) r.reasons.push({ kind: "wire", ref: `${p}>${nx}`, ...here, text: `Passes the wire ${p} → ${nx}, whose evidence code changed in this work.` });
+      });
+      for (const c of new Set(pathOf(st))) if (!own && strongComps.has(c)) r.reasons.push({ kind: "component", ref: c, ...here, text: `The component ${c}'s own evidence code (start-up, configuration) changed in this work.` });
+    }
+  }
+
+  const testFiles = new Set(tests?.changedTests ?? []);
+  const items = [];
+  for (const u of model.useCases) {
+    const r = info.get(u.id);
+    // one reason per (kind, ref, step) is enough
+    const seen = new Set(), reasons = r.reasons.filter((x) => { const k = `${x.kind}|${x.ref}|${x.step}`; if (seen.has(k)) return false; seen.add(k); return true; });
+    if (!r.direct.length && !reasons.length) continue;
+    const found = tests?.byUseCase?.[u.id];
+    const t = !tests ? { state: "unknown", files: [], note: "The repository was not read, so tests were not looked for." }
+      : found?.length ? { state: found.some((f) => testFiles.has(f.file)) ? "covered-changed" : "covered", files: found, note: found.some((f) => testFiles.has(f.file)) ? "A test that mentions this path changed in this work too." : "A test mentions this path, but it did not change in this work." }
+      : { state: "none-found", files: [], note: "No test file mentions this path (a guess from path strings: tests that name it differently are missed)." };
+    items.push({
+      id: u.id, title: u.title, trigger: u.trigger, relation: r.direct.length ? "direct" : "indirect",
+      direct: r.direct, reasons, tests: t,
+      // what to re-check by hand: the steps that moved, or the steps that share the changed thing
+      recheck: [...new Set([...r.direct.map((d) => d.step), ...reasons.map((x) => x.step)])].map((sid) => ({ step: sid, label: stepOf(u.id, sid)?.label ?? sid })),
+    });
+  }
+  const rank = (i) => (i.relation === "direct" ? 0 : 2) + (i.tests.state === "none-found" ? 0 : i.tests.state === "unknown" ? 0 : 1);
+  items.sort((a, b) => rank(a) - rank(b));
+  const withoutTests = items.filter((i) => i.tests.state === "none-found").length;
+  return {
+    useCases: items,
+    summary: { direct: items.filter((i) => i.relation === "direct").length, indirect: items.filter((i) => i.relation === "indirect").length, withoutTests, changedSteps: changedKeys.size, testsKnown: !!tests },
+  };
+}
+
+/** `/api/orders` style path tokens in a trigger line ("GET /api/auth/start → provider → GET /api/auth/callback" has two) */
+export function triggerPaths(trigger) {
+  return [...new Set([...String(trigger ?? "").matchAll(/\/[A-Za-z0-9_\-./{}:]*[A-Za-z0-9_}]/g)].map((m) => m[0]))].filter((p) => p.length > 1);
+}
+
+/**
+ * Test files that mention a use case's route. `files` = [{path, text}] of test files at head;
+ * `changedTests` = test files the diff touched. A path counts at a boundary (`/api/orders` matches `/api/orders/1`
+ * and `"/api/orders"`, not `/api/orders-archive`). Route parameters (`:id`, `{id}`) cut the literal at the parameter.
+ */
+export function discoverTests(model, files, changedTests = []) {
+  const byUseCase = {};
+  for (const u of model.useCases) {
+    const paths = triggerPaths(u.trigger).map((p) => p.split(/\/[:{]/)[0]).filter((p) => p.length > 1);
+    const hits = [];
+    for (const f of files) {
+      const n = paths.filter((p) => { let i = f.text.indexOf(p); while (i >= 0) { const nx = f.text[i + p.length]; if (!nx || !/[A-Za-z0-9_-]/.test(nx)) return true; i = f.text.indexOf(p, i + 1); } return false; });
+      if (n.length) hits.push({ file: f.path, paths: n });
+    }
+    byUseCase[u.id] = hits;
+  }
+  return { byUseCase, changedTests };
+}
+
+export const isTestFile = (path) => ignoreReason(path) === "test" && !/(^|\/)fixtures\//i.test(path);
+
+// ───────────────────────────── bundle ─────────────────────────────
+
+export function buildReview(model, changes, { beforeModel = null, intent = null, tests = null } = {}) {
+  const review = {};
+  if (changes || beforeModel) review.compare = buildCompare(model, changes, beforeModel);
+  if (intent) review.intent = checkIntent(model, intent, changes);
+  if (changes) review.impact = buildImpact(model, changes, tests);
+  return Object.keys(review).length ? review : null;
+}
+

package/src/scan.js

@@ -0,0 +1,255 @@
+// Candidate finder for drafting a model. Output is a list of *leads* with file:line, not facts:
+// the author must read the code and write evidence themselves. Read-only; uses `git ls-files`.
+//
+// Stacks understood: Node (Express, Hono, Fastify, Koa, Next, NestJS), Python (FastAPI, Flask, Django),
+// Go (net/http, chi, gin, echo), Java (Spring annotations), plus infra files (nginx, Caddy, Ingress, compose, wrangler).
+import { execFileSync } from "node:child_process";
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+const SKIP = /(^|\/)(node_modules|dist|build|out|\.git|vendor|coverage|\.wrangler|\.next|\.astro|\.venv|venv|__pycache__|target)\//;
+const CODE = /\.(m?[jt]sx?|py|go|rs|java|kt|rb|php|cs|sql|toml|ya?ml|jsonc?|astro|vue|svelte|conf|hcl)$|(^|\/)Caddyfile$/i;
+const TESTISH = /(^|\/)(tests?|__tests__|e2e|fixtures)\/|\.(test|spec)\.|_test\.go$|(^|\/)test_[^/]+\.py$/i;
+const CONFIG_NAMES = /(^|\/)(wrangler\.(toml|jsonc?)|docker-compose[^/]*\.ya?ml|compose\.ya?ml|Dockerfile[^/]*|serverless\.ya?ml|vercel\.json|fly\.toml|netlify\.toml|_routes\.json|_worker\.js|openapi\.(json|ya?ml)|package\.json|go\.mod|requirements[^/]*\.txt|pyproject\.toml|Caddyfile|nginx[^/]*\.conf|[^/]+\.tf)$/;
+
+/* ---------- stack ---------- */
+const LANG_BY_EXT = { js: "javascript", mjs: "javascript", cjs: "javascript", jsx: "javascript", ts: "typescript", tsx: "typescript", py: "python", go: "go", java: "java", kt: "kotlin", rb: "ruby", rs: "rust", php: "php", cs: "csharp" };
+// package name (npm / pip / go module fragment) -> label
+const LIBS = {
+  express: "express", hono: "hono", fastify: "fastify", koa: "koa", next: "next", "@nestjs/core": "nestjs", "@hapi/hapi": "hapi", restify: "restify", nuxt: "nuxt", "@sveltejs/kit": "sveltekit", "itty-router": "itty-router",
+  pg: "pg", mysql2: "mysql2", "better-sqlite3": "better-sqlite3", sqlite3: "sqlite3", mongoose: "mongoose", mongodb: "mongodb", ioredis: "ioredis", redis: "redis", "@prisma/client": "prisma", "drizzle-orm": "drizzle", typeorm: "typeorm", sequelize: "sequelize", knex: "knex", "@libsql/client": "libsql", axios: "axios", got: "got",
+  fastapi: "fastapi", flask: "flask", django: "django", starlette: "starlette", aiohttp: "aiohttp", tornado: "tornado", sanic: "sanic", bottle: "bottle",
+  sqlalchemy: "sqlalchemy", psycopg2: "psycopg2", "psycopg2-binary": "psycopg2", psycopg: "psycopg", asyncpg: "asyncpg", pymysql: "pymysql", pymongo: "pymongo", httpx: "httpx", requests: "requests",
+  "gin-gonic/gin": "gin", "labstack/echo": "echo", "go-chi/chi": "chi", "gorilla/mux": "gorilla-mux", "gofiber/fiber": "fiber", "gorm.io/gorm": "gorm", "jackc/pgx": "pgx", "lib/pq": "pq", "redis/go-redis": "go-redis", "go-redis/redis": "go-redis",
+};
+const IMPORT_LIBS = [
+  /(?:require\(\s*|from\s+|import\s+)["'](express|hono|fastify|koa|next|@nestjs\/core|pg|mysql2|better-sqlite3|sqlite3|mongoose|mongodb|ioredis|redis|axios|got)["']/g,
+  /^\s*(?:from|import)\s+(fastapi|flask|django|starlette|aiohttp|sqlalchemy|psycopg2?|asyncpg|pymysql|pymongo|httpx|requests)\b/gm,
+];
+
+// standard-library servers (no framework to name)
+const STD_SERVERS = [
+  [/(?:from\s+|require\(\s*)["'](?:node:)?https?["']/, "node:http", /\.(m?[jt]sx?)$/],
+  [/^\s*"net\/http"|^\s*import\s+"net\/http"|\bhttp\.NewServeMux\(|\bhttp\.ListenAndServe\(/m, "net/http", /\.go$/],
+  [/^\s*(?:from|import)\s+http\.server\b/m, "http.server", /\.py$/],
+];
+
+function detectManifestLibs(file, text, add) {
+  const base = file.slice(file.lastIndexOf("/") + 1);
+  if (base === "package.json") {
+    try {
+      const j = JSON.parse(text);
+      for (const k of Object.keys({ ...j.dependencies, ...j.devDependencies, ...j.peerDependencies })) if (LIBS[k]) add(LIBS[k]);
+    } catch { /* not valid json */ }
+  } else if (/^requirements.*\.txt$|^pyproject\.toml$|^Pipfile$/.test(base)) {
+    for (const ln of text.split("\n")) {
+      const m = /^\s*["']?([A-Za-z0-9_.-]+)/.exec(ln);
+      if (m && LIBS[m[1].toLowerCase()]) add(LIBS[m[1].toLowerCase()]);
+      for (const k of Object.keys(LIBS)) if (/^[a-z0-9_-]+$/.test(k) && new RegExp(`["']${k}[\\s>=<~!\\]"']`, "i").test(ln)) add(LIBS[k]);
+    }
+  } else if (base === "go.mod") {
+    for (const [k, v] of Object.entries(LIBS)) if ((k.includes("/") || k.includes(".")) && text.includes(k)) add(v);
+  }
+}
+
+/* ---------- route leads ---------- */
+const METHODS = "get|post|put|patch|delete|all|options|head";
+const ROUTER_NAME = /^(app|router|api|server|fastify|hono|koa|route|routes|r|e|g|mux|engine|group|v\d+|\w*Router|\w*[Aa]pp|\w*Routes?)$/;
+const RE_JS_ROUTE = new RegExp(`([A-Za-z_$][\\w$]*)\\.(${METHODS})\\(\\s*(["'\`])(\\/[^"'\`]*)\\3`, "i");
+const RE_ROUTE_CALL = /\.route\(\s*["'`](\/[^"'`]*)["'`]/;
+const RE_GO_HANDLE = /\.(?:HandleFunc|Handle)\(\s*"([^"]+)"/;
+const RE_GO_VERB = /\.(Get|Post|Put|Patch|Delete|Options|Head|GET|POST|PUT|PATCH|DELETE|OPTIONS|HEAD|Any|ANY)\(\s*"(\/[^"]*)"/;
+const RE_PY_DECO = /@[\w.]+\.(get|post|put|patch|delete|route|api_route|websocket)\(\s*["']([^"']*)["']/;
+const RE_PY_METHODS = /methods\s*=\s*\[([^\]]*)\]/;
+const RE_DJANGO = /\b(?:re_)?path\(\s*r?["']([^"']*)["']\s*,/;
+const RE_SPRING = /@(Get|Post|Put|Patch|Delete|Request)Mapping\(\s*(?:value\s*=\s*)?["']([^"']+)["']/;
+const RE_NEST = /@(Get|Post|Put|Patch|Delete|All|Options|Head)\(\s*(?:["'`]([^"'`]*)["'`])?\s*\)/;
+
+// hand-written routers: a string literal that is exactly "METHOD /path" (switch/case, key === "GET /x", route tables)
+const RE_VERB_LITERAL = /["'`](GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS) (\/[^\s"'`]*)["'`]/;
+
+function routeFromLine(file, ln, fileHasMethod = false) {
+  return routeByFramework(file, ln) ?? literalRoute(file, ln) ?? dispatchRoute(file, ln, fileHasMethod);
+}
+// one handler that branches on the HTTP method (Go stdlib, Node http, Python http.server / hand-rolled)
+function dispatchRoute(file, ln, fileHasMethod) {
+  let m;
+  if (file.endsWith(".go") && (m = /\bcase\s+http\.Method(Get|Post|Put|Patch|Delete|Head|Options)\b|\.Method\s*==\s*http\.Method(Get|Post|Put|Patch|Delete)\b/.exec(ln)))
+    return { method: (m[1] ?? m[2]).toUpperCase(), path: "(method dispatch in one handler)" };
+  if (/\.(m?[jt]sx?)$/.test(file) && fileHasMethod && (m = /\bcase\s+["'](GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)["']\s*:/.exec(ln)))
+    return { method: m[1], path: "(method dispatch in one handler)" };
+  if (file.endsWith(".py") && (m = /\.method\s*(?:==|in)\s*[\(\[]?\s*["'](GET|POST|PUT|PATCH|DELETE)["']/.exec(ln)))
+    return { method: m[1], path: "(method dispatch in one handler)" };
+  return null;
+}
+function literalRoute(file, ln) {
+  if (!/\.(m?[jt]sx?|py|go|java|kt|rb|php|cs)$/.test(file)) return null;
+  const m = RE_VERB_LITERAL.exec(ln);
+  return m ? { method: m[1], path: m[2] } : null;
+}
+
+function routeByFramework(file, ln) {
+  const isGo = file.endsWith(".go"), isPy = file.endsWith(".py"), isJs = /\.(m?[jt]sx?|vue|svelte|astro)$/.test(file);
+  let m;
+  if (isPy) {
+    if ((m = RE_PY_DECO.exec(ln))) {
+      const verb = m[1].toLowerCase();
+      let method = verb === "route" || verb === "api_route" ? "ANY" : verb.toUpperCase();
+      const ms = RE_PY_METHODS.exec(ln);
+      if (ms) method = ms[1].replace(/["'\s]/g, "").toUpperCase() || method;
+      return { method, path: m[2] };
+    }
+    if (/urlpatterns|path\(|re_path\(/.test(ln) && (m = RE_DJANGO.exec(ln)) && /urls?\.py$|urlpatterns/.test(file + ln)) return { method: "ANY", path: m[1] };
+    return null;
+  }
+  if (isGo) {
+    if ((m = RE_GO_HANDLE.exec(ln))) {
+      const mm = /^(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\s+(\/.*)$/.exec(m[1]);
+      return mm ? { method: mm[1], path: mm[2] } : { method: "ANY", path: m[1] };
+    }
+    if ((m = RE_GO_VERB.exec(ln))) return { method: m[1].toUpperCase(), path: m[2] };
+    return null;
+  }
+  if (file.endsWith(".java") || file.endsWith(".kt")) {
+    return (m = RE_SPRING.exec(ln)) ? { method: m[1] === "Request" ? "ANY" : m[1].toUpperCase(), path: m[2] } : null;
+  }
+  if (isJs) {
+    if ((m = RE_NEST.exec(ln))) return { method: m[1].toUpperCase(), path: m[2] ?? "" };
+    if ((m = RE_JS_ROUTE.exec(ln)) && ROUTER_NAME.test(m[1])) return { method: m[2].toUpperCase(), path: m[4] };
+    if ((m = RE_ROUTE_CALL.exec(ln))) return { method: "ANY", path: m[1] };
+  }
+  return null;
+}
+
+/** Next.js file-based routes: pages/api/** and app/**\/route.(ts|js). Returns [{method,path,line}] */
+function nextRoutes(file, text) {
+  let m = /(?:^|\/)pages\/api\/(.+)\.(?:[mc]?[jt]sx?)$/.exec(file);
+  if (m) return [{ method: "ANY", path: "/api/" + m[1].replace(/\/?index$/, ""), line: 1 }];
+  m = /(?:^|\/)app\/(.+)\/route\.(?:[mc]?[jt]sx?)$/.exec(file) ?? /(?:^|\/)app\/()route\.(?:[mc]?[jt]sx?)$/.exec(file);
+  if (!m) return [];
+  const dir = ("/" + (m[1] ?? "")).replace(/\/\([^/)]+\)/g, "");
+  const out = [];
+  text.split("\n").forEach((ln, i) => {
+    const e = /export\s+(?:async\s+)?(?:function|const)\s+(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\b/.exec(ln);
+    if (e) out.push({ method: e[1], path: dir === "" ? "/" : dir, line: i + 1 });
+  });
+  return out.length ? out : [{ method: "ANY", path: dir || "/", line: 1 }];
+}
+
+/* ---------- other leads ---------- */
+const GATEWAY = [
+  /\bproxy_pass\b/, /\breverse_proxy\b/, /\bNewSingleHostReverseProxy\b|\bReverseProxy\b/, /\bcreateProxyMiddleware\b|\bhttp-proxy\b|\bhttpProxy\b|\bproxyPass\b/,
+  /^\s*kind:\s*Ingress\b|\bIngressRoute\b/, /\bimage:\s*["']?(?:[\w.\/-]*\/)?(?:traefik|nginx|envoyproxy|haproxy|kong|caddy)\b/,
+  /\brewrites\s*\(|\bdestination:\s*["']https?:\/\//, /\baws_api_gateway|AWS::ApiGateway|\bapigateway\b/i,
+  /\bfetch\(\s*[\w.$]+\s*\+\s*(?:req|request)\.(?:url|path)/, /\bconst\s+upstream\b|\bupstream\s*=/,
+];
+const DATA = [
+  /\.(prepare|query|execute|exec)\(\s*[`"']\s*(SELECT|INSERT|UPDATE|DELETE|CREATE|ALTER)\b/i,
+  /\b(new Pool|createPool|createClient|MongoClient|sqlite3?\.connect|redis\.)/,
+  /(?:require\(\s*|from\s+|import\s+)["'](pg|mysql2?|better-sqlite3|sqlite3|mongoose|mongodb|ioredis|redis|@prisma\/client|drizzle-orm[^"']*|typeorm|sequelize|knex|@libsql\/client|node:sqlite)["']/,
+  /\bnew\s+(Pool|Client|PrismaClient|Redis|DatabaseSync|MongoClient|Sequelize)\(/,
+  /^\s*(?:from|import)\s+(sqlalchemy|psycopg2?|asyncpg|pymysql|pymongo|redis|sqlite3|motor|peewee|tortoise|databases)\b/,
+  /\bcreate_engine\(|\bredis\.(Redis|from_url|StrictRedis)\(|\bsqlite3\.connect\(/,
+  /\bsql\.Open\(|\bgorm\.Open\(|\bpgxpool\.New\(|\bpgx\.Connect\(|\bredis\.NewClient\(|\bmongo\.Connect\(|\bsqlx\.(Connect|Open)\(/,
+  /^\s*image:\s*["']?(?:[\w.\/-]*\/)?(postgres|mysql|mariadb|mongo|redis|memcached|cassandra|clickhouse|elasticsearch|opensearch|rabbitmq|kafka)\b/,
+];
+// binding keys only count inside config files (otherwise `services: Foo[]` type fields match)
+const DATA_CONFIG = /["']?\b(d1_databases|kv_namespaces|r2_buckets|queues|durable_objects|hyperdrive|services)\b["']?\s*[:=\[]/;
+const CONFIG_FILE = /\.(toml|jsonc?|ya?ml)$/i;
+const CLIENT = [
+  /\bfetch\(/, /\baxios(?:\.\w+)?\(/, /\bgot(?:\.(?:get|post|put|patch|delete))?\(\s*["'`\w]/,
+  /\brequests\.(get|post|put|patch|delete|request|Session)\b/, /\bhttpx\.(get|post|put|patch|delete|request|AsyncClient|Client)\b/, /\baiohttp\.ClientSession\b|\burllib\.request\.urlopen\b/,
+  /\bhttp\.(Get|Post|NewRequest|NewRequestWithContext)\(/, /\b(?:RestTemplate|WebClient|HttpClient)\b/, /Net::HTTP/,
+];
+const ENV_NAME = "[A-Z][A-Z0-9_]{1,63}";
+const ENV_READ = [
+  new RegExp(`process\\.env\\.(${ENV_NAME})`, "g"), new RegExp(`process\\.env\\[["'](${ENV_NAME})["']\\]`, "g"),
+  new RegExp(`os\\.environ(?:\\.get)?[\\[(]\\s*["'](${ENV_NAME})["']`, "g"), new RegExp(`os\\.getenv\\(\\s*["'](${ENV_NAME})["']`, "g"),
+  new RegExp(`os\\.Getenv\\(\\s*"(${ENV_NAME})"`, "g"), new RegExp(`Deno\\.env\\.get\\(\\s*["'](${ENV_NAME})["']`, "g"),
+];
+const ENV_ADDRESS = /(URL|URI|HOST|ENDPOINT|ADDR|DSN|ORIGIN|UPSTREAM|BROKER|BACKEND)$|^(DATABASE|DB|REDIS|MONGO|POSTGRES|MYSQL|API|UPSTREAM)_/;
+const ENV_SECRET = /(TOKEN|SECRET|PASSWORD|PASSWD|KEY|CREDENTIAL)/;
+const URLRE = /https?:\/\/([A-Za-z0-9.-]+\.[A-Za-z]{2,})(?::\d+)?[^\s"'`)<>]*/g;
+const NOISE_HOSTS = /(^|\.)(w3\.org|example\.(com|org)|localhost|schema\.org|json-schema\.org|github\.com\/actions|npmjs\.org|mozilla\.org|apache\.org|opensource\.org|creativecommons\.org)$/i;
+
+const PER_FILE_CAP = 4; // one big file must not hide the rest of the repo
+// migration history is schema, not data access; these files also carry URLs that are not outbound calls
+const NOISY_DATA_DIR = /(^|\/)(migrations?|alembic\/versions|db\/migrate|versions)\//i;
+const NOISY_HOST_FILE = /\.(sql|md|mdx|lock|json|svg)$|(^|\/)(\.github|migrations?|alembic|docs?)\/|(^|\/)Dockerfile|\.gen\.[a-z]+$|pre-commit/i;
+
+const clip = (s, n = 140) => { s = s.trim().replace(/\s+/g, " "); return s.length > n ? s.slice(0, n - 1) + "…" : s; };
+
+export function scanRepo(repoPath, { limit = 60 } = {}) {
+  const list = execFileSync("git", ["-C", repoPath, "ls-files", "-z"], { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 })
+    .split("\0").filter(Boolean);
+  const out = { stack: { languages: [], frameworks: [] }, configs: [], routes: [], gateways: [], data: [], outbound: [], outboundEnv: [], clients: [], stats: { files: list.length, scanned: 0 } };
+  const hosts = new Map(), envs = new Map(), langCount = {}, libs = new Set();
+  for (const f of list) {
+    if (SKIP.test(f)) continue;
+    const ext = f.slice(f.lastIndexOf(".") + 1).toLowerCase();
+    if (!TESTISH.test(f) && LANG_BY_EXT[ext]) langCount[LANG_BY_EXT[ext]] = (langCount[LANG_BY_EXT[ext]] ?? 0) + 1;
+    const isConfig = CONFIG_NAMES.test(f) && !/package-lock/.test(f);
+    if (isConfig) out.configs.push({ file: f, line: 1, text: f });
+    if (!CODE.test(f) && !isConfig) continue;
+    if (TESTISH.test(f)) continue;
+    let text;
+    try { if (statSync(join(repoPath, f)).size > 400_000) continue; text = readFileSync(join(repoPath, f), "utf8"); } catch { continue; }
+    out.stats.scanned++;
+    if (isConfig) detectManifestLibs(f, text, (l) => libs.add(l));
+    for (const [re, label, only] of STD_SERVERS) if (only.test(f) && re.test(text)) libs.add(label);
+    for (const re of IMPORT_LIBS) for (const m of text.matchAll(re)) if (LIBS[m[1].toLowerCase()]) libs.add(LIBS[m[1].toLowerCase()]);
+    for (const r of nextRoutes(f, text)) out.routes.push({ file: f, line: r.line, method: r.method, path: r.path, text: `${r.method} ${r.path}  (file-based route)` });
+
+    const lines = text.split("\n");
+    const fileHasMethod = /\.method\b|\bMethod\b/.test(text);
+    const noData = NOISY_DATA_DIR.test(f), noHosts = NOISY_HOST_FILE.test(f);
+    const perFile = { data: 0, clients: 0, gateways: 0 };
+    lines.forEach((ln, i) => {
+      if (ln.length > 600) return;
+      const rt = routeFromLine(f, ln, fileHasMethod);
+      if (rt) out.routes.push({ file: f, line: i + 1, method: rt.method, path: rt.path, text: clip(ln) });
+      const isComment = /^\s*(\/\/|#|\*|\/\*|<!--)/.test(ln);
+      if (perFile.gateways < PER_FILE_CAP && GATEWAY.some((re) => re.test(ln))) { out.gateways.push({ file: f, line: i + 1, text: clip(ln) }); perFile.gateways++; }
+      if (!noData && perFile.data < PER_FILE_CAP && (DATA.some((re) => re.test(ln)) || (CONFIG_FILE.test(f) && DATA_CONFIG.test(ln)))) { out.data.push({ file: f, line: i + 1, text: clip(ln) }); perFile.data++; }
+      if (perFile.clients < PER_FILE_CAP && !isComment && CLIENT.some((re) => re.test(ln))) { out.clients.push({ file: f, line: i + 1, text: clip(ln) }); perFile.clients++; }
+      for (const re of ENV_READ) for (const m of ln.matchAll(re)) {
+        const name = m[1];
+        if (ENV_SECRET.test(name) || !ENV_ADDRESS.test(name) || envs.has(name)) continue;
+        envs.set(name, { file: f, line: i + 1, name, text: clip(ln) });
+      }
+      if (!noHosts && !isComment)
+        for (const m of ln.matchAll(URLRE)) {
+          const h = m[1].toLowerCase();
+          if (NOISE_HOSTS.test(h)) continue;
+          if (!hosts.has(h)) hosts.set(h, { file: f, line: i + 1, text: clip(ln), host: h });
+        }
+    });
+  }
+  out.outbound = [...hosts.values()];
+  out.outboundEnv = [...envs.values()];
+  out.stack.languages = Object.entries(langCount).sort((a, b) => b[1] - a[1]).map(([k]) => k);
+  out.stack.frameworks = [...libs].sort();
+  for (const k of ["configs", "routes", "gateways", "data", "outbound", "outboundEnv", "clients"]) {
+    out[k + "Total"] = out[k].length;
+    out[k] = out[k].slice(0, limit);
+  }
+  return out;
+}
+
+export function formatScan(r) {
+  const line = (x) => `  ${x.file}:${x.line}  ${x.host ? `[${x.host}] ` : x.name ? `[${x.name}] ` : ""}${x.text}`;
+  const sec = (title, hint, items, total) =>
+    [`## ${title} (${total}${total > items.length ? `, 상위 ${items.length}개 표시` : ""}) — ${hint}`, ...items.map(line), ""].join("\n");
+  return [
+    `# nacholens scan — 후보 목록 (사실이 아닙니다. 코드를 직접 읽고 근거를 쓰세요)`,
+    `파일 ${r.stats.files}개 중 ${r.stats.scanned}개 검사`, "",
+    `## 스택 — 언어: ${r.stack.languages.join(", ") || "(없음)"} · 프레임워크/라이브러리: ${r.stack.frameworks.join(", ") || "(없음)"}`, "",
+    sec("설정/배포 파일", "게이트웨이·바인딩·컨테이너 구성을 확인", r.configs, r.configsTotal),
+    sec("라우트 후보", "유즈케이스의 진입 요청(trigger)을 고르는 단서", r.routes, r.routesTotal),
+    sec("게이트웨이 후보", "프록시·리버스 프록시·Ingress·리라이트 — gateway 컴포넌트와 via 의 단서", r.gateways, r.gatewaysTotal),
+    sec("데이터 저장소 후보", "datastore 컴포넌트와 call 단계의 단서 (드라이버 import·연결·SQL·compose 이미지)", r.data, r.dataTotal),
+    sec("바깥으로 나가는 호스트", "external 컴포넌트 후보 (호스트별 첫 위치)", r.outbound, r.outboundTotal),
+    sec("환경변수로 주입되는 주소", "주소가 코드에 없고 설정으로 들어오는 external/내부 호출 (이름만, 값은 보지 않음)", r.outboundEnv, r.outboundEnvTotal),
+    sec("HTTP 클라이언트 호출", "외부/내부 서비스를 부르는 코드 위치 — call 단계의 단서", r.clients, r.clientsTotal),
+  ].join("\n");
+}

package/src/template.js

@@ -0,0 +1,36 @@
+// Empty model template for a repo that has none yet. Every value an author must supply starts
+// with "TODO"; validateModel reports each one with its JSON path, so the error output is the checklist.
+export function makeTemplate({ slug = null, commit, name = null }) {
+  const id = (name ?? "my-product").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").replace(/^[^a-z]+/, "") || "my-product";
+  const ev = (what) => [{ file: `TODO: ${what} 가 있는 파일 (저장소 기준 상대 경로)`, lines: [1, 1], contains: `TODO: 그 줄 범위에 실제로 있는 문자열(선택, 지우면 검사 생략)` }];
+  return {
+    schemaVersion: 1,
+    product: {
+      id,
+      name: `TODO: 제품 이름`,
+      description: `TODO: 한 줄 설명 — 사용자가 무엇을 하는 제품이고 요청이 어디를 거치는지`,
+    },
+    source: { repo: slug ?? `TODO: owner/repo`, commit },
+    components: [
+      { id: "client", kind: "client", label: "TODO: 클라이언트 이름\nTODO: 부제", detail: "TODO: 이 컴포넌트가 하는 일 (코드에서 확인한 것만)", evidence: ev("클라이언트가 API 를 호출하는 코드") },
+      { id: "gateway", kind: "gateway", label: "TODO: 게이트웨이 이름\nTODO: 부제", detail: "TODO: 요청을 어디로 넘기는지 (게이트웨이가 없으면 이 컴포넌트와 연결·via 를 지우세요)", evidence: ev("게이트웨이/프록시 설정·코드") },
+      { id: "server", kind: "service", label: "TODO: 서버 이름\nTODO: 부제", detail: "TODO: 서버가 하는 일", evidence: ev("요청 핸들러 진입점") },
+    ],
+    links: [
+      { a: "client", b: "gateway", label: "TODO: 어떤 통신인지(예: HTTPS /api/*)", evidence: ev("연결을 보여주는 코드·설정") },
+      { a: "gateway", b: "server", label: "TODO: 어떤 통신인지(예: 서비스 바인딩)", evidence: ev("연결을 보여주는 코드·설정") },
+    ],
+    useCases: [
+      {
+        id: "first-use-case",
+        title: "TODO: 유즈케이스 이름 (사용자가 하는 행동, 예: 관리자 로그인)",
+        summary: "TODO: 한두 문장 요약",
+        trigger: "TODO: 진입 요청 (예: GET /api/session)",
+        steps: [
+          { id: "request", kind: "request", from: "client", via: ["gateway"], to: "server", label: "TODO: 짧은 제목", narration: "TODO: 사람이 읽는 문장 — 무슨 일이 일어나는가", request: "TODO: 요청 요약", evidence: ev("이 단계를 보여주는 코드") },
+          { id: "response", kind: "response", from: "server", via: ["gateway"], to: "client", label: "TODO: 짧은 제목", narration: "TODO: 사람이 읽는 문장", response: "TODO: 응답 요약", evidence: ev("응답을 만드는 코드") },
+        ],
+      },
+    ],
+  };
+}