stillhunter 0.0.1 → 0.2.1

package/dist/change.mjs

@@ -0,0 +1,217 @@
+// The change a hunt tests, printed whole by `start`: the diff of tracked files
+// against the base plus the content of untracked files, CSS and templates
+// included, so the hunter reads the same thing a reviewer would.
+import { spawnSync } from 'node:child_process';
+import { appendFileSync, closeSync, existsSync, lstatSync, openSync, readdirSync, readFileSync, readlinkSync, readSync, realpathSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { FOLDER, git, GIT_FLAGS, secretFile } from './common.mjs';
+export const CHANGE_CAP = 60 * 1024;
+const UNTRACKED_READ_LIMIT = CHANGE_CAP + 1;
+// diff --file prints a file whole, up to this.
+export const FILE_CAP = 1024 * 1024;
+export const SECRET_BODY = '(left out: a secret file, such as .env or a key, which the hunter does not read)\n';
+function diffSections(root, base) {
+    const r = spawnSync('git', [...GIT_FLAGS, 'diff', '--no-color', '--no-ext-diff', base, '--', '.', `:(exclude)${FOLDER}`], { cwd: root, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
+    if (r.status !== 0)
+        return [];
+    const sections = [];
+    for (const chunk of r.stdout.split(/^(?=diff --git )/m).filter((c) => c.startsWith('diff --git '))) {
+        const first = chunk.split('\n', 1)[0] ?? '';
+        const names = sectionNames(chunk);
+        const file = names.new ?? first;
+        // A section whose names cannot all be read, or that names a secret file on
+        // either side (a key renamed to notes.txt), keeps its header only.
+        const hidden = names.unread || names.all.some(secretFile);
+        sections.push({ file, header: first, body: hidden ? SECRET_BODY : chunk.slice(first.length + 1) });
+    }
+    return sections;
+}
+// git quotes a name holding a quote, a backslash or a control character, in C
+// style, even with core.quotePath off.
+const ESCAPES = { a: '\x07', b: '\b', t: '\t', n: '\n', v: '\v', f: '\f', r: '\r', '"': '"', '\\': '\\' };
+const unquote = (s) => s.replace(/\\([0-7]{3}|.)/g, (_, e) => (e.length === 3 ? String.fromCharCode(parseInt(e, 8)) : ESCAPES[e] ?? e));
+const QUOTED = '"((?:[^"\\\\]|\\\\.)*)"';
+// Every path a diff section's header lines name: the new side, the old side,
+// and a rename's or copy's source and destination.
+export function sectionNames(chunk) {
+    const head = chunk.split('\n');
+    const end = head.findIndex((l) => l.startsWith('@@'));
+    const lines = end === -1 ? head : head.slice(0, end);
+    const all = [];
+    let unread = false;
+    let newName = null;
+    const take = (quoted, plain) => {
+        const name = quoted !== undefined ? unquote(quoted) : plain;
+        if (name === undefined)
+            unread = true;
+        else
+            all.push(name);
+        return name ?? null;
+    };
+    for (const line of lines) {
+        let m;
+        if ((m = new RegExp(`^diff --git .* (?:${QUOTED.replace('"(', '"b/(')}|b/(.+))$`).exec(line)))
+            newName = take(m[1], m[2]);
+        else if (line.startsWith('diff --git '))
+            unread = true;
+        else if ((m = new RegExp(`^(?:---|\\+\\+\\+) (?:${QUOTED.replace('"(', '"[ab]/(')}|[ab]/(.*?))\t?$`).exec(line)))
+            take(m[1], m[2]);
+        else if ((m = new RegExp(`^(?:rename|copy) (?:from|to) (?:${QUOTED}|(.+))$`).exec(line)))
+            take(m[1], m[2]);
+    }
+    return { new: newName, all, unread };
+}
+function readHead(file, limit) {
+    const fd = openSync(file, 'r');
+    try {
+        const buf = Buffer.alloc(limit);
+        const n = readSync(fd, buf, 0, limit, 0);
+        return buf.subarray(0, n);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function untrackedSection(root, file) {
+    const header = `=== untracked file: ${file} ===`;
+    if (secretFile(file))
+        return { file, header, body: SECRET_BODY };
+    const full = path.join(root, file);
+    let size = 0;
+    try {
+        // A link is shown as a link: its target may be outside the repository.
+        const st = lstatSync(full);
+        if (st.isSymbolicLink())
+            return { file, header, body: `(symbolic link to ${readlinkSync(full)})\n` };
+        size = st.size;
+    }
+    catch {
+        return { file, header, body: '(could not be read)\n' };
+    }
+    const head = readHead(full, Math.min(size, UNTRACKED_READ_LIMIT));
+    if (head.subarray(0, 8000).includes(0))
+        return { file, header, body: `(binary file, ${size} bytes)\n` };
+    // Too large to print whole: the cap cuts it anyway, so its size is what counts.
+    const body = size > UNTRACKED_READ_LIMIT ? 'x'.repeat(UNTRACKED_READ_LIMIT) : head.toString('utf8');
+    return { file, header, body: body.endsWith('\n') ? body : `${body}\n` };
+}
+// The commit the change is measured from: where HEAD left the main branch.
+export function baseRef(root) {
+    for (const ref of ['origin/main', 'main', 'origin/master', 'master']) {
+        const mb = git(['merge-base', 'HEAD', ref], root);
+        if (mb)
+            return mb;
+    }
+    return 'HEAD';
+}
+export function collectChange(root, base) {
+    const files = (git(['diff', '--name-status', base, '--', '.', `:(exclude)${FOLDER}`], root) ?? '').split('\n').filter(Boolean);
+    const untracked = (git(['ls-files', '--others', '--exclude-standard'], root) ?? '').split('\n').filter((f) => f && !f.startsWith(`${FOLDER}/`));
+    const sections = [...diffSections(root, base), ...untracked.map((f) => untrackedSection(root, f))];
+    return { files: [...files, ...untracked.map((f) => `A (untracked)\t${f}`)], sections, empty: files.length === 0 && untracked.length === 0 };
+}
+const bytes = (s) => Buffer.byteLength(s, 'utf8');
+const kb = (n) => `${Math.max(1, Math.round(n / 1024))} KB`;
+// Fits the change under the cap by leaving out the bodies of the largest files
+// first. A file's header always stays, so no changed file goes unnamed.
+export function capSections(sections, cap = CHANGE_CAP) {
+    const total = sections.reduce((n, s) => n + bytes(s.header) + 1 + bytes(s.body), 0);
+    const kept = sections.map((s) => ({ ...s, size: bytes(s.body), cut: false }));
+    let size = total;
+    const byLargest = [...kept].sort((a, b) => b.size - a.size);
+    for (const s of byLargest) {
+        if (size <= cap)
+            break;
+        s.cut = true;
+        size -= s.size;
+    }
+    const cut = kept.filter((s) => s.cut).map((s) => ({ file: s.file, size: s.size }));
+    const text = kept.map((s) => (s.cut ? `${s.header}\n(left out: ${kb(s.size)}, see the note above)\n` : `${s.header}\n${s.body}`)).join('');
+    return { text, cut, total };
+}
+export function changeText(change, cap = CHANGE_CAP) {
+    if (change.sections.length === 0)
+        return ['(no change)'];
+    const { text, cut, total } = capSections(change.sections, cap);
+    const note = cut.length === 0 ? [] : [
+        `The change is ${kb(total)}; to fit ${kb(cap)} the bodies of the largest files were left out: ${cut.map((c) => `${c.file} (${kb(c.size)})`).join(', ')}.`,
+        'Read each with the runner\'s `diff --file <file>`.',
+    ];
+    return [...note, text.replace(/\n$/, '')];
+}
+// Run folders hold a signed-in session, so they must never be committed.
+export function ensureRunsIgnored(file) {
+    if (!existsSync(file)) {
+        writeFileSync(file, '/.env\n/.env.*\n/runs/\n');
+        return;
+    }
+    const text = readFileSync(file, 'utf8');
+    const rules = text.split(/\r?\n/).map((l) => l.trim());
+    if (rules.some((r) => ['/runs/', '/runs', 'runs/', 'runs', '/runs/*', 'runs/*', '/runs/**'].includes(r)))
+        return;
+    appendFileSync(file, `${text === '' || text.endsWith('\n') ? '' : '\n'}/runs/\n`);
+}
+export function readSpecs(root) {
+    const dir = path.join(root, FOLDER, 'specs');
+    if (!existsSync(dir))
+        return [];
+    const limit = 20 * 1024;
+    return readdirSync(dir).filter((f) => /\.(txt|md)$/.test(f)).sort().map((name) => {
+        const raw = readFileSync(path.join(dir, name), 'utf8');
+        return { file: `${FOLDER}/specs/${name}`, text: raw.length > limit ? `${raw.slice(0, limit)}\n(cut at 20 KB)` : raw };
+    });
+}
+// What `diff` lists with no file: every changed and untracked file, with the
+// size of what `diff --file` would print for it.
+export function changeList(change) {
+    if (change.sections.length === 0)
+        return ['(no change)'];
+    const status = new Map(change.files.map((l) => { const [s, ...rest] = l.split('\t'); return [rest.at(-1) ?? '', s ?? '']; }));
+    return change.sections.map((s) => `${(status.get(s.file) ?? '?').padEnd(13)} ${s.file} (${kb(bytes(s.header) + 1 + bytes(s.body))})`);
+}
+// One file's whole diff against the base, or its whole content when it is
+// untracked. Only a file the change holds, inside the repository and outside
+// the runner's own folder, is printed; anything else is read with the Read
+// tool, which the guard watches.
+export function fileDiff(root, base, file, cwd = process.cwd()) {
+    const outside = { ok: false, message: `${file} is outside the repository.` };
+    let real;
+    let realRoot;
+    try {
+        realRoot = realpathSync.native(root);
+        const full = path.resolve(cwd, file);
+        real = existsSync(full) ? realpathSync.native(full) : path.join(realpathSync.native(path.dirname(full)), path.basename(full));
+    }
+    catch {
+        return { ok: false, message: `${file} is not in the change.` };
+    }
+    const rel = path.relative(realRoot, real);
+    if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel))
+        return outside;
+    const posix = rel.split(path.sep).join('/');
+    if (posix.split('/').some((seg) => seg.toLowerCase() === FOLDER))
+        return { ok: false, message: `${FOLDER}/ is the runner's own folder; read its files with the Read tool.` };
+    if (secretFile(posix))
+        return { ok: false, message: `${posix} is a secret file (such as .env or a key), which the hunter does not read.` };
+    const changed = (git(['diff', '--name-only', base, '--', '.', `:(exclude)${FOLDER}`], root) ?? '').split('\n').filter(Boolean);
+    const untracked = (git(['ls-files', '--others', '--exclude-standard'], root) ?? '').split('\n').filter(Boolean);
+    if (changed.includes(posix)) {
+        const r = spawnSync('git', [...GIT_FLAGS, 'diff', '--no-color', '--no-ext-diff', base, '--', `:(literal)${posix}`], { cwd: root, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
+        return r.status === 0 ? { ok: true, text: capFile(r.stdout) } : { ok: false, message: `git diff failed for ${posix}: ${r.stderr.trim()}` };
+    }
+    if (untracked.includes(posix)) {
+        const header = `=== untracked file: ${posix} ===`;
+        const size = lstatSync(real).size;
+        const head = readHead(real, Math.min(size, FILE_CAP + 1));
+        if (head.subarray(0, 8000).includes(0))
+            return { ok: true, text: `${header}\n(binary file, ${size} bytes)\n` };
+        return { ok: true, text: `${header}\n${capFile(head.toString('utf8'), size)}` };
+    }
+    return { ok: false, message: `${posix} is not in the change. Run diff with no --file to list the changed files, or read it with the Read tool.` };
+}
+// Up to FILE_CAP of a file's diff or content, with a line saying what was cut.
+function capFile(text, size = bytes(text)) {
+    const body = size > FILE_CAP ? Buffer.from(text, 'utf8').subarray(0, FILE_CAP).toString('utf8') : text;
+    const ended = body.endsWith('\n') ? body : `${body}\n`;
+    return size > FILE_CAP ? `${ended}(cut at ${kb(FILE_CAP)} of ${kb(size)})\n` : ended;
+}

package/dist/common.mjs

@@ -0,0 +1,110 @@
+// What every runner command shares: the run folder, its context, the config,
+// the output block and the small helpers around git and the command line.
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { nuxtCandidates, proveLock } from './target.mjs';
+export const FOLDER = '.stillhunter';
+export const HUNT_ID = /^\d{8}-\d{6}-hunt-[a-z0-9]{4}$/;
+export const PROBE_NAME = /^[a-z0-9][a-z0-9-]{0,47}$/;
+export const START = '--- stillhunter (copy this block unchanged) ---';
+export const END = '--- end of stillhunter ---';
+export const SEVERITIES = ['high', 'medium', 'low'];
+export const runsDir = (root) => path.join(root, FOLDER, 'runs');
+export const testsDir = (root) => path.join(root, FOLDER, 'tests');
+// Paths come back as typed, not quoted with octal escapes, so a name that is
+// not ASCII (`café.pem`) is matched like any other.
+export const GIT_FLAGS = ['-c', 'core.quotePath=false'];
+export function git(args, cwd) {
+    const r = spawnSync('git', [...GIT_FLAGS, ...args], { cwd, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
+    return r.status === 0 ? r.stdout.trim() : null;
+}
+export function block(lines) {
+    return [START, ...lines, END].join('\n') + '\n';
+}
+export function fail(message) {
+    process.stdout.write(block(['stillhunter | stopped', message]));
+    process.exit(1);
+}
+export function readStdin() {
+    try {
+        return readFileSync(0, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+export function flag(args, name) {
+    const i = args.indexOf(name);
+    return i === -1 ? null : (args[i + 1] ?? null);
+}
+export function stamp(d = new Date()) {
+    const p = (n) => String(n).padStart(2, '0');
+    return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
+}
+export function repoRoot() {
+    const root = git(['rev-parse', '--show-toplevel'], process.cwd());
+    if (!root)
+        fail('Not inside a git repository.');
+    return root;
+}
+export function readConfig(root) {
+    const file = path.join(root, FOLDER, 'config.json');
+    if (!existsSync(file))
+        return {};
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch (e) {
+        fail(`${FOLDER}/config.json is not valid JSON: ${e.message}`);
+    }
+}
+export function loadRun(args) {
+    const root = repoRoot();
+    const id = flag(args, '--run');
+    if (!id || !HUNT_ID.test(id))
+        fail('Give the run id from `start` with --run.');
+    const dir = path.join(runsDir(root), id);
+    if (!existsSync(path.join(dir, 'context.json')))
+        fail(`No hunt run ${id}.`);
+    return { ctx: JSON.parse(readFileSync(path.join(dir, 'context.json'), 'utf8')), dir, root };
+}
+export const remaining = (ctx, now = Date.now()) => Math.max(0, Math.round((ctx.deadline - now) / 1000));
+export async function findTargetUrl(root, config) {
+    if (config.target?.url)
+        return config.target.url;
+    for (const candidate of nuxtCandidates(root)) {
+        const url = await proveLock(candidate);
+        if (url)
+            return url;
+    }
+    return null;
+}
+// A path the hunter never reads: the same rule as secretPath() in
+// hooks/guard.mjs (a test holds the two to the same answers), applied by the
+// runner to what it prints of the change.
+const SECRET_FOLDERS = new Set(['.ssh', '.aws', '.gnupg', '.git']);
+const SECRET_FILES = new Set(['.npmrc', '.netrc', '.pgpass', 'session.json']);
+export function secretFile(file) {
+    const segments = file.replace(/\\/g, '/').toLowerCase().split('/').filter(Boolean);
+    const name = segments.at(-1) ?? '';
+    if (segments.some((s) => SECRET_FOLDERS.has(s)) || SECRET_FILES.has(name) || name.startsWith('.env'))
+        return true;
+    return /\.(pem|key|p12|pfx)$/.test(name);
+}
+// Names only: the values never leave the environment they came from.
+export function signInVariableNames(env = process.env) {
+    return Object.keys(env)
+        .filter((k) => /(EMAIL|USER(NAME)?|LOGIN|PASSWORD|PASS)$/.test(k) && !/^(npm_|HOMEBREW|LOGNAME$|USER$)/.test(k))
+        .sort();
+}
+export const severityOf = (s) => (SEVERITIES.includes(String(s ?? '').toLowerCase()) ? String(s).toLowerCase() : 'medium');
+export const atOrAbove = (s, min) => SEVERITIES.indexOf(s) <= SEVERITIES.indexOf(min);
+// An error on one line, short enough to read in a report.
+export function brief(text, max = 300) {
+    const line = text.replace(/\s+/g, ' ').trim();
+    return line.length > max ? `${line.slice(0, max)}…` : line;
+}
+export function minutesAndSeconds(seconds) {
+    return `${Math.floor(seconds / 60)}m${String(seconds % 60).padStart(2, '0')}s`;
+}

package/dist/coverage.mjs

@@ -0,0 +1,119 @@
+export const NARROW_WIDTH = 375;
+const ID_SEGMENT = [
+    /^\d+$/,
+    /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
+    /^(?=.*\d)[0-9a-f]{12,}$/i,
+    /^(?=.*\d)(?=.*[a-z])[A-Za-z0-9_-]{20,}$/,
+];
+const ASSET = /\.(m?js|css|map|png|jpe?g|gif|svg|ico|webp|avif|woff2?|ttf|otf|eot|wasm|txt)$/i;
+// The dev server's own requests (bundles, error overlays, devtools, hot reload
+// and its sockets, the icon): no person's action makes them, and faulting
+// them tests the dev server, not the app. Framework paths that carry the
+// app's data, such as /_next/data/, /_next/image and /__nuxt_island/, count.
+const DEV_PATH = /^\/(?:_nuxt\/|__nuxt_dev__\/|__nuxt_devtools__\/|_next\/static\/|_next\/webpack-hmr|__nextjs|__vite|@vite\/|@fs\/|@id\/|__webpack|sockjs-node|favicon\.ico|node_modules\/)/;
+const LOOPBACK = new Set(['localhost', '127.0.0.1', '[::1]', '::1']);
+function parse(url, target) {
+    try {
+        return new URL(url, target);
+    }
+    catch {
+        return null;
+    }
+}
+// A request the loopback-only route let through, so it reached the app (the
+// target origin or another loopback port). A page call to a tracker or
+// analytics host was aborted before it reached anything, so it is not coverage
+// of the app and must not feed "seen but never faulted".
+function reachesApp(url, target) {
+    const u = parse(url, target);
+    return Boolean(u && (LOOPBACK.has(u.hostname) || u.hostname.endsWith('.localhost')));
+}
+export function foldPath(pathname) {
+    const segments = pathname.split('/').map((s) => {
+        let decoded = s;
+        try {
+            decoded = decodeURIComponent(s);
+        }
+        catch { }
+        return ID_SEGMENT.some((p) => p.test(decoded)) ? ':id' : s;
+    });
+    const folded = segments.join('/');
+    return folded.length > 1 && folded.endsWith('/') ? folded.slice(0, -1) : folded || '/';
+}
+// The folded "METHOD /path" of an API request, or null for assets and the dev
+// server's own requests. Another loopback origin keeps its host and port.
+export function endpointOf(method, url, target) {
+    const u = parse(url, target);
+    if (!u || !/^https?:$/.test(u.protocol))
+        return null;
+    if (ASSET.test(u.pathname) || DEV_PATH.test(u.pathname))
+        return null;
+    const t = parse(target, target);
+    const origin = t && u.host === t.host ? '' : u.host;
+    return `${method.toUpperCase()} ${origin}${foldPath(u.pathname)}`;
+}
+export function pageOf(url, target) {
+    const u = parse(url, target);
+    const t = parse(target, target);
+    if (!u || !t || !/^https?:$/.test(u.protocol) || u.host !== t.host || DEV_PATH.test(u.pathname))
+        return null;
+    return foldPath(u.pathname);
+}
+// Signing in is how a hunt gets started, not what it tests: what a probe saw
+// while it signed in (the sign-in page and the requests made before the page
+// it landed on) is left out, unless another probe saw it too. The page it
+// landed on, and everything after, counts.
+export function coverage(results, target) {
+    const endpoints = new Map();
+    const pages = new Map();
+    const viewports = new Set();
+    for (const r of results) {
+        const flow = r.signInFlow;
+        (r.requests ?? []).forEach((req, i) => {
+            if ((flow && i < flow.requests) || req.via !== 'page' || !reachesApp(req.url, target))
+                return;
+            const e = endpointOf(req.method, req.url, target);
+            if (e && !endpoints.has(e))
+                endpoints.set(e, new Set());
+        });
+        for (const f of r.faults ?? []) {
+            if (!reachesApp(f.url, target))
+                continue;
+            const e = endpointOf(f.method, f.url, target);
+            if (!e)
+                continue;
+            const set = endpoints.get(e) ?? new Set();
+            set.add(f.fault);
+            endpoints.set(e, set);
+        }
+        for (const p of r.pages ?? []) {
+            if (p.viewport && (p.visited ?? []).length)
+                viewports.add(`${p.viewport.width}x${p.viewport.height}`);
+            for (const v of p.visited ?? []) {
+                const page = flow?.pages.includes(v.url) ? null : pageOf(v.url, target);
+                if (!page)
+                    continue;
+                const set = pages.get(page) ?? new Set();
+                if (typeof v.width === 'number')
+                    set.add(v.width);
+                pages.set(page, set);
+            }
+        }
+    }
+    const endpointList = [...endpoints].map(([endpoint, faults]) => ({ endpoint, faults: [...faults].sort() })).sort((a, b) => a.endpoint.localeCompare(b.endpoint));
+    const pageList = [...pages].map(([page, widths]) => ({ page, widths: [...widths].sort((a, b) => a - b) })).sort((a, b) => a.page.localeCompare(b.page));
+    return {
+        endpoints: endpointList,
+        neverFaulted: endpointList.filter((e) => e.faults.length === 0).map((e) => e.endpoint),
+        pages: pageList,
+        neverNarrow: pageList.filter((p) => !p.widths.some((w) => w <= NARROW_WIDTH)).map((p) => p.page),
+        viewports: [...viewports].sort((a, b) => Number.parseInt(a, 10) - Number.parseInt(b, 10)),
+    };
+}
+export function coverageLines(c) {
+    return [
+        `endpoints seen: ${c.endpoints.length} (${c.endpoints.length - c.neverFaulted.length} faulted); pages visited: ${c.pages.length} (${c.pages.length - c.neverNarrow.length} at ${NARROW_WIDTH} px); viewports: ${c.viewports.length ? c.viewports.join(', ') : 'none'}`,
+        `seen but never faulted: ${c.neverFaulted.length ? c.neverFaulted.join(', ') : 'none'}`,
+        `pages never seen at ${NARROW_WIDTH} px: ${c.neverNarrow.length ? c.neverNarrow.join(', ') : 'none'}`,
+    ];
+}