@gatedpath/preflight 0.2.3 → 0.2.4

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gatedpath/preflight",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "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.4",
+    "@gatedpath/chains": "0.2.4"
   },
   "devDependencies": {
     "@types/node": "^22.20.2",