@cheongfish/bouncer 0.0.0-stage → 0.1.13

package/dist/finalize-digest.js

@@ -0,0 +1,164 @@
+'use strict';
+const path = require('node:path');
+const paths = require("./paths");
+const { toPosix } = paths;
+const digestCollect = require("./finalize-digest-collect");
+const { collectDigestStart } = digestCollect;
+const finalizePr = require("./finalize-pr");
+const { buildPrDraft } = finalizePr;
+const digestModel = require("./finalize-digest-model");
+const { summarizeDrive, summarizeDriveIssues } = digestModel;
+const { assembleDigestBody } = digestModel;
+const { assessDigestSnapshot } = digestModel;
+const { buildBlueprintSnapshot } = digestModel;
+const { buildTaskSnapshots } = digestModel;
+const { applyTaskTrailers } = digestModel;
+const { collectDigestWarnings } = digestModel;
+const { normalizeChangedPaths, extractSymbols, parseCommitSubjects, summarizeDiffStat } = digestModel;
+const { readReviewEvidence, readReview, resolvePrBase } = digestCollect;
+const { readBlueprintIndex, collectTaskDocuments, readDigestRegistry, readDigestConfig, collectDigestGit, } = digestCollect;
+/**
+ * Explain·Quiz·PR에 필요한 finalize 입력을 한 JSON으로 모은다.
+ * 문서·Git·원장을 쓰지 않는다. drive면 integration worktree에서 git을 읽고,
+ * 깨진 원장은 기존 finalize와 같은 coordinator-ledger로 거절한다.
+ * 성공 결과에는 최상위 `coordinator`와 `tasks[].actual_paths`를 싣지 않는다 —
+ * 둘 다 drive 실행 기록이고 PR 초안은 읽지 않는다. 대신 최상위 `drive`
+ * (`summarizeDrive`: 준비 여부와 task별 status·sha, 원장 없으면 null)를 `pr`과
+ * 나란히 싣는다. `drive`는 PR 입력이 아니므로 buildPrDraft 뒤에 붙인다. `git.branch`만 원장
+ * `integrationBranch`(없으면 checkout)로 정한다. 성공 시 `pr`는
+ * buildPrDraft로 채운다 — agent가 제목·확인 방법을 손으로 조립하지 않게
+ * 하기 위함이다. `review_scope: blueprint`이면 루트 리뷰 finding을
+ * `blueprint_review`로 싣고, 아니면 그 필드는 null이다.
+ * 루트 리뷰의 deferred must_fix는 최상위 `warnings`(blueprint 모드가 아니면 [])로,
+ * 원장 event 통계는 최상위 `drive_issues`로 싣는다. 둘 다 buildPrDraft 뒤에 붙여
+ * 실행 통계가 PR 입력에 섞이지 않게 한다 — PR의 미해결 절은 같은 판정 함수로
+ * `blueprint_review`에서 직접 만든다.
+ *
+ * @param {object} opts
+ * @param {string} opts.repoRoot - 호출 checkout(보통 main). 원장 경로 해석 기준
+ * @param {string} opts.blueprintDir - blueprint 상대 경로
+ * @param {(args: string[]) => { status: number, stdout: string }} [opts.exec] - `git` 뒤 argv seam
+ * @param {Date} [opts.now] - PR 제목 날짜(KST). 기본 `new Date()`
+ * @returns {FinalizeDigest | DigestFail} 성공 digest 또는 reason 코드
+ */
+function prepareFinalizeDigest({ repoRoot, blueprintDir, exec, now, }) {
+    const bp = toPosix(blueprintDir);
+    const collected = collectDigestStart({ repoRoot, blueprintDir: bp, exec });
+    if ('ok' in collected)
+        return collected;
+    const { checkoutRoot, listing, ledger, base, head, run } = collected;
+    // blueprint index — Intent 파싱 실패는 digest 거절이 아니라 빈 intent로 두지 않는다.
+    // Intent는 Interface 필수 필드이므로 읽기 실패 시 빈 배열만 허용(파일이 있을 때).
+    const bpIndexRel = `${bp}/index.md`;
+    const bpIndexAbs = path.join(checkoutRoot, bpIndexRel);
+    const blueprintDoc = readBlueprintIndex(bpIndexAbs);
+    const blueprint = buildBlueprintSnapshot({
+        data: blueprintDoc?.data,
+        body: typeof blueprintDoc?.body === 'string' ? blueprintDoc.body : '',
+    });
+    if (!blueprint.ok) {
+        return {
+            ok: false,
+            reason: 'validate',
+            failures: [{
+                    code: 'S33',
+                    message: `blueprint Intent invalid: ${blueprint.message}`,
+                    file: bpIndexRel,
+                }],
+        };
+    }
+    const { title: bpTitle, commit_type: bpCommitType, scale: bpScale, epicId: bpEpicId, blueprintId: bpBlueprintId, stable_id: stableBlueprint, intent, outOfScope, reviewMode: blueprintReviewMode } = blueprint;
+    // provenance는 git.branch 결정에만 쓴다. 결과 JSON에 싣지 않는 이유:
+    // 원장 색인은 cleanup·finalize payload 자리이고, digest는 PR 입력이다.
+    const taskRows = collectTaskDocuments({ checkoutRoot, listing });
+    const initialTasks = buildTaskSnapshots({
+        rows: taskRows,
+        blueprintEpicId: bpEpicId,
+        blueprintId: bpBlueprintId,
+        ledger,
+    });
+    const stableIds = initialTasks.map((item) => item.digest.stable_id);
+    // 등록부는 이 진입점에서 한 번만 읽는다. 없거나 깨졌으면 null — 정규화 없이 정확 일치로 조회해
+    // 이관 전 동작과 같다(깨진 등록부의 거절은 S35 검증 소관이고 digest는 읽기 전용이다).
+    const registryRead = readDigestRegistry(checkoutRoot);
+    const registry = registryRead.status === 'ok' ? registryRead.registry : null;
+    const git = collectDigestGit({
+        checkoutRoot,
+        base,
+        head,
+        run,
+        stableIds,
+        registry,
+        integrationBranch: ledger && typeof ledger.integrationBranch === 'string'
+            ? ledger.integrationBranch
+            : null,
+    });
+    const built = applyTaskTrailers(initialTasks, git.trailerMap);
+    const changedPaths = normalizeChangedPaths(git.nameOnly);
+    const symbols = git.unified.status === 0 ? extractSymbols(git.unified.stdout) : [];
+    const commits = git.subjectLog.status === 0
+        ? parseCommitSubjects(git.subjectLog.stdout)
+        : [];
+    const diff = git.diff;
+    const diffSummary = summarizeDiffStat(git.numstat);
+    const rootReview = blueprintReviewMode
+        ? readReview(path.join(checkoutRoot, `${bp}/review.md`))
+        : null;
+    const assessed = assessDigestSnapshot({
+        built,
+        ledger,
+        blueprintReviewMode,
+        rootReview,
+        changedPaths,
+        diffSummaryUnavailable: !diffSummary,
+    });
+    const unverified = assessed.unverified;
+    const blueprintReview = assessed.blueprint_review;
+    // branch는 collector가 integrationBranch 우선순위로 수집한다.
+    const branch = git.branch;
+    // pr는 나머지 digest 필드를 입력으로 쓴다 — 순환 참조를 피하려고 본문을
+    // 먼저 조립한 뒤 buildPrDraft에 넘긴다.
+    const body = assembleDigestBody({
+        blueprint: {
+            dir: bp,
+            stable_id: stableBlueprint,
+            title: bpTitle,
+            intent,
+            commit_type: bpCommitType,
+            scale: bpScale,
+        },
+        range: {
+            base,
+            head,
+            diff_sha: diff.ok ? diff.sha : null,
+        },
+        git: {
+            branch,
+            pr_base: resolvePrBase(checkoutRoot, run),
+        },
+        tasks: assessed.tasks,
+        changed_paths: changedPaths,
+        symbols,
+        commits,
+        diff: diffSummary,
+        reviewEvidence: readReviewEvidence(path.join(checkoutRoot, `${bp}/review.md`), `${bp}/review.md`),
+        unverified,
+        out_of_scope: outOfScope,
+        blueprint_review: blueprintReview,
+    });
+    // task 범위는 경고를 만들지 않는다 — blueprintReview는 blueprint 모드에서만 non-null.
+    const warnings = blueprintReview ? collectDigestWarnings(blueprintReview.findings) : [];
+    const config = readDigestConfig(checkoutRoot) ?? {};
+    return {
+        ...body,
+        pr: buildPrDraft(body, {
+            now: now instanceof Date ? now : new Date(),
+            config,
+        }),
+        // PR draft 입력(body)에 섞이지 않도록 buildPrDraft 호출 뒤 반환 객체에만 붙인다.
+        drive: summarizeDrive(ledger),
+        warnings,
+        drive_issues: summarizeDriveIssues(ledger, warnings.length),
+    };
+}
+module.exports = { prepareFinalizeDigest, summarizeDrive, summarizeDriveIssues };

package/dist/finalize-explain.js

@@ -0,0 +1,176 @@
+'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 render = require("./render");
+const { renderDoc } = render;
+const commitSha = require("./commit-sha");
+const { normalizeCommitSha } = commitSha;
+const collect = require("./finalize-collect");
+const { stableIdFromTaskData, taskStableParts } = collect;
+function asRecord(value) { return value; }
+const TASK_SECTIONS = [
+    ['goal', /^##\s+(Goal\s*&\s*intent|목적[·・.]?의도)\s*$/i],
+    ['currentBehavior', /^##\s+(Current\s+behavior|현재\s*동작)\s*$/i],
+    ['targetBehavior', /^##\s+(Target\s+behavior|목표\s*동작)\s*$/i],
+    ['interface', /^##\s+(Interface|인터페이스)\s*$/i],
+    ['touch', /^##\s+(Touch|수정할\s*부분)\s*$/i],
+    ['doNotTouch', /^##\s+(Do\s+not\s+touch|절대\s*수정\s*금지)\s*$/i],
+    ['constraints', /^##\s+(Constraints|제약)\s*$/i],
+    ['checklist', /^##\s+(Checklist|체크리스트)\s*$/i],
+];
+/**
+ * tasks.md에서 Explain에 보존하는 설계 절의 본문을 읽는다.
+ * HTML 주석은 template 안내이므로 본문에서 제외하고, 누락된 절은 null로 둔다.
+ *
+ * @param {unknown} body - tasks.md 본문
+ * @returns {Record<string, string | null>} 절 키에서 잘라낸 본문으로의 매핑
+ */
+function parseTasksSections(body) {
+    const lines = (typeof body === 'string' ? body : '').replace(/<!--[\s\S]*?-->/g, '').split('\n');
+    const starts = [];
+    for (let i = 0; i < lines.length; i++) {
+        for (const [key, re] of TASK_SECTIONS)
+            if (re.test(lines[i].trim())) {
+                starts.push({ key: key, line: i });
+            }
+    }
+    const out = Object.fromEntries(TASK_SECTIONS.map(([key]) => [key, null]));
+    for (let i = 0; i < starts.length; i++) {
+        const start = starts[i];
+        const end = i + 1 < starts.length ? starts[i + 1].line : lines.length;
+        out[start.key] = lines.slice(start.line + 1, end).join('\n').trim() || null;
+    }
+    return out;
+}
+/**
+ * explain.md frontmatter에 task_commits를 쓴다. 파일이 없으면 false.
+ * 기존 배열은 통째로 교체한다 — finalize가 삭제 직전 스냅샷의 정본이다.
+ * 직렬화는 `{ task, sha, intent_anchor }`만 남긴다. legacy `{ id, sha }`는 쓰지 않는다.
+ * 부모 Epic·Blueprint를 못 읽거나 행의 stable ref가 그 번호와 다르면 그 행은
+ * 쓰지 않는다.
+ *
+ * @param {object} opts
+ * @param {string} opts.repoRoot - 저장소 루트
+ * @param {string} opts.blueprintDir - blueprint 상대 경로
+ * @param {TaskCommitEntry[]} opts.taskCommits - collectTaskCommits 결과
+ * @returns {boolean} 썼으면 true, explain 부재·파싱 실패면 false
+ */
+function writeExplainTaskCommits({ repoRoot, blueprintDir, taskCommits }) {
+    const explainRel = `${toPosix(blueprintDir)}/explain.md`;
+    const abs = path.join(repoRoot, explainRel);
+    if (!fs.existsSync(abs))
+        return false;
+    const { data, body } = readDoc(abs);
+    if (!data || typeof data !== 'object')
+        return false;
+    const bouncer = asRecord(asRecord(data).bouncer);
+    const epicId = bouncer.epic_id;
+    const blueprintId = bouncer.blueprint_id;
+    // collectTaskCommits가 걸러도 직접 호출이면 다른 Epic·Blueprint 행이
+    // 들어온다. 부모 번호를 못 읽거나 다르면 새 행을 남기지 않는다.
+    if (typeof epicId !== 'string' || typeof blueprintId !== 'string') {
+        bouncer.task_commits = [];
+    }
+    else {
+        bouncer.task_commits = taskCommits.flatMap((entry) => {
+            const parts = taskStableParts(entry.task);
+            if (!parts || parts.epicKey !== epicId || parts.blueprintKey !== blueprintId)
+                return [];
+            return [{
+                    task: entry.task,
+                    sha: entry.sha,
+                    intent_anchor: entry.intent_anchor,
+                }];
+        });
+    }
+    fs.writeFileSync(abs, renderDoc(data, body));
+    return true;
+}
+/**
+ * task 문서에서 장기 보존할 설계 절만 렌더링한다.
+ * parseTasksSections가 반환한 본문을 그대로 사용해 작성자가 나눈 줄바꿈을
+ * 보존한다. Do not touch·Checklist·verification·review는 실행 시점 범위
+ * 통제·절차라서 여기 넣지 않는다 — Git history와 삭제된 task 원문이 정본이다.
+ * Current/Target은 값이 있을 때만 넣어 legacy task에 두 절을 요구하지 않는다.
+ * 제목은 frontmatter로 stable ID를 만들 수 있으면 `### EPIC-…/BP-…/TASK-…`(번호 경로) 또는
+ * `### <epic-slug>/<bp-slug>/NNN`(slug 경로)이고,
+ * `commits`에 그 ID의 sha8이 있으면 ` · \`sha8\``을 붙인다. 못 만들면 기존
+ * `### Task NNN`으로 폴백한다.
+ *
+ * @param {TaskUnitLike[] | undefined} taskUnits - Blueprint의 task 묶음
+ * @param {Map<string, TrailerCommit>} [commits] - resolveTaskCommits 결과. 선택
+ * @returns {string} Explain `## Tasks` 본문. 장기 절이 없으면 빈 문자열
+ */
+function buildTaskContext(taskUnits, commits) {
+    const units = (Array.isArray(taskUnits) ? taskUnits : [])
+        .filter((unit) => unit && unit.tasks && typeof unit.tasks.body === 'string')
+        .slice()
+        .sort((a, b) => (typeof a.number === 'number' ? a.number : Infinity)
+        - (typeof b.number === 'number' ? b.number : Infinity));
+    const rendered = [];
+    for (const unit of units) {
+        const sections = parseTasksSections(unit.tasks && unit.tasks.body);
+        // 순서는 Plan/intent 소비자가 기대하는 장기 allowlist와 같다.
+        // doNotTouch는 의도적으로 빠진다 — 후속 금지는 Interface·Constraints에 적는다.
+        const selected = [
+            ['Goal & intent', sections.goal],
+            ['Current behavior', sections.currentBehavior],
+            ['Target behavior', sections.targetBehavior],
+            ['Interface', sections.interface],
+            ['Touch', sections.touch],
+            ['Constraints', sections.constraints],
+        ].filter(([, body]) => typeof body === 'string' && body.trim());
+        if (!selected.length)
+            continue;
+        const stableId = stableIdFromTaskData(unit.tasks && unit.tasks.data);
+        let heading;
+        if (stableId) {
+            const hit = commits && commits.get(stableId);
+            const sha8 = hit && normalizeCommitSha(hit.sha8 || hit.sha);
+            // SHA가 있으면 통합 commit을 제목에 남긴다. 없으면 ID만 — trailer 해석
+            // 실패·미존재 시에도 제목 형식을 깨지 않기 위함.
+            heading = sha8 ? `### ${stableId} · \`${sha8}\`` : `### ${stableId}`;
+        }
+        else {
+            const number = typeof unit.number === 'number'
+                ? String(unit.number).padStart(3, '0')
+                : 'unknown';
+            heading = `### Task ${number}`;
+        }
+        rendered.push([heading, ...selected.flatMap(([h, body]) => [
+                `#### ${h}`,
+                body,
+            ])].join('\n\n'));
+    }
+    return rendered.length ? `## Tasks\n\n${rendered.join('\n\n')}\n` : '';
+}
+function replaceTaskContext(body, taskContext) {
+    if (!taskContext)
+        return body;
+    const lines = body.split('\n');
+    const start = lines.findIndex((line) => /^##\s+Tasks\s*$/i.test(line.trim()));
+    if (start < 0)
+        return `${body.replace(/\s*$/, '')}\n\n${taskContext}`;
+    let end = start + 1;
+    while (end < lines.length && !/^##\s+\S/.test(lines[end].trim()))
+        end += 1;
+    return [...lines.slice(0, start), taskContext.trimEnd(), ...lines.slice(end)].join('\n');
+}
+function writeExplainTaskContext({ repoRoot, blueprintDir, taskContext }) {
+    if (!taskContext)
+        return false;
+    const explainRel = `${toPosix(blueprintDir)}/explain.md`;
+    const abs = path.join(repoRoot, explainRel);
+    if (!fs.existsSync(abs))
+        return false;
+    const { data, body } = readDoc(abs);
+    if (!data || typeof data !== 'object' || typeof body !== 'string')
+        return false;
+    fs.writeFileSync(abs, renderDoc(data, replaceTaskContext(body, taskContext)));
+    return true;
+}
+module.exports = { writeExplainTaskCommits, buildTaskContext, writeExplainTaskContext };