@pugi/cli 0.1.0-alpha.9 → 0.1.0-beta.10

package/dist/core/consensus/rubric.js

@@ -0,0 +1,233 @@
+/**
+ * Consensus rubric — `pugi review --consensus` (α6.7).
+ *
+ * Three independent reviewers (Codex / Claude / DeepSeek) produce findings
+ * tagged `[P0]` / `[P1]` / `[P2]` / `[P3]`. The rubric translates the per-
+ * reviewer severity vector into one of `PASS` / `WARN` / `BLOCK`.
+ *
+ * Rubric (verbatim from /triple-review skill + admin-api OES MCP triple_review):
+ *
+ *   any reviewer reports [P0]              -> BLOCK
+ *   two or more reviewers report [P1]      -> BLOCK   (consensus)
+ *   exactly one reviewer reports [P1]      -> WARN    (asymmetric)
+ *   no reviewer reports [P0] or [P1]       -> PASS    (P2/P3 only)
+ *   every reviewer errored                 -> BLOCK   (no signal)
+ *
+ * The rubric never reads model text beyond the severity markers; the
+ * reviewer-side narrative is shown to the operator unchanged. Keeping the
+ * verdict deterministic + LLM-free is the entire point of the gate (CEO
+ * directive 2026-05-19): a model that disagrees with the rubric can be
+ * audited, a model that produces the verdict cannot.
+ */
+/**
+ * Regex matches the `[P0]` / `[P1]` / `[P2]` / `[P3]` token at the start
+ * of a line OR inline. Accepts surrounding whitespace and lowercase form.
+ * The line-anchored `m` flag scans every line; `g` allows `matchAll`.
+ *
+ * The capture group on the digit lets `parseFindings` reconstruct the
+ * severity without a second regex. Square brackets are escaped because
+ * the JS regex engine treats `[` as a character class otherwise.
+ */
+const SEVERITY_TOKEN = /\[\s*[Pp]([0-3])\s*\]/g;
+/**
+ * Parse a raw reviewer text blob into structured findings.
+ *
+ * Heuristics (intentionally permissive — different models format very
+ * differently and a strict parser would drop signal):
+ *
+ *   1. Split the text on `[Px]` tokens, preserving the marker.
+ *   2. Each marker starts a new finding. The summary is the rest of the
+ *      same line (and the next line if the first is `:` or empty after
+ *      stripping whitespace).
+ *   3. Empty / whitespace-only summaries are dropped — a bare `[P1]`
+ *      with no context cannot be acted on, and treating it as a finding
+ *      would falsely trigger consensus.
+ */
+export function parseFindings(raw) {
+    if (typeof raw !== 'string' || raw.length === 0)
+        return [];
+    const findings = [];
+    // Track marker positions so we can slice the summary up to the next
+    // marker without quadratic re-scans.
+    const markers = [];
+    // Reset lastIndex defensively — `matchAll` allocates its own iterator,
+    // but belt-and-braces against a future caller passing a stateful regex.
+    SEVERITY_TOKEN.lastIndex = 0;
+    for (const match of raw.matchAll(SEVERITY_TOKEN)) {
+        const digit = match[1] ?? '';
+        const severity = `P${digit}`;
+        markers.push({ severity, index: match.index ?? 0, matchLength: match[0].length });
+    }
+    for (let i = 0; i < markers.length; i += 1) {
+        const marker = markers[i];
+        const start = marker.index + marker.matchLength;
+        const end = i + 1 < markers.length ? markers[i + 1].index : raw.length;
+        const slice = raw.slice(start, end);
+        const summary = extractSummary(slice);
+        if (summary.length === 0)
+            continue;
+        findings.push({ severity: marker.severity, summary });
+    }
+    return findings;
+}
+/**
+ * Extract a single-line summary from the text following a severity
+ * marker. Trims leading colon / dash / whitespace; truncates at the
+ * first newline so multi-paragraph findings render as one line in the
+ * REPL transcript (the full reviewer text stays available in `rawContent`).
+ */
+function extractSummary(slice) {
+    let cursor = 0;
+    while (cursor < slice.length && /[\s:\-—–]/.test(slice[cursor]))
+        cursor += 1;
+    const tail = slice.slice(cursor);
+    const newlineIdx = tail.search(/\r?\n/);
+    const oneLine = newlineIdx === -1 ? tail : tail.slice(0, newlineIdx);
+    return oneLine.trim();
+}
+/**
+ * Compute the highest BLOCKING severity from a finding list. Returns
+ * `null` when the reviewer is clean for gating purposes, i.e. either:
+ *   - no findings at all, OR
+ *   - only P2 / P3 findings (informational, non-blocking by rubric).
+ *
+ * `null` is the right contract for downstream tooling that gates on
+ * "did this reviewer flag anything that should block ship?" - the
+ * rubric in `aggregate` already treats P2/P3 as non-blocking, so an
+ * external `topSeverity === null` check matches the gate's semantics
+ * exactly without re-parsing the finding list.
+ *
+ * Per-finding severity is still preserved in `findings[].severity`
+ * for callers that want to surface P2/P3 counts in their UX.
+ *
+ * Returns the priority floor for blocking findings only: P0 > P1.
+ */
+export function topSeverityOf(findings) {
+    let best = null;
+    for (const finding of findings) {
+        if (finding.severity === 'P0')
+            return 'P0';
+        if (finding.severity === 'P1')
+            best = 'P1';
+        // P2 / P3 are non-blocking by rubric -> they do NOT contribute to
+        // topSeverity. They remain visible via `findings[].severity` for
+        // operators who want to see the full breakdown.
+    }
+    return best;
+}
+/**
+ * Convenience: parse a raw reviewer text blob into a `ReviewerVerdict`.
+ * `errored` defaults to false; callers that detected a transport-level
+ * failure should set it true and pass an empty raw string.
+ */
+export function reviewerVerdictFromRaw(reviewer, raw, errored = false) {
+    if (errored) {
+        return { reviewer, topSeverity: null, findings: [], errored: true };
+    }
+    const findings = parseFindings(raw);
+    return {
+        reviewer,
+        topSeverity: topSeverityOf(findings),
+        findings,
+        errored: false,
+    };
+}
+/**
+ * Apply the rubric to 1..N reviewer verdicts. The shape is N-aware so the
+ * same function handles the dev `/triple-review` 3-reviewer case AND a
+ * customer running with 2 reviewers (e.g. a tier that does not yet include
+ * DeepSeek).
+ */
+export function aggregate(verdicts) {
+    const totalReviewers = verdicts.length;
+    const erroredReviewers = verdicts.filter((v) => v.errored).length;
+    // Zero reviewers = zero signal. Falling through to the no-P0/no-P1
+    // branch would emit a false PASS — exactly the regression flagged by
+    // Codex during PR #370 review. Treat empty input as BLOCK so the gate
+    // fails closed when the backend returns no events at all (5xx that
+    // somehow drained the SSE, server-side bug, dispatcher misconfig).
+    if (totalReviewers === 0) {
+        return {
+            verdict: 'BLOCK',
+            p0Count: 0,
+            p1Count: 0,
+            p1Reviewers: 0,
+            reasoning: 'No reviewer signal: backend returned 0 events. Fail-closed BLOCK.',
+        };
+    }
+    if (totalReviewers > 0 && erroredReviewers === totalReviewers) {
+        return {
+            verdict: 'BLOCK',
+            p0Count: 0,
+            p1Count: 0,
+            p1Reviewers: 0,
+            reasoning: 'Every reviewer errored: no signal. Treating as BLOCK until at least one reviewer returns.',
+        };
+    }
+    let p0Count = 0;
+    let p1Count = 0;
+    let p1Reviewers = 0;
+    for (const verdict of verdicts) {
+        if (verdict.errored)
+            continue;
+        const p0 = verdict.findings.filter((f) => f.severity === 'P0').length;
+        const p1 = verdict.findings.filter((f) => f.severity === 'P1').length;
+        p0Count += p0;
+        p1Count += p1;
+        if (p1 > 0)
+            p1Reviewers += 1;
+    }
+    if (p0Count > 0) {
+        return {
+            verdict: 'BLOCK',
+            p0Count,
+            p1Count,
+            p1Reviewers,
+            reasoning: `${p0Count}x P0 finding${p0Count === 1 ? '' : 's'}: BLOCK (any P0 fails the gate).`,
+        };
+    }
+    if (p1Reviewers >= 2) {
+        return {
+            verdict: 'BLOCK',
+            p0Count,
+            p1Count,
+            p1Reviewers,
+            reasoning: `${p1Reviewers} reviewers each reported P1: consensus = likely real bug, BLOCK.`,
+        };
+    }
+    if (p1Reviewers === 1) {
+        return {
+            verdict: 'WARN',
+            p0Count,
+            p1Count,
+            p1Reviewers,
+            reasoning: 'One reviewer reported P1: asymmetric signal, examine the disagreement before merging.',
+        };
+    }
+    return {
+        verdict: 'PASS',
+        p0Count,
+        p1Count,
+        p1Reviewers,
+        reasoning: 'No P0 or P1 findings: PASS. P2/P3 findings are non-blocking.',
+    };
+}
+/**
+ * Map a rubric verdict to the conventional exit code Pugi CLI uses for
+ * gates (spec α6.7):
+ *
+ *   PASS  -> 0
+ *   WARN  -> 1
+ *   BLOCK -> 2
+ *
+ * The non-zero codes are distinct so a shell script can branch on the
+ * exact outcome without re-parsing stdout.
+ */
+export function exitCodeFor(verdict) {
+    if (verdict === 'PASS')
+        return 0;
+    if (verdict === 'WARN')
+        return 1;
+    return 2;
+}
+//# sourceMappingURL=rubric.js.map

package/dist/core/context/index.js

@@ -0,0 +1,21 @@
+/**
+ * Three-tier context model - α6.5 Phase 1 barrel.
+ *
+ * Bundles the four primitives so the REPL bootstrap can import from a
+ * single path:
+ *
+ *   import {
+ *     loadPugiIgnore,
+ *     buildRepoSkeleton,
+ *     renderSkeleton,
+ *     WorkingSet,
+ *     PugiWatcher,
+ *   } from '../context/index.js';
+ *
+ * No new logic lives here - just re-exports.
+ */
+export { BASELINE_IGNORE_PATTERNS, SECRET_IGNORE_PATTERNS, globalPugiIgnorePath, loadPugiIgnore, parsePatternText, readPatternFile, workspaceGitIgnorePath, workspacePugiIgnorePath, } from './pugiignore.js';
+export { COLLAPSE_DIR_ENTRIES, MAX_README_LINES, MAX_SKELETON_BYTES, MAX_TREE_DEPTH, MAX_WALK_NODES, TOP_LANGUAGES, buildRepoSkeleton, detectPackageManager, languageForExtension, readGitBranch, readPackageJson, readReadme, renderSkeleton, topLanguages, } from './repo-skeleton.js';
+export { DEFAULT_WORKING_SET_CAPACITY, WorkingSet, } from './working-set.js';
+export { MAX_WATCHED_PATHS, PugiWatcher, THROTTLE_WINDOW_MS, } from './watcher.js';
+//# sourceMappingURL=index.js.map

package/dist/core/context/pugiignore.js

@@ -0,0 +1,316 @@
+/**
+ * `.pugiignore` parser - α6.5 Phase 1 (three-tier context).
+ *
+ * The CLI walks the workspace to build a repo skeleton and to feed the
+ * chokidar watcher. Both passes need a single source of truth for which
+ * paths are off-limits. `.pugiignore` extends (not replaces) `.gitignore`
+ * with Pugi-specific defaults: secret files, large binaries, build
+ * outputs, lockfiles.
+ *
+ * Design choices:
+ *
+ *   1. We layer four sources, last-write-wins per the .gitignore spec:
+ *      (a) Built-in DEFAULT_IGNORE_PATTERNS - secret / binary / build
+ *          paths every workspace should drop.
+ *      (b) `~/.pugi/global.pugiignore` - operator-global overrides.
+ *      (c) Repo `.gitignore` (when present) - so we don't re-walk
+ *          node_modules / dist / etc.
+ *      (d) Repo `.pugiignore` - workspace-local extensions.
+ *
+ *   2. The `ignore` npm package handles negation (`!path`) and nested
+ *      directories correctly. Rolling a minimal glob matcher is doable
+ *      but the test surface for gitignore semantics (esp. negation +
+ *      ancestor matching) is wide enough that pulling the audited
+ *      library is the safer call. It is already in the workspace via
+ *      transitive deps; we add it as an explicit pugi-cli dep.
+ *
+ *   3. Privacy is defense-in-depth: even if the operator deletes the
+ *      built-in defaults from their `.pugiignore`, we re-add the
+ *      secret patterns at the END of the chain so a typo in user
+ *      config cannot expose `.env` / `*.pem` / `*.key`. The user can
+ *      explicitly negate (`!.env.example`) but cannot wipe the
+ *      defense.
+ *
+ *   4. Paths are normalised to forward slashes (the `ignore` package
+ *      requires POSIX-style separators even on Windows) and stripped
+ *      of any leading workspace root so `isIgnored` answers in
+ *      repo-relative terms.
+ *
+ * The API surface is minimal: `loadPugiIgnore(cwd)` returns a
+ * `PugiIgnore` matcher with `isIgnored(absPath): boolean`. The matcher
+ * is built once at session bootstrap and reused by the skeleton walker
+ * and the chokidar watcher.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { relative, resolve, sep } from 'node:path';
+// The `ignore` package ships as CommonJS with `module.exports = factory`
+// plus a `.d.ts` that re-exports the factory as default. Under
+// `module: nodenext` TypeScript treats CJS default imports as the
+// `module.exports` shape, which for `ignore` IS the callable factory -
+// but only when we use the namespace-default dance below. A bare
+// `import ignore from 'ignore'` fails with "expression is not callable"
+// because TS resolves the import to the `typeof` shape rather than the
+// callable value.
+import * as ignoreModule from 'ignore';
+const ignoreFactory = ignoreModule.default
+    ?? ignoreModule;
+/**
+ * Built-in patterns shipped with every Pugi workspace. The list is a
+ * conservative union of three categories:
+ *
+ *   - **Secrets** (defense in depth): `.env*`, `*.pem`, `*.key`,
+ *     `secrets/**`, `.netrc`, `id_rsa*`, `*.secret`, `credentials*`.
+ *     These are re-applied at the END of the chain so user config
+ *     cannot accidentally expose them.
+ *
+ *   - **Build outputs / caches**: `node_modules/`, `dist/`, `build/`,
+ *     `.next/`, `.nuxt/`, `.svelte-kit/`, `coverage/`, `.nx/`, `.cache/`,
+ *     `.turbo/`, `.parcel-cache/`, `out/`, `.output/`, `*.tsbuildinfo`.
+ *
+ *   - **Large binaries / data**: lockfiles (`*.lock`, `*-lock.json`,
+ *     `*-lock.yaml`), images (`*.png`, `*.jpg`, `*.jpeg`, `*.gif`,
+ *     `*.ico`), PDFs, videos, archives (`*.zip`, `*.tar`, `*.gz`),
+ *     DB dumps (`*.sql`, `*.dump`), logs.
+ *
+ * The split between baseline patterns (applied first) and secret
+ * patterns (applied last) matters: a user `.pugiignore` can `!`-negate
+ * baseline entries (e.g. unignore a particular generated file under
+ * `dist/`) but cannot reach the trailing secret block. The trailing
+ * block is exported as `SECRET_IGNORE_PATTERNS` for tests.
+ */
+export const BASELINE_IGNORE_PATTERNS = Object.freeze([
+    // VCS / Pugi state
+    '.git/',
+    '.pugi/',
+    '.hg/',
+    '.svn/',
+    // Build outputs / package manager caches
+    'node_modules/',
+    '.pnpm-store/',
+    'dist/',
+    'build/',
+    'out/',
+    '.output/',
+    '.next/',
+    '.nuxt/',
+    '.svelte-kit/',
+    '.astro/',
+    'coverage/',
+    '.nyc_output/',
+    '.nx/',
+    '.turbo/',
+    '.parcel-cache/',
+    '.cache/',
+    '.vercel/',
+    '.netlify/',
+    '*.tsbuildinfo',
+    // Lockfiles - rebuilds, never agent-relevant
+    '*.lock',
+    'package-lock.json',
+    'yarn.lock',
+    'pnpm-lock.yaml',
+    'bun.lockb',
+    'composer.lock',
+    'poetry.lock',
+    'Cargo.lock',
+    'Gemfile.lock',
+    // Logs
+    '*.log',
+    'logs/',
+    '.pm2/',
+    // Large binaries
+    '*.png',
+    '*.jpg',
+    '*.jpeg',
+    '*.gif',
+    '*.ico',
+    '*.webp',
+    '*.bmp',
+    '*.tiff',
+    '*.svg',
+    '*.pdf',
+    '*.mp3',
+    '*.mp4',
+    '*.mov',
+    '*.webm',
+    '*.zip',
+    '*.tar',
+    '*.tar.gz',
+    '*.tgz',
+    '*.gz',
+    '*.bz2',
+    '*.7z',
+    '*.rar',
+    '*.dmg',
+    '*.iso',
+    // DB dumps / fixtures
+    '*.sql',
+    '*.dump',
+    '*.sqlite',
+    '*.sqlite3',
+    '*.db',
+    // OS noise
+    '.DS_Store',
+    'Thumbs.db',
+]);
+/**
+ * Secret patterns re-applied at the END of every layered chain. Even
+ * if the operator deletes these from `.pugiignore` (or accidentally
+ * negates them with `!.env`), the trailing block restores the gate.
+ * This is defense-in-depth: the skeleton walker MUST NOT read
+ * credentials into the agent context, period.
+ */
+export const SECRET_IGNORE_PATTERNS = Object.freeze([
+    '.env',
+    '.env.*',
+    '*.pem',
+    '*.key',
+    '*.crt',
+    '*.cert',
+    // X.509 cert formats - `*.cer` is the PEM-style cert extension common
+    // on Windows / Java keystores, `*.der` is the binary DER-encoded form
+    // used by Java + .NET tooling. Both can carry private keys when
+    // bundled (PKCS#7 / PKCS#12) and the file extension alone does not
+    // tell us whether the bundle includes a key. Treat as secrets by
+    // default. triple-review P1 (PR #380).
+    '*.cer',
+    '*.der',
+    '*.p12',
+    '*.pfx',
+    '*.jks',
+    '*.keystore',
+    'secrets/**',
+    '.netrc',
+    'id_rsa',
+    'id_rsa.*',
+    'id_ed25519',
+    'id_ed25519.*',
+    '*.secret',
+    'credentials',
+    'credentials.json',
+    'service-account*.json',
+    '*.kdbx',
+    '.aws/',
+    '.ssh/',
+    '.gnupg/',
+]);
+/**
+ * Where the operator's global ignore file lives. Mirrors the
+ * `~/.gitignore_global` convention. We do NOT auto-create it; if it
+ * exists, we load its non-empty / non-comment lines.
+ */
+export function globalPugiIgnorePath(home = homedir()) {
+    return resolve(home, '.pugi', 'global.pugiignore');
+}
+/** Path to the workspace `.pugiignore`. */
+export function workspacePugiIgnorePath(cwd) {
+    return resolve(cwd, '.pugiignore');
+}
+/** Path to the workspace `.gitignore`. */
+export function workspaceGitIgnorePath(cwd) {
+    return resolve(cwd, '.gitignore');
+}
+/**
+ * Load and compile the layered ignore matcher for `cwd`. The chain
+ * is built in this exact order so later layers override earlier ones,
+ * with the trailing secret block as the inviolable backstop:
+ *
+ *   1. BASELINE_IGNORE_PATTERNS  (built-in defaults)
+ *   2. ~/.pugi/global.pugiignore (operator global, optional)
+ *   3. <cwd>/.gitignore          (workspace, optional)
+ *   4. <cwd>/.pugiignore         (workspace, optional)
+ *   5. SECRET_IGNORE_PATTERNS    (defense-in-depth backstop)
+ *
+ * Any FS error reading optional files is swallowed - workspace
+ * context is best-effort and must never block the REPL bootstrap.
+ */
+export function loadPugiIgnore(cwd, options = {}) {
+    const home = options.home ?? homedir();
+    const normalisedCwd = resolve(cwd);
+    const patterns = [];
+    patterns.push(...BASELINE_IGNORE_PATTERNS);
+    const globalPath = globalPugiIgnorePath(home);
+    const globalPatterns = readPatternFile(globalPath);
+    patterns.push(...globalPatterns);
+    const gitignorePath = workspaceGitIgnorePath(normalisedCwd);
+    const gitPatterns = readPatternFile(gitignorePath);
+    patterns.push(...gitPatterns);
+    const pugiIgnorePath = workspacePugiIgnorePath(normalisedCwd);
+    const pugiPatterns = readPatternFile(pugiIgnorePath);
+    patterns.push(...pugiPatterns);
+    // Secrets last so they cannot be silently negated by user config.
+    patterns.push(...SECRET_IGNORE_PATTERNS);
+    const matcher = ignoreFactory().add(patterns);
+    return {
+        cwd: normalisedCwd,
+        patterns: Object.freeze(patterns.slice()),
+        isIgnored(absPath, isDir) {
+            return isIgnoredImpl(matcher, normalisedCwd, absPath, isDir === true);
+        },
+    };
+}
+/**
+ * Read a `.gitignore`-shaped file and return the non-comment / non-empty
+ * lines. Returns `[]` on any FS error. Lines are returned verbatim - the
+ * `ignore` library parses leading `!`, trailing `/`, and `**` correctly
+ * on its own.
+ */
+export function readPatternFile(path) {
+    try {
+        if (!existsSync(path))
+            return [];
+        const raw = readFileSync(path, 'utf8');
+        return parsePatternText(raw);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Pure parser for a `.gitignore`-shaped string. Splits on newlines,
+ * strips comment lines (`#`), trims whitespace, drops empty lines.
+ * Exported for the test suite so the chain is exercisable without a
+ * real filesystem.
+ */
+export function parsePatternText(raw) {
+    const lines = raw.split(/\r?\n/);
+    const out = [];
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        if (trimmed.startsWith('#'))
+            continue;
+        out.push(trimmed);
+    }
+    return out;
+}
+/**
+ * Normalise an absolute path to a repo-relative POSIX path, then run
+ * it through the `ignore` matcher. Inputs outside the workspace return
+ * `false` - the matcher has no opinion about paths above its root.
+ */
+function isIgnoredImpl(matcher, cwd, absPath, isDir) {
+    const normalisedAbs = resolve(absPath);
+    if (normalisedAbs === cwd)
+        return false;
+    const rel = relative(cwd, normalisedAbs);
+    // Paths above the workspace root come back as `..` or `../foo`.
+    // The matcher has no opinion about those; treat as not-ignored.
+    if (rel.length === 0)
+        return false;
+    if (rel.startsWith('..'))
+        return false;
+    // `ignore` requires POSIX-style separators on every platform.
+    const posixRel = sep === '/' ? rel : rel.split(sep).join('/');
+    // Append a trailing slash for directories so gitignore-style
+    // dir patterns (`node_modules/`, `dist/`) match the dir itself,
+    // not just its children. Without this, `isIgnored('/abs/node_modules', true)`
+    // would return false because `ignore` only matches the child path
+    // shape for those patterns. See the spec for the failing case
+    // (skeleton walker descending into node_modules/).
+    const queryPath = isDir ? `${posixRel}/` : posixRel;
+    return matcher.ignores(queryPath);
+}
+//# sourceMappingURL=pugiignore.js.map