deel-local-cli 1.5.7 → 1.6.0

package/src/tools/fastgrep.js

@@ -0,0 +1,217 @@
+// 이미 깔려 있는 빠른 찾기 도구를 빌려 쓴다.
+//
+// ── 왜 필요한가 ────────────────────────────────────────────────────────
+//
+// `Grep` 은 자바스크립트로 파일을 하나씩 열어 읽는다. 의존성 0개라는 약속을
+// 지키려면 그래야 했다. 그런데 파일이 5만 개쯤 되는 저장소에서는 한 번 찾는
+// 데 수십 초가 간다. 그동안 화면은 멈춰 있고 사람은 기다린다.
+//
+// 그런데 개발자 PC 에는 `rg`(ripgrep)가 이미 깔려 있는 경우가 많다. VS Code
+// 가 같이 깔고, git 이 있으면 `git grep` 도 있다. **깔지는 않고, 있으면 쓴다.**
+// 이건 의존성이 아니다 — 없으면 예전 길로 가고 결과는 같다.
+//
+// ── 무엇을 조심하나 ────────────────────────────────────────────────────
+//
+//   1) **어느 엔진으로 찾았는지 말한다.** rg 와 자바스크립트 정규식은 문법이
+//      조금 다르다(rg 는 Rust regex — 되돌아보기가 없다). 결과가 다르게 나왔을
+//      때 무엇으로 찾은 것인지 모르면 사람은 코드를 의심한다.
+//
+//   2) **범위 밖으로 못 나간다.** 찾을 자리는 언제나 scope 가 준 절대경로
+//      하나뿐이고, 무늬는 인자로만 넘긴다. 셸을 안 거치므로 무늬 안의
+//      따옴표·세미콜론이 명령이 되지 못한다.
+//
+//   3) **못 찾으면 조용히 예전 길로.** 엔진이 죽거나 낯선 문법에 화를 내면
+//      결과가 없는 것이 아니라 우리가 못 물어본 것이다. 그때 '일치 없음' 을
+//      돌려주면 사람은 없는 줄 안다. 그래서 실패는 실패로 두고 JS 로 다시 찾는다.
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+
+/*
+ * 정규식으로 찾을 것이 없는 파일들.
+ *
+ * **여기가 한 벌뿐인 원본이다.** Grep 의 자바스크립트 길은 이 목록으로 정규식을
+ * 만들고, rg 는 이 목록으로 `--iglob !*.png` 를 만든다. 두 군데에 따로 적어 두면
+ * 언젠가 한쪽만 고쳐지고, 그때부터 같은 명령이 PC 마다 다른 답을 낸다 —
+ * rg 가 깔린 사람만 8MB 번들 속 글자를 찾게 되는 식으로. 그건 오류도 안 나고
+ * 아무도 눈치 못 챈다.
+ */
+export const 안볼확장자 = [
+  'png', 'jpg', 'jpeg', 'gif', 'bmp', 'ico', 'webp', 'svgz', 'pdf',
+  'zip', 'gz', 'tgz', '7z', 'rar',
+  'exe', 'dll', 'so', 'dylib', 'bin', 'dat',
+  'db', 'sqlite', 'sqlite3',
+  'woff', 'woff2', 'ttf', 'otf', 'eot',
+  'mp3', 'mp4', 'wav', 'avi', 'mov', 'mkv',
+  'class', 'jar', 'pyc', 'pyo', 'o', 'a', 'lib', 'pack', 'idx',
+  'map', 'min.js', 'min.css', 'lock',
+];
+
+/** 위 목록으로 만든 정규식. 자바스크립트 길이 쓴다. */
+export const 안볼정규식 = new RegExp(`\\.(${안볼확장자.map((x) => x.replace(/\./g, '\\.')).join('|')})$`, 'i');
+
+/** 위 목록으로 만든 rg 옵션. 대소문자를 안 가린다(정규식의 `i` 와 맞춘다). */
+export function 안볼글로브() {
+  return 안볼확장자.flatMap((x) => ['--iglob', `!*.${x}`]);
+}
+
+/*
+ * 있는지 한 번만 본다.
+ *
+ * 매번 `rg --version` 을 돌리면 찾기 한 번에 프로세스가 하나 더 뜬다.
+ * 없는 PC 에서는 그 실패가 매번 수십 ms 씩 쌓인다.
+ */
+let 본것 = null;
+
+function 있나(이름, 인자) {
+  const r = spawnSync(이름, 인자, { encoding: 'utf8', timeout: 4000, windowsHide: true });
+  return !r.error && r.status === 0;
+}
+
+export function 엔진찾기({ 다시 = false, env = process.env } = {}) {
+  if (본것 && !다시) return 본것;
+  // 끄고 싶을 때가 있다 — 결과가 다르다고 의심될 때 같은 자리에서 견주려면.
+  if (env.DEEL_GREP === 'js') { 본것 = { rg: false, gitgrep: false, 왜: 'DEEL_GREP=js 로 꺼 두었습니다' }; return 본것; }
+  본것 = {
+    rg: 있나('rg', ['--version']),
+    gitgrep: 있나('git', ['--version']),
+    왜: null,
+  };
+  return 본것;
+}
+
+/** 검사가 원래대로 돌려놓을 때. */
+export function 엔진잊기() { 본것 = null; return null; }
+
+/** 이 폴더가 git 저장소 안인가. `git grep` 은 저장소 안에서만 돈다. */
+export function 저장소인가(폴더) {
+  const r = spawnSync('git', ['-C', 폴더, 'rev-parse', '--is-inside-work-tree'], {
+    encoding: 'utf8', timeout: 4000, windowsHide: true,
+  });
+  return !r.error && r.status === 0 && /true/.test(r.stdout ?? '');
+}
+
+/*
+ * rg 로 찾는다.
+ *
+ * 돌려주는 것은 **줄 목록**이다. 세는 일과 자르는 일은 부르는 쪽이 한다 —
+ * 그래야 JS 로 찾았을 때와 결과 모양이 같아진다. 모양이 갈리면 '엔진에 따라
+ * 화면이 다른' 프로그램이 되는데, 그건 이 도구가 피하려는 것이다.
+ *
+ * @returns {{ok:true, 줄들:string[], 잘림:boolean} | {ok:false, 왜:string}}
+ */
+export function rg로찾기({ 무늬, 자리, glob = null, 대소문자무시 = false, 무시파일 = null, 최대 = 5000, timeout = 20000 }) {
+  const 인자 = [
+    '--line-number',
+    '--no-heading',
+    '--with-filename',
+    '--color', 'never',
+    // 아주 큰 파일은 안 본다(JS 길과 같은 규칙). 글이 아닌 파일은 rg 가 기본으로 건너뛴다.
+    '--max-filesize', '2M',
+    /*
+     * git 저장소가 아니어도 .gitignore 를 지킨다.
+     *
+     * rg 는 기본으로 **저장소 안에서만** .gitignore 를 본다. 저장소 밖에서는
+     * 그 파일을 글자로만 여기고 out/ · secret.txt 를 그냥 뒤진다. 우리 JS 길은
+     * 저장소든 아니든 지키므로, 이 한 줄이 없으면 같은 폴더에서 엔진에 따라
+     * 답이 갈린다 — 그것도 **비밀을 더 보는 쪽으로**.
+     */
+    '--no-require-git',
+  ];
+  if (대소문자무시) 인자.push('--ignore-case');
+  if (glob) 인자.push('--glob', glob);
+  // 자바스크립트 길이 안 여는 파일은 rg 도 안 열게 한다. 같은 목록에서 나온다.
+  인자.push(...안볼글로브());
+  /*
+   * .deelignore 도 지켜야 한다.
+   *
+   * rg 는 .gitignore 는 알지만 .deelignore 는 모른다. 그대로 두면 "git 에는
+   * 안 적고 deel 만 건너뛸 것" 이 rg 가 깔린 PC 에서만 조용히 검색된다.
+   * 같은 명령이 PC 마다 다른 답을 내는 셈이라, 이건 빠른 것보다 나쁘다.
+   */
+  if (무시파일) 인자.push('--ignore-file', 무시파일);
+  // `--` 뒤로 넘겨서 무늬가 옵션으로 안 읽히게 한다. `-foo` 같은 무늬가 실제로 있다.
+  인자.push('--regexp', 무늬, '--', 자리);
+
+  const r = spawnSync('rg', 인자, {
+    encoding: 'utf8', timeout, windowsHide: true, maxBuffer: 32 * 1024 * 1024,
+  });
+  // rg 는 못 찾으면 1, 진짜 탈이 나면 2 를 준다. 1 은 성공(빈 결과)이다.
+  if (r.error) return { ok: false, 왜: r.error.message };
+  if (r.status === 2) return { ok: false, 왜: (r.stderr ?? '').split('\n')[0] || 'rg 가 무늬를 못 읽었습니다' };
+  const 줄들 = String(r.stdout ?? '').split('\n').filter(Boolean);
+  return { ok: true, 줄들: 줄들.slice(0, 최대), 잘림: 줄들.length > 최대 };
+}
+
+/** `git grep` 으로 찾는다. rg 가 없고 여기가 저장소일 때. */
+export function git로찾기({ 무늬, 자리, 대소문자무시 = false, 최대 = 5000, timeout = 20000 }) {
+  const 인자 = ['-C', 자리, '--no-pager', 'grep', '--line-number', '--no-color', '-I', '-E'];
+  if (대소문자무시) 인자.push('-i');
+  // 여기도 같은 목록으로 뺀다. git 은 경로무늬 앞머리에 마법을 붙여 빼낸다.
+  인자.push('-e', 무늬, '--', '.', ...안볼확장자.map((x) => `:(exclude,icase)*.${x}`));
+  const r = spawnSync('git', 인자, {
+    encoding: 'utf8', timeout, windowsHide: true, maxBuffer: 32 * 1024 * 1024,
+  });
+  if (r.error) return { ok: false, 왜: r.error.message };
+  if (r.status !== 0 && r.status !== 1) {
+    return { ok: false, 왜: (r.stderr ?? '').split('\n')[0] || 'git grep 이 무늬를 못 읽었습니다' };
+  }
+  const 줄들 = String(r.stdout ?? '').split('\n').filter(Boolean);
+  // git grep 은 저장소 기준 상대경로를 준다. 절대경로로 맞춰 준다 — 아래에서 한 모양으로 쓴다.
+  const 고친것 = 줄들.map((l) => {
+    const i = l.indexOf(':');
+    if (i < 0) return l;
+    return join(자리, l.slice(0, i)) + l.slice(i);
+  });
+  return { ok: true, 줄들: 고친것.slice(0, 최대), 잘림: 고친것.length > 최대 };
+}
+
+/*
+ * `경로:줄번호:내용` 한 줄을 가른다.
+ *
+ * 윈도우 경로에는 `C:` 가 있어서 **첫 번째 콜론으로 자르면 안 된다.**
+ * `C:\a\b.js:12:const x = 1;` 을 첫 콜론에서 자르면 파일 이름이 `C` 가 된다.
+ *
+ * 그 일은 아래 정규식이 이미 막는다. `(.*?)` 는 게으른 짝짓기라 짧은 쪽부터
+ * 보지만, 그 뒤에 **`:숫자:` 가 반드시 와야 한다.** `C` 다음은 `:\Users…`
+ * 라 숫자가 아니므로 그 자리는 버려지고, 진짜 줄 번호 앞 콜론까지 늘어난다.
+ *
+ * 전에는 여기에 "첫 조각이 한 글자면 다시 본다" 는 갈래가 하나 더 있었다.
+ * 지우고 검사를 돌려도 아무것도 안 빨개졌다 — 닿지 않는 길이었다는 뜻이다.
+ * 막고 있는 척만 하는 코드는 없느니만 못해서 지웠다. 대신 윈도우 경로를
+ * 재는 검사를 test/fastgrep.test.js 에 남겨 둔다.
+ */
+export function 줄가르기(줄) {
+  const m = /^(.*?):(\d+):([\s\S]*)$/.exec(줄);
+  if (!m) return null;
+  return { 파일: m[1], 줄: Number(m[2]), 내용: m[3] };
+}
+
+/**
+ * 빠른 엔진으로 찾아 본다. 못 쓰면 null — 부르는 쪽이 예전 길로 간다.
+ *
+ * @returns {{엔진:string, 줄들:Array<{파일,줄,내용}>, 잘림:boolean} | null}
+ */
+export function 빠르게찾기({ 무늬, 자리, glob = null, 대소문자무시 = false, 무시파일 = null, 최대 = 5000 }) {
+  const 것 = 엔진찾기();
+  if (것.rg) {
+    const r = rg로찾기({ 무늬, 자리, glob, 대소문자무시, 무시파일, 최대 });
+    if (r.ok) return { 엔진: 'rg', 줄들: r.줄들.map(줄가르기).filter(Boolean), 잘림: r.잘림 };
+    // rg 가 무늬를 못 읽은 것일 수 있다(Rust regex 에는 되돌아보기가 없다).
+    // 그건 '없다' 가 아니라 '못 물어봤다' 이므로 예전 길로 내려간다.
+    return null;
+  }
+  // git grep 은 .deelignore 를 시킬 방법이 없다. 그 파일이 있으면 예전 길로 간다 —
+  // 사람이 "deel 은 여기 보지 마라" 고 적어 둔 것을 못 지키면 빠른 것이 뜻이 없다.
+  if (것.gitgrep && !무시파일 && 저장소인가(자리)) {
+    const r = git로찾기({ 무늬, 자리, 대소문자무시, 최대 });
+    if (r.ok) return { 엔진: 'git grep', 줄들: r.줄들.map(줄가르기).filter(Boolean), 잘림: r.잘림 };
+    return null;
+  }
+  return null;
+}
+
+/** 화면·결과 꼬리에 적을 한마디. 무엇으로 찾았는지 사람이 알아야 한다. */
+export function 엔진말(이름) {
+  if (!이름) return '';
+  return `(${이름} 으로 찾았습니다 — 이 PC 에 이미 있어서 빌려 썼습니다)`;
+}

package/src/tools/fsutil.js

@@ -1,7 +1,8 @@
 // 파일 훑기와 glob 매칭. 외부 패키지 없이 직접 구현한다.
 import { readdirSync, statSync, readFileSync, mkdirSync, copyFileSync } from 'node:fs';
-import { join, relative, sep } from 'node:path';
+import { join } from 'node:path';
 import { decode, looksBinary } from './encoding.js';
+import { 뿌리규칙읽기, 파일규칙읽기, 걸리나 } from './ignore.js';
 
 /**
  * 폴더를 통째로 옮겨 담는다.
@@ -142,32 +143,74 @@ function escapeLiteral(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
-// 폴더를 훑어 파일 목록을 낸다. { path(절대), rel(/구분), mtime, size }
-export function walk(root, { limit = 20000, skipDirs = SKIP_DIRS } = {}) {
+/**
+ * 폴더를 훑어 파일 목록을 낸다. { path(절대), rel(/구분), mtime, size }
+ *
+ * `ignore` 가 켜져 있으면(기본) .gitignore 가 건너뛰라는 것은 건너뛴다 (tools/ignore.js).
+ * skipDirs 는 그 아래의 바닥이다 — .gitignore 가 없어도 node_modules 는 늘 건너뛴다.
+ * 돌려주는 배열에는 `건너뜀 = { 폴더, 파일 }` 이 (열거되지 않게) 붙어 있다. 부르는 쪽이 그 수를
+ * 화면에 적는다 — 조용히 빼면 "그 파일이 없다" 로 읽힌다.
+ * 폴더를 통째로 옮기거나 복사할 때는 `ignore: false` 로 — 그때는 다 있어야 한다.
+ *
+ * `잘림` 도 같이 붙는다 — **상한에서 멈췄다는 뜻이다.**
+ *
+ * 전에는 이 상한이 조용했다. 파일 5만 개짜리 저장소에서 앞의 2만 개만 훑고
+ * 멈추는데, 아무 데도 그 말이 안 나갔다. 그래서 `Grep` 이 "일치 없음" 이라고
+ * 답했다 — 실제로는 뒤쪽 3만 개에 100군데가 있는데도. 못 찾은 것과 안 본 것은
+ * 다르고, 그걸 안 가르면 사람은 없는 줄 알고 그냥 간다. 조용한 상한은
+ * 틀린 답보다 나쁘다.
+ */
+export const 기본훑기상한 = 20000;
+
+/**
+ * 몇 개까지 훑을까.
+ *
+ * 2만 개는 대부분의 저장소에 넉넉하지만 큰 단일 저장소에는 모자란다. 그래서
+ * 올릴 수 있게 열어 둔다 — 못 보는 것을 알려 주기만 하고 손쓸 방법이 없으면
+ * 알려 준 뜻이 없다. 터무니없는 값은 안 받는다(100 미만·200만 초과).
+ */
+export function 훑기상한(env = process.env) {
+  const n = Number(env.DEEL_WALK_LIMIT);
+  if (!Number.isFinite(n) || n < 100 || n > 2000000) return 기본훑기상한;
+  return Math.floor(n);
+}
+
+export function walk(root, { limit = 훑기상한(), skipDirs = SKIP_DIRS, ignore = true } = {}) {
   const out = [];
-  const stack = [root];
+  const 건너뜀 = { 폴더: 0, 파일: 0 };
+  const stack = [{ dir: root, rel: '', 규칙: ignore ? 뿌리규칙읽기(root) : [] }];
   while (stack.length && out.length < limit) {
-    const dir = stack.pop();
+    const { dir, rel, 규칙 } = stack.pop();
     let entries;
     try { entries = readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    // 이 폴더에 .gitignore 가 있으면 그 아래에만 더한다 (뿌리 것은 위에서 읽었다).
+    let 여기규칙 = 규칙;
+    if (ignore && rel && entries.some((e) => e.name === '.gitignore' && e.isFile())) {
+      const 추가 = 파일규칙읽기(join(dir, '.gitignore'), rel);
+      if (추가.length) 여기규칙 = [...규칙, ...추가];
+    }
     for (const e of entries) {
       const full = join(dir, e.name);
+      const erel = rel ? `${rel}/${e.name}` : e.name;
       if (e.isDirectory()) {
         if (skipDirs.has(e.name)) continue;
-        stack.push(full);
+        if (여기규칙.length && 걸리나(erel, true, 여기규칙)) { 건너뜀.폴더 += 1; continue; }
+        stack.push({ dir: full, rel: erel, 규칙: 여기규칙 });
       } else if (e.isFile()) {
+        if (여기규칙.length && 걸리나(erel, false, 여기규칙)) { 건너뜀.파일 += 1; continue; }
         let st;
         try { st = statSync(full); } catch { continue; }
-        out.push({
-          path: full,
-          rel: relative(root, full).split(sep).join('/'),
-          mtime: st.mtimeMs,
-          size: st.size,
-        });
+        out.push({ path: full, rel: erel, mtime: st.mtimeMs, size: st.size });
         if (out.length >= limit) break;
       }
     }
   }
+  Object.defineProperty(out, '건너뜀', { value: 건너뜀, enumerable: false });
+  // 상한까지 찼으면 "여기서 멈췄다" 고 표시한다. 딱 맞아떨어져 끝난 경우까지
+  // 잘렸다고 하게 되지만, 그쪽으로 틀리는 편이 낫다 — 덜 봤다고 말하는 것은
+  // 사람을 한 번 더 보게 만들 뿐이고, 다 봤다고 말하는 것은 못 보게 만든다.
+  Object.defineProperty(out, '잘림', { value: out.length >= limit, enumerable: false });
+  Object.defineProperty(out, '상한', { value: limit, enumerable: false });
   return out;
 }
 

package/src/tools/ignore.js

@@ -0,0 +1,192 @@
+// .gitignore 를 읽어, git 이 건너뛰는 것을 도구도 건너뛴다 — Glob · Grep · Outline · Verify · @폴더.
+//
+// 왜: walk() 는 정해진 폴더 몇 개(node_modules · dist …)만 건너뛰었다. 실제 저장소는 out/ ·
+// .gradle/ · coverage/ · 만들어진 코드 · 자료 덤프를 .gitignore 에 적어 두는데, 그걸 다 훑으면
+// 32k 창에서 Grep 한 번이 빌드 산출물로 예산을 다 쓴다. 사람은 git 이 안 보는 것을 도구도
+// 안 볼 거라고 생각한다 — 그 기대를 맞춘다.
+//
+// 지원하는 것 — git 규칙의 부분집합:
+//   빈 줄 · # 주석 · !부정 · 끝의 / (폴더만) · 앞의 / (그 자리에 고정) · * · ** · ? · [abc] · \ 이스케이프
+//   슬래시가 없는 패턴은 어느 깊이든 이름으로 맞고, 슬래시가 있으면 그 파일이 있는 폴더 기준이다.
+//   아래 폴더의 .gitignore 는 그 아래에만 적용되고, 뒤에 오는 규칙이 이긴다 (git 과 같다).
+//   건너뛴 폴더 안의 것은 !로도 되살릴 수 없다 (git 도 그렇다 — 폴더째 안 들어간다).
+//   뿌리의 .deelignore 도 같은 문법으로 .gitignore 뒤에 읽는다 — git 에는 안 적고 deel 만 건너뛸 것.
+// 안 하는 것: 작업 폴더 **위**의 .gitignore, .git/info/exclude, core.excludesFile.
+// 윈도우에서는 대소문자를 안 가린다 (globToRegex 와 같다).
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * 규칙 파일 하나를 규칙 목록으로.
+ * @param {string} text  파일 내용
+ * @param {string} 기준  그 파일이 있는 폴더 (작업 폴더 기준 상대, / 구분, 뿌리면 '')
+ */
+export function 규칙읽기(text, 기준 = '') {
+  const out = [];
+  for (const 줄 of String(text ?? '').replace(/\r/g, '').split('\n')) {
+    const r = 패턴규칙(줄, 기준);
+    if (r) out.push(r);
+  }
+  return out;
+}
+
+/** 줄 하나 → 규칙. 빈 줄·주석이면 null. */
+export function 패턴규칙(줄, 기준 = '') {
+  let p = String(줄 ?? '');
+  // 끝의 빈칸은 뗀다 — 역슬래시로 살린 것만 남긴다.
+  p = p.replace(/(?<!\\)\s+$/, '');
+  if (!p || p.startsWith('#')) return null;
+  let 부정 = false;
+  if (p.startsWith('!')) { 부정 = true; p = p.slice(1); }
+  else if (p.startsWith('\\!') || p.startsWith('\\#')) p = p.slice(1);
+  if (!p) return null;
+  let 폴더만 = false;
+  if (p.endsWith('/') && !p.endsWith('\\/')) { 폴더만 = true; p = p.replace(/\/+$/, ''); }
+  if (!p) return null;
+  let 고정 = false;
+  if (p.startsWith('/')) { 고정 = true; p = p.replace(/^\/+/, ''); }
+  // 슬래시가 가운데 있어도 그 자리에 고정된다. 없으면 어느 깊이든 이름으로.
+  if (p.includes('/')) 고정 = true;
+  const 몸 = 글롭정규식(p);
+  const src = 고정 ? `^${몸}$` : `(?:^|/)${몸}$`;
+  return { re: new RegExp(src, process.platform === 'win32' ? 'i' : ''), 부정, 폴더만, 기준: String(기준 ?? '').replace(/\\/g, '/').replace(/^\/+|\/+$/g, ''), 원문: 줄 };
+}
+
+// gitignore 글롭 → 정규식 몸통 (앞뒤 고정은 부르는 쪽이 붙인다).
+function 글롭정규식(p) {
+  let re = '';
+  let i = 0;
+  while (i < p.length) {
+    const ch = p[i];
+    if (ch === '\\' && i + 1 < p.length) { re += 글자(p[i + 1]); i += 2; continue; }
+    if (ch === '*') {
+      if (p[i + 1] === '*') {
+        /*
+         * `**` 는 **제 자리에 있을 때만** 슬래시를 넘는다.
+         *
+         *   맨 앞의 별둘 + 슬래시   → 어느 깊이든
+         *   맨 뒤의 슬래시 + 별둘   → 그 안의 전부
+         *   슬래시 사이의 별둘      → 폴더 0개 이상
+         *
+         * 그 밖의 자리(`a**b`)는 git 이 그냥 별 하나로 읽는다 — 슬래시를 안
+         * 넘는다. 여기서 `.*` 로 읽으면 `a**b` 가 `a/dir/b` 를 걸어 버려서,
+         * git 은 그대로 두는 파일을 deel 만 감춘다. 규칙을 적은 사람은
+         * 없어진 파일을 찾을 길이 없다.
+         */
+        const 앞이경계 = i === 0 || p[i - 1] === '/';
+        if (앞이경계 && p[i + 2] === '/') { re += '(?:.*/)?'; i += 3; continue; }
+        if (앞이경계 && i + 2 === p.length) { re += '.*'; i += 2; continue; }
+        // 붙어 있는 별은 몇 개든 하나로 친다.
+        while (p[i] === '*') i += 1;
+        re += '[^/]*';
+        continue;
+      }
+      re += '[^/]*'; i += 1; continue;
+    }
+    if (ch === '?') { re += '[^/]'; i += 1; continue; }
+    if (ch === '[') {
+      const end = p.indexOf(']', i + 1);
+      if (end > i + 1) {
+        let 안 = p.slice(i + 1, end);
+        if (안.startsWith('!')) 안 = '^' + 안.slice(1);
+        re += `[${안.replace(/\\/g, '\\\\')}]`;
+        i = end + 1;
+        continue;
+      }
+      re += '\\['; i += 1; continue;
+    }
+    re += 글자(ch); i += 1;
+  }
+  return re;
+}
+
+function 글자(ch) { return ch.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&'); }
+
+// 규칙의 기준 폴더 안에 있는 경로면 그 기준부터의 경로를, 아니면 null.
+function 기준안(rel, 기준) {
+  if (!기준) return rel;
+  if (rel === 기준) return null;                    // 기준 폴더 자신은 그 안의 규칙 대상이 아니다
+  if (!rel.startsWith(기준 + '/')) return null;
+  return rel.slice(기준.length + 1);
+}
+
+/** 경로 하나가 규칙에 걸리는가 — 부모 폴더는 이미 통과했다고 보고 이 경로만 본다. walk 가 쓴다. */
+export function 걸리나(rel, 폴더인가, 규칙들) {
+  let 답 = false;
+  for (const r of 규칙들) {
+    if (r.폴더만 && !폴더인가) continue;
+    const sub = 기준안(rel, r.기준);
+    if (sub === null) continue;
+    if (r.re.test(sub)) 답 = !r.부정;
+  }
+  return 답;
+}
+
+/**
+ * 경로 하나가 무시되는가 — 부모 폴더까지 본다. 건너뛴 폴더 안의 것은 !로도 못 살린다.
+ * @param {string} rel  작업 폴더 기준 상대 경로 (/ 구분)
+ */
+export function 무시하나(rel, 폴더인가, 규칙들) {
+  if (!규칙들?.length) return false;
+  const 칸 = String(rel).replace(/\\/g, '/').replace(/^\/+|\/+$/g, '').split('/');
+  for (let i = 1; i < 칸.length; i++) {
+    if (걸리나(칸.slice(0, i).join('/'), true, 규칙들)) return true;
+  }
+  return 걸리나(칸.join('/'), 폴더인가, 규칙들);
+}
+
+/** 파일을 읽어 규칙으로. 없거나 못 읽으면 빈 목록. */
+export function 파일규칙읽기(path, 기준 = '') {
+  try { return 규칙읽기(readFileSync(path, 'utf8'), 기준); } catch { return []; }
+}
+
+/** 뿌리의 규칙 — .gitignore 다음에 .deelignore. */
+export function 뿌리규칙읽기(root) {
+  return [...파일규칙읽기(join(root, '.gitignore'), ''), ...파일규칙읽기(join(root, '.deelignore'), '')];
+}
+
+/**
+ * 뿌리부터 이 폴더까지 오면서 만나는 규칙을 다 모은다.
+ *
+ * walk() 는 내려가면서 폴더마다 더하면 되지만, @폴더 처럼 중간을 바로 들여다보는
+ * 쪽은 자기 위쪽을 스스로 되짚어야 한다. 안 그러면 sub/.gitignore 가 있는데도
+ * @sub 로 지목했을 때만 규칙이 없는 것처럼 보인다 — 같은 폴더가 도구마다 다르게
+ * 보이는 것이 제일 나쁘다.
+ */
+export function 계보규칙읽기(root, rel = '') {
+  const 규칙 = 뿌리규칙읽기(root);
+  const 조각 = String(rel ?? '').replace(/\\/g, '/').split('/').filter((x) => x && x !== '.');
+  let 여기 = '';
+  for (const 한칸 of 조각) {
+    여기 = 여기 ? `${여기}/${한칸}` : 한칸;
+    규칙.push(...파일규칙읽기(join(root, ...여기.split('/'), '.gitignore'), 여기));
+  }
+  return 규칙;
+}
+
+/** 화면 한 줄. 건너뛴 것이 없으면 빈 문자열 — 없는데 줄을 만들면 그게 소음이다. */
+/**
+ * @param 건너뜀 `{ 폴더, 파일 }` — .gitignore 로 뺀 수
+ * @param 잘림   상한에서 멈췄나 (walk 가 붙여 준다)
+ * @param 상한   몇 개까지 봤나. 0 이면 수 없이 말한다.
+ *               (숫자를 인자로 받는다 — fsutil 이 ignore 를 부르므로 거꾸로 가져오면 고리가 된다)
+ */
+export function 건너뜀말(건너뜀, 잘림 = false, 상한 = 0) {
+  const 폴더 = 건너뜀?.폴더 ?? 0;
+  const 파일 = 건너뜀?.파일 ?? 0;
+  const 줄 = [];
+  if (폴더 || 파일) {
+    const 몫 = [폴더 ? `폴더 ${폴더}개` : null, 파일 ? `파일 ${파일}개` : null].filter(Boolean).join(' · ');
+    줄.push(`(.gitignore 로 ${몫} 건너뜀 — 경로를 직접 주면 Read 된다)`);
+  }
+  /*
+   * 상한에서 멈췄으면 반드시 말한다.
+   *
+   * 이 한 줄이 없으면 "일치 없음" 이 "없다" 로 읽힌다. 실제로는 안 본 것이다.
+   */
+  if (잘림) {
+    const 몇 = 상한 ? `${상한.toLocaleString('en-US')}개까지만` : '앞부분만';
+    줄.push(`(파일이 너무 많아 ${몇} 봤습니다 — 못 본 자리에 있는 것은 여기 안 나옵니다. 폴더를 좁혀서 다시 시켜 보세요)`);
+  }
+  return 줄.length ? `\n\n${줄.join('\n')}` : '';
+}