@tuzi-ince/hi-loop 0.2.1 → 0.3.0

package/src/vcs.js

@@ -0,0 +1,167 @@
+/**
+ * 브랜치·커밋 메커니즘 (FR-16) — 엔진이 소유하는 git 조작.
+ *
+ * 철학: **엔진은 메커니즘(git 실행)을, LLM 은 산문(좋은 커밋 메시지)을 소유한다.**
+ * 그래서 여기 함수들은 순수 git 이고, 메시지는 인자로 받거나(스킬이 지어 넘김) 없으면
+ * goal 기반 휴리스틱으로 만든다. checkpoint.js 의 git 패턴(실패 시 null, 비-git skip)을 따른다.
+ */
+import { execFile } from 'node:child_process';
+import { isGitRepo } from './checkpoint.js';
+
+/** `{ ok, out }`. 실패(비-0 exit)면 ok:false, out 은 stdout+stderr. */
+function git(args, cwd) {
+  return new Promise((resolve) => {
+    execFile('git', args, { cwd, maxBuffer: 1024 * 1024 }, (err, stdout, stderr) => {
+      const out = `${String(stdout ?? '')}${String(stderr ?? '')}`.trim();
+      resolve({ ok: !err, out });
+    });
+  });
+}
+
+/** 현재 브랜치명. detached/비-git 이면 null. */
+export async function currentBranch(cwd) {
+  const r = await git(['rev-parse', '--abbrev-ref', 'HEAD'], cwd);
+  if (!r.ok) return null;
+  const name = r.out.trim();
+  return name && name !== 'HEAD' ? name : null; // 'HEAD' = detached
+}
+
+/** 이 브랜치가 보호 대상인가. */
+export function isProtected(branch, protectedBranches) {
+  if (!branch) return false;
+  const list = Array.isArray(protectedBranches) ? protectedBranches : [];
+  return list.includes(branch);
+}
+
+/** goal → 브랜치 slug. 소문자 kebab, 안전 문자만, 앞부분만. 비면 'change'. */
+export function slugify(goal) {
+  const base = String(goal ?? '')
+    .toLowerCase()
+    .replace(/[^a-z0-9가-힣]+/g, '-') // 공백·기호 → 하이픈 (한글은 보존)
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40)
+    .replace(/-+$/g, '');
+  return base || 'change';
+}
+
+/** feature 브랜치로 생성/전환. 이미 있으면 전환. 반환 `{ ok, branch, created, reason }`. */
+export async function createBranch(cwd, name) {
+  const branch = String(name ?? '').trim();
+  if (!branch) return { ok: false, reason: '브랜치 이름이 비어 있습니다.' };
+  const exists = (await git(['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`], cwd)).ok;
+  const r = exists ? await git(['switch', branch], cwd) : await git(['switch', '-c', branch], cwd);
+  if (!r.ok) return { ok: false, reason: r.out || 'git switch 실패' };
+  return { ok: true, branch, created: !exists };
+}
+
+/** 워킹트리 전체를 스테이징하고 커밋. 변경 없으면 실패로 돌려준다. 반환 `{ ok, sha, reason }`. */
+export async function commitAll(cwd, message) {
+  const msg = String(message ?? '').trim();
+  if (!msg) return { ok: false, reason: '커밋 메시지가 비어 있습니다.' };
+  await git(['add', '-A'], cwd);
+  // 스테이징 후에도 변경이 없으면 커밋할 게 없다 — 조용히 실패로 신호.
+  const staged = await git(['diff', '--cached', '--quiet'], cwd);
+  if (staged.ok) return { ok: false, reason: '커밋할 변경이 없습니다.' };
+  const c = await git(['commit', '-m', msg], cwd);
+  if (!c.ok) return { ok: false, reason: c.out || 'git commit 실패' };
+  const sha = await git(['rev-parse', 'HEAD'], cwd);
+  return { ok: true, sha: sha.ok ? sha.out.trim() : null };
+}
+
+const CONVENTIONAL = /^(\w+)(\(.+\))?!?:\s/;
+
+/** 최근 커밋 제목들을 보고 Conventional Commits 관행인지 추정. 'conventional' | 'plain'. */
+export async function detectCommitStyle(cwd) {
+  const r = await git(['log', '-20', '--pretty=%s'], cwd);
+  if (!r.ok || !r.out) return 'plain'; // 커밋 이력이 없으면 평문
+  const subjects = r.out.split('\n').filter(Boolean);
+  const conv = subjects.filter((s) => CONVENTIONAL.test(s)).length;
+  return conv / subjects.length >= 0.5 ? 'conventional' : 'plain';
+}
+
+/** goal 키워드 → conventional type. 확신 없으면 chore. */
+function inferType(goal) {
+  const g = String(goal ?? '').toLowerCase();
+  if (/(추가|만들|신규|기능|feat|add|implement)/.test(g)) return 'feat';
+  if (/(고치|버그|수정|오류|fix|bug)/.test(g)) return 'fix';
+  if (/(리팩터|정리|refactor|cleanup)/.test(g)) return 'refactor';
+  if (/(문서|docs|readme)/.test(g)) return 'docs';
+  if (/(테스트|test)/.test(g)) return 'test';
+  return 'chore';
+}
+
+/** goal 첫 줄을 커밋 제목 길이로 다듬는다. */
+function firstLine(goal) {
+  const line = String(goal ?? '').split('\n')[0].trim();
+  return line.length > 72 ? `${line.slice(0, 69)}...` : line;
+}
+
+/**
+ * 메시지가 안 주어졌을 때 goal 로 커밋 메시지를 만든다.
+ * styleConfig: 'korean'=goal 그대로 | 'conventional'=type 접두 | 'match-log'=repo 관행 따름.
+ */
+export async function buildCommitMessage({ goal, styleConfig = 'match-log', cwd }) {
+  const subject = firstLine(goal) || 'update';
+  if (styleConfig === 'korean') return subject;
+  const conventional =
+    styleConfig === 'conventional' || (styleConfig === 'match-log' && (await detectCommitStyle(cwd)) === 'conventional');
+  return conventional ? `${inferType(goal)}: ${subject}` : subject;
+}
+
+/**
+ * 주입 가능한 브랜치 포트 (NFR-3). 보호 브랜치에 있을 때만 feature 로 분기한다.
+ * 반환: `{ branched, branch, reason }`.
+ */
+export function makeBrancher() {
+  return async ({ cwd, name = null, goal, protectedBranches, logger = () => {} }) => {
+    if (!(await isGitRepo(cwd))) return { branched: false, reason: 'non-git' };
+    const cur = await currentBranch(cwd);
+    if (!isProtected(cur, protectedBranches)) {
+      return { branched: false, branch: cur, reason: 'not-protected' };
+    }
+    const target = (typeof name === 'string' && name.trim()) ? name.trim() : `feature/${slugify(goal)}`;
+    const r = await createBranch(cwd, target);
+    if (!r.ok) {
+      logger(`[hi-loop] ⚠️ 브랜치 분기 실패: ${r.reason}`);
+      return { branched: false, reason: r.reason };
+    }
+    logger(`[hi-loop] 🌱 ${cur} → ${r.branch} (${r.created ? '생성' : '전환'})`);
+    return { branched: true, branch: r.branch };
+  };
+}
+
+/**
+ * 브랜치 프리스텝 (FR-16) — loop.js 를 얇게 유지하려 여기 둔다.
+ * 분기했으면 브랜치명을, 아니면 null 을 돌려준다.
+ */
+export async function branchPreStep({ brancher, cwd, branch, goal, protectedBranches, logger }) {
+  if (branch == null) return null;
+  const res = await brancher({
+    cwd,
+    name: typeof branch === 'string' ? branch : null,
+    goal,
+    protectedBranches,
+    logger,
+  });
+  return res.branched ? res.branch : null;
+}
+
+/**
+ * 주입 가능한 커밋 포트 (NFR-3). 메시지가 없으면 goal 로 만든다. 비-git·변경없음이면 조용히 skip.
+ * 반환: `{ committed, sha, message, reason }`.
+ */
+export function makeCommitter() {
+  return async ({ cwd, message = null, goal, styleConfig = 'match-log', logger = () => {} }) => {
+    if (!(await isGitRepo(cwd))) return { committed: false, reason: 'non-git' };
+    const msg = (typeof message === 'string' && message.trim())
+      ? message.trim()
+      : await buildCommitMessage({ goal, styleConfig, cwd });
+    const r = await commitAll(cwd, msg);
+    if (!r.ok) {
+      logger(`[hi-loop] · 커밋 skip — ${r.reason}`);
+      return { committed: false, message: msg, reason: r.reason };
+    }
+    logger(`[hi-loop] ✅ 커밋 ${r.sha?.slice(0, 8)} — ${msg}`);
+    return { committed: true, sha: r.sha, message: msg };
+  };
+}

package/src/verdict.js

@@ -0,0 +1,54 @@
+/**
+ * 판정 조립 — Tier 1 의 여러 신호를 하나의 실패 사유와 하나의 정체 지문으로 합친다.
+ *
+ * build.js 에서 뺀 이유는 크기(NFR-5)만이 아니다. 이 세 함수는 **부수효과가 없다** —
+ * state 도 로거도 만지지 않고, 신호를 받아 문자열을 돌려줄 뿐이다. 순수한 부분을 떼어놓으면
+ * 판정 규칙을 루프를 돌리지 않고 단위 테스트할 수 있고, 규칙이 늘어도 CHECK 블록이
+ * 커지지 않는다. 가드가 하나 늘 때마다 손대는 곳도 여기 한 곳이다.
+ */
+import { errorSignature } from './state.js';
+import { violationMessage } from './integrity.js';
+import { regressionMessage } from './metrics.js';
+
+/**
+ * 무결성 신호 합성: 지문 비교(L1) + 유령 테스트(L13).
+ * 둘 다 "테스트를 믿을 수 있는가"에 대한 답이라 한 결과로 합친다.
+ */
+export function composeIntegrity(fpViolations, ghostMessages) {
+  const violations = [...(fpViolations ?? []), ...(ghostMessages ?? [])];
+  return { ok: violations.length === 0, violations };
+}
+
+/**
+ * 다음 루프의 연료가 될 실패 사유.
+ *
+ * 순서가 규칙이다. 절단은 tail-biased 이므로(§5.2) **꼬리에 있는 것이 살아남는다.**
+ * 그래서 에이전트가 반드시 봐야 할 위반 사유를 뒤에 둔다 — 앞에 두면 잘려나가고,
+ * 에이전트는 자기가 뭘 어겼는지 모른 채 같은 짓을 반복한다.
+ */
+export function composeFailure({ specReject, output, checkCode, specPath, integrity, regressed, baseline, metrics }) {
+  if (specReject) {
+    return [
+      '스펙 검증이 이 구현을 기각했다. 테스트는 통과했지만 스펙 요구를 못 채웠다:',
+      specReject,
+      `스펙(${specPath})을 다시 읽고 그 요구를 충족하도록 구현을 고쳐라. 테스트만 통과시키는 것으로는 부족하다.`,
+    ].join('\n');
+  }
+  const parts = [output || `테스트가 코드 ${checkCode}로 실패했습니다.`];
+  if (!integrity.ok) parts.push(violationMessage(integrity.violations));
+  if (regressed?.length) parts.push(regressionMessage(baseline, metrics, regressed));
+  return parts.join('\n\n');
+}
+
+/**
+ * 정체 판정용 지문. 같은 값이 반복되면 이 접근으로는 못 고친다는 뜻이다.
+ *
+ * 실패의 **종류**마다 다른 접두사를 붙인다. 스펙 기각과 테스트 실패가 같은 지문을 가지면
+ * 서로 다른 두 문제를 오가는 실행이 정체로 오판된다.
+ */
+export function stagnationSignature({ specReject, integrity, regressed, output }) {
+  if (specReject) return `SPEC:${errorSignature(specReject)}`;
+  if (!integrity.ok) return `INTEGRITY:${integrity.violations.join('|')}`;
+  if (regressed?.length) return `REGRESS:${regressed.join('|')}`;
+  return errorSignature(output);
+}

package/src/verify.js

@@ -40,12 +40,13 @@ export function parseVerdict(text) {
     const m = String(text).match(/\{[\s\S]*"verdict"[\s\S]*\}/);
     const obj = JSON.parse(m ? m[0] : text);
     const verdict = obj.verdict === 'reject' ? 'reject' : 'pass';
-    return { verdict, reason: typeof obj.reason === 'string' ? obj.reason : '' };
+    // 여기만 verified: true 다 — 검증자가 실제로 판정문을 냈다는 뜻이다.
+    return { verdict, verified: true, reason: typeof obj.reason === 'string' ? obj.reason : '' };
   } catch {
     // 판정 형식을 못 읽으면 기각하지 않는다 — 검증자가 헛소리를 했다고 통과를
     // 막으면, 잘못된 입력이 방어를 "더 약하게"가 아니라 "더 세게" 만드는 게 아니라
     // 반대가 된다. Tier 2 는 하향 전용이고 확신 없으면 통과가 원칙이다.
-    return { verdict: 'pass', reason: '검증자 응답을 파싱하지 못해 통과로 처리(하향 전용)' };
+    return { verdict: 'pass', verified: false, reason: '검증자 응답을 파싱하지 못해 통과로 처리(하향 전용)' };
   }
 }
 
@@ -63,7 +64,7 @@ export function makeSpecVerifier({
       const specFull = specPath ? join(cwd, specPath) : null;
       if (!specFull || !existsSync(specFull)) {
         // 스펙이 없으면 대조할 오라클이 없다 → 기각할 근거 없음 → 통과.
-        resolve({ verdict: 'pass', reason: '스펙 파일이 없어 검증 생략' });
+        resolve({ verdict: 'pass', verified: false, reason: '스펙 파일이 없어 검증 생략' });
         return;
       }
       const specText = readFileSync(specFull, 'utf8');
@@ -81,12 +82,12 @@ export function makeSpecVerifier({
         child.on('error', () => {
           clearTimeout(timer);
           // 검증자 실행 자체가 실패하면 통과를 막지 않는다(인프라 장애가 판정을 뒤집으면 안 됨).
-          resolve({ verdict: 'pass', reason: `검증자 실행 실패 — 통과로 처리` });
+          resolve({ verdict: 'pass', verified: false, reason: `검증자 실행 실패 — 통과로 처리` });
         });
         child.on('close', (code) => {
           clearTimeout(timer);
           if (code !== 0) {
-            resolve({ verdict: 'pass', reason: `검증자가 코드 ${code}로 종료 — 통과로 처리` });
+            resolve({ verdict: 'pass', verified: false, reason: `검증자가 코드 ${code}로 종료 — 통과로 처리` });
             return;
           }
           const { text } = parseAgentOutput(stdout);

package/src/wiring.js

@@ -0,0 +1,74 @@
+/**
+ * 미배선 검출 (L19) — "만들었지만 아무도 안 쓰는" 통과.
+ *
+ * 이 엔진이 아직 못 보던 false green 이 하나 남아 있다. 에이전트가 `src/foo.js` 를 만들고
+ * `tests/foo.test.js` 가 그 모듈을 **직접** import 해서 테스트하면:
+ *   · exit 0 (테스트가 통과한다)
+ *   · 무결성 깨끗 (케이스 수가 늘었지 줄지 않았다)
+ *   · 비회귀 깨끗 (통과 수가 늘었다)
+ *   · 유령 아님 (git 에 추적된다)
+ * 그런데 **제품 코드 어디에서도 foo 를 부르지 않는다.** 기능은 없고 테스트만 있다.
+ * 기존 게이트는 전부 테스트를 보는데, 이 결함은 테스트가 아니라 **제품 배선**에 있다.
+ *
+ * bkit 은 이걸 CI 하드 게이트로 갖고 있다(`scripts/check-deadcode.js`, exit 1). 함수 단위
+ * 스캐너의 주석이 이름까지 붙여놨다 — *"Built But Not Wired"*.
+ *
+ * 판정이 아니라 **공개**로 다룬다. 새 모듈이 아직 안 불리는 정상 상황이 흔하기 때문이다
+ * (다음 회차에 배선할 수도 있고, 엔트리포인트일 수도 있다). 차단하면 오탐이 루프를 죽인다.
+ * 대신 Gaps 에 실어서 "테스트는 통과했지만 이 파일은 제품 경로에서 안 불린다"를 밝힌다.
+ */
+import { readFileSync } from 'node:fs';
+import { basename, extname, join } from 'node:path';
+
+const CODE_RE = /\.[cm]?[jt]sx?$/;
+const TEST_RE = /(?:^|\/)(?:tests?|__tests__)\//;
+const TEST_FILE_RE = /\.(?:test|spec)\.[cm]?[jt]sx?$/;
+
+/** 제품 코드인가 (테스트·설정이 아닌). */
+export function isProductionFile(rel) {
+  return CODE_RE.test(rel) && !TEST_RE.test(rel) && !TEST_FILE_RE.test(rel);
+}
+
+/** 모듈 참조를 뽑는다. import/require/동적 import 를 모두 본다. */
+export function referencedNames(text) {
+  const out = new Set();
+  const patterns = [
+    /(?:from|import)\s*\(?\s*['"]([^'"]+)['"]/g,
+    /require\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+  ];
+  for (const re of patterns) {
+    for (const m of String(text ?? '').matchAll(re)) {
+      const spec = m[1];
+      if (!spec.startsWith('.') && !spec.startsWith('/')) continue; // 패키지 import 는 관심 밖
+      out.add(basename(spec, extname(spec)));
+    }
+  }
+  return out;
+}
+
+/**
+ * baseline 이후 새로 생긴 제품 파일 중 **제품 코드 어디에서도 참조되지 않는 것**.
+ *
+ * 기준이 baseline 인 이유: 이 루프가 만든 것만 본다. 원래부터 안 불리던 파일까지 들추면
+ * 매 실행이 남의 부채를 보고하는 소음이 된다.
+ *
+ * 관측 불가(baseline 이 없거나 현재 목록을 못 얻음)면 빈 배열 — 인프라는 fail-open.
+ */
+export function detectUnwired({ cwd, baselineFiles, currentFiles }) {
+  if (!Array.isArray(baselineFiles) || !Array.isArray(currentFiles)) return [];
+  const was = new Set(baselineFiles);
+  const fresh = currentFiles.filter((f) => !was.has(f) && isProductionFile(f));
+  if (!fresh.length) return [];
+
+  // 참조 집합은 **제품 파일에서만** 모은다. 테스트가 부르는 것은 배선이 아니다 —
+  // 그게 바로 이 검출기가 겨냥하는 형태다.
+  const referenced = new Set();
+  for (const rel of currentFiles.filter(isProductionFile)) {
+    try {
+      for (const name of referencedNames(readFileSync(join(cwd, rel), 'utf8'))) referenced.add(name);
+    } catch {
+      /* 읽는 사이 사라졌으면 무시 — 가드가 루프를 죽이면 안 된다 */
+    }
+  }
+  return fresh.filter((f) => !referenced.has(basename(f, extname(f))));
+}