@mindlace/chreode 0.2.0 → 0.3.0

package/README.md

@@ -61,8 +61,9 @@ Wire them into `package.json` as `"signoff": "chreode signoff"` and
 3. **Base**: `--base`, else the nearest commit on the branch carrying a `refs/notes/chreode`
    note (the last successful signoff), else the merge-base with `origin/<baseBranch>`.
 4. **Plan**: changed paths (both sides of renames, deletions included) → triggers (first
-   matching rule; a path no rule matches fires every trigger) → steps (`when`, `if`,
-   `--skip`, `supersededBy`). The plan and every skipped step's reason are printed.
+   matching rule; a path no rule matches fires every trigger, unless it is a version-only
+   `package.json` / `package-lock.json` bump, which fires `versionBumpTriggers`) → steps
+   (`when`, `if`, `--skip`, `supersededBy`). The plan and every skipped step's reason are printed.
 5. **Run** the steps in order under one machine-wide lock shared by every chreode repo on the
    machine. Each step runs in its own process group with a hard timeout; policed steps fail
    on unexpected stderr. Children see `CHREODE_SIGNOFF=1`.
@@ -119,7 +120,7 @@ export default defineConfig({
 ```
 
 ```ts
-// vitest.config.ts (reporters are root-level only)
+// vitest.config.ts (reporters are root-level only; keep 'default' explicit, see below)
 import VitestFlakeReporter from '@mindlace/chreode/reporters/vitest';
 
 export default defineConfig({
@@ -200,6 +201,7 @@ export default defineConfig({
     { match: 'src/**', triggers: ['lint', 'check', 'unit', 'e2e'] },
     { match: 'generated/**', triggers: [] } // matched, nothing to run
   ],
+  versionBumpTriggers: ['format'], // default []: see below
   steps: [
     { label: 'format', run: 'npx prettier --check .', when: ['format'], supersededBy: ['lint'] },
     { label: 'lint', run: 'npm run lint', when: ['lint'] },
@@ -223,6 +225,15 @@ glob, dotfiles included, or a RegExp, or an array of them) matches a changed pat
 triggers. A path no rule matches fires every trigger: rules can only make runs smaller, so a
 forgotten rule costs time, never coverage. Triggers are free-form strings.
 
+**Version bumps** are the one exception. A `package.json` or `package-lock.json` (at any depth)
+that matches no rule, exists on both sides, and whose only change is its version (for the
+lockfile, the top-level `version` and `packages[""].version`; key order and formatting are
+ignored) fires `versionBumpTriggers` instead of every trigger. The default is `[]`, so a
+release commit that only bumps the version runs nothing. The plan prints such paths as
+`version-only: package.json`. A rule that matches the file still wins, any other change to
+it (or an added, deleted or unparseable file) fires everything as before, and `--full`
+ignores the distinction.
+
 **Steps** run in config order.
 
 | Field          | Type                        | Meaning                                                                |
@@ -239,6 +250,15 @@ forgotten rule costs time, never coverage. Triggers are free-form strings.
 leave the checkout clean (signoff refuses to run otherwise), so use `npm ci`, which installs
 exactly the lockfile, rather than `npm install`, which can rewrite it.
 **`stderrAllowlist`** entries need a `reason`: allowlisting noise is a reviewed decision.
+
+**Pin vitest's `reporters`** in any project whose test steps police stderr. With no
+`reporters` set, vitest picks its `agent` reporter whenever it detects an AI agent (`AI_AGENT`,
+`CLAUDECODE`, `CODEX_*` and others, via std-env), and that reporter hides console output from
+passing tests. Signoff would then pass under an agent and fail for a human on the same commit.
+An explicit `reporters: ['default']` (plus `VitestFlakeReporter` when flakes is on) makes every
+run show that output, so a stray `console.error` fails signoff whoever runs it. Assert expected
+logs in the test (`vi.spyOn(console, 'error')`) rather than allowlisting them.
+
 Unknown keys, duplicate labels, and `supersededBy` naming a missing step are load errors.
 
 **`flakes`** (presence turns flake tracking on) and **`burnIn`** are described under

package/dist/config/types.d.ts

@@ -77,6 +77,9 @@ export interface ChreodeConfig {
     baseBranch?: string;
     statusContext?: string;
     rules?: RuleConfig[];
+    /** Fired, instead of every trigger, by a package.json / package-lock.json that matched no
+     *  rule and whose only change is its version. Default [] (a version bump runs nothing). */
+    versionBumpTriggers?: string[];
     steps: StepConfig[];
     /** Runs only when the merge of origin/<baseBranch> actually changed the branch. */
     afterMerge?: string;
@@ -94,6 +97,7 @@ export interface ResolvedConfig {
     baseBranch: string;
     statusContext: string;
     rules: RuleConfig[];
+    versionBumpTriggers: string[];
     steps: ResolvedStep[];
     afterMerge: string | null;
     stderrAllowlist: AllowlistEntry[];

package/dist/config/validate.js

@@ -11,6 +11,7 @@ const TOP_KEYS = new Set([
     'baseBranch',
     'statusContext',
     'rules',
+    'versionBumpTriggers',
     'steps',
     'afterMerge',
     'stderrAllowlist',
@@ -84,6 +85,15 @@ function validateRules(raw, problems) {
     });
     return raw;
 }
+function validateVersionBumpTriggers(raw, problems) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw) || !raw.every(isNonEmptyString)) {
+        problems.push('config.versionBumpTriggers: must be an array of trigger names ([] runs nothing)');
+        return [];
+    }
+    return raw;
+}
 function validateSteps(raw, problems) {
     if (!Array.isArray(raw)) {
         problems.push('config.steps: must be an array');
@@ -257,6 +267,7 @@ export function validateConfig(raw) {
         }
     }
     const rules = validateRules(raw.rules, problems);
+    const versionBumpTriggers = validateVersionBumpTriggers(raw.versionBumpTriggers, problems);
     const steps = validateSteps(raw.steps, problems);
     const stderrAllowlist = validateAllowlist(raw.stderrAllowlist, problems);
     const protection = validateProtection(raw.protection, problems);
@@ -268,6 +279,7 @@ export function validateConfig(raw) {
         baseBranch: raw.baseBranch ?? DEFAULT_BASE_BRANCH,
         statusContext: raw.statusContext ?? DEFAULT_STATUS_CONTEXT,
         rules,
+        versionBumpTriggers,
         steps,
         afterMerge: raw.afterMerge ?? null,
         stderrAllowlist,

package/dist/git/version-only.d.ts

@@ -0,0 +1,11 @@
+import { type Exec } from '../run/exec.js';
+/**
+ * True when `path` is a package.json or package-lock.json (at any depth) present on both
+ * sides whose only difference between base and head is its version field(s) (for the
+ * lockfile, the top-level `version` and `packages[""].version`). Anything else, including
+ * an added or deleted file or unparseable JSON, is false: the caller falls back to treating
+ * the path as an ordinary change.
+ */
+export declare function isVersionOnlyChange(base: string, head: string, path: string, exec?: Exec): boolean;
+/** The subset of `paths` that are version-only changes between base and head. */
+export declare function versionOnlyPaths(base: string, head: string, paths: readonly string[], exec?: Exec): string[];

package/dist/git/version-only.js

@@ -0,0 +1,56 @@
+import { posix } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { defaultExec } from '../run/exec.js';
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/** Each version-bearing file: the version fields it carries, read and blanked. */
+const VERSIONED = {
+    'package.json': (doc) => {
+        const { version, ...rest } = doc;
+        return { versions: [version], rest };
+    },
+    'package-lock.json': (doc) => {
+        const { version, ...rest } = doc;
+        const packages = rest.packages;
+        if (!isObject(packages) || !isObject(packages['']))
+            return { versions: [version], rest };
+        const { version: rootVersion, ...root } = packages[''];
+        return {
+            versions: [version, rootVersion],
+            rest: { ...rest, packages: { ...packages, '': root } }
+        };
+    }
+};
+function readJson(rev, path, exec) {
+    try {
+        const doc = JSON.parse(exec('git', ['show', `${rev}:${path}`]));
+        return isObject(doc) ? doc : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * True when `path` is a package.json or package-lock.json (at any depth) present on both
+ * sides whose only difference between base and head is its version field(s) (for the
+ * lockfile, the top-level `version` and `packages[""].version`). Anything else, including
+ * an added or deleted file or unparseable JSON, is false: the caller falls back to treating
+ * the path as an ordinary change.
+ */
+export function isVersionOnlyChange(base, head, path, exec = defaultExec) {
+    const strip = VERSIONED[posix.basename(path)];
+    if (strip === undefined)
+        return false;
+    const before = readJson(base, path, exec);
+    const after = readJson(head, path, exec);
+    if (before === null || after === null)
+        return false;
+    const a = strip(before);
+    const b = strip(after);
+    return isDeepStrictEqual(a.rest, b.rest) && !isDeepStrictEqual(a.versions, b.versions);
+}
+/** The subset of `paths` that are version-only changes between base and head. */
+export function versionOnlyPaths(base, head, paths, exec = defaultExec) {
+    return paths.filter((p) => isVersionOnlyChange(base, head, p, exec));
+}

package/dist/signoff/plan.d.ts

@@ -9,6 +9,8 @@ export interface PlanInput {
     base: string;
     head: string;
     isWorktree: boolean;
+    /** Changed package.json / package-lock.json paths whose only change is the version. */
+    versionOnly: readonly string[];
 }
 export interface PlannedStep {
     label: string;
@@ -30,6 +32,9 @@ export interface Plan {
     triggers: string[];
     /** Changed paths no rule matched; each one fired every trigger. */
     unmatched: string[];
+    /** Changed paths no rule matched that were version-only bumps; each fired only the
+     *  config's versionBumpTriggers. */
+    versionOnly: string[];
     steps: PlannedStep[];
     skipped: {
         label: string;
@@ -41,10 +46,18 @@ export interface Plan {
 export declare function matchesAny(path: string, matchers: Matcher | Matcher[]): boolean;
 export declare function matchRule(path: string, rules: readonly RuleConfig[]): RuleConfig | null;
 export declare function allTriggers(steps: readonly ResolvedStep[]): string[];
-/** Rules can only make a run smaller by matching: an unmatched path fires everything. */
-export declare function fireTriggers(paths: readonly string[], rules: readonly RuleConfig[], steps: readonly ResolvedStep[]): {
+export interface VersionBumps {
+    /** Paths whose only change is a version bump. */
+    versionOnly: readonly string[];
+    /** What such a path fires when no rule matched it. */
+    versionBumpTriggers: readonly string[];
+}
+/** Rules can only make a run smaller by matching: an unmatched path fires everything,
+ *  unless it is a version-only bump, which fires just the versionBumpTriggers. */
+export declare function fireTriggers(paths: readonly string[], rules: readonly RuleConfig[], steps: readonly ResolvedStep[], bumps?: VersionBumps): {
     triggers: string[];
     unmatched: string[];
+    versionOnly: string[];
 };
 export declare function planSignoff(config: ResolvedConfig, input: PlanInput): Plan;
 export declare function describeSkip(reason: SkipReason): string;

package/dist/signoff/plan.js

@@ -27,19 +27,31 @@ export function matchRule(path, rules) {
 export function allTriggers(steps) {
     return [...new Set(steps.flatMap((s) => s.when))].sort();
 }
-/** Rules can only make a run smaller by matching: an unmatched path fires everything. */
-export function fireTriggers(paths, rules, steps) {
+/** Rules can only make a run smaller by matching: an unmatched path fires everything,
+ *  unless it is a version-only bump, which fires just the versionBumpTriggers. */
+export function fireTriggers(paths, rules, steps, bumps = { versionOnly: [], versionBumpTriggers: [] }) {
     const fired = new Set();
     const unmatched = [];
+    const versionOnly = [];
+    const bumped = new Set(bumps.versionOnly);
     for (const path of paths) {
         const rule = matchRule(path, rules);
-        const triggers = rule === null ? allTriggers(steps) : rule.triggers;
-        if (rule === null)
+        let triggers;
+        if (rule !== null) {
+            triggers = rule.triggers;
+        }
+        else if (bumped.has(path)) {
+            versionOnly.push(path);
+            triggers = bumps.versionBumpTriggers;
+        }
+        else {
             unmatched.push(path);
+            triggers = allTriggers(steps);
+        }
         for (const t of triggers)
             fired.add(t);
     }
-    return { triggers: [...fired].sort(), unmatched };
+    return { triggers: [...fired].sort(), unmatched, versionOnly };
 }
 export function planSignoff(config, input) {
     const known = config.steps.map((s) => s.label);
@@ -47,9 +59,12 @@ export function planSignoff(config, input) {
     if (unknownSkips.length > 0) {
         throw new PlanError(`--skip names unknown step(s): ${unknownSkips.join(', ')} (known: ${known.join(', ')})`);
     }
-    const { triggers, unmatched } = input.full
-        ? { triggers: allTriggers(config.steps), unmatched: [] }
-        : fireTriggers(input.paths, config.rules, config.steps);
+    const { triggers, unmatched, versionOnly } = input.full
+        ? { triggers: allTriggers(config.steps), unmatched: [], versionOnly: [] }
+        : fireTriggers(input.paths, config.rules, config.steps, {
+            versionOnly: input.versionOnly,
+            versionBumpTriggers: config.versionBumpTriggers
+        });
     const ctx = {
         base: input.base,
         head: input.head,
@@ -96,7 +111,7 @@ export function planSignoff(config, input) {
             timeoutMs: step.timeoutMs
         });
     }
-    return { triggers, unmatched, steps, skipped, skippedByFlag };
+    return { triggers, unmatched, versionOnly, steps, skipped, skippedByFlag };
 }
 export function describeSkip(reason) {
     switch (reason.kind) {

package/dist/signoff/run.js

@@ -4,6 +4,7 @@ import { FLAKE_LOG_FILE } from '../flakes/log.js';
 import { escalationFailure, runFlakePhase } from '../flakes/phase.js';
 import { committedPaths, isWorktree, resolveBase, resolveRef } from '../git/change-set.js';
 import { mergeBaseBranch } from '../git/merge.js';
+import { versionOnlyPaths } from '../git/version-only.js';
 import { repoInfo } from '../github/status.js';
 import { signoffLock } from '../lock/machine-lock.js';
 import { defaultExec, defaultRun } from '../run/exec.js';
@@ -48,6 +49,9 @@ export function printPlan(plan, where, log) {
     if (plan.unmatched.length > 0) {
         log(`[chreode] matched no rule, so every trigger fired: ${plan.unmatched.join(', ')}`);
     }
+    if (plan.versionOnly.length > 0) {
+        log(`[chreode] version-only: ${plan.versionOnly.join(', ')}`);
+    }
     log(`[chreode] triggers: ${plan.triggers.length > 0 ? plan.triggers.join(', ') : '(none)'}`);
     log(`[chreode] plan: ${plan.steps.length > 0 ? plan.steps.map((s) => s.label).join(', ') : '(no steps: a no-op signoff)'}`);
     for (const { label, reason } of plan.skipped) {
@@ -148,7 +152,8 @@ export async function runSignoff(loadConfig, opts, overrides = {}) {
             skip: opts.skip,
             base,
             head,
-            isWorktree: isWorktree(d.exec)
+            isWorktree: isWorktree(d.exec),
+            versionOnly: opts.full ? [] : versionOnlyPaths(base, head, paths, d.exec)
         });
     }
     catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindlace/chreode",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A deterministic, selective, unavoidable local-CI gate for agent-written code",
   "keywords": [
     "ci",