@pareto4/pp-core 1.11.1 → 1.12.1

package/pp-core/bin/lib/discovery-input-check.cjs

@@ -0,0 +1,218 @@
+"use strict";
+/**
+ * Discovery input-package enforcement engine (discovery-v2 Phase 2,
+ * INPUT-02/INPUT-03, D-18/D-19/D-22).
+ *
+ * Scans the per-engagement `.planning/discovery/session-NN.md` files and the
+ * confidential input directory, failing loud (D-19) when:
+ *   - a session is `Completed` while `[TO CONFIRM]` markers remain in its
+ *     body (completed_with_unconfirmed), or
+ *   - a completeness_score of 100 counts unconfirmed topics — markers remain,
+ *     or the session is still `Pre-Filled` (score_counts_unconfirmed; D-18:
+ *     Pre-Filled is not Completed), or
+ *   - git tracks any file under `.planning/discovery-input/confidential/`
+ *     (confidential_tracked — the D-22 mechanical backstop), with a single
+ *     designed exception: the backstop `confidential/.gitignore` itself is
+ *     exempt — it is written to be committed (UAT gap 1).
+ *
+ * Graceful arms (Pitfall 4 / RESEARCH A3): a non-git project, a project with
+ * no `.planning/discovery/` directory, and a session without a frontmatter
+ * block all pass clean — the check fails only on real violations.
+ *
+ * Content-free contract (T-02-05): output names file paths, structured
+ * reasons, and counts only — never file contents.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const io = require("./io.cjs");
+const { output, error, ERROR_REASON } = io;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const fm = require("./frontmatter.cjs");
+// ─── Constants ────────────────────────────────────────────────────────────────
+const SESSION_STATUS = Object.freeze({
+    NOT_STARTED: 'Not Started',
+    PRE_FILLED: 'Pre-Filled',
+    IN_PROGRESS: 'In Progress',
+    COMPLETED: 'Completed',
+});
+const TO_CONFIRM_MARKER = '[TO CONFIRM]';
+const CONFIDENTIAL_DIR = '.planning/discovery-input/confidential/';
+// UAT gap 1 / D-22: input-package.md Step 4 writes this file with `*` +
+// `!.gitignore` so the confidentiality backstop travels with the repo; the
+// gate must accept its own designed state, else Step 6 remediation would
+// strip protection from fresh clones. `git ls-files` emits forward-slash
+// relative paths on every platform, so strict `===` equality is correct.
+const CONFIDENTIAL_BACKSTOP = `${CONFIDENTIAL_DIR}.gitignore`;
+const DISCOVERY_DIR = '.planning/discovery';
+const GIT_TIMEOUT_MS = 5000;
+// Anchored fixed-shape filename filter (threat T-02-07): never a regex over
+// untrusted session content — content scanning is literal-only below.
+const SESSION_FILE_RE = /^session-\d{2}\.md$/;
+// Frontmatter block at byte 0 — same shape extractFrontmatter recognizes, so
+// the body slice stays in lockstep with what the parser consumed.
+const FRONTMATTER_BLOCK_RE = /^---\r?\n[\s\S]+?\r?\n---/;
+// ─── Session content check (D-18/D-19) ────────────────────────────────────────
+/**
+ * Check one session file's content for pre-fill violations. Pure.
+ *
+ * Marker counting scans only the body (content after the closing frontmatter
+ * delimiter) via literal split on TO_CONFIRM_MARKER — zero regex over
+ * untrusted content (T-02-07), counts every occurrence. A session without a
+ * frontmatter block is not pre-filled (A3) and returns no violations. A
+ * session can carry both violation kinds.
+ */
+function checkSessionContent(name, content) {
+    const violations = [];
+    if (typeof content !== 'string' || content.length === 0)
+        return violations;
+    const front = fm.extractFrontmatter(content);
+    if (Object.keys(front).length === 0)
+        return violations;
+    const blockMatch = FRONTMATTER_BLOCK_RE.exec(content);
+    const body = blockMatch ? content.slice(blockMatch[0].length) : content;
+    const markers = body.split(TO_CONFIRM_MARKER).length - 1;
+    const status = typeof front.status === 'string' ? front.status : '';
+    const scoreRaw = front.completeness_score;
+    const score = typeof scoreRaw === 'string' && scoreRaw.trim() !== '' ? Number(scoreRaw) : NaN;
+    // D-19: a Completed session must have zero unconfirmed markers.
+    if (status === SESSION_STATUS.COMPLETED && markers > 0) {
+        violations.push({ session: name, reason: 'completed_with_unconfirmed', markers });
+    }
+    // D-18/D-19: a score of 100 may never count unconfirmed topics — markers
+    // remain (any status) or the session never left Pre-Filled.
+    if ((markers > 0 && score === 100) || (status === SESSION_STATUS.PRE_FILLED && score === 100)) {
+        violations.push({ session: name, reason: 'score_counts_unconfirmed', score: 100, markers });
+    }
+    return violations;
+}
+// ─── Confidential backstop (D-22) ─────────────────────────────────────────────
+/**
+ * Ask git for tracked files under the confidential directory. Array args,
+ * fixed literal path, no shell, bounded timeout (threat T-02-04; T-01-08
+ * precedent). Any failure — non-git directory, missing git binary, timeout —
+ * degrades to zero tracked files with git flagged unavailable: a non-git
+ * project cannot track anything (Pitfall 4).
+ */
+function findTrackedConfidentialInternal(cwd) {
+    try {
+        const stdout = (0, node_child_process_1.execFileSync)('git', ['ls-files', '--', CONFIDENTIAL_DIR], {
+            cwd,
+            encoding: 'utf-8',
+            timeout: GIT_TIMEOUT_MS,
+            windowsHide: true, // #685: no console-window flash on Windows
+        });
+        return { files: stdout.split(/\r?\n/).map(l => l.trim()).filter(Boolean), git: 'ok' };
+    }
+    catch {
+        return { files: [], git: 'unavailable' };
+    }
+}
+/** Public form of the D-22 backstop: tracked confidential paths, [] when none or non-git. */
+function findTrackedConfidential(cwd) {
+    return findTrackedConfidentialInternal(cwd).files;
+}
+// ─── Package aggregation ──────────────────────────────────────────────────────
+/**
+ * Aggregate the full input-package check for a project root: every
+ * `.planning/discovery/session-NN.md` runs through checkSessionContent, and
+ * each git-tracked confidential file appends a confidential_tracked
+ * violation — except the one designed path, the backstop `.gitignore`
+ * itself (exact-path exemption, UAT gap 1 / D-22). Missing discovery dir →
+ * ok:true with sessions_checked 0.
+ */
+function checkInputPackage(cwd) {
+    const violations = [];
+    let names = [];
+    try {
+        names = node_fs_1.default.readdirSync(node_path_1.default.join(cwd, DISCOVERY_DIR));
+    }
+    catch {
+        names = []; // no input package — graceful arm (Pitfall 4)
+    }
+    const sessions = names.filter(n => SESSION_FILE_RE.test(n)).sort();
+    let prefilled = 0;
+    for (const name of sessions) {
+        let content = '';
+        try {
+            content = node_fs_1.default.readFileSync(node_path_1.default.join(cwd, DISCOVERY_DIR, name), 'utf-8');
+        }
+        catch {
+            continue; // unreadable session: nothing to scan, nothing to fail on
+        }
+        const front = fm.extractFrontmatter(content);
+        const status = typeof front.status === 'string' ? front.status : '';
+        const mode = typeof front.mode === 'string' ? front.mode : '';
+        if (status === SESSION_STATUS.PRE_FILLED || mode === 'pre-fill')
+            prefilled += 1;
+        violations.push(...checkSessionContent(name, content));
+    }
+    const tracked = findTrackedConfidentialInternal(cwd);
+    for (const file of tracked.files) {
+        // Violation-policy exemption, not a git-truth change: findTrackedConfidential
+        // still reports the backstop path; only the exact designed path is skipped.
+        if (file === CONFIDENTIAL_BACKSTOP)
+            continue;
+        violations.push({ file, reason: 'confidential_tracked' });
+    }
+    const summary = {
+        sessions_checked: sessions.length,
+        prefilled,
+        git: tracked.git,
+    };
+    if (violations.length > 0)
+        return { ok: false, violations, ...summary };
+    return { ok: true, ...summary };
+}
+// ─── CLI adapter ──────────────────────────────────────────────────────────────
+/** One content-free line per violation: path + structured reason + counts (T-02-05). */
+function formatViolation(v) {
+    if (v.reason === 'confidential_tracked') {
+        return `  ${v.file}: confidential_tracked`;
+    }
+    const score = v.reason === 'score_counts_unconfirmed' ? `score: ${v.score}, ` : '';
+    return `  ${v.session}: ${v.reason} (${score}markers: ${v.markers})`;
+}
+/**
+ * CLI adapter for `pp-tools discovery input-check` (dotted form
+ * `pp-tools query discovery.input-check`).
+ *
+ * Exit semantics (D-19/D-22): any violation exits non-zero via
+ * ERROR_REASON.DISCOVERY_INPUT_CHECK_FAILED, naming each violation by path
+ * and reason — never file contents. A clean run exits 0 with
+ * { ok, sessions_checked, prefilled, git }. The command takes no positional
+ * path argument — fixed convention paths resolve against cwd, eliminating
+ * the traversal surface entirely (T-02-08).
+ */
+function cmdDiscoveryInputCheck(cwd, args, raw) {
+    // args arrive shaped ['discovery', 'input-check', ...]; global output
+    // flags are consumed by the dispatcher, so anything left is a usage error.
+    if (args.slice(2).length > 0) {
+        error('Usage: pp-tools discovery input-check', ERROR_REASON.USAGE);
+        return; // unreachable — error() exits
+    }
+    const result = checkInputPackage(cwd);
+    if (!result.ok) {
+        const lines = result.violations.map(formatViolation).join('\n');
+        error(`discovery input-check: ${result.violations.length} violation(s):\n${lines}`, ERROR_REASON.DISCOVERY_INPUT_CHECK_FAILED);
+        return; // unreachable — error() exits
+    }
+    output({
+        ok: true,
+        sessions_checked: result.sessions_checked,
+        prefilled: result.prefilled,
+        git: result.git,
+    }, raw);
+}
+module.exports = {
+    SESSION_STATUS,
+    TO_CONFIRM_MARKER,
+    checkSessionContent,
+    findTrackedConfidential,
+    checkInputPackage,
+    cmdDiscoveryInputCheck,
+};