@pareto4/pp-core 1.19.0 → 1.21.0

package/pp-core/bin/lib/plan-sizing.cjs

@@ -0,0 +1,346 @@
+"use strict";
+/**
+ * Plan Sizing: the per-plan budget and the plan-split check (Phase 36).
+ *
+ * ADR-457 build-at-publish: this TypeScript file is the SOURCE OF TRUTH. It
+ * compiles to the gitignored `pp-core/bin/lib/plan-sizing.cjs`; do NOT
+ * hand-edit the compiled output.
+ *
+ * Two consumers share these numbers so the planner and the plan checker cannot
+ * disagree about them:
+ *   - `init plan-phase` spreads `planBudget(config.context_window)` into its JSON
+ *     (D-03): the planner reads the window and the per-plan budget there.
+ *   - `check plan-sizing <phase>` reads the phase's PLAN.md files and reports
+ *     plans over the 6-task ceiling, plans over the budget, and serial splits
+ *     that have neither a parallelism nor a budget reason (D-05, D-14). Executed
+ *     plans are reported but never block.
+ *
+ * A larger window raises only the per-plan budget (50% of the window). The task
+ * band (20000-60000 tokens, the 10-30% of the 200k calibration) and the 6-task
+ * ceiling stay fixed (D-04). The check is read-only: it never writes.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIN_TOKENS_PER_FILE = exports.TASK_TOKENS_MAX = exports.TASK_TOKENS_MIN = exports.MAX_TASKS_PER_PLAN = exports.DEFAULT_CONTEXT_WINDOW = void 0;
+exports.resolveContextWindow = resolveContextWindow;
+exports.planBudget = planBudget;
+exports.parseEstimate = parseEstimate;
+exports.analyzePlanSizing = analyzePlanSizing;
+exports.readPhasePlans = readPhasePlans;
+exports.computePlanSizing = computePlanSizing;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseMod = require("./phase.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const coreUtilsMod = require("./core-utils.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const frontmatterMod = require("./frontmatter.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const configLoaderMod = require("./config-loader.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseScopeMod = require("./phase-scope.cjs");
+const { computeDependencyLevels, countPlanTasks } = phaseMod;
+const { extractCanonicalPlanId } = coreUtilsMod;
+const { extractFrontmatter } = frontmatterMod;
+const { loadConfig } = configLoaderMod;
+const { resolvePhaseForRead } = phaseScopeMod;
+exports.DEFAULT_CONTEXT_WINDOW = 200000;
+exports.MAX_TASKS_PER_PLAN = 6;
+/** 10% of the 200k calibration (D-04); stated in tokens so a 1M window does not inflate tasks. */
+exports.TASK_TOKENS_MIN = 20000;
+/** 30% of the 200k calibration (D-04). */
+exports.TASK_TOKENS_MAX = 60000;
+/** Cross-check floor for the estimate against the number of files a plan touches (D-10). */
+exports.MIN_TOKENS_PER_FILE = 5000;
+/** A positive integer window; anything else (a bad config value) falls back to the default. */
+function resolveContextWindow(raw) {
+    const n = typeof raw === 'string' && raw.trim() !== '' ? Number(raw) : raw;
+    return typeof n === 'number' && Number.isInteger(n) && n > 0 ? n : exports.DEFAULT_CONTEXT_WINDOW;
+}
+/** The flat budget object: one place for the numbers (D-03, D-04). */
+function planBudget(raw) {
+    const context_window = resolveContextWindow(raw);
+    return {
+        context_window,
+        plan_budget_tokens: Math.floor(context_window / 2),
+        task_tokens_min: exports.TASK_TOKENS_MIN,
+        task_tokens_max: exports.TASK_TOKENS_MAX,
+        max_tasks_per_plan: exports.MAX_TASKS_PER_PLAN,
+    };
+}
+/**
+ * Read `context_estimate`. The frontmatter parser keeps an inline comment
+ * (`90000   # tokens` parses to that whole string), so a trailing `# comment` is
+ * allowed. Accepted: digits (optionally grouped in threes by `,` or `_`) and an
+ * optional `k` multiplier (`60k` is 60000; a decimal only with `k`, `1.5k`).
+ * Anything else - a range, an exponent, a `~` prefix, a unit - is null (treated
+ * as missing) rather than its leading digits; this never throws. readPhasePlans
+ * keeps the rejected text so the report can name it (`unparseable_estimate`).
+ * The comment is cut at the first `#` and the text trimmed before the anchored
+ * match, so one whitespace quantifier is left (36-W-1a: adjacent whitespace
+ * quantifiers were quadratic on a long run of spaces).
+ */
+function parseEstimate(raw) {
+    if (typeof raw === 'number') {
+        return Number.isSafeInteger(raw) && raw >= 0 ? raw : null;
+    }
+    if (typeof raw !== 'string')
+        return null;
+    // The old comment group was `#` then `.*` to the end, and nothing else in the pattern
+    // matches `#`, so a comment always starts at the first `#`. `.` refuses a line
+    // terminator, so a comment that runs across one made the whole value invalid.
+    let text = raw;
+    const hash = raw.indexOf('#');
+    if (hash >= 0) {
+        if (/[\n\r\u2028\u2029]/.test(raw.slice(hash)))
+            return null;
+        text = raw.slice(0, hash);
+    }
+    const m = /^(\d+|\d{1,3}(?:[_,]\d{3})+)(?:\.(\d+))?\s*([kK])?$/.exec(text.trim());
+    if (!m)
+        return null;
+    const [, whole, fraction, kilo] = m;
+    if (fraction !== undefined && !kilo)
+        return null;
+    const base = Number(`${whole.replace(/[_,]/g, '')}.${fraction ?? '0'}`);
+    const n = kilo ? Math.round(base * 1000) : base;
+    return Number.isSafeInteger(n) ? n : null;
+}
+/** Analyse already-parsed plans against a budget. Pure: tests feed literals. */
+function analyzePlanSizing(plans, budget) {
+    const { plan_budget_tokens: limit, max_tasks_per_plan: ceiling, context_window } = budget;
+    const rawPlans = plans.map((p) => ({
+        id: p.id,
+        declaredWave: null,
+        dependsOn: p.dependsOn,
+        autonomous: true,
+        objective: null,
+        filesModified: p.files,
+        taskCount: p.tasks,
+        hasSummary: p.hasSummary,
+    }));
+    const planMap = new Map(rawPlans.map((p) => [p.id.toLowerCase(), p]));
+    const canonicalToId = new Map(rawPlans.map((p) => [extractCanonicalPlanId(p.id).toLowerCase(), p.id]));
+    const { level, visited } = computeDependencyLevels(rawPlans, planMap, canonicalToId);
+    const cycle = visited < plans.length;
+    const waveOf = (id) => (level.get(id) ?? 0) + 1;
+    const entries = plans.map((p) => ({
+        id: p.id,
+        wave: cycle ? 0 : waveOf(p.id),
+        tasks: p.tasks,
+        files: p.files.length,
+        context_estimate: p.estimate,
+        percent_of_window: p.estimate === null ? null : Math.floor((p.estimate * 100) / context_window),
+        gap_closure: p.gapClosure,
+        has_summary: p.hasSummary,
+    }));
+    const over_ceiling = plans.filter((p) => p.tasks > ceiling).map((p) => p.id);
+    const over_budget = plans.filter((p) => p.estimate !== null && p.estimate > limit).map((p) => p.id);
+    // An executed plan (it has a SUMMARY) is reported but never blocks: the planner
+    // cannot split it, and a lowered context_window would otherwise block forever.
+    const over_blocking = plans.some((p) => !p.hasSummary && (over_ceiling.includes(p.id) || over_budget.includes(p.id)));
+    const unestimated = plans.filter((p) => p.estimate === null).map((p) => p.id);
+    // Present but rejected (`~35000`, `35000 tokens`): named with its value so the
+    // planner can tell it from a missing key; it still counts as unestimated.
+    const unparseable_estimate = plans.flatMap((p) => p.estimate === null && p.rawEstimate !== undefined ? [{ id: p.id, value: p.rawEstimate }] : []);
+    const estimate_files_mismatch = plans
+        .filter((p) => p.estimate !== null && p.estimate < p.files.length * exports.MIN_TOKENS_PER_FILE)
+        .map((p) => p.id);
+    const unjustified_splits = [];
+    const unestimated_serial = [];
+    let min_plans = plans.length;
+    if (!cycle) {
+        const byWave = new Map();
+        for (const p of plans) {
+            const w = waveOf(p.id);
+            const list = byWave.get(w);
+            if (list)
+                list.push(p);
+            else
+                byWave.set(w, [p]);
+        }
+        const resolveDeps = (p) => {
+            const out = new Set();
+            for (const dep of p.dependsOn) {
+                const lower = dep.toLowerCase();
+                const hit = planMap.get(lower)?.id ?? canonicalToId.get(lower);
+                if (hit)
+                    out.add(hit);
+            }
+            return out;
+        };
+        // Serial link (a, b): a alone in wave w, b alone in wave w+1, b depends on a,
+        // neither a gap-closure plan, a `type: tdd` plan nor already executed.
+        const links = [];
+        for (const [w, list] of [...byWave.entries()].sort((x, y) => x[0] - y[0])) {
+            const next = byWave.get(w + 1);
+            if (list.length !== 1 || !next || next.length !== 1)
+                continue;
+            const a = list[0];
+            const b = next[0];
+            if (a.gapClosure || b.gapClosure || a.hasSummary || b.hasSummary || a.tdd || b.tdd)
+                continue;
+            if (!resolveDeps(b).has(a.id))
+                continue;
+            links.push({ a, b });
+        }
+        // A missing estimate is judged on task count only: a serial pair whose merge fits
+        // the ceiling has no visible budget reason, so it is reported (and blocks) rather
+        // than passing silently.
+        const chainNext = new Map();
+        const hasChainPrev = new Set();
+        for (const { a, b } of links) {
+            chainNext.set(a.id, b);
+            hasChainPrev.add(b.id);
+            const mergedTasks = a.tasks + b.tasks;
+            if (a.estimate === null || b.estimate === null) {
+                if (mergedTasks <= ceiling)
+                    unestimated_serial.push({ plans: [a.id, b.id], merged_tasks: mergedTasks });
+                continue;
+            }
+            const mergedEstimate = a.estimate + b.estimate;
+            if (mergedTasks <= ceiling && mergedEstimate <= limit) {
+                unjustified_splits.push({ plans: [a.id, b.id], merged_tasks: mergedTasks, merged_estimate: mergedEstimate });
+            }
+        }
+        // min_plans: pack each maximal serial chain greedily in wave order (optimal for
+        // contiguous grouping; a missing estimate counts its tasks only); a plan in no
+        // chain is one plan.
+        let groups = 0;
+        const inChain = new Set();
+        for (const p of plans) {
+            if (hasChainPrev.has(p.id) || !chainNext.has(p.id))
+                continue;
+            let cur = p;
+            let tasks = 0;
+            let est = 0;
+            let open = false;
+            while (cur) {
+                inChain.add(cur.id);
+                const curEst = cur.estimate ?? 0;
+                if (open && (tasks + cur.tasks > ceiling || est + curEst > limit)) {
+                    groups++;
+                    tasks = 0;
+                    est = 0;
+                }
+                tasks += cur.tasks;
+                est += curEst;
+                open = true;
+                cur = chainNext.get(cur.id);
+            }
+            if (open)
+                groups++;
+        }
+        min_plans = groups + plans.filter((p) => !inChain.has(p.id)).length;
+    }
+    return {
+        ...budget,
+        plans: entries,
+        over_ceiling,
+        over_budget,
+        unjustified_splits,
+        unestimated,
+        unparseable_estimate,
+        unestimated_serial,
+        estimate_files_mismatch,
+        dependency_cycle: cycle,
+        min_plans,
+        // Over the ceiling or the budget is the planner's split threshold (D-05), so both
+        // block, for plans that are not executed yet.
+        block: over_blocking || unjustified_splits.length > 0 || unestimated_serial.length > 0,
+    };
+}
+/**
+ * Tasks as `phase-plan-index` counts them (the shared `countPlanTasks`: `<task>`
+ * elements, else `## Task N` headings). A `type: tdd` plan holds one `<feature>`
+ * block instead (tdd.md), counted as one task.
+ */
+const FEATURE_RE = /<feature[\s>]/gi;
+function planTaskCount(content) {
+    return countPlanTasks(content) || (content.match(FEATURE_RE) || []).length;
+}
+/** The raw value of a present, non-empty frontmatter key, as text; else undefined. */
+function rawValue(v) {
+    if (typeof v === 'number')
+        return String(v);
+    if (typeof v === 'string')
+        return v.trim() === '' ? undefined : v.trim();
+    if (Array.isArray(v))
+        return v.length === 0 ? undefined : JSON.stringify(v);
+    if (v !== null && typeof v === 'object')
+        return Object.keys(v).length === 0 ? undefined : JSON.stringify(v);
+    return undefined;
+}
+function asStringList(v) {
+    if (Array.isArray(v))
+        return v.map(String);
+    if (typeof v === 'string' && v.trim() !== '')
+        return [v];
+    return [];
+}
+/** Parse every `*-PLAN.md` in a phase directory. An unreadable directory yields no plans. */
+function readPhasePlans(phaseDirAbs) {
+    let names;
+    try {
+        names = node_fs_1.default.readdirSync(phaseDirAbs);
+    }
+    catch {
+        return [];
+    }
+    const planFiles = names.filter((f) => f.endsWith('-PLAN.md') || f === 'PLAN.md').sort();
+    const completed = new Set();
+    for (const s of names) {
+        if (!(s.endsWith('-SUMMARY.md') || s === 'SUMMARY.md'))
+            continue;
+        const exact = s.replace('-SUMMARY.md', '').replace('SUMMARY.md', '');
+        completed.add(exact);
+        completed.add(extractCanonicalPlanId(s));
+    }
+    const out = [];
+    for (const file of planFiles) {
+        let content;
+        try {
+            content = node_fs_1.default.readFileSync(node_path_1.default.join(phaseDirAbs, file), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const fm = extractFrontmatter(content);
+        const id = file.replace('-PLAN.md', '').replace('PLAN.md', '');
+        const estimate = parseEstimate(fm['context_estimate']);
+        const rawEstimate = estimate === null ? rawValue(fm['context_estimate']) : undefined;
+        out.push({
+            id,
+            dependsOn: asStringList(fm['depends_on']),
+            tasks: planTaskCount(content),
+            files: asStringList(fm['files_modified'] ?? fm['files-modified']),
+            estimate,
+            ...(rawEstimate === undefined ? {} : { rawEstimate }),
+            // eslint-disable-next-line @typescript-eslint/no-base-to-string -- FrontmatterValue scalar compare
+            gapClosure: fm['gap_closure'] === 'true' || String(fm['gap_closure']) === 'true',
+            hasSummary: completed.has(id) || completed.has(extractCanonicalPlanId(file)),
+            // eslint-disable-next-line @typescript-eslint/no-base-to-string -- FrontmatterValue scalar compare
+            tdd: String(fm['type'] ?? '').trim() === 'tdd',
+        });
+    }
+    return out;
+}
+/**
+ * The phase-scoped check: budget from config, plans from the resolved phase directory.
+ * An unknown phase blocks (`phase_found: false`, `block: true`) so a wrong phase
+ * argument cannot pass the gate; a resolver error propagates instead of reading as
+ * "not found".
+ */
+function computePlanSizing(projectDir, phase) {
+    const budget = planBudget(loadConfig(projectDir).context_window);
+    const result = resolvePhaseForRead(projectDir, phase);
+    const relDir = result && typeof result['directory'] === 'string' ? result['directory'] : '';
+    if (!relDir) {
+        return { phase, phase_found: false, ...analyzePlanSizing([], budget), block: true };
+    }
+    const phaseDir = node_path_1.default.resolve(projectDir, relDir);
+    return { phase, phase_found: true, ...analyzePlanSizing(readPhasePlans(phaseDir), budget) };
+}