@rmyndharis/aimhooman 0.3.0 → 0.4.0

package/src/report.mjs

@@ -9,13 +9,17 @@ const HUMAN_FINDING_CAP = 20;
 
 export function human(findings, tone) {
     if (!findings.length) return '';
-    let out = tone === 'professional' ? '\n' : '\nnot very hooman.\n\n';
     let block = 0;
     let review = 0;
     for (const f of findings) {
         if (f.decision === 'block') block += 1;
         else if (f.decision === 'review') review += 1;
     }
+    // The banner means "aimhooman stopped or reshaped your operation". A pure
+    // advisory (review findings only, the commit proceeds untouched) prints
+    // without it — otherwise the banner fires on allowed work and stops
+    // meaning anything when a real block lands.
+    let out = tone === 'professional' || block === 0 ? '\n' : '\nnot very hooman.\n\n';
     // Render findings in order up to the cap, then collapse the rest into one
     // summary line. Keeps the first findings fully visible (the actionable ones)
     // while bounding stderr for repeated-rule scans.
@@ -34,10 +38,11 @@ export function human(findings, tone) {
             out += `       > ${isSensitive(f) ? '[redacted]' : visible(f.text.trim())}\n`;
         }
         // Render the whole remediation array, not just the first entry. Several
-        // rules carry a second line (e.g. "rotate the key if it was ever exposed")
-        // that the previous single-index render dropped silently. UT-08: print a
-        // rule's fix once — a repeated rule (20 hits of the same secret rule)
-        // used to reprint the identical fix block for every finding.
+        // rules carry a second line (e.g. "or unstage if it is personal" on
+        // generic.agent-instructions) that the previous single-index render
+        // dropped silently. UT-08: print a rule's fix once — a repeated rule
+        // (20 hits of the same path rule) used to reprint the identical fix
+        // block for every finding.
         const remedies = f.remediation || [];
         if (remedies.length && fixesPrinted.has(f.ruleId)) {
             out += `       fix: as above for ${f.ruleId}\n`;
@@ -91,8 +96,13 @@ function isSensitive(finding) {
 // final ref boundary (failClosedIncomplete). Frictionless profiles warn and
 // continue — the reference-transaction guard still scans introduced commits
 // with failClosedIncomplete set, so the skipped content is checked before any
-// ref moves.
-export function exitCode(findings, profile, complete = true, { failClosedIncomplete = false } = {}) {
+// ref moves. One exception at that final boundary: a scan whose only gap is
+// 'size-limit' (a file over maxFileBytes went unscanned for content rules —
+// path rules still ran) warns and continues on frictionless profiles. Blocking
+// the whole commit there cost developers a legit large file for a marker risk
+// that clean/compliance treat as advisory anyway. Strict stays fail-closed on
+// any gap, size-limit included.
+export function exitCode(findings, profile, complete = true, { failClosedIncomplete = false, incompleteReasons = [] } = {}) {
     let block = false;
     let review = false;
     for (const f of findings) {
@@ -100,7 +110,11 @@ export function exitCode(findings, profile, complete = true, { failClosedIncompl
         else if (f.decision === 'review') review = true;
     }
     if (block) return 10;
-    if (!complete && (profile === 'strict' || failClosedIncomplete)) return 31;
+    if (!complete && (profile === 'strict' || failClosedIncomplete)) {
+        const sizeLimitOnly = incompleteReasons.length > 0
+            && incompleteReasons.every((reason) => reason === 'size-limit');
+        if (profile === 'strict' || !sizeLimitOnly) return 31;
+    }
     if (review && findings.some((finding) => (finding.scanProfile || profile) !== 'clean')) return 11;
     return 0;
 }

package/src/scan-session.mjs

@@ -7,6 +7,17 @@ export const DEFAULT_SCAN_LIMITS = Object.freeze({
     maxFindings: 1000,
 });
 
+// Skip reasons that mean a rule never ran on its input, so the scan cannot
+// claim full coverage. What that costs is the caller's call: strict stops on
+// any of them; the final ref guard stops on all but 'size-limit' (see
+// exitCode in report.mjs). 'local-pack-error' never originates here — it is
+// tallied by scan-target — but it belongs to the same contract.
+export const FATAL_SKIP_REASONS = new Set([
+    'metadata-unavailable', 'size-limit', 'total-byte-limit',
+    'missing-object', 'unexpected-object', 'finding-limit',
+    'local-input-limit', 'local-pack-error',
+]);
+
 export function scanEntries(repo, engine, entries, options = {}) {
     const limits = { ...DEFAULT_SCAN_LIMITS, ...options };
     const stats = {
@@ -131,12 +142,9 @@ export function scanEntries(repo, engine, entries, options = {}) {
         stats.skipped[reason] = (stats.skipped[reason] || 0) + count;
     }
 
-    const incompleteReasons = new Set([
-        'metadata-unavailable', 'size-limit', 'total-byte-limit', 'object-read-failed',
-        'missing-object', 'unexpected-object', 'finding-limit', 'local-input-limit',
-    ]);
-    const complete = !Object.keys(stats.skipped).some((reason) => incompleteReasons.has(reason));
-    return { findings, complete, stats };
+    const complete = !Object.keys(stats.skipped).some((reason) => FATAL_SKIP_REASONS.has(reason));
+    const incompleteReasons = Object.keys(stats.skipped).filter((reason) => FATAL_SKIP_REASONS.has(reason));
+    return { findings, complete, incompleteReasons, stats };
 }
 
 function readObjects(repo, objectIds, expectedBytes = 0) {

package/src/scan-target.mjs

@@ -8,7 +8,7 @@ import {
     unmergedPaths,
 } from './gitx.mjs';
 import { commitChanges, commitMessage, commitSnapshot, historyRange } from './history-scan.mjs';
-import { DEFAULT_SCAN_LIMITS, scanEntries } from './scan-session.mjs';
+import { DEFAULT_SCAN_LIMITS, FATAL_SKIP_REASONS, scanEntries } from './scan-session.mjs';
 import { loadRulesWithDiagnostics } from './rules.mjs';
 
 // A tiebreak for the one profile a range report has to name, not a strength
@@ -75,7 +75,7 @@ export function scanMessage(repo, text, options = {}) {
 
 function scanIndex(repo, options) {
     const kind = options.kind || 'staged';
-    const { rawPolicy, floor, policy, head, acknowledged } = resolveStagedPolicy(repo, options.explicitProfile);
+    const { rawPolicy, floor, policy, head, acknowledged, baselineObjectId } = resolveStagedPolicy(repo, options.explicitProfile);
     const loaded = engineForPolicy(repo, policy, options.overrideHead || head);
     const accumulator = createAccumulator(options.limits);
     accumulator.addSkipped(loaded.skipped);
@@ -96,11 +96,14 @@ function scanIndex(repo, options) {
         });
         // A reviewed-path override can suppress a matching path rule, but it
         // cannot turn an unresolved index into a complete commit snapshot.
-        accumulator.markIncomplete();
+        accumulator.markIncomplete('index-unresolved');
     }
 
     if (floor && !isVersionedStrict(rawPolicy)) {
-        accumulator.add([protectedPolicyFinding(rawPolicy, policy, null)]);
+        accumulator.add([protectedPolicyFinding(rawPolicy, policy, null, {
+            oldObjectId: baselineObjectId,
+            transition: 'staged',
+        })]);
     }
     scanEntryGroup(repo, loaded.engine, entries, policy, accumulator, {
         allowMissingPolicy: acknowledged && !rawPolicy.policy_object_id,
@@ -140,6 +143,7 @@ export function resolveStagedPolicy(repo, explicitProfile) {
         floor,
         head,
         acknowledged,
+        baselineObjectId: baselineStrict ? baseline.policy_object_id : null,
         policy: effectivePolicy(
             rawPolicy,
             explicitProfile,
@@ -209,11 +213,14 @@ function scanCommit(repo, options) {
             throw new GitRevisionError(options.revision, message);
         }
         diagnostics.push({ level: 'warning', message });
-        accumulator.markIncomplete();
+        accumulator.markIncomplete('shallow-repository');
     }
 
     if (floor && !isVersionedStrict(rawPolicy)) {
-        accumulator.add([protectedPolicyFinding(rawPolicy, policy, snapshot)]);
+        accumulator.add([protectedPolicyFinding(rawPolicy, policy, snapshot, {
+            oldObjectId: strictParentPolicies[0]?.policy_object_id ?? null,
+            transition: snapshot.commit,
+        })]);
     }
     // A commit is judged by what it changes, not by the whole tree it inherits.
     // Scanning snapshot.entries (a full `ls-tree`) re-applied path rules to
@@ -284,7 +291,7 @@ function scanRange(repo, options) {
             throw new GitRevisionError(options.range, message);
         }
         diagnostics.push({ level: 'warning', message });
-        accumulator.markIncomplete();
+        accumulator.markIncomplete('shallow-repository');
     }
     const policies = [];
     let usedStrictFloor = false;
@@ -336,7 +343,10 @@ function scanRange(repo, options) {
         diagnostics.push(...loaded.diagnostics);
 
         if (floor && !isVersionedStrict(rawPolicy)) {
-            accumulator.add([protectedPolicyFinding(rawPolicy, policy, commit)]);
+            accumulator.add([protectedPolicyFinding(rawPolicy, policy, commit, {
+                oldObjectId: [...parentStrictObjects][0] ?? null,
+                transition: commit.commit,
+            })]);
         }
         scanEntryGroup(repo, loaded.engine, changes.entries, policy, accumulator, {
             allowMissingPolicy: acknowledged && !rawPolicy.policy_object_id,
@@ -556,12 +566,27 @@ function isVersionedStrict(policy) {
     ));
 }
 
-function protectedPolicyFinding(rawPolicy, policy, entry) {
+function protectedPolicyFinding(rawPolicy, policy, entry, migration = {}) {
     const removed = !rawPolicy.policy_object_id;
     const reason = removed
         ? 'A versioned strict project policy cannot be deleted or renamed away without a bound review acknowledgment.'
         : 'A versioned strict project policy cannot be downgraded without a bound review acknowledgment.';
-    const remediation = ['Restore the strict policy or use the reviewed migration command bound to this target.'];
+    // Name the exact command, oids included: "use the reviewed migration
+    // command" sent developers to the docs for a three-flag incantation they
+    // could not guess (field-test rerun). The staged form binds to the live
+    // index; the transition form binds to the commit that carries the change.
+    const remediation = ['Restore the strict policy, or unstage the change to keep the current baseline.'];
+    if (migration.oldObjectId && migration.transition) {
+        const newOid = rawPolicy.policy_object_id ?? 'missing';
+        const form = migration.transition === 'staged'
+            ? '--staged'
+            : `--transition ${migration.transition}`;
+        remediation.push(
+            `or acknowledge the migration: aimhooman policy-review --head HEAD ${form} --old ${migration.oldObjectId} --new ${newOid} --reason "reviewed policy migration"`
+        );
+    } else {
+        remediation.push('or acknowledge the migration with a reviewed aimhooman policy-review invocation.');
+    }
     return decorate({
         ruleId: 'generic.project-policy',
         ruleVersion: 1,
@@ -637,10 +662,10 @@ function rangeReportPolicy(basePolicy, policies, usedStrictFloor, explicitProfil
     };
 }
 
-// Skip reasons that mean a rule never ran, as opposed to a rule running and
-// matching nothing. Either way the scan cannot claim to have covered its input.
-const INCOMPLETE_SKIP_REASONS = new Set(['local-input-limit', 'local-pack-error']);
-
+// The canonical set of fatal skip reasons lives in scan-session.mjs
+// (FATAL_SKIP_REASONS); the accumulator records which of them fired so callers
+// can tell "only an oversized file went unscanned" apart from gaps that must
+// stay fail-closed.
 function createAccumulator(limits = {}) {
     const effectiveLimits = { ...DEFAULT_SCAN_LIMITS, ...limits };
     const findings = [];
@@ -657,6 +682,12 @@ function createAccumulator(limits = {}) {
         skippedPaths: {},
     };
     let complete = true;
+    const incompleteReasons = new Set();
+
+    function flagIncomplete(reason) {
+        complete = false;
+        incompleteReasons.add(reason);
+    }
 
     function add(values, total = values.length) {
         stats.findings_total += total;
@@ -667,7 +698,7 @@ function createAccumulator(limits = {}) {
                 continue;
             }
             if (findings.length >= effectiveLimits.maxFindings) {
-                complete = false;
+                flagIncomplete('finding-limit');
                 increment(stats.skipped, 'finding-limit');
                 continue;
             }
@@ -675,7 +706,7 @@ function createAccumulator(limits = {}) {
             findings.push(finding);
         }
         stats.findings_returned = findings.length;
-        if (total > values.length) complete = false;
+        if (total > values.length) flagIncomplete('finding-limit');
     }
 
     return {
@@ -698,16 +729,17 @@ function createAccumulator(limits = {}) {
                     if (stats.skippedPaths[reason].length < 10) stats.skippedPaths[reason].push(entry);
                 }
             }
+            for (const reason of scanned.incompleteReasons || []) incompleteReasons.add(reason);
             if (!scanned.complete) complete = false;
         },
         addSkipped(skipped = {}) {
             for (const [reason, count] of Object.entries(skipped)) {
                 stats.skipped[reason] = (stats.skipped[reason] || 0) + count;
-                if (INCOMPLETE_SKIP_REASONS.has(reason)) complete = false;
+                if (FATAL_SKIP_REASONS.has(reason)) flagIncomplete(reason);
             }
         },
-        markIncomplete() {
-            complete = false;
+        markIncomplete(reason = 'target-unverifiable') {
+            flagIncomplete(reason);
         },
         remaining() {
             return Math.max(0, effectiveLimits.maxFindings - findings.length);
@@ -718,6 +750,9 @@ function createAccumulator(limits = {}) {
         isComplete() {
             return complete;
         },
+        get incompleteReasons() {
+            return [...incompleteReasons];
+        },
     };
 }
 
@@ -731,6 +766,7 @@ function result({ target, policy, accumulator, diagnostics, messageScanned, comm
             policy_enforced_object_ids: policy.enforced_policy_object_ids,
         } : {}),
         complete: accumulator.isComplete(),
+        incomplete_reasons: accumulator.incompleteReasons,
         stats: accumulator.stats,
         findings: accumulator.findings,
         diagnostics,

package/src/state.mjs

@@ -4,7 +4,7 @@ import {
     readFileSync,
 } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { atomicWrite } from './atomic-write.mjs';
+import { atomicWrite, withLock } from './atomic-write.mjs';
 import { normalizeGitPath } from './git-path.mjs';
 
 // Per-repository state, stored in the common Git dir (never the worktree).
@@ -105,8 +105,20 @@ export function parseProjectPolicy(text, file = '.aimhooman.json') {
 
 export function loadConfig(stateDir, root) {
     const project = loadProjectPolicy(root);
-    if (project) return { profile: project.profile, source: 'project', file: project.file };
     const file = join(stateDir, 'config.json');
+    if (project) {
+        // The project policy owns the profile, but the --gitignore opt-in stays
+        // per-clone state in config.json; a two-arg caller still needs it. The
+        // profile no longer depends on that file here, so a missing or corrupt
+        // one just omits the record instead of failing the load.
+        const gitignore = readGitignoreRecord(file);
+        return {
+            profile: project.profile,
+            source: 'project',
+            file: project.file,
+            ...(gitignore ? { gitignore } : {}),
+        };
+    }
     let text;
     try {
         text = readFileSync(file, 'utf8');
@@ -129,6 +141,17 @@ export function loadConfig(stateDir, root) {
     };
 }
 
+// Best-effort read of the per-clone gitignore record for the project-policy
+// branch above: any failure (absent file, invalid JSON, invalid shape) means
+// no record, never a failed load.
+function readGitignoreRecord(file) {
+    try {
+        return normalizeLocalConfig(JSON.parse(stripBom(readFileSync(file, 'utf8'))), file).gitignore;
+    } catch {
+        return undefined;
+    }
+}
+
 export function saveConfig(stateDir, config) {
     const file = join(stateDir, 'config.json');
     const normalized = normalizeLocalConfig(config, file);
@@ -193,7 +216,28 @@ export function loadOverrides(stateDir) {
         if (error?.code === 'ENOENT') return { allow: [], deny: [] };
         throw new LocalOverridesError(file, `cannot read file: ${error.message}`, error);
     }
-    return parseOverrides(text, file);
+    const dropped = { count: 0 };
+    const overrides = parseOverrides(text, file, dropped);
+    if (dropped.count) {
+        process.stderr.write(
+            `aimhooman: warning: ${file}: dropped ${dropped.count} override(s) with retired scope "secret-path"; built-in secret scanning was removed in v0.3.0\n`
+        );
+        // Persist the cleaned file so the migration warns once, not on every
+        // command. Re-read under the lock so a concurrent allow/deny write is
+        // never clobbered; a failed rewrite only means the warning returns
+        // next run, so this stays best effort. One attempt, no queue wait:
+        // allow/deny/override/review/policy-review call loadOverrides while
+        // already holding this same lock, and the bakery queue would park the
+        // inner candidate behind the outer one for the full retry budget
+        // before the catch below swallowed the throw.
+        try {
+            withLock(`${file}.lock`, () => {
+                const fresh = parseOverrides(readFileSync(file, 'utf8'), file);
+                atomicWriteJson(file, { schema_version: 1, ...fresh });
+            }, { retries: 1 });
+        } catch { /* best effort */ }
+    }
+    return overrides;
 }
 
 export function saveOverrides(stateDir, overrides) {
@@ -207,17 +251,17 @@ export function normalizeOverrideTarget(target) {
     return normalizeGitPath(target);
 }
 
-function parseOverrides(text, file) {
+function parseOverrides(text, file, dropped = { count: 0 }) {
     let value;
     try {
         value = JSON.parse(stripBom(text));
     } catch (error) {
         throw new LocalOverridesError(file, `invalid JSON: ${error.message}`, error);
     }
-    return normalizeOverrides(value, file);
+    return normalizeOverrides(value, file, dropped);
 }
 
-function normalizeOverrides(value, file) {
+function normalizeOverrides(value, file, dropped = { count: 0 }) {
     if (!value || typeof value !== 'object' || Array.isArray(value)) {
         throw new LocalOverridesError(file, 'root must be a JSON object');
     }
@@ -230,17 +274,13 @@ function normalizeOverrides(value, file) {
     if (value.schema_version !== undefined && value.schema_version !== 1) {
         throw new LocalOverridesError(file, 'schema_version must be 1');
     }
-    const dropped = { count: 0 };
-    const normalized = {
+    // The caller owns the drop count: loadOverrides warns and persists the
+    // cleaned file, saveOverrides drops retired entries silently on the next
+    // write.
+    return {
         allow: overrideEntries(value.allow, 'allow', file, dropped),
         deny: overrideEntries(value.deny, 'deny', file, dropped),
     };
-    if (dropped.count) {
-        process.stderr.write(
-            `aimhooman: warning: ${file}: dropped ${dropped.count} override(s) with retired scope "secret-path"; built-in secret scanning was removed in v0.3.0\n`
-        );
-    }
-    return normalized;
 }
 
 function overrideEntries(value, key, file, dropped = { count: 0 }) {
@@ -251,8 +291,8 @@ function overrideEntries(value, key, file, dropped = { count: 0 }) {
     return value.map((entry, index) => {
         // Built-in secret scanning and its secret-path override scope were
         // removed in v0.3.0. An overrides file written by an older version may
-        // still carry such entries; drop them (one warning per file, below)
-        // instead of failing the whole load.
+        // still carry such entries; drop them (loadOverrides warns once and
+        // persists the cleaned file) instead of failing the whole load.
         if (entry && typeof entry === 'object' && !Array.isArray(entry) && entry.scope === 'secret-path') {
             dropped.count += 1;
             return null;