@m1kapp/kit 0.0.36 → 0.0.37

package/bin/skills/m1kapp-clean.md

@@ -5,9 +5,24 @@
 - 최악 함수 cognitive 20 초과분 ×1 (최대 -15)
 - **중복 밀도 3% 초과분 ×2.5 (최대 -25)** — 토큰 단위 복붙 검출 (식별자 정규화, 테스트 제외)
 - 200줄 초과 파일 비율 ×2 (최대 -10) / 평균 파일 길이 80줄 초과분 ÷5 (최대 -10)
+- **루프 안 무캐시 파일읽기 ×4 (최대 -20)** — 호출 1번이 파일을 N번 읽는 구조 (`quality.io`)
+- **렌더 인질 ×3 (최대 -10)** — fetch 하나가 무관한 UI까지 막는 자리 (`quality.renderGates`)
 
 cognitive = 중첩 깊이 가중 복잡도 (SonarQube 방식): `a && b && c`는 1, 5중 중첩 if는 flat if 5개보다 훨씬 비쌈. `??`는 미카운트. 즉 **평평하게 펴는 것(조기 반환)이 진짜 점수가 됨** — 함수 쪼개기만으론 안 오름.
 
+`io` 축은 나머지와 성격이 다르다. cognitive·중복은 "코드가 얼마나 꼬였나"라 5줄짜리
+흠 없는 리더가 루프에서 120번 불리는 종류는 **원리상 못 잡는다** — 실제로 요청당 파일을
+492번 읽던 코드가 A+ 100점을 통과한 적이 있다. 그래서 파일을 읽는 함수(한 다리 건너
+읽는 얇은 래퍼 포함)를 찾아 루프·`map` 안에서 불리는 자리를 센다. 그 리더가 캐시를
+끼고 있으면(모듈 Map을 get/set) 반복 호출돼도 실제 읽기는 한 번이라 감점하지 않는다.
+**고치는 법은 리팩토링이 아니라 캐시를 끼우거나 한 번 읽어 재사용하도록 구조를 바꾸는 것** —
+`quality.io.worst`가 위치를 지목한다.
+
+`renderGates`도 같은 성격이다. `{data && <Nav a={local} b={data.x} onChange={fn} />}`처럼
+프롭 3개 중 1개만 그 데이터에 의존하는데 전체가 대기하면, 사용자에겐 이미 아는 UI까지
+매번 로딩으로 보인다. 데이터에 의존하는 부분만 늦게 채우고 나머지는 먼저 그리는 게 답이다
+(서버가 아는 값이면 아예 서버에서 내려주면 된다).
+
 즉 **효율 순서: ① 중복 블록 제거 (kit-stats.json `quality.duplication.worstBlocks`가 위치 지목) ② 최악 함수 중첩 평탄화 ③ cog15+ 함수들 ④ 긴 파일 분할**.
 
 `--llm` 플래그(선택): cognitive 최악 3개를 Claude(haiku)가 네이밍·응집도·본질적 복잡성 여부 자문 — 점수 미반영, `quality.llm`에 기록. "essential: true"로 나온 함수는 억지로 쪼개지 말 것.

package/bin/stats.mjs

@@ -340,6 +340,306 @@ function analyzeDuplication(ts, fileContents) {
   return { percent, dupTokens, totalTokens, blocks: blockKeys.size, worstFiles, worstBlocks };
 }
 
+// 파일 I/O 밀도 — "한 번 처리하는 데 파일을 몇 번이나 읽게 되는 구조인가".
+// cognitive·중복은 코드 모양만 보므로, 5줄짜리 흠 없는 리더가 루프에서 120번 불리는
+// 종류는 원리상 못 잡는다(그래서 요청당 492회 읽던 코드가 A+ 100점을 통과했다).
+// 여기선 리더 함수를 찾고, 그게 루프 안에서 불리는 자리를 센다. 리더가 캐시를 끼고
+// 있으면 반복 호출돼도 실제 읽기는 한 번이라 감점하지 않고 참고로만 남긴다.
+const FILE_READ_CALLS = new Set(["readFileSync", "readFile", "readdirSync"]);
+const ITERATING_METHODS = new Set(["map", "forEach", "flatMap", "filter", "reduce", "some", "every", "find"]);
+
+function analyzeIoDensity(ts, fileContents) {
+  const parsed = fileContents.map(({ file, content }) => ({
+    file,
+    sf: ts.createSourceFile(
+      file,
+      content,
+      ts.ScriptTarget.Latest,
+      true,
+      /\.(tsx|jsx)$/.test(file) ? ts.ScriptKind.TSX : ts.ScriptKind.TS,
+    ),
+  }));
+
+  const isFnLike = (n) =>
+    ts.isFunctionDeclaration(n) || ts.isFunctionExpression(n) || ts.isArrowFunction(n) ||
+    ts.isMethodDeclaration(n);
+
+  const nameOf = (sf, n) => {
+    if (n.name) return n.name.getText(sf);
+    const p = n.parent;
+    if (p && ts.isVariableDeclaration(p)) return p.name.getText(sf);
+    return null;
+  };
+
+  const lineOf = (sf, n) => sf.getLineAndCharacterOfPosition(n.getStart(sf)).line + 1;
+
+  // 1단계: 함수마다 "직접 파일을 읽는가 / 자기 캐시를 쓰는가 / 누구를 부르는가"를 모은다
+  const fns = new Map(); // 이름 -> { file, line, readsDirectly, hasOwnCache, calls:Set }
+  for (const { file, sf } of parsed) {
+    const moduleHasMap = /new (Map|WeakMap)\s*[<(]/.test(sf.text);
+    // 모듈 스코프 변수 이름 — "읽고 또 대입하는" 변수를 쓰면 그게 메모이제이션이다
+    // (globalThis에 물린 캐시나 `let memo = null` 패턴. Map만 캐시로 보면 이런 걸 다 놓친다)
+    const moduleVars = new Set();
+    for (const stmt of sf.statements) {
+      if (ts.isVariableStatement(stmt)) {
+        for (const decl of stmt.declarationList.declarations) {
+          if (ts.isIdentifier(decl.name)) moduleVars.add(decl.name.getText(sf));
+        }
+      }
+    }
+
+    const collect = (node) => {
+      if (isFnLike(node) && node.body) {
+        let readsDirectly = false;
+        let mapCacheOps = 0;
+        const calls = new Set();
+        const readVars = new Set();
+        const writtenVars = new Set();
+        const rootName = (expr) => {
+          let cur = expr;
+          while (ts.isPropertyAccessExpression(cur) || ts.isElementAccessExpression(cur)) cur = cur.expression;
+          return ts.isIdentifier(cur) ? cur.getText(sf) : null;
+        };
+        const scan = (n) => {
+          if (n !== node && isFnLike(n)) return; // 중첩 함수는 자기 항목에서 본다
+          if (ts.isCallExpression(n)) {
+            const callee = n.expression;
+            const called = ts.isPropertyAccessExpression(callee) ? callee.name.getText(sf) : callee.getText(sf);
+            if (FILE_READ_CALLS.has(called)) readsDirectly = true;
+            if (called === "get" || called === "set") mapCacheOps++;
+            calls.add(called);
+          }
+          if (ts.isBinaryExpression(n) && n.operatorToken.kind === ts.SyntaxKind.EqualsToken) {
+            const target = rootName(n.left);
+            if (target && moduleVars.has(target)) writtenVars.add(target);
+          }
+          if (ts.isIdentifier(n) && moduleVars.has(n.getText(sf))) readVars.add(n.getText(sf));
+          ts.forEachChild(n, scan);
+        };
+        ts.forEachChild(node, scan);
+        const memoizesByVar = [...writtenVars].some((v) => readVars.has(v));
+        const name = nameOf(sf, node);
+        if (name && !fns.has(name)) {
+          fns.set(name, {
+            file,
+            line: lineOf(sf, node),
+            readsDirectly,
+            // 캐시로 보는 두 형태: 모듈 Map을 get/set 하거나, 모듈 변수를 읽고 다시 대입하거나
+            hasOwnCache: (moduleHasMap && mapCacheOps >= 2) || memoizesByVar,
+            calls,
+          });
+        }
+      }
+      ts.forEachChild(node, collect);
+    };
+    ts.forEachChild(sf, collect);
+  }
+
+  // 2단계: 호출 그래프로 "리더"를 전파한다 — getThemeComments → readJson → readFileSync 처럼
+  //        직접 읽지 않고 한 다리 건너 읽는 함수가 실제 N+1의 주인공이라 이게 핵심이다.
+  //        읽기 경로가 전부 캐시를 거치면 그 함수도 캐시된 리더로 본다(반복 호출돼도 읽기는 한 번).
+  const readers = new Map(); // 이름 -> { file, line, cached }
+  for (const [name, fn] of fns) {
+    if (fn.readsDirectly) readers.set(name, { file: fn.file, line: fn.line, cached: fn.hasOwnCache });
+  }
+  const MAX_HOPS = 2; // 얇은 래퍼(getThemeComments → readJson)까지만. 더 깊으면 전부 리더가 된다
+  for (let pass = 0; pass < MAX_HOPS; pass++) {
+    let changed = false;
+    for (const [name, fn] of fns) {
+      if (readers.has(name)) continue;
+      const calledReaders = [...fn.calls].map((c) => readers.get(c)).filter(Boolean);
+      if (calledReaders.length === 0) continue;
+      readers.set(name, {
+        file: fn.file,
+        line: fn.line,
+        cached: fn.hasOwnCache || calledReaders.every((r) => r.cached),
+      });
+      changed = true;
+    }
+    if (!changed) break;
+  }
+
+  // 3단계: 그 리더(또는 fs 읽기 자체)가 루프 안에서 불리는 자리를 찾는다.
+  //        for/while뿐 아니라 map·forEach 같은 순회 콜백 안도 루프로 본다.
+  const sites = [];
+  for (const { file, sf } of parsed) {
+    // 캐시를 직접 관리하는 함수 안에서의 읽기는 캐시 미스일 때만 나간다(2단 캐시의 디스크 티어 등)
+    const walk = (node, inLoop, inCachingFn) => {
+      let childInLoop = inLoop;
+      let childInCachingFn = inCachingFn;
+      if (isFnLike(node)) {
+        const self = fns.get(nameOf(sf, node));
+        if (self && self.hasOwnCache) childInCachingFn = true;
+      }
+      switch (node.kind) {
+        case ts.SyntaxKind.ForStatement:
+        case ts.SyntaxKind.ForInStatement:
+        case ts.SyntaxKind.ForOfStatement:
+        case ts.SyntaxKind.WhileStatement:
+        case ts.SyntaxKind.DoStatement:
+          childInLoop = true;
+          break;
+      }
+      if (ts.isCallExpression(node)) {
+        const callee = node.expression;
+        const called = ts.isPropertyAccessExpression(callee) ? callee.name.getText(sf) : callee.getText(sf);
+        const reader = readers.get(called);
+        if (inLoop && (FILE_READ_CALLS.has(called) || reader)) {
+          const cached = inCachingFn || (reader ? reader.cached : false);
+          sites.push({ file, line: lineOf(sf, node), callee: called, cached });
+        }
+        // 순회 메서드에 넘긴 콜백 본문은 루프 안으로 취급
+        if (ts.isPropertyAccessExpression(callee) && ITERATING_METHODS.has(callee.name.getText(sf))) {
+          for (const arg of node.arguments) {
+            if (isFnLike(arg)) walk(arg, true, childInCachingFn);
+          }
+        }
+      }
+      ts.forEachChild(node, (child) => {
+        const alreadyWalked =
+          ts.isCallExpression(node) &&
+          ts.isPropertyAccessExpression(node.expression) &&
+          ITERATING_METHODS.has(node.expression.name.getText(sf)) &&
+          isFnLike(child);
+        if (!alreadyWalked) walk(child, childInLoop, childInCachingFn);
+      });
+    };
+    ts.forEachChild(sf, (n) => walk(n, false, false));
+  }
+
+  const uncached = sites.filter((s) => !s.cached);
+  const readerList = [...readers.entries()].map(([name, r]) => ({ name, ...r }));
+  return {
+    readers: readerList.length,
+    uncachedReaders: readerList.filter((r) => !r.cached).length,
+    loopSites: sites.length,
+    uncachedLoopSites: uncached.length,
+    worst: uncached.slice(0, 5).map(({ file, line, callee }) => ({ file, line, callee })),
+  };
+}
+
+// 렌더 인질 — 데이터 하나를 기다리느라 그와 무관한 UI까지 통째로 못 그리는 자리.
+// `{data && <Nav a={local} b={data.x} onChange={fn} />}` 처럼 프롭 대부분이 이미 아는
+// 값인데 fetch 하나 때문에 전체가 대기하면, 사용자에겐 매번 로딩으로 보인다.
+// 게이트에 걸린 요소가 그 데이터에 실제로 의존하는 비율로 판정한다.
+const HOSTAGE_DEP_RATIO = 0.5; // 프롭 절반도 안 쓰면서 전체를 막고 있으면 인질
+
+function analyzeRenderGates(ts, fileContents) {
+  const findings = [];
+
+  for (const { file, content } of fileContents) {
+    if (!/\.(tsx|jsx)$/.test(file)) continue;
+    const sf = ts.createSourceFile(file, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+
+    // 훅이 물어다 주는 값(로딩이 있는 값)을 찾는다: const { data: x } = useSomething()
+    const fetched = new Set();
+    const findHookVars = (n) => {
+      if (
+        ts.isVariableDeclaration(n) &&
+        n.initializer &&
+        ts.isCallExpression(n.initializer) &&
+        /^use[A-Z]/.test(
+          ts.isPropertyAccessExpression(n.initializer.expression)
+            ? n.initializer.expression.name.getText(sf)
+            : n.initializer.expression.getText(sf),
+        ) &&
+        ts.isObjectBindingPattern(n.name)
+      ) {
+        for (const el of n.name.elements) {
+          const source = (el.propertyName || el.name).getText(sf);
+          if (source === "data") fetched.add(el.name.getText(sf));
+        }
+      }
+      ts.forEachChild(n, findHookVars);
+    };
+    ts.forEachChild(sf, findHookVars);
+    if (fetched.size === 0) continue;
+
+    const rootName = (expr) => {
+      let cur = expr;
+      while (ts.isPropertyAccessExpression(cur) || ts.isElementAccessExpression(cur)) cur = cur.expression;
+      return ts.isIdentifier(cur) ? cur.getText(sf) : null;
+    };
+
+    /** 이 노드가 그 변수를 실제로 참조하는가 */
+    const references = (node, name) => {
+      let found = false;
+      const scan = (n) => {
+        if (found) return;
+        if (ts.isIdentifier(n) && n.getText(sf) === name) found = true;
+        else ts.forEachChild(n, scan);
+      };
+      scan(node);
+      return found;
+    };
+
+    /** 게이트에 쓰인 fetch 변수들 */
+    const gateVars = (expr) => {
+      const names = new Set();
+      const scan = (n) => {
+        if (ts.isIdentifier(n) && fetched.has(n.getText(sf))) names.add(n.getText(sf));
+        ts.forEachChild(n, scan);
+      };
+      scan(expr);
+      return [...names];
+    };
+
+    const inspectGate = (testExpr, element) => {
+      const vars = gateVars(testExpr);
+      if (vars.length === 0) return;
+      const el = ts.isJsxElement(element) ? element.openingElement : element;
+      if (!el.attributes) return;
+      const props = el.attributes.properties;
+      if (props.length < 2) return; // 프롭이 거의 없으면 판단할 근거가 없다
+
+      const dependent = props.filter((p) => vars.some((v) => references(p, v))).length;
+      const ratio = dependent / props.length;
+      if (ratio < HOSTAGE_DEP_RATIO) {
+        findings.push({
+          file,
+          line: sf.getLineAndCharacterOfPosition(el.getStart(sf)).line + 1,
+          element: el.tagName ? el.tagName.getText(sf) : "?",
+          gate: vars.join(", "),
+          dependentProps: dependent,
+          totalProps: props.length,
+        });
+      }
+    };
+
+    const walk = (n) => {
+      // {data && <El .../>}
+      if (
+        ts.isBinaryExpression(n) &&
+        n.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken &&
+        (ts.isJsxElement(n.right) || ts.isJsxSelfClosingElement(n.right))
+      ) {
+        inspectGate(n.left, n.right);
+      }
+      // {data ? <El .../> : null}
+      if (ts.isConditionalExpression(n) && (ts.isJsxElement(n.whenTrue) || ts.isJsxSelfClosingElement(n.whenTrue))) {
+        inspectGate(n.condition, n.whenTrue);
+      }
+      // 괄호로 감싼 JSX도 같은 취급
+      if (
+        ts.isBinaryExpression(n) &&
+        n.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken &&
+        ts.isParenthesizedExpression(n.right) &&
+        (ts.isJsxElement(n.right.expression) || ts.isJsxSelfClosingElement(n.right.expression))
+      ) {
+        inspectGate(n.left, n.right.expression);
+      }
+      ts.forEachChild(n, walk);
+    };
+    ts.forEachChild(sf, walk);
+    void rootName;
+  }
+
+  return {
+    hostages: findings.length,
+    worst: findings.slice(0, 5),
+  };
+}
+
 // 파일 분류 — frontend(UI) / backend(API·서버) / shared(공용 유틸)
 function classifyFile(filePath, content) {
   const rel = filePath.replace(/\\/g, "/");
@@ -439,10 +739,15 @@ const avgFileLines = files.length > 0 ? Math.round(codeLines / files.length) : 0
 //   ※ 파일 개수 기준 이진 카운트(200줄 넘으면 무조건 1) 대신 심각도 가중 — 살짝 넘는 파일과
 //     터무니없이 큰 파일을 구분하고, 파일 수 적은 프로젝트가 파일 1개만으로 즉시 만점 감점 맞는 절벽 방지.
 // / 평균 파일 길이 80줄 초과분 /5 (최대 10)
+// - 렌더 인질(fetch 하나가 무관한 UI까지 막는 자리) ×3 (최대 10)
+// - 루프 안 무캐시 파일읽기 사이트 ×4 (최대 20) ← 새 축. 코드 모양이 아무리 깔끔해도
+//   호출 1번이 파일 N번을 읽는 구조는 여기서만 드러난다(cognitive·중복으론 원리상 안 잡힘).
 let qualityScore;
 let cc = null;
 let cognitive = null;
 let duplication = null;
+let io = null;
+let renderGates = null;
 if (ts && allFns.length > 0) {
   const byCc = [...allFns].sort((a, b) => b.cc - a.cc);
   cc = {
@@ -469,6 +774,8 @@ if (ts && allFns.length > 0) {
   };
 
   duplication = analyzeDuplication(ts, fileContents);
+  io = analyzeIoDensity(ts, fileContents);
+  renderGates = analyzeRenderGates(ts, fileContents);
 
   const over15Pct = (cogOver15.length / allFns.length) * 100;
   const over25Pct = (cogOver25.length / allFns.length) * 100;
@@ -481,6 +788,8 @@ if (ts && allFns.length > 0) {
     - Math.min(25, Math.max(0, duplication.percent - 3) * 2.5)
     - Math.min(10, longFileSeverityPct * 1.5)
     - Math.min(10, Math.max(0, avgFileLines - 80) / 5)
+    - Math.min(20, io.uncachedLoopSites * 4)
+    - Math.min(10, renderGates.hostages * 3)
   ));
 } else {
   // regex 폴백 (typescript 미설치)
@@ -543,6 +852,8 @@ const stats = {
     grade: qualityGrade,
     cognitive,            // {avg, p90, max, over15, over25, worst[5]} — 중첩 가중 복잡도
     duplication,          // {percent, blocks, worstFiles, worstBlocks} — 토큰 중복 밀도
+    io,                   // {readers, uncachedReaders, loopSites, uncachedLoopSites, worst} — 루프 안 파일 읽기
+    renderGates,          // {hostages, worst} — fetch 하나가 무관한 UI까지 막고 있는 자리
     cc,                   // {functions, avg, p90, max, over10, over20, worst[5]} — McCabe (참고용)
     branchDensity,        // 100줄당 분기 수 (regex 근사, 참고용)
     branches: totalBranches,
@@ -588,6 +899,18 @@ if (cc) {
       console.log(`    중복 블록: ${ex.join(" ≒ ")}`);
     }
   }
+  if (renderGates.hostages > 0) {
+    console.log(`  렌더 인질: ${renderGates.hostages}곳 — 데이터를 기다리느라 이미 아는 UI까지 못 그립니다`);
+    for (const w of renderGates.worst) {
+      console.log(`    인질: <${w.element}> ${w.gate} 대기 (의존 프롭 ${w.dependentProps}/${w.totalProps}) — ${w.file}:${w.line}`);
+    }
+  }
+  if (io.uncachedLoopSites > 0) {
+    console.log(`  루프 안 파일읽기: ${io.uncachedLoopSites}곳 (캐시 없는 리더 ${io.uncachedReaders}/${io.readers}개) — 호출 1번이 파일 N번 읽습니다`);
+    for (const w of io.worst) {
+      console.log(`    반복 읽기: ${w.callee}() — ${w.file}:${w.line}`);
+    }
+  }
 } else {
   console.log(`  청결도: ${qualityGrade} (${qualityScore}점) — 분기밀도 ${branchDensity}/100줄, 평균 ${avgFileLines}줄/파일, 200줄+ ${longFiles}개 (regex 폴백 — typescript 설치 시 AST 정밀 분석)`);
 }