@pareto4/pp-core 1.13.0 → 1.18.0

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

@@ -1,368 +0,0 @@
-"use strict";
-/**
- * Plan graph — the single owner of how a phase's plans are ordered.
- *
- * Computes, from each PLAN.md's frontmatter (`depends_on`, `files_modified`,
- * `serial_group`, `chain_reason`, task shapes):
- *
- *   - the wave of every plan;
- *   - the serial groups (plans that share a wave but must run one after
- *     another because they touch the same non-source file);
- *   - the chain metrics (plan count, wave count, longest chain, and how many
- *     links of that chain exist only because two plans touch the same
- *     non-source file);
- *   - the chain check the plan checker enforces (a longest chain longer than
- *     half the plan count FAILS unless every link of it carries a recorded
- *     `chain_reason`);
- *   - same-shape merge candidates for the planner.
- *
- * Callers: `phase-plan-index` (src/phase.cts) adds this to the plan inventory.
- * The planner and plan-checker agents read that output; they never compute a
- * wave or a chain themselves.
- *
- * ## The wave rule
- *
- * A plan's wave is its longest-path level over two kinds of edges:
- *   1. declared `depends_on` edges;
- *   2. implicit edges between two plans that share a SOURCE file (see
- *      `classifyPlanFile`) and are not already ordered by (1). The implicit
- *      edge runs from the earlier plan (file order) to the later one.
- * Two plans that share only NON-source files (a test file, a size baseline, a
- * changeset, a doc, a planning file) get no edge: they stay in the same wave
- * and are put in one serial group instead.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.PLAN_TASK_CAP = exports.PLAN_TITLE_MAX = void 0;
-exports.classifyPlanFile = classifyPlanFile;
-exports.isInstructionFile = isInstructionFile;
-exports.isSourceFile = isSourceFile;
-exports.planTitleProblem = planTitleProblem;
-exports.readPlanTitle = readPlanTitle;
-exports.computePlanGraph = computePlanGraph;
-const SOURCE_DIRS = ['src/', 'bin/', 'pp-core/bin/', 'hooks/', 'scripts/'];
-const DOC_EXTENSIONS = /\.(md|mdx|markdown|rst|txt|adoc)$/i;
-const DOC_BASENAMES = /^(LICENSE|NOTICE|CHANGELOG|AUTHORS)(\.[a-z]+)?$/i;
-function normalizePath(file) {
-    return String(file).trim().replace(/\\/g, '/').replace(/^\.\//, '');
-}
-/**
- * Classify one `files_modified` entry. This is THE source/non-source predicate
- * for plan ordering; nothing else decides it.
- *
- * Checked in this order (first match wins):
- *   planning  — under `.planning/`
- *   changeset — under `.changeset/` or `.changesets/`
- *   baseline  — a `*baseline*.json`/`*.baseline.*` file, `__snapshots__/`, `*.snap`
- *   test      — under a `test/`, `tests/` or `__tests__/` directory or a
- *               `*.Tests/` project; or named `*.test.*`, `*.spec.*`,
- *               `*_test.go|py`, `test_*.py`
- *   source    — under `src/`, `bin/`, `pp-core/bin/`, `hooks/` or `scripts/`
- *               (pp-core ships executable code from these)
- *   doc       — a `.md/.mdx/.markdown/.rst/.txt/.adoc` file, anything under
- *               `docs/` or `doc/`, or LICENSE/NOTICE/CHANGELOG/AUTHORS. In
- *               pp-core this includes workflow, agent, reference and template
- *               markdown.
- *   source    — anything else. An unrecognised file is treated as source, so
- *               it keeps the strict "shared file = later wave" rule.
- */
-function classifyPlanFile(file) {
-    const p = normalizePath(file);
-    const base = p.split('/').pop() ?? p;
-    if (p.startsWith('.planning/'))
-        return 'planning';
-    if (/^\.changesets?\//.test(p))
-        return 'changeset';
-    if (/baseline[^/]*\.json$/i.test(base) || /\.baseline\./i.test(base) || /(^|\/)__snapshots__\//.test(p) || /\.snap$/i.test(base)) {
-        return 'baseline';
-    }
-    if (/(^|\/)(tests?|__tests__)\//.test(p) ||
-        /(^|\/)[^/]+\.Tests?\//.test(p) ||
-        /\.(test|spec)\.[^/]+$/i.test(base) ||
-        /_test\.(go|py)$/i.test(base) ||
-        /^test_[^/]*\.py$/i.test(base)) {
-        return 'test';
-    }
-    if (SOURCE_DIRS.some((dir) => p.startsWith(dir)))
-        return 'source';
-    if (DOC_EXTENSIONS.test(base) || /^docs?\//.test(p) || DOC_BASENAMES.test(base))
-        return 'doc';
-    return 'source';
-}
-/** A workflow or agent markdown file (the unit same-shape plans are made of). */
-function isInstructionFile(file) {
-    const p = normalizePath(file);
-    return /\.md$/i.test(p) && (/(^|\/)workflows\//.test(p) || /(^|\/)agents\//.test(p));
-}
-/** True when `file` is a source file for plan ordering (see `classifyPlanFile`). */
-function isSourceFile(file) {
-    return classifyPlanFile(file) === 'source';
-}
-/** Longest a plan title may be before it is reported (still valid). */
-exports.PLAN_TITLE_MAX = 100;
-/**
- * Problem with a plan's `title:` frontmatter value, or null when it is a valid
- * one-line title. `undefined` means the key is absent.
- */
-function planTitleProblem(value) {
-    if (value === undefined)
-        return 'Missing required frontmatter field: title';
-    if (typeof value !== 'string' || value.trim() === '') {
-        return 'Frontmatter field title must be a non-empty one-line string';
-    }
-    if (/[\r\n]/.test(value))
-        return 'Frontmatter field title must be one line';
-    return null;
-}
-/** Normalised title, or null when absent/invalid. */
-function readPlanTitle(value) {
-    return planTitleProblem(value) === null ? value.trim() : null;
-}
-/** Default task cap per plan (agents/pp-planner.md: "Each plan: 2-3 tasks maximum."). */
-exports.PLAN_TASK_CAP = 3;
-function slug(text) {
-    return text.toLowerCase().replace(/\.[a-z0-9]+$/i, '').replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'group';
-}
-function intersect(a, b) {
-    return [...new Set(a.filter((f) => b.has(f)))].sort();
-}
-/**
- * Compute the plan graph. `nodes` must be in plan file order (that order
- * breaks ties and orients implicit edges).
- */
-function computePlanGraph(nodes, opts = {}) {
-    const taskCap = opts.taskCap ?? exports.PLAN_TASK_CAP;
-    const ids = nodes.map((n) => n.id);
-    const index = new Map(ids.map((id, i) => [id, i]));
-    const files = nodes.map((n) => n.filesModified.map(normalizePath).filter((f) => f !== ''));
-    const fileSets = files.map((f) => new Set(f));
-    const warnings = [];
-    // Adjacency over indices: edges[i] = successors of i.
-    const succ = nodes.map(() => new Set());
-    nodes.forEach((n, j) => {
-        for (const dep of n.dependsOn) {
-            const i = index.get(dep);
-            if (i === undefined || i === j)
-                continue;
-            succ[i].add(j);
-        }
-    });
-    const levelsOf = () => {
-        const inDeg = nodes.map(() => 0);
-        succ.forEach((s) => s.forEach((j) => { inDeg[j]++; }));
-        const level = nodes.map(() => 0);
-        const queue = [];
-        inDeg.forEach((d, i) => { if (d === 0)
-            queue.push(i); });
-        let head = 0;
-        while (head < queue.length) {
-            const cur = queue[head++];
-            for (const nxt of [...succ[cur]].sort((a, b) => a - b)) {
-                level[nxt] = Math.max(level[nxt], level[cur] + 1);
-                if (--inDeg[nxt] === 0)
-                    queue.push(nxt);
-            }
-        }
-        return { level, done: new Set(queue) };
-    };
-    // A declared cycle has no waves; nodes Kahn never dequeued are on or behind it.
-    const declaredLevels = levelsOf();
-    if (declaredLevels.done.size < nodes.length) {
-        return emptyGraph(nodes, ids.filter((_, i) => !declaredLevels.done.has(i)));
-    }
-    const reaches = (from, to) => {
-        const stack = [from];
-        const seen = new Set([from]);
-        while (stack.length > 0) {
-            const cur = stack.pop();
-            if (cur === to)
-                return true;
-            for (const nxt of succ[cur]) {
-                if (!seen.has(nxt)) {
-                    seen.add(nxt);
-                    stack.push(nxt);
-                }
-            }
-        }
-        return false;
-    };
-    // Implicit edges: a shared SOURCE file orders two otherwise-unordered plans.
-    const implicitEdges = [];
-    for (let i = 0; i < nodes.length; i++) {
-        for (let j = i + 1; j < nodes.length; j++) {
-            const sharedSource = intersect(files[j], fileSets[i]).filter(isSourceFile);
-            if (sharedSource.length === 0)
-                continue;
-            if (reaches(i, j) || reaches(j, i))
-                continue;
-            succ[i].add(j);
-            implicitEdges.push({ from: ids[i], to: ids[j], shared_source_files: sharedSource });
-        }
-    }
-    const { level } = levelsOf();
-    // Same-shape merge candidates: no source file, exactly one workflow/agent file
-    // (any other files are tests, baselines, changesets or planning), same task shape.
-    const shapeGroups = new Map();
-    nodes.forEach((n, i) => {
-        if (n.taskTypes.length === 0)
-            return;
-        const kinds = files[i].map(classifyPlanFile);
-        if (kinds.includes('source'))
-            return;
-        if (files[i].filter(isInstructionFile).length !== 1 || kinds.filter((k) => k === 'doc').length !== 1)
-            return;
-        const shape = n.taskTypes.join('+');
-        if (!shapeGroups.has(shape))
-            shapeGroups.set(shape, []);
-        shapeGroups.get(shape).push(i);
-    });
-    const mergeCandidates = [];
-    for (const [shape, members] of shapeGroups) {
-        if (members.length < 2)
-            continue;
-        const totalTasks = members.reduce((sum, i) => sum + nodes[i].taskTypes.length, 0);
-        mergeCandidates.push({
-            shape,
-            plans: members.map((i) => ids[i]),
-            total_tasks: totalTasks,
-            task_cap: taskCap,
-            action: totalTasks <= taskCap ? 'merge' : 'serial_group',
-        });
-    }
-    // Serial groups: union-find within each level.
-    const parent = nodes.map((_, i) => i);
-    const find = (x) => (parent[x] === x ? x : (parent[x] = find(parent[x])));
-    const union = (a, b) => {
-        const ra = find(a);
-        const rb = find(b);
-        if (ra !== rb)
-            parent[Math.max(ra, rb)] = Math.min(ra, rb);
-    };
-    for (let i = 0; i < nodes.length; i++) {
-        for (let j = i + 1; j < nodes.length; j++) {
-            if (level[i] !== level[j])
-                continue;
-            const shared = intersect(files[j], fileSets[i]);
-            const sameDeclared = nodes[i].serialGroup !== null && nodes[i].serialGroup === nodes[j].serialGroup;
-            if (shared.length > 0 || sameDeclared)
-                union(i, j);
-        }
-    }
-    for (const cand of mergeCandidates) {
-        if (cand.action !== 'serial_group')
-            continue;
-        const members = cand.plans.map((id) => index.get(id));
-        for (const a of members)
-            for (const b of members)
-                if (a < b && level[a] === level[b])
-                    union(a, b);
-    }
-    const groupsByRoot = new Map();
-    nodes.forEach((_, i) => {
-        const r = find(i);
-        if (!groupsByRoot.has(r))
-            groupsByRoot.set(r, []);
-        groupsByRoot.get(r).push(i);
-    });
-    const serialGroupOf = Object.fromEntries(ids.map((id) => [id, null]));
-    const serialGroups = [];
-    const usedNames = new Set();
-    const roots = [...groupsByRoot.keys()].sort((a, b) => a - b);
-    for (const root of roots) {
-        const members = groupsByRoot.get(root).sort((a, b) => a - b);
-        if (members.length < 2)
-            continue;
-        const sharedFiles = new Set();
-        for (const a of members)
-            for (const b of members)
-                if (a < b)
-                    intersect(files[b], fileSets[a]).forEach((f) => sharedFiles.add(f));
-        const shared = [...sharedFiles].sort();
-        const declaredName = members.map((i) => nodes[i].serialGroup).find((g) => !!g);
-        let name = declaredName ?? `w${level[root] + 1}-${shared.length > 0 ? slug(shared[0].split('/').pop()) : 'same-shape'}`;
-        if (usedNames.has(name)) {
-            let k = 2;
-            while (usedNames.has(`${name}-${k}`))
-                k++;
-            name = `${name}-${k}`;
-        }
-        usedNames.add(name);
-        for (const i of members)
-            serialGroupOf[ids[i]] = name;
-        serialGroups.push({ name, level: level[root], plans: members.map((i) => ids[i]), shared_files: shared });
-    }
-    nodes.forEach((n, i) => {
-        if (n.serialGroup && serialGroupOf[ids[i]] !== n.serialGroup) {
-            warnings.push(`Plan ${ids[i]}: declares serial_group: ${n.serialGroup} but the plan graph puts it in ` +
-                `${serialGroupOf[ids[i]] ?? 'no serial group'} (a serial group only holds plans of one wave).`);
-        }
-    });
-    // Longest chain (by plan count) over the full DAG.
-    const order = ids.map((_, i) => i).sort((a, b) => level[a] - level[b] || a - b);
-    const best = nodes.map(() => 1);
-    const prev = nodes.map(() => null);
-    const preds = nodes.map(() => []);
-    succ.forEach((s, i) => s.forEach((j) => preds[j].push(i)));
-    for (const j of order) {
-        for (const i of preds[j].sort((a, b) => a - b)) {
-            if (best[i] + 1 > best[j]) {
-                best[j] = best[i] + 1;
-                prev[j] = i;
-            }
-        }
-    }
-    let end = -1;
-    nodes.forEach((_, i) => { if (end === -1 || best[i] > best[end])
-        end = i; });
-    const chain = [];
-    for (let cur = end; cur !== null && cur !== -1; cur = prev[cur])
-        chain.unshift(cur);
-    const links = [];
-    for (let k = 1; k < chain.length; k++) {
-        const a = chain[k - 1];
-        const b = chain[k];
-        const shared = intersect(files[b], fileSets[a]);
-        const kind = shared.some(isSourceFile) ? 'source-file' : shared.length > 0 ? 'non-source-file' : 'declared';
-        links.push({ from: ids[a], to: ids[b], kind, shared_files: shared, reason: nodes[b].chainReason });
-    }
-    const nonSourceLinks = links.filter((l) => l.kind === 'non-source-file').length;
-    const limit = nodes.length / 2;
-    const unreasoned = links.filter((l) => !l.reason).map((l) => ({ from: l.from, to: l.to, kind: l.kind }));
-    const passed = chain.length <= limit || unreasoned.length === 0;
-    const waveCount = nodes.length === 0 ? 0 : Math.max(...level) + 1;
-    const message = passed
-        ? `longest chain ${chain.length} of ${nodes.length} plans (limit ${limit})` +
-            (chain.length > limit ? ' — every link has a chain_reason' : '')
-        : `longest chain is ${chain.length} plans, over half the plan count (${nodes.length} plans, limit ${limit}), ` +
-            `and ${unreasoned.length} link(s) have no chain_reason: ${unreasoned.map((l) => `${l.from}->${l.to} (${l.kind})`).join(', ')}. ` +
-            `Drop depends_on edges that exist only because two plans touch the same non-source file ` +
-            `(they share a wave in a serial group instead), merge same-shape plans, or record a ` +
-            `chain_reason on each later plan saying why it must wait.`;
-    return {
-        cycle: null,
-        level: Object.fromEntries(ids.map((id, i) => [id, level[i]])),
-        serialGroupOf,
-        serialGroups,
-        implicitEdges,
-        plan_count: nodes.length,
-        wave_count: waveCount,
-        longest_chain: { length: chain.length, plans: chain.map((i) => ids[i]), links, non_source_links: nonSourceLinks },
-        chain_check: { passed, limit, unreasoned_links: passed ? [] : unreasoned, message },
-        merge_candidates: mergeCandidates,
-        warnings,
-    };
-}
-function emptyGraph(nodes, cycle) {
-    return {
-        cycle,
-        level: {},
-        serialGroupOf: Object.fromEntries(nodes.map((n) => [n.id, null])),
-        serialGroups: [],
-        implicitEdges: [],
-        plan_count: nodes.length,
-        wave_count: 0,
-        longest_chain: { length: 0, plans: [], links: [], non_source_links: 0 },
-        chain_check: { passed: false, limit: nodes.length / 2, unreasoned_links: [], message: `depends_on cycle: ${cycle.join(', ')}` },
-        merge_candidates: [],
-        warnings: [],
-    };
-}