residoo 0.3.6 → 0.3.8

package/README.md

@@ -121,6 +121,13 @@ won't be built into the tool that writes it.
 - Redacts everything in its own output. You get a shape and a first/last-4
   preview, never the real value, including in `--json` mode. A decoded or
   rejoined secret is redacted exactly like a plain one.
+- Every report opens with the exact version and timestamp it was run with
+  (`residoo v0.3.8 · scanned 2026-01-01 12:00`; `--json` carries the same
+  as `residooVersion`/`scannedAt`), so a report pasted or screenshotted
+  later never leaves you guessing which build produced it. On an
+  interactive terminal, a lightweight spinner shows scan progress on
+  stderr; it is a complete no-op when stdout/stderr are piped, redirected,
+  or run in CI, so it can never interleave with `--json`/`--sarif` output.
 - `--sarif` emits SARIF 2.1.0 for GitHub code scanning's Security tab and
   inline pull-request annotations, the same format gitleaks/trufflehog/
   agentsweep already speak, so residoo's own Action and pre-commit hook plug
@@ -317,7 +324,7 @@ As a GitHub Action (this repository doubles as a composite action):
 ```yaml
 steps:
   - uses: actions/checkout@v4
-  - uses: dandovdub/residoo@v0.3.6
+  - uses: dandovdub/residoo@v0.3.8
 ```
 
 As a pre-commit hook:
@@ -325,7 +332,7 @@ As a pre-commit hook:
 ```yaml
 repos:
   - repo: https://github.com/dandovdub/residoo
-    rev: v0.3.6
+    rev: v0.3.8
     hooks:
       - id: residoo
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "residoo",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "description": "Find secrets leaking through your AI coding agent's session history. Zero network calls in the scan path, zero dependencies.",
   "license": "MIT",
   "author": "CloudRoam (https://cloudroam.io)",

package/src/cli.js

@@ -5,7 +5,7 @@ const fs = require("fs");
 const crypto = require("crypto");
 const { availableSources, ALL_SOURCES } = require("./sources");
 const { scan, emptyResult } = require("./scan");
-const { render, renderIntegrity, renderJson, renderSarif } = require("./report");
+const { render, renderIntegrity, renderJson, renderSarif, makeProgressReporter } = require("./report");
 const { checkIntegrity } = require("./integrity");
 const {
   ROTATION_GUIDANCE, guidanceFor, loadAcks, ackFinding, renderRotation,
@@ -494,7 +494,9 @@ async function main(argv) {
     return failOnFind && integrityWarnCount(integrity) > 0 ? 1 : 0;
   }
 
-  const result = await scan({ sources, includeNoisy, includeSuppressed });
+  const progress = makeProgressReporter();
+  const result = await scan({ sources, includeNoisy, includeSuppressed, onProgress: progress.onProgress });
+  progress.stop();
   const integrity = wantsIntegrity ? runIntegrity() : null;
   const rotation = renderRotation(result.findings, acks);
   process.stdout.write((wantsSarif

package/src/report.js

@@ -29,6 +29,43 @@ function ageDays(mtimeMs) {
   return Math.max(0, Math.floor((Date.now() - mtimeMs) / 86400000));
 }
 
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+/**
+ * A minimal progress indicator for the scan phase, wired to scan()'s own
+ * onProgress callback. Writes to STDERR only, never stdout: --json/--sarif
+ * consumers pipe stdout into a parser, and a spinner corrupting that would
+ * be a much worse bug than not having one. Gated on stderr actually being a
+ * TTY, so it is a complete no-op under redirection, piping, or CI, exactly
+ * the contexts where carriage-return spam in a captured log would be
+ * useless or actively annoying, not merely invisible. `stop()` clears the
+ * line so whatever prints next (the report, on stdout, is unaffected
+ * either way since this never touched stdout, but a plain-text stderr
+ * reader watching live should not see a stale line lingering) starts
+ * clean.
+ */
+function makeProgressReporter() {
+  if (!process.stderr.isTTY) return { onProgress: null, stop() {} };
+  let count = 0;
+  let lastWriteMs = 0;
+  let lastLineLen = 0;
+  let frame = 0;
+  const write = (s) => {
+    process.stderr.write("\r" + " ".repeat(lastLineLen) + "\r" + s);
+    lastLineLen = s.length;
+  };
+  const onProgress = ({ source }) => {
+    count++;
+    const now = Date.now();
+    if (now - lastWriteMs < 80) return; // throttled: avoid flicker on a fast scan
+    lastWriteMs = now;
+    frame = (frame + 1) % SPINNER_FRAMES.length;
+    write(`${SPINNER_FRAMES[frame]} scanning… ${count} file${count === 1 ? "" : "s"} checked (${source})`);
+  };
+  const stop = () => { if (lastLineLen > 0) process.stderr.write("\r" + " ".repeat(lastLineLen) + "\r"); };
+  return { onProgress, stop };
+}
+
 // File NAMES are attacker-controllable text headed for a terminal: in
 // --project mode a hostile checkout chooses its own filenames, and a name
 // carrying raw ESC bytes could clear the screen or overwrite the findings
@@ -160,11 +197,23 @@ function renderIntegrity(integrity, { noColor = false } = {}) {
   return lines.join("\n");
 }
 
+/** "YYYY-MM-DD HH:MM" in local time — matches the user's own system clock, not UTC. */
+function localTimestamp(d) {
+  const p2 = (n) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${p2(d.getMonth() + 1)}-${p2(d.getDate())} ${p2(d.getHours())}:${p2(d.getMinutes())}`;
+}
+
 function render({ findings, filesScanned, sourcesScanned, bytesScanned, suppressedCount = 0, distinctCounts = {}, unreadableFiles = [] }, { noColor = false, integrity = null, rotation = null } = {}) {
   const paint = makePaint(noColor);
   const lines = [];
   const push = (s = "") => lines.push(s);
 
+  // Which build ran and when, up front: a report pasted or screenshotted
+  // hours later (or a "why don't I see feature X" question) should never
+  // require asking "what version were you even running."
+  const { version } = require("../package.json");
+  push(paint(c.dim, `residoo v${version} · scanned ${localTimestamp(new Date())}`));
+
   const suppressedNote = suppressedCount > 0
     ? paint(c.dim, ` (${suppressedCount} more matched but looked like placeholder/example text; see --include-suppressed)`)
     : "";
@@ -197,7 +246,15 @@ function render({ findings, filesScanned, sourcesScanned, bytesScanned, suppress
     byRule.get(f.ruleId).items.push(f);
   }
   const byFile = new Map();
-  for (const f of findings) byFile.set(f.file, (byFile.get(f.file) || 0) + 1);
+  for (const f of findings) {
+    const entry = byFile.get(f.file) || { count: 0, mtimeMs: f.fileMTimeMs };
+    entry.count++;
+    // Newest mtime wins if a file's own findings ever carried different
+    // values (they should not, mtimeMs is a per-file stat, but a defensive
+    // max here costs nothing and avoids depending on finding order).
+    if (f.fileMTimeMs > entry.mtimeMs) entry.mtimeMs = f.fileMTimeMs;
+    byFile.set(f.file, entry);
+  }
   const oldest = findings.reduce((a, b) => (b.fileMTimeMs < a ? b.fileMTimeMs : a), Date.now());
   const newest = findings.reduce((a, b) => (b.fileMTimeMs > a ? b.fileMTimeMs : a), 0);
 
@@ -230,9 +287,9 @@ function render({ findings, filesScanned, sourcesScanned, bytesScanned, suppress
 
   push();
   push(paint(c.bold, "By file:"));
-  const fileRows = [...byFile.entries()].sort((a, b) => b[1] - a[1]).slice(0, 15);
-  for (const [file, count] of fileRows) {
-    push(`  ${String(count).padStart(4)}  ${paint(c.cyan, safeBasename(file))}`);
+  const fileRows = [...byFile.entries()].sort((a, b) => b[1].count - a[1].count).slice(0, 15);
+  for (const [file, { count, mtimeMs }] of fileRows) {
+    push(`  ${String(count).padStart(4)}  ${paint(c.dim, `~${String(ageDays(mtimeMs)).padStart(2)}d old`)}  ${paint(c.cyan, safeBasename(file))}`);
   }
   if (byFile.size > fileRows.length) push(paint(c.dim, `  … and ${byFile.size - fileRows.length} more file(s)`));
 
@@ -263,8 +320,11 @@ function render({ findings, filesScanned, sourcesScanned, bytesScanned, suppress
 // way, since it is derived from already-redacted material and is what
 // "residoo ack" takes.
 function renderJson(result, integrity = null, rotation = null) {
+  const { version } = require("../package.json");
   return JSON.stringify(
     {
+      residooVersion: version,
+      scannedAt: new Date().toISOString(),
       summary: {
         findingCount: result.findings.length,
         filesScanned: result.filesScanned,
@@ -277,6 +337,7 @@ function renderJson(result, integrity = null, rotation = null) {
       findings: result.findings.map((f) => ({
         rule: f.ruleId, label: f.label, confidence: f.confidence,
         source: f.source, file: f.relFile, line: f.line, preview: f.preview,
+        fileMTimeMs: f.fileMTimeMs,
         // Markers for the two decode/reconstruct passes (absent on ordinary
         // findings). `encoding` names how the value was wrapped ("base64" /
         // "base64url"); `spanLines` names the adjacent line pair a split value
@@ -389,4 +450,4 @@ function renderSarif(result) {
   }, null, 2);
 }
 
-module.exports = { render, renderIntegrity, renderRotationSection, renderJson, renderSarif };
+module.exports = { render, renderIntegrity, renderRotationSection, renderJson, renderSarif, makeProgressReporter };