@rmyndharis/aimhooman 0.1.5 → 0.1.6

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
             "name": "aimhooman",
             "source": "./",
             "description": "Keeps AI session files, secrets, and unwanted attribution out at the agent and Git boundary.",
-            "version": "0.1.5",
+            "version": "0.1.6",
             "license": "MIT",
             "keywords": [
                 "git",
@@ -20,4 +20,4 @@
             ]
         }
     ]
-}
+}

package/.claude-plugin/plugin.json

@@ -1,9 +1,9 @@
 {
     "name": "aimhooman",
-    "version": "0.1.5",
+    "version": "0.1.6",
     "description": "AI works. Hoomans ship. Keeps AI session files, secrets, and unwanted attribution out at the agent and Git boundary.",
     "author": {
         "name": "aimhooman"
     },
     "hooks": "./hooks/hooks.json"
-}
+}

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
     "name": "aimhooman",
-    "version": "0.1.5",
+    "version": "0.1.6",
     "description": "AI works. Hoomans ship. Keeps AI session files, secrets, and unwanted attribution out at the agent and Git boundary.",
     "author": {
         "name": "aimhooman maintainers",
@@ -34,4 +34,4 @@
         ],
         "brandColor": "#111827"
     }
-}
+}

package/CHANGELOG.md

@@ -5,6 +5,42 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.6] - 2026-07-18
+
+### Fixed
+
+- A tracked file over the per-file scan budget no longer blocks every commit in
+  the repository. 0.1.5 content-scanned the whole tree on every commit, so a 3 MiB
+  vendored bundle that crossed the 2 MiB default budget wedged every later commit
+  with `scan incomplete (size-limit=1)` — even one-line edits to an unrelated file
+  — and the only way out was to raise the budget above the largest tracked file.
+  Path rules still run on the full tree, so a staged `.env` stays blocked, but the
+  content scan now reads only the files a commit actually changes. Editing the
+  oversized file itself still fails the commit until the budget is raised.
+- An oversized file that is binary now skips as `binary` (complete) instead of
+  `size-limit` (incomplete). A PSD, WOFF, or PNG cannot hide the text-pattern
+  secrets the content scan looks for, so it was never really an incomplete scan.
+  The first 8 KB of each oversized file is probed for a NUL byte to tell binary
+  from text; files above 16 MiB stay `size-limit` without probing, because
+  `cat-file --batch` reads the whole blob into memory and probing a 500 MB file
+  just to check for NULs is not worth it. A text file over budget stays a real
+  `size-limit` skip, and the owner must raise `AIMHOOMAN_MAX_FILE_BYTES` to cover
+  it.
+- `secret.dotenv` now excepts `*.minimal`. A `.env.minimal` shipped as a template
+  was blocked by the same rule that catches a real `.env`, because `*.sample`,
+  `*.template`, `*.dist`, and `*.defaults` were excepted but `*.minimal` was not.
+  The rule's version bumps to 4.
+
+### Added
+
+- Incomplete-scan messages name the files that were dropped and why. A budget
+  miss used to print a count (`size-limit=3`) with no path, so the owner had to
+  hunt for the offender. The CLI now lists up to five skipped paths with their
+  sizes and reason, and the JSON scan report carries a `skippedPaths` object so a
+  caller can see every dropped file the same way. The schema documents the field.
+- `aimhooman explain` prints a rule's `except` clause when it has one, so an
+  `allow`/`deny` override can be reasoned about without opening the rule pack.
+
 ## [0.1.5] - 2026-07-18
 
 ### Fixed

package/README.md

@@ -9,7 +9,7 @@
 
 <p align="center">
   <img src="https://img.shields.io/github/actions/workflow/status/rmyndharis/aimhooman/test.yml?branch=main&label=CI" alt="CI">
-  <img src="https://img.shields.io/badge/version-v0.1.5-blue" alt="v0.1.5">
+  <img src="https://img.shields.io/badge/version-v0.1.6-blue" alt="v0.1.6">
   <img src="https://img.shields.io/badge/node-%E2%89%A522.8-339933?logo=node.js&logoColor=white" alt="Node 22.8+">
   <img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="Zero dependencies">
   <img src="https://img.shields.io/badge/license-MIT-111111" alt="MIT">

package/bin/aimhooman.mjs

@@ -212,7 +212,24 @@ function incompleteMessage(scan) {
         : budgeted
             ? 'reduce the target, or raise AIMHOOMAN_MAX_FILE_BYTES / AIMHOOMAN_MAX_TOTAL_BYTES, and retry'
             : 'reduce the target or limits and retry';
-    return `aimhooman: scan incomplete${skipped ? ` (${skipped})` : ''}; ${hint}\n`;
+    let message = `aimhooman: scan incomplete${skipped ? ` (${skipped})` : ''}; ${hint}\n`;
+    const skippedPaths = scan.stats?.skippedPaths || {};
+    const pathLines = [];
+    for (const [reason, entries] of Object.entries(skippedPaths)) {
+        for (const entry of entries.slice(0, 5)) {
+            const sizeStr = formatBytes(entry.size);
+            pathLines.push(`  skipped: ${entry.path} (${reason}, ${sizeStr})\n`);
+        }
+        if (entries.length > 5) pathLines.push(`  ... and ${entries.length - 5} more\n`);
+    }
+    return message + pathLines.join('');
+}
+
+function formatBytes(bytes) {
+    if (bytes == null || bytes < 0) return '?';
+    if (bytes < 1024) return `${bytes} B`;
+    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
 }
 
 function snapshotFile(path) {
@@ -978,6 +995,7 @@ function cmdExplain(args) {
     console.log(`Actions:     clean=${af('clean')} strict=${af('strict')} compliance=${af('compliance')}`);
     console.log(`Reason:      ${r.reason}`);
     if (r.match?.paths) console.log(`Paths:       ${r.match.paths.join(', ')}`);
+    if (r.match?.except) console.log(`Except:      ${r.match.except.join(', ')}`);
     if (r.match?.content) console.log(`Content:     ${r.match.content.join(', ')}`);
     if (r.remediation?.length) {
         console.log('Remediation:');

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rmyndharis/aimhooman",
-    "version": "0.1.5",
+    "version": "0.1.6",
     "description": "AI works. Hoomans ship. Keep AI session files, secrets, and attribution out of your commits.",
     "homepage": "https://github.com/rmyndharis/aimhooman#readme",
     "repository": {
@@ -74,4 +74,4 @@
         "developer-tools",
         "pre-commit"
     ]
-}
+}

package/rules/paths.json

@@ -218,7 +218,7 @@
     },
     {
         "id": "secret.dotenv",
-        "version": 3,
+        "version": 4,
         "provider": "generic",
         "category": "secret",
         "confidence": "high",
@@ -236,7 +236,8 @@
                 "**/*.sample",
                 "**/*.template",
                 "**/*.dist",
-                "**/*.defaults"
+                "**/*.defaults",
+                "**/*.minimal"
             ]
         },
         "actions": {

package/schemas/scan-report.schema.json

@@ -82,6 +82,21 @@
                 "skipped": {
                     "type": "object",
                     "additionalProperties": { "type": "integer", "minimum": 1 }
+                },
+                "skippedPaths": {
+                    "type": "object",
+                    "additionalProperties": {
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "required": ["path", "size"],
+                            "properties": {
+                                "path": { "type": "string" },
+                                "size": { "type": ["integer", "null"], "minimum": 0 }
+                            },
+                            "additionalProperties": false
+                        }
+                    }
                 }
             },
             "additionalProperties": false

package/src/scan-session.mjs

@@ -18,9 +18,11 @@ export function scanEntries(repo, engine, entries, options = {}) {
         findings_total: 0,
         findings_returned: 0,
         skipped: {},
+        skippedPaths: {},
     };
     const candidates = [];
     let selectedBytes = 0;
+    const oversized = [];
 
     for (const entry of entries) {
         if (entry.type !== 'blob') {
@@ -37,17 +39,48 @@ export function scanEntries(repo, engine, entries, options = {}) {
             continue;
         }
         if (entry.size > limits.maxFileBytes) {
-            increment(stats.skipped, 'size-limit');
+            oversized.push(entry);
             continue;
         }
         if (selectedBytes + entry.size > limits.maxTotalBytes) {
             increment(stats.skipped, 'total-byte-limit');
+            appendPath(stats.skippedPaths, 'total-byte-limit', entry.path, entry.size);
             continue;
         }
         selectedBytes += entry.size;
         candidates.push(entry);
     }
 
+    // Oversized files: probe the first 8 KB to separate binary from text.
+    // A binary file (PSD, WOFF, PNG) can't hide text-pattern secrets that
+    // the full content scan would find, so it skips as 'binary' (complete).
+    // A text file that exceeds the budget is a genuine 'size-limit' skip
+    // (incomplete) and the caller must raise the limit to cover it.
+    // Cap probing at 16 MiB: cat-file --batch reads the full blob into memory,
+    // so probing a 500 MB file just to check for NULs is wasteful. Files above
+    // the cap are classified as size-limit without probing.
+    const PROBE_CAP = 16 * 1024 * 1024;
+    const probeable = oversized.filter((entry) => entry.size <= PROBE_CAP);
+    const tooBig = oversized.filter((entry) => entry.size > PROBE_CAP);
+    for (const entry of tooBig) {
+        increment(stats.skipped, 'size-limit');
+        appendPath(stats.skippedPaths, 'size-limit', entry.path, entry.size);
+    }
+    if (probeable.length) {
+        const probeOids = [...new Set(probeable.map((entry) => entry.oid))];
+        const probes = probeObjects(repo, probeOids, probeable);
+        for (const entry of probeable) {
+            const header = probes.get(entry.oid);
+            if (header && isBinary(header)) {
+                increment(stats.skipped, 'binary');
+                appendPath(stats.skippedPaths, 'binary', entry.path, entry.size);
+            } else {
+                increment(stats.skipped, 'size-limit');
+                appendPath(stats.skippedPaths, 'size-limit', entry.path, entry.size);
+            }
+        }
+    }
+
     const objectIds = [...new Set(candidates.map((entry) => entry.oid))];
     const batch = readObjects(repo, objectIds, selectedBytes);
     stats.objects_read = batch.objects.size;
@@ -65,6 +98,7 @@ export function scanEntries(repo, engine, entries, options = {}) {
         let matched;
         if (isBinary(blob)) {
             increment(stats.skipped, 'binary');
+            appendPath(stats.skippedPaths, 'binary', entry.path, blob.length);
             // Binary classification only skips text-oriented policy rules. Secret
             // signatures are ASCII byte sequences, so latin1 preserves a
             // one-byte-to-one-code-unit view and keeps the existing byte limits.
@@ -148,10 +182,55 @@ function readObjects(repo, objectIds, expectedBytes = 0) {
     return { objects, failures };
 }
 
+// probeObjects reads the first 8000 bytes of each blob to decide whether it is
+// binary (contains a NUL). cat-file --batch outputs full blobs, so the buffer
+// must accommodate total blob sizes, but we only inspect the leading bytes.
+function probeObjects(repo, objectIds, entries) {
+    const unique = [...new Set(objectIds.filter(Boolean))];
+    if (!unique.length) return new Map();
+    const PROBE_BYTES = 8000;
+    // Sum the actual sizes so the buffer can hold the full output.
+    const sizeByOid = new Map();
+    for (const entry of entries) {
+        if (entry.oid && entry.size > 0) sizeByOid.set(entry.oid, Math.max(sizeByOid.get(entry.oid) || 0, entry.size));
+    }
+    const totalExpected = unique.reduce((sum, oid) => sum + (sizeByOid.get(oid) || 0), 0);
+    const output = execFileSync('git', ['cat-file', '--batch'], {
+        cwd: repo.root,
+        env: gitEnvironment(),
+        input: Buffer.from(unique.join('\n') + '\n'),
+        encoding: 'buffer',
+        maxBuffer: Math.max(2 * 1024 * 1024, totalExpected + unique.length * 256 + 1024),
+        timeout: GIT_TIMEOUT_MS,
+        stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const probes = new Map();
+    let offset = 0;
+    for (const requested of unique) {
+        const newline = output.indexOf(0x0a, offset);
+        if (newline < 0) break;
+        const header = output.subarray(offset, newline).toString('utf8');
+        offset = newline + 1;
+        const fields = header.split(' ');
+        if (fields[1] === 'missing' || fields.length !== 3 || fields[1] !== 'blob') continue;
+        const size = Number(fields[2]);
+        const end = offset + size;
+        if (end > output.length || output[end] !== 0x0a) break;
+        probes.set(requested, output.subarray(offset, offset + Math.min(size, PROBE_BYTES)));
+        offset = end + 1;
+    }
+    return probes;
+}
+
 function increment(record, key) {
     record[key] = (record[key] || 0) + 1;
 }
 
+function appendPath(record, reason, path, size) {
+    if (!record[reason]) record[reason] = [];
+    if (record[reason].length < 10) record[reason].push({ path, size });
+}
+
 function isBinary(buffer) {
     const length = Math.min(buffer.length, 8000);
     for (let index = 0; index < length; index++) if (buffer[index] === 0) return true;

package/src/scan-target.mjs

@@ -217,6 +217,7 @@ function scanCommit(repo, options) {
     }
     scanEntryGroup(repo, loaded.engine, snapshot.entries, policy, accumulator, {
         reviewPathEntries: snapshot.changes,
+        contentEntries: snapshot.changes,
         allowMissingPolicy: acknowledged && !rawPolicy.policy_object_id,
         transition: snapshot.commit,
     });
@@ -367,8 +368,15 @@ function scanEntryGroup(repo, engine, entries, policy, accumulator, options = {}
         })
             .map((finding) => decorate(finding, entry, policy)));
     }
+    // Content scanning can target a narrower set than the path check. When
+    // contentEntries is provided (e.g. only changed files in a commit), read
+    // blobs only for those entries instead of the full snapshot. Path-based
+    // rules already ran on the full tree above, so secrets like .env are still
+    // caught even when their blob isn't re-read.
+    const contentScannable = (options.contentEntries ?? entries)
+        .filter((entry) => entry.status !== 'D' && entry.type !== 'deleted');
     const remaining = accumulator.remaining();
-    const scanned = scanEntries(repo, engine, scannable, {
+    const scanned = scanEntries(repo, engine, contentScannable, {
         maxFileBytes: accumulator.limits.maxFileBytes,
         maxTotalBytes: accumulator.remainingBytes(),
         maxFindings: remaining,
@@ -628,6 +636,7 @@ function createAccumulator(limits = {}) {
         findings_total: 0,
         findings_returned: 0,
         skipped: {},
+        skippedPaths: {},
     };
     let complete = true;
 
@@ -665,6 +674,12 @@ function createAccumulator(limits = {}) {
             for (const [reason, count] of Object.entries(scanned.stats.skipped || {})) {
                 stats.skipped[reason] = (stats.skipped[reason] || 0) + count;
             }
+            for (const [reason, paths] of Object.entries(scanned.stats.skippedPaths || {})) {
+                if (!stats.skippedPaths[reason]) stats.skippedPaths[reason] = [];
+                for (const entry of paths) {
+                    if (stats.skippedPaths[reason].length < 10) stats.skippedPaths[reason].push(entry);
+                }
+            }
             if (!scanned.complete) complete = false;
         },
         addSkipped(skipped = {}) {