@cheongfish/bouncer 0.0.0-stage → 0.1.13

package/dist/task-brief-hash.js

@@ -0,0 +1,34 @@
+'use strict';
+const guards = require("./guards");
+const { isRecord } = guards;
+const frontmatter = require("./frontmatter");
+const { parseFrontmatter } = frontmatter;
+const approvalSnapshot = require("./approval-snapshot");
+const { sha256Canonical } = approvalSnapshot;
+const LIFECYCLE_KEYS = ['status', 'commit_sha'];
+/**
+ * task brief의 canonical SHA-256을 계산한다.
+ * dispatch·record·intent bundle이 같은 값을 써야, commit이 `status`/`commit_sha`만
+ * 찍거나 YAML을 다시 써도 stale-worker-report가 나지 않는다. 본문이나 그 외
+ * frontmatter가 바뀌면 해시도 바뀐다.
+ *
+ * js-yaml은 따옴표 없는 날짜를 Date로 읽는다. canonicalJson은 Date를 객체로
+ * 보고 `{}`로 접으므로, 해시 직전에 JSON 왕복으로 ISO 문자열로 고정한다.
+ *
+ * @param {string} markdown - tasks.md 전체 텍스트(UTF-8)
+ * @returns {string} 64자리 소문자 hex
+ */
+function taskBriefHash(markdown) {
+    const parsed = parseFrontmatter(markdown);
+    // 1. 입력 data를 깊은 복사한 뒤에만 lifecycle 키를 지운다. parseFrontmatter
+    //    결과를 직접 delete하면 같은 객체를 쥔 호출자가 status를 잃는다.
+    const data = structuredClone(parsed.data);
+    if (isRecord(data) && isRecord(data.bouncer)) {
+        for (const key of LIFECYCLE_KEYS) {
+            delete data.bouncer[key];
+        }
+    }
+    // 2. Date → ISO 문자열. 같은 날짜 값이 YAML 인용만 달라도 같은 해시가 된다.
+    return sha256Canonical(JSON.parse(JSON.stringify({ data, body: parsed.body })));
+}
+module.exports = { taskBriefHash, LIFECYCLE_KEYS };

package/dist/task-commits.js

@@ -0,0 +1,124 @@
+'use strict';
+const { spawnSync } = require('node:child_process');
+const commitSha = require('./commit-sha');
+const { normalizeCommitSha } = commitSha;
+const contextIds = require("./context-ids");
+const { normalizeStableId } = contextIds;
+const TRAILER_RE = /^Bouncer-Task\s*:\s*(.*?)\s*$/;
+// fan-in이 붙인 worker 출처. 40자리 hex가 아니면 매칭하지 않아 workerSha가 null이 된다.
+const WORKER_TRAILER_RE = /^Bouncer-Worker-Commit\s*:\s*([0-9a-f]{40})\s*$/m;
+// `%H%x00%B`는 커밋 사이에 구분 NUL이 없어 다음 SHA가 본문 뒤에 붙는다.
+// SHA\0 위치를 먼저 찾고, 본문은 다음 SHA 직전까지로 자른다.
+const FULL_SHA_NUL_RE = /([0-9a-f]{40})\0/gi;
+/**
+ * 기본 git 실행기. 주입 가능 exec와 같은 `{ status, stdout }` 모양만 돌려
+ * 테스트 seam이 stderr 유무로 갈라지지 않게 한다.
+ *
+ * @param {string} repoRoot - git cwd
+ * @param {string[]} args - `git` 뒤 argv
+ * @returns {{ status: number, stdout: string }}
+ */
+function defaultExec(repoRoot, args) {
+    const r = spawnSync('git', args, {
+        cwd: repoRoot,
+        encoding: 'utf8',
+        env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+    });
+    return {
+        status: typeof r.status === 'number' ? r.status : 1,
+        stdout: r.stdout || '',
+    };
+}
+/**
+ * `git log --format=%H%x00%B` 출력을 `{ sha, body }[]`로 쪼갠다.
+ * format이 커밋 경계 NUL을 넣지 않으므로 `\0` split만으로는 다음 SHA가
+ * 이전 본문에 붙는다 — SHA\0 앵커로만 경계를 잡는다.
+ *
+ * @param {string} stdout - git log 원문
+ * @returns {Array<{ sha: string, body: string }>} 최신순 커밋
+ */
+function parseShaBodyLog(stdout) {
+    const starts = [];
+    FULL_SHA_NUL_RE.lastIndex = 0;
+    let match;
+    while ((match = FULL_SHA_NUL_RE.exec(stdout)) !== null) {
+        starts.push({
+            sha: match[1].toLowerCase(),
+            bodyStart: match.index + match[0].length,
+            shaStart: match.index,
+        });
+    }
+    const out = [];
+    for (let i = 0; i < starts.length; i += 1) {
+        const end = i + 1 < starts.length ? starts[i + 1].shaStart : stdout.length;
+        out.push({
+            sha: starts[i].sha,
+            body: stdout.slice(starts[i].bodyStart, end),
+        });
+    }
+    return out;
+}
+/**
+ * `base..head` 커밋 본문에서 `Bouncer-Task` trailer만 읽어 stable ID → SHA 맵을 만든다.
+ * 문서를 읽지 않는다 — digest와 Explain 제목이 같은 trailer 출처를 쓰게 하기 위함이다.
+ * 같은 ID가 여러 커밋에 있으면 최신(git log 기본 최신순)만 남긴다.
+ *
+ * @param {object} opts
+ * @param {string} opts.repoRoot - git cwd(finalize checkout)
+ * @param {string} opts.base - 범위 시작(미포함)
+ * @param {string} opts.head - 범위 끝(포함). 보통 HEAD
+ * @param {string[]} opts.stableIds - 찾을 `EPIC-…/BP-…/TASK-…` 목록
+ * @param {(args: string[]) => { status: number, stdout: string }} [opts.exec] - `git` 뒤 argv seam
+ * @param {object | null} [opts.registry] - 등록부. 있으면 구형·slug trailer를 `normalizeStableId`로 같은 키에 묶는다.
+ *   없으면(또는 별칭이 없으면) 정확 일치로 비교해 이관 전 동작과 같다
+ * @returns {Map<string, { sha: string, sha8: string, workerSha: string | null }>} 매칭된 ID만 담은 맵.
+ *   키는 호출자가 넘긴 `stableIds` 원래 값이다
+ */
+function resolveTaskCommits({ repoRoot, base, head, stableIds, exec, registry, }) {
+    // 묶음 키: 별칭 표로 정규화한 ID. 정규화 불가(별칭 없음·해석 불가)면 원래 문자열로 비교한다.
+    // 같은 task의 구형·slug trailer가 한 키로 모여 "가장 최근 커밋" 규칙이 형식을 가로질러 적용된다.
+    const groupKey = (id) => normalizeStableId(id, registry ?? null) ?? id;
+    // 묶음 키 → 호출자가 넘긴 원래 ID. 반환 Map은 호출자 값을 키로 써야 호출부 조회가 그대로 맞는다.
+    // 호출자가 같은 task를 두 형식으로 함께 넘겨도 둘 다 채우도록 목록으로 둔다.
+    const wanted = new Map();
+    for (const id of Array.isArray(stableIds) ? stableIds : []) {
+        if (typeof id !== 'string' || id === '')
+            continue;
+        wanted.set(groupKey(id), [...(wanted.get(groupKey(id)) ?? []), id]);
+    }
+    const out = new Map();
+    if (wanted.size === 0)
+        return out;
+    const run = typeof exec === 'function'
+        ? exec
+        : (args) => defaultExec(repoRoot, args);
+    const logged = run(['log', '--format=%H%x00%B', `${base}..${head}`]);
+    if (logged.status !== 0 || !logged.stdout)
+        return out;
+    for (const record of parseShaBodyLog(logged.stdout)) {
+        let taskId = null;
+        for (const line of record.body.split('\n')) {
+            const trailer = TRAILER_RE.exec(line);
+            if (!trailer)
+                continue;
+            // 같은 본문에 Task trailer가 둘이면 첫 줄만 본다. 상충 값을 고르지 않는다.
+            taskId = trailer[1];
+            break;
+        }
+        if (!taskId)
+            continue;
+        const callerIds = wanted.get(groupKey(taskId));
+        if (callerIds === undefined || callerIds.every((id) => out.has(id)))
+            continue;
+        const sha8 = normalizeCommitSha(record.sha);
+        if (!sha8)
+            continue;
+        const workerSha = WORKER_TRAILER_RE.exec(record.body)?.[1] ?? null;
+        for (const id of callerIds) {
+            if (!out.has(id))
+                out.set(id, { sha: record.sha, sha8, workerSha });
+        }
+    }
+    return out;
+}
+module.exports = { resolveTaskCommits };

package/dist/tasks-docs.js

@@ -0,0 +1,192 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+// 레거시 단일/번호 문서와 새 tasks/<NNN>/ 묶음을 한 모듈에서만 판정한다.
+// 다른 모듈이 tasks.md / verification.md / review.md / \d{3} 문자열을
+// 직접 매칭하지 않게 하기 위함 (묶음 basename 정본).
+const LEGACY_TASKS_BASENAME = 'tasks.md';
+const INITIAL_NUMBERED_TASKS_BASENAME = 'tasks-001.md';
+// tasks-1.md · tasks-01.md 는 정본이 아니다 — 세 자리 zero-pad만 인정.
+const NUMBERED_TASKS_RE = /^tasks-(\d{3})\.md$/;
+// 새 레이아웃: <bp>/tasks/<NNN>/ — NNN 아닌 이름(01, foo)은 invalidDirs 로만 보고,
+// 엔트리로 올리지 않는다. 거절 게이트는 002.
+const TASK_DIR_RE = /^(\d{3})$/;
+const TASK_UNIT_BASENAMES = ['tasks.md', 'verification.md', 'review.md'];
+const schema = require("./schema");
+const posixPath = require("./posix-path");
+const { toPosix } = posixPath;
+const { executionKindOf } = schema;
+const frontmatter = require("./frontmatter");
+const { readDoc } = frontmatter;
+function isNumberedTasksBasename(name) {
+    return typeof name === 'string' && NUMBERED_TASKS_RE.test(name);
+}
+function isLegacyTasksBasename(name) {
+    return name === LEGACY_TASKS_BASENAME;
+}
+/**
+ * basename → 문서 kind. paths.parsePathIds 가 FILE_KIND 에
+ * verification/review 문자열을 두지 않도록 여기로 모은다.
+ * 번호 붙은 레거시 tasks-{NNN}.md 도 tasks 로 본다.
+ */
+function unitDocKind(basename) {
+    if (typeof basename !== 'string')
+        return null;
+    if (isNumberedTasksBasename(basename))
+        return 'tasks';
+    const idx = TASK_UNIT_BASENAMES.indexOf(basename);
+    if (idx === 0)
+        return 'tasks';
+    if (idx === 1)
+        return 'verification';
+    if (idx === 2)
+        return 'review';
+    return null;
+}
+/**
+ * 모든 task 소비자가 같은 부재=commit 규칙을 쓰도록 frontmatter를 해석한다.
+ *
+ * @param {unknown} data - tasks.md의 전체 frontmatter 객체
+ * @returns {'commit' | 'verification' | null} 유효 종류 또는 잘못된 선언의 null
+ */
+function taskExecutionKind(data) {
+    const bouncer = data && typeof data === 'object' && !Array.isArray(data)
+        ? data.bouncer
+        : null;
+    return executionKindOf(bouncer);
+}
+/**
+ * S5 기대 id (레거시 판정용).
+ * - tasks.md → TASKS-{blueprintId} (레거시: 파일 이름에 번호가 없어 blueprint id를 씀)
+ * - tasks-{NNN}.md → TASKS-{NNN} (파일 번호가 곧 task id)
+ */
+function expectedTasksId(basename, blueprintId) {
+    if (typeof basename !== 'string')
+        return null;
+    const m = NUMBERED_TASKS_RE.exec(basename);
+    if (m)
+        return `TASKS-${m[1]}`;
+    if (basename === LEGACY_TASKS_BASENAME && typeof blueprintId === 'string' && blueprintId) {
+        return `TASKS-${blueprintId}`;
+    }
+    return null;
+}
+/**
+ * 새 묶음 문서의 기대 id 셋. number 는 '001' 또는 1  alike — 항상 zero-pad 세 자리로 정규화.
+ */
+function expectedTaskDocIds(number) {
+    const digits = typeof number === 'number'
+        ? String(number).padStart(3, '0')
+        : String(number).padStart(3, '0');
+    return {
+        tasks: `TASKS-${digits}`,
+        verification: `VERIFY-${digits}`,
+        review: `REVIEW-${digits}`,
+    };
+}
+function makeEntry({ dir, number, tasks, verification, review, executionKind, }) {
+    return {
+        dir,
+        number,
+        tasks,
+        verification,
+        ...(review ? { review } : {}),
+        rel: tasks.rel,
+        id: tasks.id,
+        basename: path.posix.basename(tasks.rel),
+        executionKind,
+    };
+}
+/**
+ * blueprint 디렉터리에서 task 묶음 목록을 번호 오름차순으로 돌려준다.
+ * 우선순위: tasks/<NNN>/ 디렉터리 엔트리, 그다음 루트 레거시 파일.
+ * tasks.md frontmatter는 정규화된 executionKind를 붙이기 위해 한 번 읽는다.
+ * 그 외 문서 내용은 읽지 않으며 invalidDirs 거절은 002 게이트가 맡는다.
+ */
+function listTasksDocs({ repoRoot, blueprintDir }) {
+    const bp = toPosix(blueprintDir);
+    const absDir = path.join(repoRoot, bp);
+    let names;
+    try {
+        names = fs.readdirSync(absDir);
+    }
+    catch (_e) {
+        return { entries: [], mixed: false, legacy: false, invalidDirs: [] };
+    }
+    const entries = [];
+    const invalidDirs = [];
+    // --- 새 레이아웃: <bp>/tasks/<NNN>/ ---
+    const tasksRootAbs = path.join(absDir, 'tasks');
+    let taskChildNames = [];
+    try {
+        taskChildNames = fs.readdirSync(tasksRootAbs);
+    }
+    catch (_e) {
+        // tasks/ 없음 — 레거시만 본다.
+    }
+    const dirItems = [];
+    for (const name of taskChildNames) {
+        let st;
+        try {
+            st = fs.statSync(path.join(tasksRootAbs, name));
+        }
+        catch (_e) {
+            continue;
+        }
+        if (!st.isDirectory())
+            continue;
+        const m = TASK_DIR_RE.exec(name);
+        if (!m) {
+            invalidDirs.push(name);
+            continue;
+        }
+        dirItems.push({ digits: m[1], n: Number(m[1]) });
+    }
+    dirItems.sort((a, b) => a.n - b.n);
+    // 게이트 메시지 안정성 — 발견 순이 아니라 이름 순으로 고정.
+    invalidDirs.sort((a, b) => a.localeCompare(b));
+    for (const item of dirItems) {
+        const dir = `${bp}/tasks/${item.digits}`;
+        const ids = expectedTaskDocIds(item.digits);
+        const tasksRel = `${dir}/${TASK_UNIT_BASENAMES[0]}`;
+        let executionKind = null;
+        try {
+            executionKind = taskExecutionKind(readDoc(path.join(repoRoot, tasksRel)).data);
+        }
+        catch (_error) {
+            // 파싱 실패는 validate loader의 S0가 경로와 함께 보고한다. listing은
+            // null을 운반해 consumer가 부재=commit으로 잘못 정규화하지 않게 한다.
+        }
+        const verificationRel = `${dir}/${TASK_UNIT_BASENAMES[1]}`;
+        entries.push(makeEntry({
+            dir,
+            number: item.n,
+            tasks: { rel: tasksRel, id: ids.tasks },
+            verification: { rel: verificationRel, id: ids.verification },
+            // verification node에는 review leaf 자체가 없다. verification.md를 review로
+            // alias하면 목록 소비자가 존재하지 않는 review 단계를 다시 만들어 낸다.
+            ...(executionKind === 'verification' ? {} : {
+                review: { rel: `${dir}/${TASK_UNIT_BASENAMES[2]}`, id: ids.review },
+            }),
+            executionKind,
+        }));
+    }
+    // 하드컷 뒤 구형 루트 파일은 묶음으로 세지 않고 잔존 목록으로만 보고한다.
+    // 해석은 migrate task-layout이 하고, validate는 S15로 거절한다.
+    const legacyFiles = names.filter((name) => isLegacyTasksBasename(name) || isNumberedTasksBasename(name)).sort();
+    return { entries, mixed: false, legacy: legacyFiles.length > 0, legacyFiles, invalidDirs };
+}
+module.exports = {
+    LEGACY_TASKS_BASENAME,
+    INITIAL_NUMBERED_TASKS_BASENAME,
+    NUMBERED_TASKS_RE,
+    TASK_DIR_RE,
+    TASK_UNIT_BASENAMES,
+    isNumberedTasksBasename,
+    isLegacyTasksBasename,
+    unitDocKind,
+    taskExecutionKind,
+    expectedTasksId,
+    expectedTaskDocIds,
+    listTasksDocs,
+};