@gatedpath/preflight 0.2.3 → 0.2.5

package/README.md

@@ -64,7 +64,8 @@ passes; `--json` for agents. The fix text is the failure table's (`@gatedpath/ag
 | `forge`, `anvil`, `cast` | yes | each on PATH and answering `--version` |
 | `foundry-version` | yes | the three report one version |
 | `foundry-exit-code` | yes | each hands its exit code back. The `@foundry-rs` npm packages (1.7.1) install a Node shim that exits 0 whatever the binary returned, so a failed `forge build` reports success; doctor probes with a flag no binary knows (the real ones exit 2, the shim 0), names the shim, and prints the `ln -sf` line to the real binary it found in the platform package beside it |
-| `slither`, `aderyn` | no | on PATH; a warning when missing or not at the version CI pins (0.11.6, 0.6.8) |
+| `slither` | no | on PATH; a warning when missing or not at the version CI pins (0.11.6) |
+| `aderyn` | no | reported, never a warning: Cyfrin retired Aderyn in November 2026 and withdrew its binaries and npm archives, so the scaffold's CI no longer runs it (0.2.5). A copy already installed is named with its version |
 | `env-tracked` | yes | no `.env` or `.env.*` (other than `.env.example`) in `git ls-files` |
 | `vendor` | yes | in a scaffold, each `vendor/redbelly-*/package.json` version equals the record the scaffolder wrote under `redbelly.vendor` in the root `package.json`; a scaffold without the record warns |
 

package/dist/checks/slither.d.ts

@@ -9,3 +9,13 @@ export declare const SOURCES_HASH_FILE = "slither.sources.sha256";
  */
 export declare function hashSources(dir: string): string;
 export declare function checkSlitherReport(project: string, sourceDir: string, reportPath?: string): Promise<CheckResult>;
+/** The project's `fail_on` from slither.config.json, or Slither's default, medium. */
+export declare function readFailOn(project: string): string;
+export interface SlitherFinding {
+    check: string;
+    impact: string;
+    confidence: string;
+    where: string;
+}
+/** Every detector result in a Slither JSON report, with one location each. */
+export declare function readFindings(reportFile: string): SlitherFinding[] | null;

package/dist/checks/slither.js

@@ -1,4 +1,5 @@
-// Does a Slither report exist, and does it describe the sources as they are now? Two ways to
+// Does a Slither report exist, does it describe the sources as they are now, and is it clean at the
+// project's own threshold? Freshness first, two ways to
 // answer. Preferred: a sidecar `slither.sources.sha256` next to the report holding the hash
 // of every .sol file under the source directory at the time Slither ran (the scaffold's
 // `npm run lint:slither` writes it); the check recomputes the hash and compares. Fallback,
@@ -8,6 +9,12 @@
 // time rule cannot be satisfied by re-running Slither on a clean project, because a report
 // with no findings is byte-identical and git records no new change for it (found on
 // 2026-09-12 running the prompt cards), which is why the hash sidecar exists.
+// Then the findings: a fresh report is not a clean one. Until 29 October 2026 this check stopped at
+// freshness, and a ship report said "pass" over a report holding a High (found on the first public CI
+// run of grant-milestone-escrow, where the same report failed `fail-on: medium`). A JSON report's
+// detectors are now read and any finding at or above the project's `fail_on` in slither.config.json
+// (default medium, Slither's own default) fails the check, naming them. A markdown report cannot be
+// read; the check says so and passes on freshness alone.
 import { execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { existsSync, readdirSync, readFileSync, statSync, realpathSync } from 'node:fs';
@@ -52,7 +59,7 @@ export async function checkSlitherReport(project, sourceDir, reportPath) {
         const current = hashSources(srcAbs);
         const data = { report: relative(project, found), sidecar: relative(project, sidecar), recordedHash: recorded, currentHash: current, sources: sources.length };
         if (recorded === current)
-            return { id: 'slither-report', status: 'pass', reason: `${data.report} describes the current sources: ${data.sidecar} matches the hash of ${sources.length} .sol file(s) under ${sourceDir}.`, data };
+            return withFindings(project, found, `${data.report} describes the current sources: ${data.sidecar} matches the hash of ${sources.length} .sol file(s) under ${sourceDir}`, data);
         return { id: 'slither-report', status: 'fail', reason: `${data.report} is stale: the sources under ${sourceDir} no longer match ${data.sidecar}; re-run slither.`, data };
     }
     const times = await fileTimes(project, [found, ...sources]);
@@ -68,9 +75,64 @@ export async function checkSlitherReport(project, sourceDir, reportPath) {
     }
     const data = { report: relative(project, found), reportTime: iso(reportTime), newestSource: relative(project, newestSource), newestSourceTime: iso(newestTime), sources: sources.length };
     if (reportTime >= newestTime)
-        return { id: 'slither-report', status: 'pass', reason: `${data.report} (${data.reportTime}) is newer than the newest source ${data.newestSource} (${data.newestSourceTime}).`, data };
+        return withFindings(project, found, `${data.report} (${data.reportTime}) is newer than the newest source ${data.newestSource} (${data.newestSourceTime})`, data);
     return { id: 'slither-report', status: 'fail', reason: `${data.report} (${data.reportTime}) is older than ${data.newestSource} (${data.newestSourceTime}); re-run slither and write ${SOURCES_HASH_FILE} beside the report (the scaffold's npm run lint:slither does both).`, data };
 }
+const IMPACT_RANK = { high: 3, medium: 2, low: 1, informational: 0, optimization: 0 };
+const FAIL_ON_RANK = { high: 3, medium: 2, low: 1, informational: 0, pedantic: 0, none: 99 };
+/** The project's `fail_on` from slither.config.json, or Slither's default, medium. */
+export function readFailOn(project) {
+    const candidates = [join(project, 'slither.config.json'), join(project, 'contracts', 'slither.config.json')];
+    for (const file of candidates) {
+        if (!existsSync(file))
+            continue;
+        try {
+            const cfg = JSON.parse(readFileSync(file, 'utf8'));
+            if (typeof cfg.fail_on === 'string' && cfg.fail_on.toLowerCase() in FAIL_ON_RANK)
+                return cfg.fail_on.toLowerCase();
+        }
+        catch {
+            /* an unreadable config falls back to the default, and the reason says which threshold applied */
+        }
+    }
+    return 'medium';
+}
+/** Every detector result in a Slither JSON report, with one location each. */
+export function readFindings(reportFile) {
+    if (!reportFile.endsWith('.json'))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(reportFile, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    const detectors = parsed.results?.detectors ?? [];
+    return detectors.map((d) => {
+        const el = d.elements?.[0]?.source_mapping;
+        const where = el?.filename_relative ? `${el.filename_relative}${el.lines?.length ? `:${el.lines[0]}` : ''}` : 'unknown location';
+        return { check: d.check ?? 'unknown', impact: d.impact ?? 'Unknown', confidence: d.confidence ?? 'Unknown', where };
+    });
+}
+/** A fresh report passes only if nothing in it reaches the project's `fail_on`. */
+function withFindings(project, reportFile, freshness, data) {
+    const findings = readFindings(reportFile);
+    const failOn = readFailOn(project);
+    if (findings === null) {
+        return { id: 'slither-report', status: 'pass', reason: `${freshness}; its findings were not read (not a JSON report), so freshness alone is checked.`, data: { ...data, failOn, findingsRead: false } };
+    }
+    const threshold = FAIL_ON_RANK[failOn] ?? 2;
+    const blocking = findings.filter((f) => (IMPACT_RANK[f.impact.toLowerCase()] ?? 0) >= threshold);
+    const counts = findings.reduce((acc, f) => { acc[f.impact] = (acc[f.impact] ?? 0) + 1; return acc; }, {});
+    const summary = Object.entries(counts).map(([k, v]) => `${v} ${k}`).join(', ') || 'no findings';
+    if (blocking.length === 0) {
+        return { id: 'slither-report', status: 'pass', reason: `${freshness}; ${summary}, none at or above fail_on ${failOn}.`, data: { ...data, failOn, findingsRead: true, counts } };
+    }
+    const named = blocking.slice(0, 5).map((f) => `${f.check} (${f.impact}) at ${f.where}`).join('; ');
+    const more = blocking.length > 5 ? ` and ${blocking.length - 5} more` : '';
+    return { id: 'slither-report', status: 'fail', reason: `${data['report']} is fresh but holds ${blocking.length} finding(s) at or above fail_on ${failOn}: ${named}${more}. Fix them or triage them in the source with a reasoned slither-disable comment, then re-run slither.`, data: { ...data, failOn, findingsRead: true, counts, blocking } };
+}
 function iso(t) {
     return t ? new Date(t * 1000).toISOString() : 'unknown';
 }

package/dist/doctor-cli.d.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-export declare const DOCTOR_HELP = "redbelly-doctor [options]\n\nChecks the machine before the first command: Node 22 or later; forge, anvil and cast on\nPATH, one version, and the real binaries rather than the @foundry-rs npm shim that exits 0\nwhatever the binary returned; slither and aderyn (optional); git; no .env tracked by git;\nand, in a scaffold, vendor/ matching the versions the scaffolder recorded. One line per\ncheck with the fix on the same line. Touches no network and no key.\n\n  --project <dir>   scaffold root, its contracts/ folder, or any directory (default: cwd)\n  --json            print the report as JSON\n  --version, --help\n\nExit 0 when every required check passes (optional checks may warn), 1 otherwise, 2 on bad arguments.\n";
+export declare const DOCTOR_HELP = "redbelly-doctor [options]\n\nChecks the machine before the first command: Node 22 or later; forge, anvil and cast on\nPATH, one version, and the real binaries rather than the @foundry-rs npm shim that exits 0\nwhatever the binary returned; slither (optional); git; no .env tracked by git;\nand, in a scaffold, vendor/ matching the versions the scaffolder recorded. One line per\ncheck with the fix on the same line. Touches no network and no key.\n\n  --project <dir>   scaffold root, its contracts/ folder, or any directory (default: cwd)\n  --json            print the report as JSON\n  --version, --help\n\nExit 0 when every required check passes (optional checks may warn), 1 otherwise, 2 on bad arguments.\n";
 export declare function parseDoctorArgs(argv: readonly string[]): {
     project?: string;
     json: boolean;

package/dist/doctor-cli.js

@@ -8,7 +8,7 @@ export const DOCTOR_HELP = `redbelly-doctor [options]
 
 Checks the machine before the first command: Node 22 or later; forge, anvil and cast on
 PATH, one version, and the real binaries rather than the @foundry-rs npm shim that exits 0
-whatever the binary returned; slither and aderyn (optional); git; no .env tracked by git;
+whatever the binary returned; slither (optional); git; no .env tracked by git;
 and, in a scaffold, vendor/ matching the versions the scaffolder recorded. One line per
 check with the fix on the same line. Touches no network and no key.
 

package/dist/doctor.d.ts

@@ -37,6 +37,10 @@ export interface DoctorReport {
 }
 export declare const NODE_MIN_MAJOR = 22;
 export declare const SLITHER_PIN = "0.11.6";
+/**
+ * @deprecated Cyfrin retired Aderyn in November 2026 and withdrew its binaries and npm archives, so
+ * CI no longer runs it and doctor no longer compares against a pin. Kept so imports of 0.2.4 still resolve.
+ */
 export declare const ADERYN_PIN = "0.6.8";
 declare const FOUNDRY_TOOLS: readonly ["forge", "anvil", "cast"];
 type FoundryTool = (typeof FOUNDRY_TOOLS)[number];

package/dist/doctor.js

@@ -1,6 +1,6 @@
 // redbelly-doctor: the machine before the first command. Node 22 or later; forge, anvil and cast
 // present, one version, and the real binaries rather than the @foundry-rs npm shim that exits 0
-// whatever the binary returned; slither and aderyn optional; git; no .env tracked; and, in a
+// whatever the binary returned; slither optional; aderyn reported, never warned on (retired); git; no .env tracked; and, in a
 // scaffold, vendor/ matching the versions the scaffolder recorded. One line per check with the fix
 // on the same line. The fix text comes from the failure table in @gatedpath/agent-rules, so
 // explain_failure and doctor use the same words. Nothing here touches a network or a key.
@@ -14,6 +14,10 @@ export const DOCTOR_VERSION = require('../package.json').version;
 export const DOCTOR_CHECK_IDS = ['node', 'git', 'forge', 'anvil', 'cast', 'foundry-version', 'foundry-exit-code', 'slither', 'aderyn', 'env-tracked', 'vendor'];
 export const NODE_MIN_MAJOR = 22;
 export const SLITHER_PIN = '0.11.6';
+/**
+ * @deprecated Cyfrin retired Aderyn in November 2026 and withdrew its binaries and npm archives, so
+ * CI no longer runs it and doctor no longer compares against a pin. Kept so imports of 0.2.4 still resolve.
+ */
 export const ADERYN_PIN = '0.6.8';
 const FOUNDRY_TOOLS = ['forge', 'anvil', 'cast'];
 /** The flag no Foundry binary knows. clap exits 2 on it; the npm shim exits 0. */
@@ -160,20 +164,34 @@ export async function runDoctor(opts = {}) {
         const concrete = shims.map((t) => (found[t].real ? `ln -sf ${found[t].real} ${found[t].path}` : null)).filter(Boolean).join(' && ');
         checks.push({ id: 'foundry-exit-code', required: true, status: 'fail', reason: `${detail}. A failed forge build or test reports success through it.`, fix: concrete || fixFor('foundry-exit-code-shim'), kind: 'foundry-exit-code-shim', data: { shims: shims.map((t) => ({ tool: t, path: found[t].path, real: found[t].real })) } });
     }
-    // slither, aderyn (optional)
-    for (const [tool, pin, kind] of [['slither', SLITHER_PIN, 'slither-not-found'], ['aderyn', ADERYN_PIN, 'aderyn-not-found']]) {
-        const path = whichOnPath(tool, env, platform);
+    // slither (optional)
+    {
+        const path = whichOnPath('slither', env, platform);
         if (!path) {
-            checks.push({ id: tool, required: false, status: 'warn', reason: `not found on PATH (optional${tool === 'slither' ? '; pre-flight wants its report before a deploy' : ''}).`, fix: fixFor(kind), kind });
-            continue;
+            checks.push({ id: 'slither', required: false, status: 'warn', reason: 'not found on PATH (optional; pre-flight wants its report before a deploy).', fix: fixFor('slither-not-found'), kind: 'slither-not-found' });
+        }
+        else {
+            const v = await toolVersion(path);
+            if (!v.version)
+                checks.push({ id: 'slither', required: false, status: 'warn', reason: `${path} did not answer --version (optional).`, fix: fixFor('slither-not-found'), kind: 'slither-not-found', data: { path } });
+            else if (v.version !== SLITHER_PIN)
+                checks.push({ id: 'slither', required: false, status: 'warn', reason: `${v.version} at ${path}; CI pins ${SLITHER_PIN}, so findings may differ.`, fix: null, kind: null, data: { path, version: v.version, pin: SLITHER_PIN } });
+            else
+                checks.push({ id: 'slither', required: false, status: 'pass', reason: `${v.version} at ${path}`, fix: null, kind: null, data: { path, version: v.version } });
+        }
+    }
+    // aderyn: reported, never warned on. Cyfrin retired it in November 2026 and withdrew every install route,
+    // so a missing copy is the normal case and there is nothing for the builder to fix. The id stays so the
+    // report keeps its shape for agents that read it.
+    {
+        const path = whichOnPath('aderyn', env, platform);
+        if (!path) {
+            checks.push({ id: 'aderyn', required: false, status: 'pass', reason: 'not installed, and not needed: Cyfrin retired Aderyn in November 2026; Slither is the analyser CI and pre-flight use.', fix: null, kind: null });
+        }
+        else {
+            const v = await toolVersion(path);
+            checks.push({ id: 'aderyn', required: false, status: 'pass', reason: `${v.version ?? 'a copy'} at ${path}; retired by Cyfrin in November 2026, so CI no longer runs it, but npm run lint:aderyn still does.`, fix: null, kind: null, data: { path, version: v.version } });
         }
-        const v = await toolVersion(path);
-        if (!v.version)
-            checks.push({ id: tool, required: false, status: 'warn', reason: `${path} did not answer --version (optional).`, fix: fixFor(kind), kind, data: { path } });
-        else if (v.version !== pin)
-            checks.push({ id: tool, required: false, status: 'warn', reason: `${v.version} at ${path}; CI pins ${pin}, so findings may differ.`, fix: null, kind: null, data: { path, version: v.version, pin } });
-        else
-            checks.push({ id: tool, required: false, status: 'pass', reason: `${v.version} at ${path}`, fix: null, kind: null, data: { path, version: v.version } });
     }
     // no .env tracked
     if (!gitPath) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gatedpath/preflight",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Pre-flight checks before deploying to Redbelly Network (151 mainnet, 153 testnet): chain ID, deployer verification, Safe admin, compiler pins, secrets in git history, RBNT balance, Slither report.",
   "license": "MIT",
   "repository": {
@@ -40,8 +40,8 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@gatedpath/agent-rules": "0.2.3",
-    "@gatedpath/chains": "0.2.3"
+    "@gatedpath/agent-rules": "0.2.5",
+    "@gatedpath/chains": "0.2.5"
   },
   "devDependencies": {
     "@types/node": "^22.20.2",