@qualisoft/ai-skills 1.0.0

package/skills/erd-visual/readers/sql.mjs

@@ -0,0 +1,205 @@
+/* DDL SQL 판독기 — CREATE TABLE + FOREIGN KEY
+ *
+ * 관계 근거가 제약조건에 명시돼 있으므로 이 형식은 전부 confidence:'fact' 다.
+ * 추측이 끼어들 자리가 없다. 그래서 가장 먼저 만들었다.
+ *
+ * 읽는 것: CREATE TABLE (인라인 REFERENCES · 테이블 레벨 FOREIGN KEY · PRIMARY KEY),
+ *          ALTER TABLE ADD CONSTRAINT FOREIGN KEY, COMMENT ON.
+ * 못 읽은 문장은 버리지 않고 unparsed 에 남긴다.
+ */
+
+import { emptyIR } from './index.mjs';
+
+/** 문자열 리터럴을 지키면서 주석만 제거한다 */
+function stripComments(src) {
+  let out = '', i = 0, n = src.length;
+  while (i < n) {
+    const c = src[i], d = src[i + 1];
+    if (c === "'" || c === '"' || c === '`') {
+      const q = c;
+      out += c; i++;
+      while (i < n) {
+        out += src[i];
+        if (src[i] === q && src[i - 1] !== '\\') { i++; break; }
+        i++;
+      }
+      continue;
+    }
+    if (c === '-' && d === '-') { while (i < n && src[i] !== '\n') i++; continue; }
+    if (c === '/' && d === '*') { i += 2; while (i < n && !(src[i] === '*' && src[i + 1] === '/')) i++; i += 2; continue; }
+    out += c; i++;
+  }
+  return out;
+}
+
+const unquote = s => (s || '').trim()
+  .replace(/^[`"\[]/, '').replace(/[`"\]]$/, '');
+
+/** schema.table -> {schema, table} */
+function splitName(raw) {
+  const parts = String(raw).trim().split('.').map(unquote).filter(Boolean);
+  if (parts.length >= 2) return { schema: parts[parts.length - 2], table: parts[parts.length - 1] };
+  return { schema: null, table: parts[0] || '' };
+}
+
+/** 여는 괄호 위치에서 짝이 맞는 닫는 괄호를 찾는다 (문자열 무시) */
+function matchParen(src, open) {
+  let depth = 0;
+  for (let i = open; i < src.length; i++) {
+    const c = src[i];
+    if (c === "'" || c === '"' || c === '`') {
+      const q = c; i++;
+      while (i < src.length && !(src[i] === q && src[i - 1] !== '\\')) i++;
+      continue;
+    }
+    if (c === '(') depth++;
+    else if (c === ')') { depth--; if (depth === 0) return i; }
+  }
+  return -1;
+}
+
+/** 괄호 깊이 0 의 콤마로 나눈다 */
+function splitTop(body) {
+  const out = []; let depth = 0, cur = '';
+  for (let i = 0; i < body.length; i++) {
+    const c = body[i];
+    if (c === "'" || c === '"' || c === '`') {
+      const q = c; cur += c; i++;
+      while (i < body.length) { cur += body[i]; if (body[i] === q && body[i - 1] !== '\\') break; i++; }
+      continue;
+    }
+    if (c === '(') depth++;
+    if (c === ')') depth--;
+    if (c === ',' && depth === 0) { out.push(cur); cur = ''; continue; }
+    cur += c;
+  }
+  if (cur.trim()) out.push(cur);
+  return out.map(s => s.trim()).filter(Boolean);
+}
+
+const colList = s => splitTop(s).map(unquote).filter(Boolean);
+
+export function readSql(src, source = 'input.sql') {
+  const ir = emptyIR(source, 'sql');
+  const sql = stripComments(src);
+  const byName = new Map();
+
+  const addRef = (from, col, to, toCol, evidence) => {
+    if (!from || !col || !to) return;
+    ir.refs.push({ from, col, to, toCol: toCol || null, evidence: evidence.replace(/\s+/g, ' ').trim(), confidence: 'fact' });
+  };
+
+  // ── CREATE TABLE ────────────────────────────────────────
+  const reCreate = /CREATE\s+(?:GLOBAL\s+|LOCAL\s+|TEMP(?:ORARY)?\s+|UNLOGGED\s+)*TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?([`"\[\]\w.]+)\s*\(/gi;
+  let m;
+  while ((m = reCreate.exec(sql))) {
+    const open = sql.indexOf('(', m.index + m[0].length - 1);
+    const close = matchParen(sql, open);
+    if (close < 0) { ir.unparsed.push(m[0].trim()); continue; }
+    const { schema, table } = splitName(m[1]);
+    if (!table) continue;
+    const body = sql.slice(open + 1, close);
+    const t = { name: table, group: schema || null, columns: [] };
+    if (byName.has(table)) ir.warnings.push('중복 CREATE TABLE: ' + table);
+    byName.set(table, t);
+
+    for (const item of splitTop(body)) {
+      const head = item.replace(/^\s+/, '');
+      const kw = head.toUpperCase();
+
+      // 테이블 레벨 제약
+      if (/^(CONSTRAINT\b|PRIMARY\s+KEY\b|FOREIGN\s+KEY\b|UNIQUE\b|CHECK\b|KEY\b|INDEX\b)/.test(kw)) {
+        const fk = head.match(/FOREIGN\s+KEY\s*\(([^)]*)\)\s*REFERENCES\s+([`"\[\]\w.]+)\s*(?:\(([^)]*)\))?/i);
+        if (fk) {
+          const cols = colList(fk[1]);
+          const ref = splitName(fk[2]);
+          const rcols = fk[3] ? colList(fk[3]) : [];
+          cols.forEach((c, i) => addRef(table, c, ref.table, rcols[i] || rcols[0] || null, head));
+          continue;
+        }
+        const pk = head.match(/PRIMARY\s+KEY\s*\(([^)]*)\)/i);
+        if (pk) {
+          for (const c of colList(pk[1])) {
+            const col = t.columns.find(x => x.name === c);
+            if (col) { col.pk = true; col.notNull = true; }
+          }
+        }
+        continue;
+      }
+
+      // 컬럼 정의
+      const cm = head.match(/^([`"\[\]\w]+)\s+([\s\S]+)$/);
+      if (!cm) { ir.unparsed.push(head); continue; }
+      const name = unquote(cm[1]);
+      const rest = cm[2];
+      // 타입은 '첫 제약 키워드 앞까지'로 잡는다. 게으른 매칭을 쓰면
+      // `uuid NOT NULL` 에서 타입이 'u' 한 글자로 잘린다 — 실제로 그랬다.
+      // 'character varying(80)', 'double precision' 같은 다단어 타입도 살아야 한다.
+      const STOP = /\b(NOT\s+NULL|NULL|PRIMARY\s+KEY|REFERENCES|DEFAULT|UNIQUE|CHECK|CONSTRAINT|GENERATED|AUTO_INCREMENT|AUTOINCREMENT|IDENTITY|COLLATE|COMMENT|ON\s+UPDATE|ON\s+DELETE)\b/i;
+      const stop = rest.match(STOP);
+      const type = (stop ? rest.slice(0, stop.index) : rest)
+        .trim().replace(/,\s*$/, '').replace(/\s+/g, ' ');
+      const col = {
+        name, type: type || 'unknown',
+        pk: /\bPRIMARY\s+KEY\b/i.test(rest),
+        notNull: /\bNOT\s+NULL\b/i.test(rest) || /\bPRIMARY\s+KEY\b/i.test(rest),
+      };
+      t.columns.push(col);
+
+      // 인라인 REFERENCES
+      const inl = rest.match(/\bREFERENCES\s+([`"\[\]\w.]+)\s*(?:\(([^)]*)\))?/i);
+      if (inl) {
+        const ref = splitName(inl[1]);
+        addRef(table, name, ref.table, inl[2] ? colList(inl[2])[0] : null, name + ' ' + rest);
+      }
+    }
+  }
+
+  // ── ALTER TABLE ... FOREIGN KEY ─────────────────────────
+  const reAlter = /ALTER\s+TABLE\s+(?:ONLY\s+)?([`"\[\]\w.]+)([\s\S]*?);/gi;
+  while ((m = reAlter.exec(sql))) {
+    const { table } = splitName(m[1]);
+    const tail = m[2];
+    const reFk = /FOREIGN\s+KEY\s*\(([^)]*)\)\s*REFERENCES\s+([`"\[\]\w.]+)\s*(?:\(([^)]*)\))?/gi;
+    let f;
+    while ((f = reFk.exec(tail))) {
+      const cols = colList(f[1]);
+      const ref = splitName(f[2]);
+      const rcols = f[3] ? colList(f[3]) : [];
+      cols.forEach((c, i) =>
+        addRef(table, c, ref.table, rcols[i] || rcols[0] || null, 'ALTER TABLE ' + m[1] + ' ' + f[0]));
+    }
+    const pk = tail.match(/PRIMARY\s+KEY\s*\(([^)]*)\)/i);
+    if (pk && byName.has(table)) {
+      for (const c of colList(pk[1])) {
+        const col = byName.get(table).columns.find(x => x.name === c);
+        if (col) { col.pk = true; col.notNull = true; }
+      }
+    }
+  }
+
+  // ── COMMENT ON — 카드에 보일 한글명으로 쓴다 ─────────────
+  const reComment = /COMMENT\s+ON\s+(TABLE|COLUMN)\s+([`"\[\]\w.]+)\s+IS\s+'((?:[^']|'')*)'/gi;
+  while ((m = reComment.exec(sql))) {
+    const text = m[3].replace(/''/g, "'").trim();
+    if (m[1].toUpperCase() === 'TABLE') {
+      const { table } = splitName(m[2]);
+      if (byName.has(table)) byName.get(table).label = text;
+    } else {
+      const parts = String(m[2]).split('.').map(unquote);
+      const cname = parts.pop(), tname = parts.pop();
+      const t = byName.get(tname);
+      const c = t && t.columns.find(x => x.name === cname);
+      if (c) c.note = text;
+    }
+  }
+
+  ir.tables = [...byName.values()];
+
+  // 대상이 정의되지 않은 참조는 버리지 않는다 — 스텁으로 남길 수 있게 표시만 한다
+  const known = new Set(ir.tables.map(t => t.name));
+  for (const r of ir.refs) if (!known.has(r.to)) r.missingTarget = true;
+
+  if (!ir.tables.length) ir.warnings.push('CREATE TABLE 을 하나도 찾지 못했습니다');
+  return ir;
+}

package/skills/erd-visual/readers/xlsx.mjs

@@ -0,0 +1,220 @@
+/* xlsx 판독기 — zip + XML.
+ *
+ * 중요: 엑셀에는 외래키 개념이 없다. 어느 열이 관계 근거인지는 자료마다 다르다.
+ * 그래서 이 판독기는 **시트를 읽어 구조를 보고할 뿐** 스스로 스키마를 만들지 않는다.
+ * 매핑(--map)이 주어졌을 때만 테이블·관계를 뽑는다.
+ * 이걸 자동으로 추측하게 만들면 그럴듯한 거짓 ERD 가 조용히 나온다.
+ */
+
+import { unzip } from './zip.mjs';
+import { emptyIR } from './index.mjs';
+
+const ENT = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" };
+export const unesc = s => String(s).replace(/&(#x?[0-9a-fA-F]+|\w+);/g, (m, e) => {
+  if (e[0] === '#') return String.fromCodePoint(e[1] === 'x' || e[1] === 'X'
+    ? parseInt(e.slice(2), 16) : parseInt(e.slice(1), 10));
+  return ENT[e] ?? m;
+});
+
+/** <t>…</t> 안의 글자를 모두 모은다 (리치 텍스트는 run 으로 쪼개져 있다) */
+function joinT(xml) {
+  let out = '';
+  const re = /<t\b[^>]*>([\s\S]*?)<\/t>|<t\b[^>]*\/>/g;
+  let m;
+  while ((m = re.exec(xml))) out += m[1] ? unesc(m[1]) : '';
+  return out;
+}
+
+function sharedStrings(zip) {
+  if (!zip.has('xl/sharedStrings.xml')) return [];
+  const xml = zip.text('xl/sharedStrings.xml');
+  const out = [];
+  const re = /<si\b[^>]*>([\s\S]*?)<\/si>|<si\b[^>]*\/>/g;
+  let m;
+  while ((m = re.exec(xml))) out.push(m[1] ? joinT(m[1]) : '');
+  return out;
+}
+
+function sheetTargets(zip) {
+  const wb = zip.text('xl/workbook.xml');
+  const rels = zip.has('xl/_rels/workbook.xml.rels') ? zip.text('xl/_rels/workbook.xml.rels') : '';
+  const rmap = new Map();
+  let m;
+  const reRel = /<Relationship\b[^>]*Id="([^"]+)"[^>]*Target="([^"]+)"[^>]*\/?>/g;
+  while ((m = reRel.exec(rels))) rmap.set(m[1], m[2]);
+
+  const out = [];
+  const reSheet = /<sheet\b[^>]*\/?>/g;
+  while ((m = reSheet.exec(wb))) {
+    const tag = m[0];
+    const name = (tag.match(/name="([^"]*)"/) || [, ''])[1];
+    const rid = (tag.match(/r:id="([^"]*)"/) || [, ''])[1];
+    let target = rmap.get(rid) || '';
+    if (!target) continue;
+    target = target.replace(/^\//, '');
+    if (!target.startsWith('xl/')) target = 'xl/' + target.replace(/^\.\//, '');
+    out.push({ name: unesc(name), path: target });
+  }
+  return out;
+}
+
+const colOf = ref => (String(ref).match(/^([A-Z]+)/) || [, ''])[1];
+
+/** 시트를 행 배열로. 각 행은 { A: '값', B: '값' } */
+export function readSheet(zip, sheetPath, ss, limit = Infinity) {
+  const xml = zip.text(sheetPath);
+  const rows = [];
+  const reRow = /<row\b[^>]*>([\s\S]*?)<\/row>|<row\b[^>]*\/>/g;
+  let m;
+  while ((m = reRow.exec(xml)) && rows.length < limit) {
+    const body = m[1] || '';
+    const cells = {};
+    const reCell = /<c\b([^>]*)(?:\/>|>([\s\S]*?)<\/c>)/g;
+    let c;
+    while ((c = reCell.exec(body))) {
+      const attrs = c[1], inner = c[2] || '';
+      const ref = (attrs.match(/r="([A-Z]+\d+)"/) || [, ''])[1];
+      if (!ref) continue;
+      const t = (attrs.match(/t="([^"]*)"/) || [, ''])[1];
+      let val = '';
+      if (t === 's') {
+        const v = inner.match(/<v>([\s\S]*?)<\/v>/);
+        if (v) val = ss[+v[1]] ?? '';
+      } else if (t === 'inlineStr') {
+        val = joinT(inner);
+      } else if (t === 'str') {
+        const v = inner.match(/<v>([\s\S]*?)<\/v>/);
+        val = v ? unesc(v[1]) : '';
+      } else {
+        const v = inner.match(/<v>([\s\S]*?)<\/v>/);
+        val = v ? unesc(v[1]) : '';
+      }
+      cells[colOf(ref)] = String(val).trim();
+    }
+    rows.push(cells);
+  }
+  return rows;
+}
+
+/**
+ * @param buf  파일 버퍼
+ * @param source 표시용 이름
+ * @param opt  { map } — 매핑이 없으면 구조만 보고한다
+ */
+export function readXlsx(buf, source = 'input.xlsx', opt = {}) {
+  const ir = emptyIR(source, 'xlsx');
+  let zip;
+  try { zip = unzip(buf); }
+  catch (e) { ir.warnings.push('열 수 없습니다: ' + e.message); return ir; }
+
+  const ss = sharedStrings(zip);
+  const sheets = [];
+  for (const s of sheetTargets(zip)) {
+    if (!zip.has(s.path)) { ir.warnings.push('시트 파일 없음: ' + s.path); continue; }
+    const rows = readSheet(zip, s.path, ss);
+    const header = rows.length ? rows[0] : {};
+    const cols = Object.keys(header).sort((a, b) => a.length - b.length || (a < b ? -1 : 1));
+    sheets.push({
+      name: s.name,
+      rows: rows.length,
+      dataRows: Math.max(0, rows.length - 1),
+      columns: cols.map(c => ({ col: c, header: header[c] || '' })),
+      sample: rows.slice(1, 4),
+      all: rows,
+    });
+  }
+  ir.sheets = sheets;
+
+  if (!opt.map) {
+    ir.needsMapping = true;
+    ir.warnings.push('엑셀에는 외래키 정보가 없습니다. 어느 열이 무엇인지 정해줘야 테이블·관계를 뽑습니다 '
+      + '(시트 ' + sheets.length + '개: ' + sheets.map(s => s.name + ' ' + s.dataRows + '행').join(', ') + ')');
+    return ir;
+  }
+
+  applyMap(ir, sheets, opt.map);
+  return ir;
+}
+
+/**
+ * 매핑 규격 (map.json)
+ * {
+ *   "entities": { "sheet":"Entities list", "name":"E", "label":"A", "group":"H" },
+ *   "attributes": {
+ *     "sheet":"Metadata", "table":"B", "name":"C", "type":"F", "label":"E",
+ *     "required":"J", "extra":"L",
+ *     "refPattern":"Targets:\\s*(.*)"      // extra 열에서 대상 엔티티를 뽑는 정규식
+ *   }
+ * }
+ */
+export function applyMap(ir, sheets, map) {
+  const find = n => sheets.find(s => s.name === n);
+  const get = (row, col) => (col && row[col] != null ? String(row[col]).trim() : '');
+  const clean = s => s.replace(/_x000D_/g, '').replace(/\r/g, '').trim();
+
+  const tables = new Map();
+
+  if (map.entities) {
+    const sh = find(map.entities.sheet);
+    if (!sh) { ir.warnings.push('시트를 찾지 못함: ' + map.entities.sheet); return ir; }
+    for (const row of sh.all.slice(1)) {
+      const name = get(row, map.entities.name);
+      if (!name) continue;
+      tables.set(name, {
+        name,
+        label: get(row, map.entities.label) || name,
+        group: get(row, map.entities.group) || null,
+        columns: [],
+      });
+    }
+  }
+
+  if (map.attributes) {
+    const sh = find(map.attributes.sheet);
+    if (!sh) { ir.warnings.push('시트를 찾지 못함: ' + map.attributes.sheet); return ir; }
+    const A = map.attributes;
+    const reRef = A.refPattern ? new RegExp(A.refPattern, 's') : null;
+
+    for (const row of sh.all.slice(1)) {
+      const tname = get(row, A.table);
+      const cname = get(row, A.name);
+      if (!tname || !cname) continue;
+      if (!tables.has(tname)) {
+        tables.set(tname, { name: tname, label: tname, group: null, columns: [] });
+      }
+      const t = tables.get(tname);
+      const req = get(row, A.required);
+      const col = {
+        name: cname,
+        type: get(row, A.type) || 'unknown',
+        pk: false,
+        notNull: /Required/i.test(req),
+        note: get(row, A.label) || cname,
+      };
+      t.columns.push(col);
+
+      if (!reRef) continue;
+      const extra = clean(get(row, A.extra));
+      const m = extra.match(reRef);
+      if (!m) continue;
+      const targets = m[1].split('\n').map(x => x.trim()).filter(Boolean);
+      if (targets.length === 1) {
+        ir.refs.push({
+          from: tname, col: cname, to: targets[0], toCol: null,
+          evidence: A.extra + ': ' + extra.slice(0, 120),
+          confidence: 'fact',
+        });
+      } else if (targets.length > 1) {
+        // 다형 참조 — 하나를 고르면 없는 사실을 만드는 것이다. 선을 긋지 않는다.
+        col.note += ' → 다형: ' + (targets.length <= 4 ? targets.join(', ')
+          : targets.slice(0, 4).join(', ') + ' 외 ' + (targets.length - 4));
+        ir.polymorphic = (ir.polymorphic || 0) + 1;
+      }
+    }
+  }
+
+  ir.tables = [...tables.values()];
+  if (ir.polymorphic)
+    ir.warnings.push('다형 참조 ' + ir.polymorphic + '건은 Ref 로 그리지 않고 컬럼 note 에만 적었습니다');
+  return ir;
+}

package/skills/erd-visual/readers/xml.mjs

@@ -0,0 +1,130 @@
+/* XML 판독기.
+ *
+ * XML 에는 표준 스키마 형태가 없다. 자료마다 뜻이 다르므로
+ * 매핑 없이는 **구조만 보고**한다.
+ *
+ * 가장 쓸모 있는 쓰임은 테이블 추출이 아니라 **그룹 힌트**다.
+ * Dynamics SiteMap 처럼 "어느 엔티티가 어느 업무 영역에 속하는가"를 담은 자료가 있으면
+ * 그걸로 TableGroup 을 만들 수 있다. 그룹은 배선 품질과 속도를 크게 좌우한다.
+ */
+
+import { emptyIR } from './index.mjs';
+
+const ENT = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" };
+const unesc = s => String(s).replace(/&(#x?[0-9a-fA-F]+|\w+);/g, (m, e) => {
+  if (e[0] === '#') return String.fromCodePoint(e[1] === 'x' || e[1] === 'X'
+    ? parseInt(e.slice(2), 16) : parseInt(e.slice(1), 10));
+  return ENT[e] ?? m;
+});
+
+const localName = n => String(n).replace(/^.*:/, '');
+
+function parseAttrs(s) {
+  const a = {};
+  const re = /([\w:.-]+)\s*=\s*"([^"]*)"|([\w:.-]+)\s*=\s*'([^']*)'/g;
+  let m;
+  while ((m = re.exec(s))) {
+    const k = localName(m[1] || m[3]);
+    a[k] = unesc(m[2] ?? m[4] ?? '');
+  }
+  return a;
+}
+
+/** 태그 스트림을 훑으며 스택으로 깊이를 추적한다 (외부 파서 없이) */
+export function walk(xml, onOpen, onClose) {
+  const clean = xml
+    .replace(/<!--[\s\S]*?-->/g, '')
+    .replace(/<!\[CDATA\[[\s\S]*?\]\]>/g, '')
+    .replace(/<\?[\s\S]*?\?>/g, '')
+    .replace(/<!DOCTYPE[^>]*>/gi, '');
+  const re = /<\s*(\/)?\s*([\w:.-]+)((?:"[^"]*"|'[^']*'|[^>"'])*?)(\/)?>/g;
+  let m;
+  while ((m = re.exec(clean))) {
+    const [, closing, rawName, attrStr, selfClose] = m;
+    const name = localName(rawName);
+    if (closing) { onClose(name); continue; }
+    onOpen(name, parseAttrs(attrStr || ''));
+    if (selfClose) onClose(name);
+  }
+}
+
+/** 구조 보고 — 어떤 요소가 몇 번 나오고 어떤 속성을 갖는지 */
+function survey(xml) {
+  const els = new Map();
+  const stack = [];
+  walk(xml,
+    (name, attrs) => {
+      if (!els.has(name)) els.set(name, { name, count: 0, attrs: new Map(), parents: new Set() });
+      const e = els.get(name);
+      e.count++;
+      if (stack.length) e.parents.add(stack[stack.length - 1]);
+      for (const [k, v] of Object.entries(attrs)) {
+        if (!e.attrs.has(k)) e.attrs.set(k, { count: 0, sample: v });
+        e.attrs.get(k).count++;
+      }
+      stack.push(name);
+    },
+    () => { stack.pop(); });
+  return [...els.values()]
+    .sort((a, b) => b.count - a.count)
+    .map(e => ({
+      name: e.name, count: e.count,
+      parents: [...e.parents].slice(0, 3),
+      attrs: [...e.attrs].map(([k, v]) => ({ name: k, count: v.count, sample: v.sample })),
+    }));
+}
+
+/**
+ * 매핑 규격
+ * {
+ *   "groups": {                      // 그룹 힌트 추출
+ *     "container": "Area",           // 영역을 뜻하는 요소
+ *     "containerName": "Id",         // 그 요소의 어느 속성이 이름인가
+ *     "member": "SubArea",           // 그 안에서 엔티티를 가리키는 요소
+ *     "memberEntity": "Entity"       // 그 요소의 어느 속성이 엔티티명인가
+ *   }
+ * }
+ */
+export function readXml(text, source = 'input.xml', opt = {}) {
+  const ir = emptyIR(source, 'xml');
+  const map = opt.map || null;
+
+  if (!map || !map.groups) {
+    ir.elements = survey(text);
+    ir.needsMapping = true;
+    const top = ir.elements.slice(0, 6).map(e => e.name + '×' + e.count).join(', ');
+    ir.warnings.push('XML 은 자료마다 뜻이 달라 매핑이 필요합니다. 주요 요소: ' + top
+      + ' (그룹 힌트를 뽑으려면 --map 의 groups 를 채우세요)');
+    return ir;
+  }
+
+  const G = map.groups;
+  const hints = new Map();
+  const stack = [];
+  let curGroup = null, groupDepth = -1;
+
+  walk(text,
+    (name, attrs) => {
+      stack.push(name);
+      if (name === G.container) {
+        const gname = (attrs[G.containerName] || '').trim();
+        if (gname) { curGroup = gname; groupDepth = stack.length; }
+      } else if (curGroup && name === G.member) {
+        const ent = (attrs[G.memberEntity] || '').trim();
+        // 엔티티명이 아닌 URL·웹리소스는 거른다
+        if (ent && /^[A-Za-z_][\w]*$/.test(ent) && !hints.has(ent)) hints.set(ent, curGroup);
+      }
+    },
+    name => {
+      if (name === G.container && stack.length === groupDepth) { curGroup = null; groupDepth = -1; }
+      stack.pop();
+    });
+
+  ir.groupHints = [...hints].map(([entity, group]) => ({ entity, group }));
+  ir.elements = survey(text);
+  if (!ir.groupHints.length)
+    ir.warnings.push('그룹 힌트를 하나도 뽑지 못했습니다 — container/member 요소 이름을 확인하세요');
+  else
+    ir.warnings.push('그룹 힌트 ' + ir.groupHints.length + '건을 뽑았습니다 (테이블·관계는 없음)');
+  return ir;
+}

package/skills/erd-visual/readers/zip.mjs

@@ -0,0 +1,74 @@
+/* 최소 ZIP 리더 — Node 에 zip 이 내장돼 있지 않아서 직접 만든다.
+ * xlsx 는 XML 을 담은 zip 이다. 외부 의존성을 붙이지 않기 위한 것이므로
+ * 필요한 만큼만 읽는다: 저장(0)과 deflate(8) 두 방식.
+ */
+
+import zlib from 'zlib';
+
+const EOCD = 0x06054b50;
+const EOCD64_LOC = 0x07064b50;
+const CEN = 0x02014b50;
+const LOC = 0x04034b50;
+
+/** 끝에서부터 EOCD 를 찾는다 (주석이 붙어 있을 수 있다) */
+function findEocd(buf) {
+  const min = Math.max(0, buf.length - 66 * 1024);
+  for (let i = buf.length - 22; i >= min; i--) {
+    if (buf.readUInt32LE(i) === EOCD) return i;
+  }
+  return -1;
+}
+
+export function unzip(buf) {
+  const eocd = findEocd(buf);
+  if (eocd < 0) throw new Error('ZIP 이 아닙니다 (EOCD 없음)');
+
+  let count = buf.readUInt16LE(eocd + 10);
+  let cdOff = buf.readUInt32LE(eocd + 16);
+
+  // ZIP64 — 항목이 65535 를 넘거나 4GB 를 넘으면 여기로 온다
+  if (count === 0xffff || cdOff === 0xffffffff) {
+    for (let i = eocd - 20; i >= 0; i--) {
+      if (buf.readUInt32LE(i) === EOCD64_LOC) {
+        const z64 = Number(buf.readBigUInt64LE(i + 8));
+        count = Number(buf.readBigUInt64LE(z64 + 32));
+        cdOff = Number(buf.readBigUInt64LE(z64 + 48));
+        break;
+      }
+    }
+  }
+
+  const files = new Map();
+  let p = cdOff;
+  for (let n = 0; n < count; n++) {
+    if (buf.readUInt32LE(p) !== CEN) break;
+    const method = buf.readUInt16LE(p + 10);
+    const csize = buf.readUInt32LE(p + 20);
+    const nameLen = buf.readUInt16LE(p + 28);
+    const extraLen = buf.readUInt16LE(p + 30);
+    const cmtLen = buf.readUInt16LE(p + 32);
+    const lho = buf.readUInt32LE(p + 42);
+    const name = buf.toString('utf8', p + 46, p + 46 + nameLen);
+    files.set(name, { method, csize, lho });
+    p += 46 + nameLen + extraLen + cmtLen;
+  }
+
+  return {
+    names: () => [...files.keys()],
+    has: n => files.has(n),
+    read(name) {
+      const e = files.get(name);
+      if (!e) throw new Error('zip 안에 없는 항목: ' + name);
+      // 로컬 헤더의 길이는 중앙 디렉터리와 다를 수 있다. 반드시 로컬을 읽는다.
+      if (buf.readUInt32LE(e.lho) !== LOC) throw new Error('손상된 로컬 헤더: ' + name);
+      const nl = buf.readUInt16LE(e.lho + 26);
+      const el = buf.readUInt16LE(e.lho + 28);
+      const start = e.lho + 30 + nl + el;
+      const raw = buf.subarray(start, start + e.csize);
+      if (e.method === 0) return raw;
+      if (e.method === 8) return zlib.inflateRawSync(raw);
+      throw new Error('지원하지 않는 압축 방식 ' + e.method + ': ' + name);
+    },
+    text(name) { return this.read(name).toString('utf8'); },
+  };
+}