@aperant/framework 0.6.4 → 0.6.6

package/dist/cli/ci-watch/stop-matrix.mjs

@@ -0,0 +1,164 @@
+/**
+ * ci-watch/stop-matrix.mjs — pure stop-matrix classifier (D-06).
+ *
+ * `classify({checks, state, prMetadata})` returns
+ *   { action, counts_toward_budget, reason }
+ *
+ * No I/O, no fs, no gh CLI shell-outs — caller pre-fetches `checks` (the
+ * payload from `gh pr checks --json name,bucket,state,conclusion,detailsUrl`)
+ * and `prMetadata` (`gh pr view --json state,reviewDecision`) and passes them
+ * in. The orchestrator in commands/ci-watch.mjs handles the side effects
+ * implied by the action.
+ *
+ * Predicate order matters — short-circuits go first (merged/closed/green/cap
+ * fire before any per-check inspection). See spec.md §9 table for the full
+ * ordering.
+ *
+ * The 11 actions:
+ *   merged, closed, green, attempts-cap, wall-cap, reviewer-pause,
+ *   identical-log, flake-skip, infra-backoff, diverged-rebased,
+ *   diverged-bailed, fix
+ *
+ * `counts_toward_budget` is `true` for fix attempts (including rebase
+ * attempts and rebase-bail); `false` for flake-skip / infra-backoff; `false`
+ * (with a sentinel meaning "n/a") for terminal actions.
+ */
+const ATTEMPTS_CAP = 5;
+const INFRA_FAILURE_CLASSES = new Set(['runner-oom', 'runner-cancelled', 'gh-5xx', 'timeout']);
+/**
+ * @typedef {Object} CheckRow
+ * @property {string} [name]
+ * @property {string} [conclusion] e.g. 'success' | 'failure' | 'cancelled' | 'timed_out' | 'neutral'
+ * @property {string} [state]
+ * @property {string} [bucket]
+ * @property {string} [failure_class] — optional pre-classified hint (test-only seam)
+ * @property {string} [log_fingerprint] — optional digest for identical-log detection
+ *
+ * @typedef {Object} ClassifyInput
+ * @property {CheckRow[]} checks
+ * @property {Object} state — per-PR state (see state.mjs §8)
+ * @property {Object} prMetadata — { state: 'OPEN'|'CLOSED'|'MERGED', reviewDecision?: string }
+ *
+ * @typedef {Object} ClassifyOutput
+ * @property {string} action
+ * @property {boolean} counts_toward_budget
+ * @property {string} reason
+ *
+ * @param {ClassifyInput} input
+ * @returns {ClassifyOutput}
+ */
+export function classify({ checks, state, prMetadata }) {
+    const pr = prMetadata || {};
+    const st = state || {};
+    const rows = Array.isArray(checks) ? checks : [];
+    // 1. MERGED.
+    if (pr.state === 'MERGED') {
+        return { action: 'merged', counts_toward_budget: false, reason: 'pr is merged' };
+    }
+    // 2. CLOSED (not merged).
+    if (pr.state === 'CLOSED') {
+        return { action: 'closed', counts_toward_budget: false, reason: 'pr is closed unmerged' };
+    }
+    const failed = rows.filter((c) => isFailing(c));
+    const allGreen = rows.length > 0 && rows.every((c) => c.conclusion === 'success');
+    // 3. All checks green.
+    if (allGreen) {
+        return { action: 'green', counts_toward_budget: false, reason: 'all checks succeeded' };
+    }
+    // 3b. No checks registered yet — CI hasn't enqueued jobs. Wait without
+    // burning a fix attempt.
+    if (rows.length === 0) {
+        return { action: 'wait', counts_toward_budget: false, reason: 'no checks registered yet' };
+    }
+    // 4. Attempts cap (only when red present — otherwise green/merged/closed would have fired).
+    const attempts = st.attempts || 0;
+    if (attempts >= ATTEMPTS_CAP && failed.length > 0) {
+        return {
+            action: 'attempts-cap',
+            counts_toward_budget: false,
+            reason: `${attempts} fix attempts used; cap is ${ATTEMPTS_CAP}`,
+        };
+    }
+    // 5. Wall-clock cap.
+    if (st.deadline && Date.now() > new Date(st.deadline).getTime() && failed.length > 0) {
+        return {
+            action: 'wall-cap',
+            counts_toward_budget: false,
+            reason: 'past 4h deadline',
+        };
+    }
+    // 6. Reviewer asked for changes.
+    if (pr.reviewDecision === 'CHANGES_REQUESTED') {
+        return {
+            action: 'reviewer-pause',
+            counts_toward_budget: false,
+            reason: 'reviewer requested changes — pausing',
+        };
+    }
+    // 7. Identical-log → non-converging fixer.
+    // Compare aggregate fingerprints (same format as the write side in ci-watch.mjs).
+    if (attempts > 0 && st.last_status && failed.length > 0) {
+        const currentFingerprint = failed
+            .map((f) => `${f.name}:${f.log_fingerprint ?? ''}`)
+            .sort()
+            .join('|');
+        if (currentFingerprint === st.last_status) {
+            return {
+                action: 'identical-log',
+                counts_toward_budget: false,
+                reason: 'failed-check fingerprint identical to last attempt',
+            };
+        }
+    }
+    // 8. Flake-skip — same check failed then passed on rerun, no commit between.
+    // The classifier sees this as an explicit hint from the caller: failed rows
+    // classified as `bucket === 'flake'` or `failure_class === 'flake'` are the
+    // flaky-test variety and must not burn a fix attempt. Fires when EVERY
+    // remaining failure is a flake — if any non-flake failure is present, we
+    // fall through and the real failure governs.
+    if (failed.length > 0 &&
+        failed.every((c) => c.bucket === 'flake' || c.failure_class === 'flake')) {
+        return {
+            action: 'flake-skip',
+            counts_toward_budget: false,
+            reason: 'check transient — passed on rerun',
+        };
+    }
+    // 9. Infra failure class.
+    if (failed.some((c) => INFRA_FAILURE_CLASSES.has(c.failure_class))) {
+        return {
+            action: 'infra-backoff',
+            counts_toward_budget: false,
+            reason: 'infra-class failure — backoff and retry',
+        };
+    }
+    // 10. Diverged branch — caller has already done the fetch + dry-rebase and
+    // passes the outcome in `prMetadata.diverged`:
+    //   { rebased: true }   → action 'diverged-rebased' (counts)
+    //   { rebased: false }  → action 'diverged-bailed'  (counts)
+    if (pr.diverged && typeof pr.diverged === 'object') {
+        if (pr.diverged.rebased === true) {
+            return {
+                action: 'diverged-rebased',
+                counts_toward_budget: true,
+                reason: 'origin ahead; rebased successfully',
+            };
+        }
+        return {
+            action: 'diverged-bailed',
+            counts_toward_budget: true,
+            reason: 'origin ahead; rebase conflict',
+        };
+    }
+    // 11. Default red — go fix.
+    return {
+        action: 'fix',
+        counts_toward_budget: true,
+        reason: 'red checks present — attempting fix',
+    };
+}
+export function isFailing(check) {
+    const c = check.conclusion;
+    return c === 'failure' || c === 'cancelled' || c === 'timed_out' || c === 'action_required';
+}
+//# sourceMappingURL=stop-matrix.mjs.map

package/dist/cli/ci-watch/stop-matrix.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"stop-matrix.mjs","sourceRoot":"","sources":["../../../src/cli/ci-watch/stop-matrix.mjs"],"names":[],"mappings":"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"}

package/dist/cli/cli-wrappers/ci-watch.d.mts

@@ -0,0 +1,2 @@
+export { cmdCiWatch as cliCiWatch } from "../commands/ci-watch.mjs";
+//# sourceMappingURL=ci-watch.d.mts.map

package/dist/cli/cli-wrappers/ci-watch.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ci-watch.d.mts","sourceRoot":"","sources":["../../../src/cli/cli-wrappers/ci-watch.mjs"],"names":[],"mappings":""}

package/dist/cli/cli-wrappers/ci-watch.mjs

@@ -0,0 +1,9 @@
+/**
+ * cli-wrappers/ci-watch.mjs — Layer 2 wrapper for the ci-watch cmd.
+ *
+ * Today this is a passthrough — DISPATCH calls wrap(cmdCiWatch) directly.
+ * Re-exporting under cliCiWatch keeps the file-per-cmd structural seam
+ * (mirrors task.mjs / pr-review.mjs).
+ */
+export { cmdCiWatch as cliCiWatch } from '../commands/ci-watch.mjs';
+//# sourceMappingURL=ci-watch.mjs.map

package/dist/cli/cli-wrappers/ci-watch.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ci-watch.mjs","sourceRoot":"","sources":["../../../src/cli/cli-wrappers/ci-watch.mjs"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,IAAI,UAAU,EAAE,MAAM,0BAA0B,CAAA"}

package/dist/cli/commands/adr.d.mts

@@ -0,0 +1,5 @@
+/**
+ * CLI entry: `apt-tools adr <subcommand> <project-dir> [flags]`.
+ */
+export function cmdAdr(subcommand: any, projectDir: any, extraArgs: any): import("../util/result.mjs").CommandResult;
+//# sourceMappingURL=adr.d.mts.map

package/dist/cli/commands/adr.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adr.d.mts","sourceRoot":"","sources":["../../../src/cli/commands/adr.mjs"],"names":[],"mappings":"AAmIA;;GAEG;AACH,qHA4GC"}

package/dist/cli/commands/adr.mjs

@@ -0,0 +1,228 @@
+/**
+ * commands/adr.mjs — `apt-tools adr write` (Pocock adoption ST-6, AC5).
+ *
+ * Writes an ADR under `docs/adr/NNNN-slug.md` ONLY when all three Nygard
+ * gates pass: hard-to-reverse AND surprising-without-context AND
+ * real-trade-off. When any gate fails, the writer returns a `filtered`
+ * envelope and writes nothing — the decision stays in
+ * `.aperant/context/notes/{task-id}.md` instead.
+ *
+ * CLI:
+ *   apt-tools adr write <project-dir>
+ *     --title <slug>
+ *     --hard-to-reverse <true|false>
+ *     --surprising-without-context <true|false>
+ *     --real-trade-off <true|false>
+ *     --decision <text>
+ *     --consequences <text>
+ *     [--context <text>]
+ *     [--status Proposed|Accepted|Deprecated|Superseded]
+ *
+ * Output: JSON envelope.
+ *   On filter:  { status: 'filtered', failed_gates: string[], reason: 'three-gate-filter' }
+ *   On write:   { status: 'ok', command: 'adr-write', file: <abs path>, number: N, slug: '...' }
+ */
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { parseFlags } from '../util/args.mjs';
+import { err, exitWith, ok } from '../util/result.mjs';
+/**
+ * Parse a flag value as a strict boolean. Returns null on unrecognized form
+ * so callers can distinguish "missing" from "false".
+ *
+ * @param {unknown} v
+ * @returns {boolean|null}
+ */
+function parseBool(v) {
+    if (v === true)
+        return true;
+    if (typeof v !== 'string')
+        return null;
+    const low = v.toLowerCase();
+    if (low === 'true' || low === 'yes' || low === '1')
+        return true;
+    if (low === 'false' || low === 'no' || low === '0')
+        return false;
+    return null;
+}
+/**
+ * Slugify a title for the filename (NNNN-slug.md).
+ *
+ * @param {string} title
+ */
+function slugify(title) {
+    return title
+        .toLowerCase()
+        .trim()
+        .replace(/[^\w\s-]/g, '')
+        .replace(/\s+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '');
+}
+/**
+ * Find the next ADR sequence number by scanning `docs/adr/`.
+ *
+ * @param {string} adrDir
+ * @returns {number}
+ */
+function nextAdrNumber(adrDir) {
+    if (!existsSync(adrDir))
+        return 1;
+    const entries = readdirSync(adrDir);
+    let max = 0;
+    for (const name of entries) {
+        const m = name.match(/^(\d{4})-/);
+        if (!m)
+            continue;
+        const n = Number.parseInt(m[1], 10);
+        if (n > max)
+            max = n;
+    }
+    return max + 1;
+}
+/**
+ * Render the ADR markdown body.
+ *
+ * @param {{
+ *   number: number,
+ *   title: string,
+ *   status: string,
+ *   date: string,
+ *   context: string,
+ *   decision: string,
+ *   consequences: string,
+ *   hardToReverse: boolean,
+ *   surprisingWithoutContext: boolean,
+ *   realTradeOff: boolean,
+ * }} opts
+ */
+function renderAdr(opts) {
+    const paddedNumber = String(opts.number).padStart(4, '0');
+    return [
+        `# ADR-${paddedNumber}: ${opts.title}`,
+        '',
+        `**Status:** ${opts.status}`,
+        `**Date:** ${opts.date}`,
+        '',
+        '## Context',
+        '',
+        opts.context,
+        '',
+        '## Decision',
+        '',
+        opts.decision,
+        '',
+        '## Consequences',
+        '',
+        opts.consequences,
+        '',
+        '---',
+        '',
+        '## Nygard 3-gate filter (audit trail)',
+        '',
+        'This ADR was written via `apt-tools adr write` and passed all three of',
+        "Nygard's filter gates. Reversible / obvious / trade-off-free decisions",
+        'stay in `.aperant/context/notes/{task-id}.md` and do NOT become ADRs.',
+        '',
+        `- **Hard to reverse:** ${opts.hardToReverse}`,
+        `- **Surprising without context:** ${opts.surprisingWithoutContext}`,
+        `- **Real trade-off:** ${opts.realTradeOff}`,
+        '',
+    ].join('\n');
+}
+/**
+ * CLI entry: `apt-tools adr <subcommand> <project-dir> [flags]`.
+ */
+export function cmdAdr(subcommand, projectDir, extraArgs) {
+    if (subcommand !== 'write') {
+        return err('Usage: apt-tools adr write <project-dir> --title <slug> --hard-to-reverse <bool> --surprising-without-context <bool> --real-trade-off <bool> --decision <text> --consequences <text> [--context <text>] [--status <status>]', 1, { command: 'adr' });
+    }
+    if (!projectDir) {
+        return err('project-dir is required', 1, { command: 'adr-write' });
+    }
+    const flags = parseFlags(extraArgs ?? []);
+    const title = flags.get('title');
+    if (typeof title !== 'string' || title.trim() === '') {
+        return err('--title <slug> is required', 1, { command: 'adr-write' });
+    }
+    // Three Nygard gates — every one must be parseable; missing means "not
+    // asked", which is the same as "no" for the filter.
+    const hardToReverse = parseBool(flags.get('hard-to-reverse'));
+    const surprisingWithoutContext = parseBool(flags.get('surprising-without-context'));
+    const realTradeOff = parseBool(flags.get('real-trade-off'));
+    for (const [name, value] of [
+        ['--hard-to-reverse', hardToReverse],
+        ['--surprising-without-context', surprisingWithoutContext],
+        ['--real-trade-off', realTradeOff],
+    ]) {
+        if (value === null) {
+            return err(`${name} <true|false> is required`, 1, { command: 'adr-write' });
+        }
+    }
+    const decision = flags.get('decision');
+    const consequences = flags.get('consequences');
+    if (typeof decision !== 'string' || decision.trim() === '') {
+        return err('--decision <text> is required', 1, { command: 'adr-write' });
+    }
+    if (typeof consequences !== 'string' || consequences.trim() === '') {
+        return err('--consequences <text> is required', 1, { command: 'adr-write' });
+    }
+    // Three-gate filter — every gate must be true to write.
+    const failed = [];
+    if (!hardToReverse)
+        failed.push('hard-to-reverse');
+    if (!surprisingWithoutContext)
+        failed.push('surprising-without-context');
+    if (!realTradeOff)
+        failed.push('real-trade-off');
+    if (failed.length > 0) {
+        return exitWith({
+            status: 'filtered',
+            command: 'adr-write',
+            reason: 'three-gate-filter',
+            failed_gates: failed,
+            note: 'Decision stays in .aperant/context/notes/{task-id}.md. ADRs are reserved for hard-to-reverse, surprising, real-trade-off decisions.',
+        }, 0);
+    }
+    // All three gates passed — write the ADR.
+    const absProjectDir = resolve(projectDir);
+    if (!existsSync(absProjectDir)) {
+        return err(`project directory not found: ${absProjectDir}`, 1, { command: 'adr-write' });
+    }
+    const adrDir = join(absProjectDir, 'docs', 'adr');
+    if (!existsSync(adrDir)) {
+        mkdirSync(adrDir, { recursive: true });
+    }
+    const number = nextAdrNumber(adrDir);
+    const slug = slugify(title);
+    const paddedNumber = String(number).padStart(4, '0');
+    const filename = `${paddedNumber}-${slug}.md`;
+    const filePath = join(adrDir, filename);
+    const status = (typeof flags.get('status') === 'string' && flags.get('status')) || 'Proposed';
+    const context = (typeof flags.get('context') === 'string' && flags.get('context')) ||
+        '{Context not supplied — provide via --context on a re-run.}';
+    const date = new Date().toISOString().slice(0, 10);
+    const body = renderAdr({
+        number,
+        title,
+        status: String(status),
+        date,
+        context: String(context),
+        decision,
+        consequences,
+        hardToReverse: true,
+        surprisingWithoutContext: true,
+        realTradeOff: true,
+    });
+    writeFileSync(filePath, body);
+    return ok({
+        status: 'ok',
+        command: 'adr-write',
+        file: filePath,
+        number,
+        slug,
+        title,
+        passed_gates: ['hard-to-reverse', 'surprising-without-context', 'real-trade-off'],
+    });
+}
+//# sourceMappingURL=adr.mjs.map

package/dist/cli/commands/adr.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"adr.mjs","sourceRoot":"","sources":["../../../src/cli/commands/adr.mjs"],"names":[],"mappings":"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"}

package/dist/cli/commands/ci-watch.d.mts

@@ -0,0 +1,7 @@
+/**
+ * @param {string} subcommand
+ * @param {string} projectDir
+ * @param {string[]} extraArgs
+ */
+export function cmdCiWatch(subcommand: string, projectDir: string, extraArgs: string[]): import("../util/result.mjs").CommandResult;
+//# sourceMappingURL=ci-watch.d.mts.map

package/dist/cli/commands/ci-watch.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ci-watch.d.mts","sourceRoot":"","sources":["../../../src/cli/commands/ci-watch.mjs"],"names":[],"mappings":"AA8DA;;;;GAIG;AACH,uCAJW,MAAM,cACN,MAAM,aACN,MAAM,EAAE,8CAyBlB"}