hullproof 0.0.0-stage → 0.5.0

package/src/discover/extract.ts

@@ -0,0 +1,235 @@
+// Fact extractors: declared dependencies from manifests, and imports from source files. Small built in readers only,
+// line based where the format allows, so every fact carries a file and a line (or a JSON key).
+
+export interface DepFact { eco: string; name: string; version: string | null; file: string; line?: number; key?: string }
+export interface ImportFact { lang: string; module: string; file: string; line: number }
+
+const base = (f: string): string => f.slice(f.lastIndexOf('/') + 1);
+const lines = (t: string): string[] => t.split(/\r?\n/);
+const pyName = (n: string): string => n.toLowerCase().replace(/_/g, '-');
+
+function jsonDeps(eco: string, file: string, text: string, sections: string[]): DepFact[] {
+  let j: Record<string, unknown>;
+  try { j = JSON.parse(text); } catch { return []; }
+  const out: DepFact[] = [];
+  for (const s of sections) {
+    const deps = j?.[s];
+    if (!deps || typeof deps !== 'object') continue;
+    for (const [name, v] of Object.entries(deps as Record<string, unknown>)) {
+      out.push({ eco, name, version: typeof v === 'string' ? v : null, file, key: `${s}.${name}` });
+    }
+  }
+  return out;
+}
+
+function eachLine(text: string, fn: (line: string, n: number) => void): void {
+  lines(text).forEach((l, i) => fn(l, i + 1));
+}
+
+function requirementString(s: string): { name: string; version: string | null } | null {
+  const m = /^\s*([A-Za-z0-9][A-Za-z0-9_.-]*)(?:\[[^\]]*\])?\s*((?:===|[<>=!~]=?)[^;#,\s]*(?:\s*,\s*[<>=!~]=?[^;#,\s]*)*)?\s*(?:;.*)?$/.exec(s);
+  return m ? { name: pyName(m[1]), version: m[2] ?? null } : null;
+}
+
+function requirementsTxt(file: string, text: string): DepFact[] {
+  const out: DepFact[] = [];
+  eachLine(text, (l, n) => {
+    const t = l.replace(/\s+#.*$/, '').trim();
+    if (!t || t.startsWith('#') || t.startsWith('-') || t.includes('://')) return;
+    const r = requirementString(t);
+    if (r) out.push({ eco: 'pypi', ...r, file, line: n });
+  });
+  return out;
+}
+
+function pyproject(file: string, text: string): DepFact[] {
+  const out: DepFact[] = [];
+  let section = '';
+  let arrayKey: string | null = null;
+  eachLine(text, (l, n) => {
+    const sec = /^\s*\[{1,2}([^\]]+)\]{1,2}\s*$/.exec(l);
+    if (sec) { section = sec[1].trim(); arrayKey = null; return; }
+    let rest = l;
+    if (arrayKey === null) {
+      const a = /^\s*"?([A-Za-z0-9_.-]+)"?\s*=\s*\[(.*)$/.exec(l);
+      if (a) { arrayKey = a[1]; rest = a[2]; }
+      else if (/(^|\.)dependencies$/.test(section) && section !== 'project') {
+        const p = /^\s*([A-Za-z0-9_.-]+)\s*=\s*(.*)$/.exec(l); // poetry style: name = "^1.0" or { version = "1.0" }
+        if (p && p[1].toLowerCase() !== 'python') {
+          const v = /^"([^"]*)"/.exec(p[2])?.[1] ?? /version\s*=\s*"([^"]*)"/.exec(p[2])?.[1] ?? null;
+          out.push({ eco: 'pypi', name: pyName(p[1]), version: v, file, line: n });
+        }
+        return;
+      } else return;
+    }
+    const depArray = (section === 'project' && arrayKey === 'dependencies') || section === 'project.optional-dependencies'
+      || section === 'dependency-groups' || (section === 'build-system' && arrayKey === 'requires');
+    if (depArray) {
+      for (const m of rest.matchAll(/"([^"]+)"|'([^']+)'/g)) {
+        const r = requirementString(m[1] ?? m[2]);
+        if (r) out.push({ eco: 'pypi', ...r, file, line: n });
+      }
+    }
+    if (rest.includes(']')) arrayKey = null;
+  });
+  return out;
+}
+
+function sectionKeyValues(eco: string, file: string, text: string, isDepSection: (s: string) => boolean, norm: (s: string) => string): DepFact[] {
+  const out: DepFact[] = [];
+  let section = '';
+  eachLine(text, (l, n) => {
+    const sec = /^\s*\[([^\]]+)\]\s*$/.exec(l);
+    if (sec) { section = sec[1].trim(); return; }
+    if (!isDepSection(section)) return;
+    const p = /^\s*"?([A-Za-z0-9_.-]+)"?\s*=\s*(.*)$/.exec(l);
+    if (!p) return;
+    const v = /^"([^"]*)"/.exec(p[2])?.[1] ?? /version\s*=\s*"([^"]*)"/.exec(p[2])?.[1] ?? null;
+    out.push({ eco, name: norm(p[1]), version: v, file, line: n });
+  });
+  return out;
+}
+
+function regexLines(eco: string, file: string, text: string, re: RegExp, nameOf: (m: RegExpExecArray) => string, verOf: (m: RegExpExecArray) => string | null): DepFact[] {
+  const out: DepFact[] = [];
+  eachLine(text, (l, n) => {
+    const m = re.exec(l);
+    if (m) out.push({ eco, name: nameOf(m), version: verOf(m), file, line: n });
+  });
+  return out;
+}
+
+function goMod(file: string, text: string): DepFact[] {
+  const out: DepFact[] = [];
+  let inBlock = false;
+  eachLine(text, (l, n) => {
+    if (/^\s*require\s*\(\s*$/.test(l)) { inBlock = true; return; }
+    if (inBlock && /^\s*\)/.test(l)) { inBlock = false; return; }
+    const m = inBlock ? /^\s*(\S+)\s+(v\S+)/.exec(l) : /^\s*require\s+(\S+)\s+(v\S+)/.exec(l);
+    if (m) out.push({ eco: 'go', name: m[1], version: m[2], file, line: n });
+  });
+  return out;
+}
+
+function pomXml(file: string, text: string): DepFact[] {
+  const out: DepFact[] = [];
+  for (const m of text.matchAll(/<(dependency|parent|plugin)>([\s\S]*?)<\/\1>/g)) {
+    const body = m[2];
+    const g = /<groupId>\s*([^<\s]+)\s*<\/groupId>/.exec(body)?.[1] ?? '';
+    const a = /<artifactId>\s*([^<\s]+)\s*<\/artifactId>/.exec(body);
+    if (!a) continue;
+    const v = /<version>\s*([^<\s]+)\s*<\/version>/.exec(body)?.[1] ?? null;
+    const at = (m.index ?? 0) + m[0].indexOf(a[0]);
+    out.push({ eco: 'maven', name: `${g}:${a[1]}`, version: v, file, line: text.slice(0, at).split('\n').length });
+  }
+  return out;
+}
+
+function pubspec(file: string, text: string): DepFact[] {
+  const out: DepFact[] = [];
+  let inDeps = false;
+  eachLine(text, (l, n) => {
+    if (/^\S/.test(l)) { inDeps = /^(dependencies|dev_dependencies|dependency_overrides):\s*$/.test(l); return; }
+    if (!inDeps) return;
+    const m = /^ {2}([A-Za-z0-9_]+):\s*(.*)$/.exec(l);
+    if (m) out.push({ eco: 'pub', name: m[1], version: m[2].trim() || null, file, line: n });
+  });
+  return out;
+}
+
+function terraform(file: string, text: string): DepFact[] {
+  const out: DepFact[] = [];
+  eachLine(text, (l, n) => {
+    // Provider blocks, and the provider prefix of resource and data types (aws_s3_bucket is provider aws).
+    const p = /^\s*provider\s+"([a-z0-9_-]+)"/.exec(l) ?? /^\s*(?:resource|data)\s+"([a-z0-9]+)_/.exec(l);
+    if (p) out.push({ eco: 'terraform', name: p[1], version: null, file, line: n });
+  });
+  return out;
+}
+
+// Every manifest format the engine reads, by file name.
+export function extractDeps(file: string, text: string): DepFact[] {
+  const b = base(file);
+  if (b === 'package.json') return jsonDeps('npm', file, text, ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']);
+  if (b === 'composer.json') return jsonDeps('composer', file, text, ['require', 'require-dev']);
+  if (/^requirements.*\.(txt|in)$/.test(b) || /(^|\/)requirements\/[^/]+\.(txt|in)$/.test(file)) return requirementsTxt(file, text);
+  if (b === 'pyproject.toml') return pyproject(file, text);
+  if (b === 'Pipfile') return sectionKeyValues('pypi', file, text, (s) => s === 'packages' || s === 'dev-packages', pyName);
+  if (b === 'setup.py') return regexLines('pypi', file, text, /^\s*['"]([A-Za-z][A-Za-z0-9_.-]*)(?:\[[^\]]*\])?\s*((?:[<>=!~]=?)[^'"]*)?['"],?\s*$/, (m) => pyName(m[1]), (m) => m[2] ?? null);
+  if (b === 'go.mod') return goMod(file, text);
+  if (b === 'Cargo.toml') return sectionKeyValues('cargo', file, text, (s) => /(^|\.)(dev-|build-)?dependencies$/.test(s), (s) => s);
+  if (b === 'Gemfile') return regexLines('rubygems', file, text, /^\s*gem\s+['"]([^'"]+)['"](?:\s*,\s*['"]([^'"]+)['"])?/, (m) => m[1], (m) => m[2] ?? null);
+  if (b === 'pom.xml') return pomXml(file, text);
+  if (b === 'build.gradle' || b === 'build.gradle.kts') {
+    return regexLines('maven', file, text, /\b(?:implementation|api|compileOnly|runtimeOnly|testImplementation|testRuntimeOnly|androidTestImplementation|kapt|ksp|annotationProcessor|classpath|compile)\s*\(?\s*(?:platform\s*\(\s*)?['"]([^'":\s]+):([^'":\s]+)(?::([^'"\s]+))?['"]/, (m) => `${m[1]}:${m[2]}`, (m) => m[3] ?? null);
+  }
+  if (b === 'pubspec.yaml') return pubspec(file, text);
+  if (/\.(cs|fs|vb)proj$/.test(b)) return regexLines('nuget', file, text, /<PackageReference\s+Include="([^"]+)"(?:\s+Version="([^"]+)")?/i, (m) => m[1], (m) => m[2] ?? null);
+  if (b === 'packages.config') return regexLines('nuget', file, text, /<package\s+id="([^"]+)"\s+version="([^"]+)"/i, (m) => m[1], (m) => m[2]);
+  if (b === 'Package.swift') {
+    return regexLines('swiftpm', file, text, /\.package\s*\([^)]*?url:\s*"(?:https?:\/\/|git@)?([^"]+?)(?:\.git)?"(?:[^)]*?(?:from|exact):\s*"([^"]+)")?/, (m) => m[1].replace(':', '/').toLowerCase(), (m) => m[2] ?? null);
+  }
+  if (b === 'Podfile') return regexLines('cocoapods', file, text, /^\s*pod\s+['"]([^'"]+)['"](?:\s*,\s*['"]([^'"]+)['"])?/, (m) => m[1], (m) => m[2] ?? null);
+  if (b === 'mix.exs') return regexLines('hex', file, text, /\{\s*:([a-z0-9_]+)\s*,\s*"([^"]+)"/, (m) => m[1], (m) => m[2]);
+  if (b.endsWith('.tf')) return terraform(file, text);
+  return [];
+}
+
+export const MANIFEST_NAMES = /(^|\/)(package\.json|composer\.json|requirements[^/]*\.(txt|in)|requirements\/[^/]+\.(txt|in)|pyproject\.toml|Pipfile|setup\.py|go\.mod|Cargo\.toml|Gemfile|pom\.xml|build\.gradle(\.kts)?|pubspec\.yaml|[^/]+\.(cs|fs|vb)proj|packages\.config|Package\.swift|Podfile|mix\.exs|[^/]+\.tf)$/;
+
+// Import scan. Language key by extension, the line patterns, and the separator used for prefix matching in rules.
+interface ImportLang { exts: string[]; res: RegExp[]; block?: { start: RegExp; end: RegExp; item: RegExp } }
+export const IMPORT_LANGS: Record<string, ImportLang & { sep: string }> = {
+  js: { exts: ['js', 'jsx', 'mjs', 'cjs', 'ts', 'tsx', 'mts', 'cts', 'vue', 'svelte', 'astro'], sep: '/',
+    res: [/(?:\bfrom\s*|\bimport\s*\(\s*|\bimport\s+|\brequire\s*\(\s*)['"]([^'"\s]+)['"]/g] },
+  python: { exts: ['py'], sep: '.', res: [/^\s*import\s+([A-Za-z_][\w.]*)/g, /^\s*from\s+([A-Za-z_][\w.]*)\s+import\b/g] },
+  go: { exts: ['go'], sep: '/', res: [/^\s*import\s+(?:[\w.]+\s+)?"([^"]+)"/g],
+    block: { start: /^\s*import\s*\(\s*$/, end: /^\s*\)/, item: /^\s*(?:[\w.]+\s+)?"([^"]+)"/ } },
+  ruby: { exts: ['rb'], sep: '/', res: [/^\s*require\s+['"]([^'"]+)['"]/g] },
+  php: { exts: ['php'], sep: '\\', res: [/^\s*use\s+\\?([A-Za-z_][\w\\]*)/g] },
+  jvm: { exts: ['java', 'kt', 'scala', 'groovy'], sep: '.', res: [/^\s*import\s+(?:static\s+)?([\w.]+)/g] },
+  swift: { exts: ['swift'], sep: '.', res: [/^\s*(?:@testable\s+)?import\s+(?:(?:class|struct|enum|protocol|func|var|typealias)\s+)?(\w+)/g] },
+  dart: { exts: ['dart'], sep: '/', res: [/^\s*import\s+['"](?:package:)?((?:dart:)?[^'"]+)['"]/g] },
+  csharp: { exts: ['cs'], sep: '.', res: [/^\s*(?:global\s+)?using\s+(?:static\s+)?([A-Z][\w.]*)\s*;/g] },
+  rust: { exts: ['rs'], sep: '::', res: [/^\s*(?:pub\s+)?use\s+([a-z_]\w*)::/g, /^\s*extern\s+crate\s+(\w+)/g] },
+};
+const LANG_BY_EXT = new Map<string, string>();
+for (const [k, v] of Object.entries(IMPORT_LANGS)) for (const e of v.exts) LANG_BY_EXT.set(e, k);
+
+export const importLangOf = (file: string): string | null => {
+  const b = base(file);
+  const dot = b.lastIndexOf('.');
+  return dot > 0 ? LANG_BY_EXT.get(b.slice(dot + 1).toLowerCase()) ?? null : null;
+};
+
+// First line per module per file. Relative and alias imports (".", "/", "~", "@/", "#") are dropped.
+export function extractImports(file: string, text: string): ImportFact[] {
+  const lang = importLangOf(file);
+  if (!lang) return [];
+  const spec = IMPORT_LANGS[lang];
+  const seen = new Map<string, number>();
+  let inBlock = false;
+  eachLine(text, (l, n) => {
+    const found: string[] = [];
+    if (spec.block) {
+      if (!inBlock && spec.block.start.test(l)) { inBlock = true; return; }
+      if (inBlock) {
+        if (spec.block.end.test(l)) { inBlock = false; return; }
+        const m = spec.block.item.exec(l);
+        if (m) found.push(m[1]);
+      }
+    }
+    for (const re of spec.res) for (const m of l.matchAll(re)) found.push(m[1]);
+    for (const mod of found) {
+      if (lang === 'js' && /^(\.|\/|~|@\/|#)/.test(mod)) continue;
+      if (!seen.has(mod)) seen.set(mod, n);
+    }
+  });
+  return [...seen].map(([module, line]) => ({ lang, module, file, line }));
+}
+
+// Does a fact name match a rule pattern? Exact, or a prefix on the separator, or "prefix*".
+export function nameMatches(name: string, pattern: string, sep: string): boolean {
+  if (pattern.endsWith('*')) return name.startsWith(pattern.slice(0, -1));
+  return name === pattern || (sep !== '' && name.startsWith(pattern + sep));
+}

package/src/discover/git.ts

@@ -0,0 +1,31 @@
+// Reads the HEAD commit from the .git folder without running git.
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+const SHA = /^[0-9a-f]{40}$/;
+const read = (p: string): string | null => { try { return readFileSync(p, 'utf8'); } catch { return null; } };
+
+export function readHeadCommit(root: string): string | null {
+  let gitDir = join(root, '.git');
+  if (!existsSync(gitDir)) return null;
+  if (statSync(gitDir).isFile()) {
+    const m = /^gitdir:\s*(.+)$/m.exec(read(gitDir) ?? '');
+    if (!m) return null;
+    gitDir = resolve(root, m[1].trim());
+  }
+  const head = (read(join(gitDir, 'HEAD')) ?? '').trim();
+  if (SHA.test(head)) return head;
+  const ref = /^ref:\s*(\S+)$/.exec(head)?.[1];
+  if (!ref) return null;
+  const common = read(join(gitDir, 'commondir'));
+  const dirs = [gitDir, ...(common ? [resolve(gitDir, common.trim())] : [])];
+  for (const d of dirs) {
+    const loose = (read(join(d, ref)) ?? '').trim();
+    if (SHA.test(loose)) return loose;
+    for (const line of (read(join(d, 'packed-refs')) ?? '').split('\n')) {
+      const [sha, name] = line.trim().split(' ');
+      if (name === ref && SHA.test(sha)) return sha;
+    }
+  }
+  return null;
+}

package/src/discover/kit-files.ts

@@ -0,0 +1,37 @@
+// Files of the Hullproof kit that were copied into the scanned project and are still byte for byte what the kit says.
+// They hold planted samples on purpose (the kit's own test files, hook self tests), so scanning them reports the kit's samples as findings in the
+// user's project. The list comes from the manifest of the kit the run was given (--kit), never from a manifest inside the scanned project, because a
+// project could name its own files in a manifest of its own and hide them from the scan. A file that differs by one byte is not skipped.
+import { createHash } from 'node:crypto';
+import { lstatSync, readFileSync, realpathSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+
+const MANIFEST_REL = 'docs/hullproof/.kit-manifest';
+const LINE = /^([0-9a-f]{64})  (\S.*)$/;
+
+export function kitOwnedFiles(repo: string, kitDir: string | null): Set<string> {
+  const out = new Set<string>();
+  if (!kitDir) return out;
+  let manifest: string;
+  try { manifest = readFileSync(join(kitDir, MANIFEST_REL), 'utf8'); } catch { return out; }
+  // A kit folder inside the scanned project is the project's own content, so its manifest is not a trusted list.
+  try {
+    const rel = relative(realpathSync(resolve(repo)), realpathSync(resolve(kitDir)));
+    if (rel === '' || (!rel.startsWith('..') && !rel.startsWith(sep) && rel.split(sep)[0] !== '..')) return out;
+  } catch { return out; }
+  for (const line of manifest.split('\n')) {
+    const m = LINE.exec(line);
+    if (!m || m[2].includes('..') || m[2].startsWith('/')) continue;
+    const f = join(repo, m[2]);
+    try {
+      const st = lstatSync(f);
+      if (!st.isFile()) continue;
+      if (createHash('sha256').update(readFileSync(f)).digest('hex') === m[1]) out.add(m[2]);
+    } catch { /* not in the project */ }
+  }
+  return out;
+}
+
+// The folders that hold the skipped kit files, collapsed to three levels, for the list of what discovery left out.
+export const kitFolders = (files: Iterable<string>): string[] =>
+  [...new Set([...files].map((f) => dirname(f).split('/').slice(0, 3).join('/') + '/'))].sort();

package/src/discover/walk.ts

@@ -0,0 +1,88 @@
+// File listing for discovery. Reads the folder tree directly and applies .gitignore files itself, so discovery never runs
+// git (a repository's git config can make git run code). Dependency, build output and tool folders are skipped and reported.
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import type { Skipped } from '../types/stack.ts';
+import { cmp, globBody } from '../util.ts';
+import { kitFolders } from './kit-files.ts';
+
+const SKIP_DIRS: Record<string, Skipped['reason']> = {
+  node_modules: 'dependency folder', bower_components: 'dependency folder', jspm_packages: 'dependency folder',
+  vendor: 'dependency folder', '.venv': 'dependency folder', venv: 'dependency folder', Pods: 'dependency folder',
+  Carthage: 'dependency folder', '.bundle': 'dependency folder', '.pnpm-store': 'dependency folder', '.yarn': 'dependency folder',
+  dist: 'build output', build: 'build output', out: 'build output', '.next': 'build output', '.nuxt': 'build output',
+  '.svelte-kit': 'build output', '.output': 'build output', '.vercel': 'build output', '.netlify': 'build output',
+  target: 'build output', '.gradle': 'build output', DerivedData: 'build output', coverage: 'build output',
+  '__pycache__': 'build output', '.pytest_cache': 'build output', '.mypy_cache': 'build output', '.tox': 'build output',
+  '.dart_tool': 'build output', '.expo': 'build output', '.turbo': 'build output', '.cache': 'build output',
+  '.parcel-cache': 'build output', '.terraform': 'build output', '.serverless': 'build output', '.aws-sam': 'build output',
+  'cdk.out': 'build output',
+  '.git': 'tool folder', '.hg': 'tool folder', '.svn': 'tool folder', '.hullproof': 'tool folder', '.idea': 'tool folder',
+};
+
+interface IgnoreRule { base: string; re: RegExp; negate: boolean; dirOnly: boolean }
+
+export function parseGitignore(text: string, base: string): IgnoreRule[] {
+  const rules: IgnoreRule[] = [];
+  for (const raw of text.split(/\r?\n/)) {
+    let p = raw.replace(/(?<!\\)\s+$/, '');
+    if (!p || p.startsWith('#')) continue;
+    const negate = p.startsWith('!');
+    if (negate) p = p.slice(1);
+    if (p.startsWith('\\')) p = p.slice(1);
+    const dirOnly = p.endsWith('/');
+    if (dirOnly) p = p.slice(0, -1);
+    if (!p) continue;
+    const anchored = p.includes('/');
+    if (p.startsWith('/')) p = p.slice(1);
+    const body = globBody(p); // ponytail: also reads {a,b} as alternation, which gitignore does not; rare in practice
+    rules.push({ base, negate, dirOnly, re: new RegExp(anchored ? `^${body}$` : `^(?:.*/)?${body}$`) });
+  }
+  return rules;
+}
+
+function ignored(rel: string, isDir: boolean, rules: IgnoreRule[]): boolean {
+  let out = false;
+  for (const r of rules) {
+    if (r.dirOnly && !isDir) continue;
+    let sub: string;
+    if (!r.base) sub = rel;
+    else if (rel.startsWith(r.base + '/')) sub = rel.slice(r.base.length + 1);
+    else continue;
+    if (r.re.test(sub)) out = !r.negate;
+  }
+  return out;
+}
+
+export interface WalkResult { files: string[]; skipped: Skipped[]; capReached: boolean }
+
+export function walk(root: string, maxFiles: number, skipFiles?: ReadonlySet<string>): WalkResult {
+  const files: string[] = [];
+  const skipped: Skipped[] = [];
+  let capReached = false;
+  const absRoot = resolve(root);
+
+  const visit = (dirRel: string, inherited: IgnoreRule[]): void => {
+    const abs = dirRel ? join(absRoot, dirRel) : absRoot;
+    let rules = inherited;
+    try { rules = inherited.concat(parseGitignore(readFileSync(join(abs, '.gitignore'), 'utf8'), dirRel)); } catch { /* no .gitignore here */ }
+    const entries = readdirSync(abs, { withFileTypes: true }).sort((a, b) => cmp(a.name, b.name));
+    for (const e of entries) {
+      if (capReached) return;
+      const rel = dirRel ? `${dirRel}/${e.name}` : e.name;
+      if (e.isSymbolicLink()) { skipped.push({ path: rel, reason: 'symlink' }); continue; }
+      const isDir = e.isDirectory();
+      if (!isDir && !e.isFile()) continue;
+      if (isDir && SKIP_DIRS[e.name]) { skipped.push({ path: rel + '/', reason: SKIP_DIRS[e.name] }); continue; }
+      if (ignored(rel, isDir, rules)) { skipped.push({ path: isDir ? rel + '/' : rel, reason: 'gitignore' }); continue; }
+      if (isDir) visit(rel, rules);
+      else if (skipFiles?.has(rel)) continue;
+      else if (files.length >= maxFiles) capReached = true;
+      else files.push(rel);
+    }
+  };
+  if (!statSync(absRoot).isDirectory()) throw new Error(`not a folder: ${root}`);
+  visit('', []);
+  if (skipFiles?.size) for (const d of kitFolders(skipFiles)) skipped.push({ path: d, reason: 'unchanged kit files' });
+  return { files, skipped, capReached };
+}

package/src/env.ts

@@ -0,0 +1,51 @@
+// Reads provider settings from a .env.local file without any dependency. Real environment variables always win. Only the names
+// in HUNT_ENV_NAMES are read, and no value is ever logged or returned in a message: callers get the names that came from a file.
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const HUNT_ENV_NAMES = [
+  'HULLPROOF_PROVIDER', 'HULLPROOF_MODEL', 'ANTHROPIC_API_KEY', 'OPENAI_API_KEY', 'GEMINI_API_KEY',
+  'HULLPROOF_OPENAI_COMPAT_BASE_URL', 'HULLPROOF_OPENAI_COMPAT_KEY',
+] as const;
+const ALLOWED = new Set<string>(HUNT_ENV_NAMES);
+const ENGINE_ROOT = fileURLToPath(new URL('../', import.meta.url));
+const MAX_BYTES = 64 * 1024;
+
+// Parses KEY=VALUE lines: blank lines and # comments skipped, an optional "export " prefix, matching quotes removed.
+export function parseEnvText(text: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) continue;
+    const m = /^(?:export\s+)?([A-Z][A-Z0-9_]*)\s*=\s*(.*)$/.exec(line);
+    if (!m || !ALLOWED.has(m[1])) continue;
+    let v = m[2].trim();
+    const q = v[0] === '"' || v[0] === "'" ? v.indexOf(v[0], 1) : -1;
+    if (q > 0) v = v.slice(1, q);
+    else v = v.replace(/\s+#.*$/, '');
+    if (v) out[m[1]] = v;
+  }
+  return out;
+}
+
+// The scanned repository's .env.local first, then the engine's. A name already set (and not empty) in `base` is never replaced.
+export function loadHuntEnv(repo: string | null, base: NodeJS.ProcessEnv = process.env, engineRoot: string = ENGINE_ROOT): { env: Record<string, string | undefined>; fromFile: string[] } {
+  const env: Record<string, string | undefined> = { ...base };
+  const fromFile: string[] = [];
+  // CI sets this: the scanned repository is untrusted there, so a .env.local inside it must not supply a provider address or key.
+  if (base.HULLPROOF_NO_ENV_FILE === '1') return { env, fromFile };
+  const roots = [...(repo ? [resolve(repo)] : []), resolve(engineRoot)];
+  for (const root of roots) {
+    const p = join(root, '.env.local');
+    try {
+      if (!existsSync(p) || statSync(p).size > MAX_BYTES) continue;
+      for (const [k, v] of Object.entries(parseEnvText(readFileSync(p, 'utf8')))) {
+        if (env[k]) continue;
+        env[k] = v;
+        fromFile.push(k);
+      }
+    } catch { /* an unreadable file is the same as no file */ }
+  }
+  return { env, fromFile: [...new Set(fromFile)].sort() };
+}

package/src/gate/gate.ts

@@ -0,0 +1,169 @@
+// The release gate of STANDARD.md (G-1 to G-8 and the three outcomes), on top of the kit's own checklist gate.
+// The checklist part (G-3 to G-5 on the results rows) and the record cross checks are the kit's functions from
+// tools/hullproof/ci/hullproof-gate.mjs, imported, not copied. This file adds what the kit gate leaves out: G-1, G-2,
+// G-6, G-7, G-8, written risk acceptance within the kit's limits, and the verdict.
+// It blocks only on FAIL rows (from FAIL checks and mapped rule hits, never unmapped observations) and on requirements
+// nothing settled, exactly as the kit gate counts them.
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { cmp } from '../util.ts';
+import type { FindingsFile, ResultRow, Severity, ToolMeta } from '../types/index.ts';
+import { GATE_REL, inScope, SEV_RANK, VALIDATOR_REL, type Control, type Scope } from '../report/kit.ts';
+
+export interface KitGate {
+  evaluate(controls: unknown[], rows: string[][], scope: string): { counts: Record<string, number>; ok: boolean };
+  collapseRows(rows: string[][]): { got: Map<string, { state: string; raw: string; note: string }>; duplicates: number };
+  crossChecks(controlMap: Map<string, unknown>, got: Map<string, unknown>, findings: unknown): { problems: string[] };
+  isStaticPass(raw: string): boolean;
+  validateFindingsText(text: string, o: { controls: Map<string, unknown> }): { c: { errorCount: number; lines(): string[] }; data: FindingsFile | null };
+}
+
+export async function loadKitGate(kitDir: string): Promise<KitGate> {
+  const g = await import(pathToFileURL(join(kitDir, GATE_REL)).href);
+  const v = await import(pathToFileURL(join(kitDir, VALIDATOR_REL)).href);
+  return { evaluate: g.evaluate, collapseRows: g.collapseRows, crossChecks: g.crossChecks, isStaticPass: g.isStaticPass, validateFindingsText: v.validateFindingsText };
+}
+
+// What the owner supplies for the conditions no file in the repository can settle. Paths are relative to the repository.
+export interface OwnerFile {
+  audit_report?: string;        // G-2: an audit report in the AUDIT-REPORT format that names this commit
+  rollback?: string;            // G-8: where the rollback path for this release is written down
+  results?: OwnerRow[];         // rows settled with owner evidence (exports, staging tests); never overrides an engine FAIL
+  acceptances?: Acceptance[];   // written risk acceptance, within the limits of STANDARD.md
+}
+// An owner row may say PASS, which the engine never writes: the owner holds the runtime evidence.
+export type OwnerRow = Omit<ResultRow, 'result'> & { result: ResultRow['result'] | 'PASS' };
+export interface Acceptance { id: string; owner: string; approver: string; compensating_control: string; effective: string; expires: string }
+
+export interface GateInput {
+  kitGate: KitGate; controls: Control[]; scope: Scope; rows: ResultRow[]; findingsText: string; metas: ToolMeta[];
+  owner: OwnerFile | null; repo: string; commit: string; today: string;
+}
+
+export type Verdict = 'NOT READY' | 'READY WITH ACCEPTED RISK' | 'READY';
+export interface Condition { id: string; met: boolean; why: string }
+export interface GateOutcome {
+  verdict: Verdict; label: string; exit: 0 | 1 | 2; problems: string[]; conditions: Condition[];
+  counts: Record<string, number>; open: { id: string; severity: Severity; state: string; accepted: boolean }[];
+  acceptancesUsed: string[]; acceptanceProblems: string[]; runSupportsReady: boolean; checklistLine: string;
+}
+
+// Hullproof policy (STANDARD.md, Protected classes): no acceptance for credentials and secrets, authentication,
+// tenant isolation or payments. The class is read from the control's domains; authorization counts as tenant isolation.
+const PROTECTED = new Set(['secrets', 'auth', 'authorization', 'tenancy', 'payments']);
+const DAY = 86_400_000;
+const days = (a: string, b: string): number => Math.round((Date.parse(b) - Date.parse(a)) / DAY);
+const isDate = (s: unknown): s is string => typeof s === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(s) && !Number.isNaN(Date.parse(s));
+
+function currentAcceptances(list: Acceptance[], byId: Map<string, Control>, today: string): { ok: Map<string, Acceptance>; problems: string[] } {
+  const ok = new Map<string, Acceptance>();
+  const problems: string[] = [];
+  let critical = 0;
+  for (const a of [...list].sort((x, y) => cmp(x.id, y.id))) {
+    const c = byId.get(a.id);
+    const bad = (why: string): void => { problems.push(`${a.id}: acceptance not current (${why})`); };
+    if (!c) { bad('not a requirement in scope'); continue; }
+    if (c.severity === 'BLOCKER') { bad('a BLOCKER is never accepted'); continue; }
+    if (c.severity !== 'CRITICAL' && c.severity !== 'HIGH') { bad('only CRITICAL and HIGH need acceptance'); continue; }
+    if (c.domains.some((d) => PROTECTED.has(d))) { bad('protected class: secrets, authentication, tenant isolation or payments'); continue; }
+    if (![a.owner, a.approver, a.compensating_control].every((s) => typeof s === 'string' && s.trim())) { bad('owner, approver and compensating control are all needed'); continue; }
+    if (a.owner.trim().toLowerCase() === a.approver.trim().toLowerCase()) { bad('the approver must not be the risk owner'); continue; }
+    if (!isDate(a.effective) || !isDate(a.expires)) { bad('effective and expires must be YYYY-MM-DD dates'); continue; }
+    const limit = c.severity === 'CRITICAL' ? 90 : 180;
+    if (days(a.effective, a.expires) > limit) { bad(`lasts more than ${limit} days`); continue; }
+    if (a.effective > today || a.expires < today) { bad(a.expires < today ? 'expired' : 'not in effect yet'); continue; }
+    if (c.severity === 'CRITICAL' && ++critical > 3) { bad('more than 3 CRITICAL acceptances for one release'); continue; }
+    ok.set(a.id, a);
+  }
+  return { ok, problems };
+}
+
+const isGated = (c: Control): boolean => c.severity === 'BLOCKER' || c.severity === 'CRITICAL';
+
+export function evaluateGate(g: GateInput): GateOutcome {
+  const scoped = g.controls.filter((c) => inScope(c, g.scope));
+  const byId = new Map(scoped.map((c) => [c.id, c]));
+  const problems: string[] = [];
+
+  // Rows: the engine's, then the owner's for anything the engine did not FAIL.
+  const engine = new Map<string, OwnerRow>(g.rows.map((r) => [r.id, r]));
+  for (const r of g.owner?.results ?? []) {
+    if (engine.get(r.id)?.result === 'FAIL') continue;
+    engine.set(r.id, r);
+  }
+  const rows = [...engine.values()].sort((a, b) => cmp(a.id, b.id)).map((r) => [r.id, r.result, r.notes]);
+
+  // The kit's checklist gate on the in scope controls; scope 'all' because the stage filter is already applied.
+  const { counts, ok } = g.kitGate.evaluate(scoped, rows, 'all');
+  const checklistLine = `hullproof checklist (${g.scope.edition}, ${g.scope.stage}): checked ${counts.checked}, pass ${counts.pass}, not applicable ${counts.notApplicable}, fail ${counts.fail}, not assessed ${counts.notAssessed} (missing rows ${counts.missing}, PASS (static) rejected ${counts.passStaticRejected}, NOT APPLICABLE without a reason ${counts.naWithoutReason}), duplicate rows ${counts.duplicates}, unknown ids ${counts.unknownIds}`;
+
+  // The findings record: validated by the kit, then cross checked against the rows by the kit.
+  // Validation and cross checks see every known requirement: an observation may name one outside this run's scope.
+  const all = new Map<string, unknown>(g.controls.map((c) => [c.id, c]));
+  const v = g.kitGate.validateFindingsText(g.findingsText, { controls: all });
+  if (v.c.errorCount) problems.push(...v.c.lines().map((l) => `findings ${l}`));
+  const findings = v.data;
+  const { got } = g.kitGate.collapseRows(rows);
+  if (findings && !v.c.errorCount) problems.push(...g.kitGate.crossChecks(all, got, findings).problems);
+  const runSupportsReady = !!findings && findings.report.run_status === 'complete' && findings.report.scope === 'full' && findings.report.profile !== 'quick';
+
+  // Open gated items, the same way the kit's evaluate counts them.
+  const open: GateOutcome['open'] = [];
+  for (const c of scoped.filter(isGated)) {
+    const r = got.get(c.id);
+    const settled = r !== undefined && (
+      (r.state === 'PASS' && !(g.kitGate.isStaticPass(r.raw) && c.authority !== 'repo')) || (r.state === 'NOT APPLICABLE' && r.note !== ''));
+    if (!settled) open.push({ id: c.id, severity: c.severity, state: r?.raw ?? 'missing row', accepted: false });
+  }
+  if ((open.length === 0) !== ok) problems.push('internal: the open item list does not agree with the kit gate');
+
+  const acc = currentAcceptances(g.owner?.acceptances ?? [], byId, g.today);
+  for (const o of open) if (o.severity === 'CRITICAL' && acc.ok.has(o.id)) o.accepted = true;
+  const highFails = (findings?.records ?? []).filter((r) => r.kind === 'fail' && r.severity === 'HIGH')
+    .flatMap((r) => (r.kind === 'fail' ? r.sec_ids : [])).filter((id) => byId.get(id)?.severity === 'HIGH');
+  const highOpen = [...new Set(highFails)].filter((id) => !acc.ok.has(id)).sort(cmp);
+  const used = [...new Set([...open.filter((o) => o.accepted).map((o) => o.id), ...highFails.filter((id) => acc.ok.has(id))])].sort(cmp);
+
+  const stagePath = join(g.repo, 'docs/security/STAGE.md');
+  const inRepo = (p: string | undefined): string | null => { if (!p) return null; const abs = resolve(g.repo, p); return abs.startsWith(resolve(g.repo)) && existsSync(abs) ? abs : null; };
+  const report = inRepo(g.owner?.audit_report);
+  const rollback = inRepo(g.owner?.rollback);
+  const ranOk = (t: string): boolean => g.metas.some((m) => m.tool === t && m.status === 'ran' && m.files_scanned !== 0);
+  const g7missing = ['gitleaks', 'semgrep', 'osv-scanner'].filter((t) => !ranOk(t));
+  const blockerOpen = open.filter((o) => o.severity === 'BLOCKER');
+  const blockerFail = blockerOpen.filter((o) => o.state.toUpperCase().startsWith('FAIL'));
+  const criticalOpen = open.filter((o) => o.severity === 'CRITICAL' && !o.accepted);
+
+  const conditions: Condition[] = [
+    { id: 'G-1', met: existsSync(stagePath) && g.scope.stageSource === 'STAGE.md', why: existsSync(stagePath) ? (g.scope.stageSource === 'STAGE.md' ? `stage ${g.scope.stage} recorded in docs/security/STAGE.md` : 'docs/security/STAGE.md names no stage') : 'docs/security/STAGE.md is missing' },
+    { id: 'G-2', met: !!report && readFileSync(report, 'utf8').includes(g.commit), why: report ? (readFileSync(report, 'utf8').includes(g.commit) ? 'audit report names this commit' : 'the audit report does not name this commit') : 'no audit report supplied (owner file, audit_report)' },
+    { id: 'G-3', met: blockerFail.length === 0, why: blockerFail.length ? `${blockerFail.length} BLOCKER requirement(s) FAIL` : 'no BLOCKER requirement FAILs' },
+    { id: 'G-4', met: blockerOpen.length === 0, why: blockerOpen.length ? `${blockerOpen.length} BLOCKER requirement(s) open (FAIL or NOT ASSESSED)` : 'every BLOCKER requirement is settled' },
+    { id: 'G-5', met: criticalOpen.length === 0, why: criticalOpen.length ? `${criticalOpen.length} CRITICAL requirement(s) open and not under a current acceptance` : 'every CRITICAL requirement is settled or accepted' },
+    g.scope.edition === 'free'
+      ? { id: 'G-6', met: true, why: 'outside the free scope' }
+      : { id: 'G-6', met: highOpen.length === 0, why: highOpen.length ? `${highOpen.length} HIGH requirement(s) with a fail record and no current acceptance` : 'no open HIGH finding' },
+    { id: 'G-7', met: g7missing.length === 0, why: g7missing.length ? `did not run on this commit: ${g7missing.join(', ')}` : 'gitleaks, semgrep and osv-scanner ran on this commit' },
+    { id: 'G-8', met: !!rollback, why: rollback ? 'rollback path supplied' : 'no rollback path supplied (owner file, rollback)' },
+  ];
+
+  const allMet = conditions.every((c) => c.met) && runSupportsReady;
+  const verdict: Verdict = !allMet ? 'NOT READY' : used.length ? 'READY WITH ACCEPTED RISK' : 'READY';
+  const label = verdict !== 'NOT READY' && g.scope.edition === 'free' ? `${verdict} (FREE SCOPE)` : verdict;
+  return {
+    verdict, label, exit: problems.length ? 2 : verdict === 'NOT READY' ? 1 : 0, problems, conditions, counts,
+    open: open.sort((a, b) => SEV_RANK[b.severity] - SEV_RANK[a.severity] || cmp(a.id, b.id)), acceptancesUsed: used, acceptanceProblems: acc.problems,
+    runSupportsReady, checklistLine,
+  };
+}
+
+export function gateLines(o: GateOutcome): string[] {
+  const lines = [o.checklistLine];
+  for (const c of o.conditions) lines.push(`${c.id}: ${c.met ? 'met' : 'not met'}, ${c.why}`);
+  if (!o.runSupportsReady) lines.push('note: this run cannot support READY (the findings record says the run is incomplete, partial or quick)');
+  for (const p of o.acceptanceProblems) lines.push(`note: ${p}`);
+  if (o.problems.length) { lines.push('RESULT: stopped, the records or a cross check need attention (exit 2)'); return lines; }
+  lines.push(`RESULT: ${o.label}`);
+  return lines;
+}