@cheongfish/bouncer 0.0.0-stage → 0.1.13

package/dist/finalize-collect.js

@@ -0,0 +1,343 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const paths = require("./paths");
+const { toPosix } = paths;
+const frontmatter = require("./frontmatter");
+const { readDoc } = frontmatter;
+const tasksDocs = require("./tasks-docs");
+const { listTasksDocs } = tasksDocs;
+const scope = require("./scope");
+const { readCoordinatorLedger } = scope;
+const commitSha = require("./commit-sha");
+const { buildStableProvenance, normalizeCommitSha } = commitSha;
+const contextIds = require("./context-ids");
+const { parseStableId } = contextIds;
+const gitOps = require("./git-ops");
+const { resolveCheckoutBranch } = gitOps;
+function asRecord(value) { return value; }
+// 번호·slug 두 형식의 task stable ID에서 epic·blueprint key와 task 번호를 꺼낸다. task가 없는 intent ID는 null이다.
+// 부모(Explain frontmatter) 비교는 형식별 key 문자열 그대로 한다 — 형식 간 변환을 여기서 하지 않는다.
+function taskStableParts(id) {
+    const parsed = parseStableId(id);
+    return parsed && parsed.task !== null
+        ? { epicKey: parsed.epicKey, blueprintKey: parsed.blueprintKey, task: parsed.task }
+        : null;
+}
+// buildStableProvenance가 던지는 "입력 형식 위반" 메시지만 가린다(번호/slug key, TASKS-NNN).
+const PROVENANCE_INPUT_ERROR_RE = /must be a three-digit id|must be a slug|must be TASKS-NNN/;
+/**
+ * tasks.md frontmatter에서 stable Task ID를 만든다.
+ * epic_id·blueprint_id·id가 정본이 아니면 null — 잘못된 값을 패딩하지 않는다.
+ *
+ * @param {unknown} data - tasks.md frontmatter 루트
+ * @returns {string | null} `EPIC-ddd/BP-ddd/TASK-ddd` 또는 `<epic>/<bp>/ddd`, 불가 시 null
+ */
+function stableIdFromTaskData(data) {
+    // data·bouncer 부재는 legacy `### Task NNN` 폴백이다. asRecord만 쓰면
+    // undefined.bouncer에서 throw해 retention·순수 테스트 fixture까지 깨진다.
+    if (!data || typeof data !== 'object')
+        return null;
+    const bouncer = asRecord(asRecord(data).bouncer);
+    if (!bouncer || typeof bouncer !== 'object')
+        return null;
+    try {
+        return buildStableProvenance({
+            epicId: bouncer.epic_id,
+            blueprintId: bouncer.blueprint_id,
+            taskId: bouncer.id,
+        }).task;
+    }
+    catch (error) {
+        // 번호·slug key·TASKS-NNN 계약 위반만 흡수한다. 그 외는 호출부에서 본다.
+        if (error instanceof Error
+            && PROVENANCE_INPUT_ERROR_RE.test(error.message)) {
+            return null;
+        }
+        throw error;
+    }
+}
+function stringOrNull(value) {
+    return typeof value === 'string' && value !== '' ? value : null;
+}
+/**
+ * 원장에서 finalize·digest가 실제로 읽는 여섯 필드만 접는다.
+ * task SHA·decisions·repair wave는 마감 JSON에 실리면 모델이 drive 실행
+ * 기록을 재사용하므로 여기서 버린다. worker별 `git symbolic-ref`도 같은
+ * 이유로 호출하지 않는다 — 소비처는 integration branch와 worktree 경로뿐이다.
+ * 원장이 없으면 위임 실행이 아니므로 null. 빈 객체를 주면 호출부가
+ * "drive인데 기록이 비었다"와 구분하지 못한다.
+ *
+ * @param {CoordinatorLedgerLike | null | undefined} ledger - coordinator 원장. 없으면 null
+ * @param {object} [paths] - integration·원장 경로. 생략 시 둘 다 null
+ * @param {string | null} [paths.integrationPath] - integration worktree 절대 경로
+ * @param {string | null} [paths.ledgerFile] - 원장 파일 절대 경로
+ * @returns {{
+ *   status: 'ok', ledgerFile: string | null, base: string | null,
+ *   integrationBranch: string | null, integrationPath: string | null,
+ *   worktrees: string[]
+ * } | null} 원장 없으면 null
+ */
+function buildCoordinatorProvenance(ledger, { integrationPath = null, ledgerFile = null } = {}) {
+    if (!ledger)
+        return null;
+    // 빈 workerPath는 정리 대상이 아니다. 순서는 원장 task 순서를 유지한다.
+    const workerPaths = (Array.isArray(ledger.tasks) ? ledger.tasks : [])
+        .filter((entry) => Boolean(entry) && typeof entry === 'object')
+        .map((entry) => stringOrNull(entry.workerPath))
+        .filter((p) => Boolean(p));
+    return {
+        status: 'ok',
+        // 성공 경로도 원장 경로를 싣는다. unreadable 분기에만 채우면 소비자가
+        // `ledgerFile: null`을 "원장이 없다"와 "원장은 있는데 알려주지 않았다"로
+        // 구분하지 못한다.
+        ledgerFile,
+        base: stringOrNull(ledger.base),
+        integrationBranch: stringOrNull(ledger.integrationBranch)
+            || resolveCheckoutBranch(integrationPath),
+        integrationPath,
+        // cleanup 목록: integration이 먼저고, 할당된 worker worktree가 뒤따른다.
+        // payload의 top-level `worktrees`는 정리 계약(SKILL step 5,
+        // cleanup-handoff.md)이 읽는 안정된 자리이다.
+        worktrees: [
+            ...(integrationPath ? [integrationPath] : []),
+            ...workerPaths,
+        ],
+    };
+}
+/**
+ * 원장 읽기 결과만으로 provenance를 접는다.
+ * finalize는 같은 읽기로 `integration`도 만들어 두 필드가 서로 다른 원장을
+ * 가리키지 않게 한다. 공개 API는 아래 `collectCoordinatorProvenance`다.
+ *
+ * @param {ReturnType<typeof readCoordinatorLedger>} read - `readCoordinatorLedger` 결과
+ * @returns {CoordinatorProvenance | UnreadableProvenance | null} 원장 없음은 null, 깨진 원장은 unreadable
+ */
+function provenanceFromLedgerRead(read) {
+    if (!read.ok) {
+        if (read.reason !== 'unreadable-ledger')
+            return null;
+        return {
+            status: 'unreadable',
+            ledgerFile: read.ledgerFile || null,
+            integrationPath: read.integrationPath || null,
+            base: null,
+            integrationBranch: null,
+            worktrees: [],
+        };
+    }
+    return buildCoordinatorProvenance(read.ledger, {
+        integrationPath: read.integrationPath,
+        ledgerFile: read.ledgerFile,
+    });
+}
+/**
+ * 저장소에서 원장을 찾아 provenance로 접는다.
+ *
+ * 원장이 아예 없으면 위임 실행이 아니므로 null이다. 읽을 수는 있으나 깨진
+ * 원장은 null이 아니다 — null로 접으면 top-level `worktrees: []`만 남아
+ * 비-drive finalize와 구분되지 않고, 검증되지 않은 fan-in이 완료로
+ * 기록된다. `status`와 고칠 파일 경로를 실어 호출부가 멈출 수 있게 한다.
+ *
+ * @param {object} opts
+ * @param {string} opts.repoRoot - 저장소 루트 절대 경로
+ * @param {string} opts.blueprintDir - blueprint 상대 경로
+ * @returns {CoordinatorProvenance | UnreadableProvenance | null} 원장 없음은 null
+ */
+function collectCoordinatorProvenance({ repoRoot, blueprintDir }) {
+    return provenanceFromLedgerRead(readCoordinatorLedger({ repoRoot, blueprint: blueprintDir }));
+}
+/**
+ * finalize가 closed 전이와 함께 지울 일회성 문서 경로를 모은다.
+ * tasks.md·verification.md·review.md와 (있을 때만) context-review.md가 대상이다.
+ * explain.md·index.md는 절대 넣지 않는다.
+ * light blueprint는 context-review.md가 없으므로 목록에 나타나지 않는다.
+ *
+ * @param {object} opts
+ * @param {string} opts.repoRoot - 저장소 루트
+ * @param {string} opts.blueprintDir - blueprint 상대 경로
+ * @returns {string[]} 존재하는 일회성 문서의 posix 상대 경로
+ */
+/**
+ * closed 전이에 지울 일회성 문서 경로를 모은다.
+ * task leaf와 context-review는 항상 대상이다. 루트 review.md는
+ * `review_scope: blueprint`일 때만 넣는다 — 구형 blueprint의 루트
+ * 파일은 사람이 둔 증적이라 마감이 지우면 안 된다.
+ *
+ * @param {object} opts - 저장소와 blueprint 경로
+ * @param {string} opts.repoRoot - 저장소 루트 절대 경로
+ * @param {string} opts.blueprintDir - blueprint 상대 경로
+ * @returns {string[]} 존재하는 일회성 문서의 상대 경로
+ */
+function collectTransientRels({ repoRoot, blueprintDir }) {
+    const listing = listTasksDocs({ repoRoot, blueprintDir });
+    const rels = [];
+    for (const entry of listing.entries) {
+        // verification.md도 task 실행 증적이라 closed 뒤에는 남기지 않는다.
+        for (const leaf of ['tasks', 'verification', 'review']) {
+            const ref = entry[leaf];
+            // verification node는 review leaf를 만들지 않는다. 없는 leaf는 삭제
+            // 대상으로 합성하지 않고, 실제 listing이 제공한 문서만 수집한다.
+            if (!ref)
+                continue;
+            const rel = ref.rel;
+            if (fs.existsSync(path.join(repoRoot, rel)))
+                rels.push(rel);
+        }
+    }
+    const bp = toPosix(blueprintDir);
+    const contextReviewRel = `${bp}/context-review.md`;
+    if (fs.existsSync(path.join(repoRoot, contextReviewRel))) {
+        rels.push(contextReviewRel);
+    }
+    if (isBlueprintReviewScopeAt(repoRoot, bp)) {
+        const rootReviewRel = `${bp}/review.md`;
+        if (fs.existsSync(path.join(repoRoot, rootReviewRel))) {
+            rels.push(rootReviewRel);
+        }
+    }
+    return rels;
+}
+/**
+ * blueprint index의 `review_scope === 'blueprint'`만 모드로 본다.
+ * 파일 부재·파싱 실패는 구형 계약(지우지 않음)으로 접는다 — 모드로
+ * 오인하면 남겨야 할 루트 리뷰를 지운다.
+ *
+ * @param {string} repoRoot - 저장소 루트
+ * @param {string} blueprintDir - blueprint 상대 경로
+ * @returns {boolean} 모드이면 true
+ */
+function isBlueprintReviewScopeAt(repoRoot, blueprintDir) {
+    const abs = path.join(repoRoot, `${toPosix(blueprintDir)}/index.md`);
+    if (!fs.existsSync(abs))
+        return false;
+    try {
+        const { data } = readDoc(abs);
+        const bouncer = asRecord(asRecord(data).bouncer);
+        return bouncer.review_scope === 'blueprint';
+    }
+    catch (error) {
+        // YAML/frontmatter 파싱 실패만 흡수한다. 권한 오류는 숨기지 않는다.
+        if (error instanceof Error && (error.name === 'YAMLException' || /frontmatter|YAML/i.test(error.message))) {
+            return false;
+        }
+        throw error;
+    }
+}
+/**
+ * explain.md frontmatter의 Epic·Blueprint 번호를 읽는다.
+ * task_commits 행의 stable ref가 이 부모와 같은 번호인지 대조하기 위해서다.
+ *
+ * @param {object} opts
+ * @param {string} opts.repoRoot - 저장소 루트
+ * @param {string} opts.blueprintDir - blueprint 상대 경로
+ * @returns {{epicId: string, blueprintId: string} | null} 읽을 수 없으면 null
+ */
+function explainParentIds({ repoRoot, blueprintDir }) {
+    const abs = path.join(repoRoot, `${toPosix(blueprintDir)}/explain.md`);
+    if (!fs.existsSync(abs))
+        return null;
+    let data;
+    try {
+        data = readDoc(abs).data;
+    }
+    catch (_e) {
+        // 깨진 YAML·frontmatter만 흡수한다. 부모 ID를 경로에서 추측하면 다른
+        // Blueprint의 커밋이 이 Explain에 실릴 수 있다. collectTaskCommits는
+        // null이면 행을 만들지 않고, writeExplainTaskCommits도 같은 부모 대조로
+        // 직렬화를 거절한다.
+        return null;
+    }
+    if (!data || typeof data !== 'object')
+        return null;
+    const bouncer = asRecord(asRecord(data).bouncer);
+    const epicId = bouncer.epic_id;
+    const blueprintId = bouncer.blueprint_id;
+    if (typeof epicId !== 'string' || typeof blueprintId !== 'string')
+        return null;
+    return { epicId, blueprintId };
+}
+/**
+ * tasks.md의 commit_sha와 stable Task ID를 모아 explain 보존용 task_commits를 만든다.
+ * 새 행은 `{ task, sha, intent_anchor }`만 쓴다. sha가 없거나 짧은 hex가 아니면 건너뛴다.
+ * `commits`에 trailer로 찾은 SHA가 있으면 그 sha8을 쓰고, 없을 때만 commit_sha로 폴백한다.
+ * stable ID가 정본이 아니거나 Explain 부모 ID를 못 읽거나 Epic·Blueprint가
+ * 다르면 행을 만들지 않는다.
+ *
+ * @param {object} opts
+ * @param {string} opts.repoRoot - 저장소 루트
+ * @param {string} opts.blueprintDir - blueprint 상대 경로
+ * @param {Map<string, TrailerCommit>} [opts.commits] - resolveTaskCommits 결과. 있으면 trailer 우선
+ * @returns {TaskCommitEntry[]} 쓸 수 있는 provenance 행. 없으면 빈 배열
+ */
+function collectTaskCommits({ repoRoot, blueprintDir, commits }) {
+    const parent = explainParentIds({ repoRoot, blueprintDir });
+    // 부모 번호를 못 읽으면 행을 만들지 않는다. 경로에서 채우면 다른
+    // Blueprint SHA가 이 Explain에 남는다.
+    if (!parent)
+        return [];
+    const listing = listTasksDocs({ repoRoot, blueprintDir });
+    const out = [];
+    for (const entry of listing.entries) {
+        if (entry.number == null)
+            continue;
+        const abs = path.join(repoRoot, entry.tasks.rel);
+        if (!fs.existsSync(abs))
+            continue;
+        let data;
+        try {
+            data = readDoc(abs).data;
+        }
+        catch (_e) {
+            continue;
+        }
+        const bouncer = asRecord(asRecord(data).bouncer);
+        let provenance;
+        try {
+            provenance = buildStableProvenance({
+                epicId: bouncer.epic_id,
+                blueprintId: bouncer.blueprint_id,
+                taskId: bouncer.id,
+            });
+        }
+        catch (error) {
+            // epic_id·blueprint_id가 \d{3}이 아니거나 id가 TASKS-NNN이 아닌 경우만
+            // 건너뛴다. 잘못된 값을 패딩하면 다른 Blueprint 커밋과 같은 ref가 된다.
+            if (error instanceof Error
+                && PROVENANCE_INPUT_ERROR_RE.test(error.message)) {
+                continue;
+            }
+            throw error;
+        }
+        const parts = taskStableParts(provenance.task);
+        // helper가 만든 문자열만 온다. 매칭 실패는 계약 파손이라 추측해서 채우지 않는다.
+        if (!parts)
+            continue;
+        if (parts.epicKey !== parent.epicId || parts.blueprintKey !== parent.blueprintId) {
+            continue;
+        }
+        // trailer SHA가 있으면 worker worktree의 commit_sha보다 우선한다 —
+        // integration에 cherry-pick된 도달 가능 commit을 Explain이 가리키게 하기 위함.
+        const trailer = commits && commits.get(provenance.task);
+        const sha = trailer
+            ? normalizeCommitSha(trailer.sha8 || trailer.sha)
+            : normalizeCommitSha(bouncer.commit_sha);
+        if (!sha)
+            continue;
+        out.push({
+            task: provenance.task,
+            sha,
+            intent_anchor: `task-${parts.task}`,
+        });
+    }
+    return out;
+}
+module.exports = {
+    taskStableParts,
+    stableIdFromTaskData,
+    buildCoordinatorProvenance,
+    provenanceFromLedgerRead,
+    collectCoordinatorProvenance,
+    collectTransientRels,
+    collectTaskCommits,
+};

package/dist/finalize-comprehension.js

@@ -0,0 +1,116 @@
+'use strict';
+// 사용자 quiz 확인 이후 explain.md의 `bouncer.comprehension` 단일 entry를 생성하는 소유자.
+// 수기 복사로 range/diff_sha가 어긋나는 일을 막으려고 digest·HEAD·computeDiffSha 세 곳이
+// 모두 같을 때만 쓴다. G16 판정과 computeDiffSha 의미는 건드리지 않는다.
+const nodeFs = require('node:fs');
+const nodePath = require('node:path');
+const { spawnSync } = require('node:child_process');
+const comprehension = require("./comprehension");
+const frontmatter = require("./frontmatter");
+const render = require("./render");
+const paths = require("./paths");
+const timeLib = require("./time");
+const { computeDiffSha, resolveComprehensionEntry } = comprehension;
+const { parseFrontmatter } = frontmatter;
+const { renderDoc } = render;
+const { toPosix } = paths;
+const { nowIsoKst } = timeLib;
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function nonEmpty(value) {
+    return typeof value === 'string' && value.trim() !== '';
+}
+/**
+ * 사용자 quiz 확인 뒤 blueprint explain.md에 comprehension entry를 정확히 한 개 기록한다.
+ * 모든 거절은 파일 bytes를 바꾸기 전에 일어난다. 쓰기는 같은 디렉터리의 임시 파일에 쓴 뒤
+ * rename하므로 쓰기 중 실패해도 기존 explain.md는 온전하다.
+ *
+ * @param {object} opts
+ * @param {string} opts.repoRoot - 실행 checkout 루트(explain.md를 쓰는 곳)
+ * @param {string} opts.blueprintDir - blueprint 상대 경로
+ * @param {unknown} opts.digest - `finalize prepare`가 낸 digest JSON(파싱된 값)
+ * @param {boolean} opts.confirmed - 실제 사용자 quiz 답변을 받은 controller의 --confirm-quiz
+ * @param {boolean} opts.refresh - 기존 유효 기록을 후속 HEAD로 갱신하는 --refresh
+ * @param {object} [opts.deps] - 테스트 seam: exec(git argv), now, fs
+ * @returns {RecordResult} 기록한 entry 또는 거절 reason
+ *   (consent-required: 확인·refresh 둘 다 없음, input-invalid: digest·Explain·기존 기록 손상,
+ *   target-stale: digest가 현재 HEAD·diff fingerprint·기존 base와 다름)
+ */
+function recordComprehension({ repoRoot, blueprintDir, digest, confirmed, refresh, deps }) {
+    const fs = (deps && deps.fs) || nodeFs;
+    const exec = (deps && deps.exec) || ((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 || '' };
+    });
+    const now = (deps && deps.now) || (() => new Date());
+    const invalid = { ok: false, reason: 'comprehension-input-invalid' };
+    const stale = { ok: false, reason: 'comprehension-target-stale' };
+    // 1. 동의가 가장 먼저다. 확인도 refresh도 없으면 입력을 읽지도 않아 어떤 검증 결과도 새지 않는다.
+    if (!confirmed && !refresh)
+        return { ok: false, reason: 'comprehension-consent-required' };
+    // 2. digest 형태 검증. 필요한 필드가 문자열이 아니면 손상 입력이다.
+    if (!isRecord(digest) || !isRecord(digest.blueprint) || !isRecord(digest.range))
+        return invalid;
+    const { base, head, diff_sha: digestSha } = digest.range;
+    if (!nonEmpty(base) || !nonEmpty(head) || !nonEmpty(digestSha))
+        return invalid;
+    const bp = toPosix(blueprintDir).replace(/\/+$/, '');
+    if (!nonEmpty(digest.blueprint.dir) || toPosix(digest.blueprint.dir).replace(/\/+$/, '') !== bp)
+        return invalid;
+    // 3. explain.md 읽기·파싱. 없거나 frontmatter가 깨졌으면 쓸 곳이 없다.
+    const explainPath = nodePath.join(repoRoot, bp, 'explain.md');
+    let parsed;
+    try {
+        parsed = parseFrontmatter(fs.readFileSync(explainPath, 'utf8'));
+    }
+    catch (_e) {
+        // 파일 부재·읽기 실패·frontmatter 파싱 실패를 모두 "쓸 수 없는 Explain"으로 모은다.
+        // 어느 경우든 아직 아무것도 쓰지 않았으므로 하나의 거절로 합쳐도 안전하다.
+        return invalid;
+    }
+    if (!isRecord(parsed.data) || !isRecord(parsed.data.bouncer))
+        return invalid;
+    const data = parsed.data;
+    const bouncer = data.bouncer;
+    // 4. 현재 HEAD·diff fingerprint가 digest와 같아야 한다. 후속 커밋 뒤의 낡은 digest를 거른다.
+    const headNow = exec(['rev-parse', 'HEAD']);
+    if (headNow.status !== 0 || headNow.stdout.trim() !== head)
+        return stale;
+    const diff = computeDiffSha({
+        repoRoot, base, exec: (args) => ({ ...exec(args), stderr: '' }),
+    });
+    if (!diff.ok || diff.sha !== digestSha)
+        return stale;
+    // 5. refresh는 기존 유효 기록이 있을 때만, 그리고 base가 같을 때만 range_from을 유지한 채 갱신한다.
+    //    quiz를 건너뛰는 최초 기록의 대체 수단이 되지 않게 한다.
+    let rangeFrom = base;
+    if (refresh) {
+        const existing = resolveComprehensionEntry(bouncer.comprehension);
+        if (!existing.ok)
+            return invalid;
+        if (existing.entry.range_from !== base)
+            return stale;
+        rangeFrom = existing.entry.range_from;
+    }
+    // 6. task 필드 없는 단일 entry로 배열을 통째 교체한다.
+    const entry = {
+        range_from: rangeFrom, range_to: head, diff_sha: digestSha, recorded_at: nowIsoKst(now()),
+    };
+    bouncer.comprehension = [entry];
+    // 7. 임시 파일 → rename. 쓰기 실패는 호출자에게 전파하되 임시 파일은 남기지 않는다.
+    const tmpPath = `${explainPath}.tmp-${process.pid}`;
+    try {
+        fs.writeFileSync(tmpPath, renderDoc(data, parsed.body));
+        fs.renameSync(tmpPath, explainPath);
+    }
+    catch (error) {
+        // 정리 실패(이미 없음 등)는 원래 오류를 가리면 안 되므로 force로 흡수한다.
+        nodeFs.rmSync(tmpPath, { force: true });
+        throw error;
+    }
+    return { ok: true, entry };
+}
+module.exports = { recordComprehension };