@rigour-labs/core 6.6.5 → 6.7.0

package/dist/review/toolchain.js

@@ -2,13 +2,17 @@
  * The repository's own tools, run on what a change touched: the formatter, the linter, the type
  * checker and the tests that import changed files. Teams already trust these; Rigour runs them at
  * the moment that matters (before a push) so nobody has to remember. Only tools the project
- * installed are run (node_modules/.bin, never a download); a missing one is reported as skipped.
- * A tool configured under `commands:` is left to that command, which every review already runs.
+ * installed are run (node_modules/.bin, never a download). A tool the project never declared is
+ * skipped and said so; one declared in package.json but not installed FAILS, since a checkout
+ * without its dependencies cannot prove anything about the change. A tool the team configured
+ * under `commands:` is run as that command instead, as written (whole project, not per file).
  */
 import { execa } from 'execa';
 import fs from 'fs';
 import path from 'path';
+import { splitCommand } from '../utils/command-line.js';
 import { installedBin } from '../utils/installed-bin.js';
+import { onChangedLines, overlayUnavailable, writeOverlayConfig } from './lint-overlay.js';
 import { ownOutputs } from './unused-exports.js';
 const CODE = /\.(ts|tsx|js|jsx|mjs|cjs|svelte)$/;
 const FORMATTED = /\.(ts|tsx|js|jsx|mjs|cjs|svelte|json|css|md|ya?ml|html)$/;
@@ -16,25 +20,90 @@ const FORMATTED = /\.(ts|tsx|js|jsx|mjs|cjs|svelte|json|css|md|ya?ml|html)$/;
 const BATCH = 150;
 const TIMEOUT_MS = 10 * 60_000;
 const OUTPUT_LINES = 30;
-export async function runToolchain(cwd, changedFiles, config) {
+/** `changedLines`: the lines the change touched, for the tools that report per line (the overlay blocks on those only). */
+export async function runToolchain(cwd, changedFiles, config, changedLines = {}) {
     const own = ownOutputs(config);
     const files = changedFiles.filter(file => !own.some(o => file === o || file.startsWith(`${o}/`)) && fs.existsSync(path.join(cwd, file)));
     const code = files.filter(file => CODE.test(file));
     const configured = config.commands ?? {};
     const results = [];
     const run = async (tool, step) => {
-        results.push(configured[tool] ? { tool, status: 'skipped', command: `commands.${tool} runs it` } : await step());
+        const command = configured[tool];
+        if (!command)
+            results.push(await step());
+        else {
+            const { bin, args } = splitCommand(command);
+            results.push(await once(tool, cwd, bin, args));
+        }
     };
     await run('format', () => formatCheck(cwd, files.filter(file => FORMATTED.test(file))));
     await run('lint', () => lint(cwd, code));
+    await run('overlay', () => lintOverlay(cwd, code, changedLines));
     await run('typecheck', () => typecheck(cwd));
     await run('test', () => relatedTests(cwd, code));
+    await run('knip', () => knip(cwd, files));
     return results;
 }
+/**
+ * Type-checked rules the repository does not enable (lint-overlay.ts), on changed lines only. The
+ * repository's own eslint and typescript-eslint run it; without them it is skipped and said so.
+ */
+async function lintOverlay(cwd, files, changedLines) {
+    const bin = installedBin(cwd, cwd, 'eslint');
+    if (!bin)
+        return skipped('overlay', 'eslint is not installed');
+    const unavailable = overlayUnavailable(cwd);
+    if (unavailable)
+        return skipped('overlay', unavailable);
+    const lintable = files.filter(file => /\.(ts|mts|cts|js|mjs|svelte)$/.test(file));
+    if (lintable.length === 0)
+        return { tool: 'overlay', status: 'pass', command: 'no lintable changed files' };
+    const configFile = writeOverlayConfig(cwd);
+    try {
+        const command = `eslint --config <typed overlay> --format json (${lintable.length} files)`;
+        const result = await execa(bin, ['--config', configFile, '--no-warn-ignored', '--format', 'json', ...lintable], { cwd, reject: false, timeout: TIMEOUT_MS, env: { ...process.env, CI: '1', FORCE_COLOR: '0' } });
+        const report = onChangedLines(String(result.stdout ?? ''), cwd, changedLines);
+        if ('error' in report)
+            return { tool: 'overlay', status: 'fail', command, output: `${report.error}\n${String(result.stderr ?? '').trim().split('\n').slice(-OUTPUT_LINES).join('\n')}` };
+        const lines = report.blocking.map(m => `${m.file}:${m.line}:${m.column} ${m.rule}: ${m.message}`);
+        const summary = `${command}: ${lines.length} on changed lines, ${report.preexisting} pre-existing (not blocking)`;
+        return lines.length ? { tool: 'overlay', status: 'fail', command: summary, output: lines.join('\n'), lines } : { tool: 'overlay', status: 'pass', command: summary };
+    }
+    finally {
+        fs.rmSync(path.dirname(configFile), { recursive: true, force: true });
+    }
+}
+/**
+ * knip, when the repository installs it, with the repository's own config: unused files and
+ * exports among the files the change touched (a pre-existing dead export elsewhere is backlog).
+ */
+async function knip(cwd, files) {
+    const bin = installedBin(cwd, cwd, 'knip');
+    if (!bin)
+        return notInstalled('knip', cwd, 'knip');
+    if (files.length === 0)
+        return { tool: 'knip', status: 'pass', command: 'no changed files' };
+    const command = 'knip --production --reporter json';
+    const result = await execa(bin, ['--production', '--no-progress', '--reporter', 'json'], { cwd, reject: false, timeout: TIMEOUT_MS, env: { ...process.env, CI: '1', FORCE_COLOR: '0' } });
+    let report;
+    try {
+        report = JSON.parse(String(result.stdout ?? ''));
+    }
+    catch {
+        return { tool: 'knip', status: 'fail', command, output: `knip printed no JSON (exit ${result.exitCode})\n${String(result.stderr ?? '').trim().split('\n').slice(-OUTPUT_LINES).join('\n')}` };
+    }
+    const changed = new Set(files);
+    const normalize = (file) => path.isAbsolute(file) ? path.relative(cwd, file).split(path.sep).join('/') : file;
+    const lines = [
+        ...(report.files ?? []).map(normalize).filter(file => changed.has(file)).map(file => `${file}: nothing imports or runs this file`),
+        ...(report.issues ?? []).filter(issue => changed.has(normalize(issue.file))).flatMap(issue => [...(issue.exports ?? []), ...(issue.types ?? [])].map(e => `${normalize(issue.file)}${e.line ? `:${e.line}` : ''}: unused export ${e.name}`)),
+    ];
+    return lines.length ? { tool: 'knip', status: 'fail', command: `${command}: ${lines.length} in changed files`, output: lines.join('\n'), lines } : { tool: 'knip', status: 'pass', command };
+}
 async function formatCheck(cwd, files) {
     const bin = installedBin(cwd, cwd, 'prettier');
     if (!bin)
-        return skipped('format', 'prettier is not installed');
+        return notInstalled('format', cwd, 'prettier');
     if (files.length === 0)
         return { tool: 'format', status: 'pass', command: 'no files to format' };
     return batched('format', cwd, bin, ['--check', '--ignore-unknown'], files);
@@ -42,7 +111,7 @@ async function formatCheck(cwd, files) {
 async function lint(cwd, files) {
     const bin = installedBin(cwd, cwd, 'eslint');
     if (!bin)
-        return skipped('lint', 'eslint is not installed');
+        return notInstalled('lint', cwd, 'eslint');
     if (files.length === 0)
         return { tool: 'lint', status: 'pass', command: 'no code files' };
     // ESLint 9 warns about an explicitly named ignored file, which --max-warnings=0 would count.
@@ -71,8 +140,21 @@ async function typecheck(cwd) {
     const tsc = fs.existsSync(path.join(cwd, 'tsconfig.json')) && installedBin(cwd, cwd, 'tsc');
     if (tsc)
         return once('typecheck', cwd, tsc, ['--noEmit']);
+    for (const pkg of ['svelte-check', 'typescript'])
+        if (declared(cwd, pkg))
+            return notInstalled('typecheck', cwd, pkg);
     return skipped('typecheck', 'no typecheck/check script, svelte-check or tsc with a tsconfig.json');
 }
+function declared(cwd, pkg) {
+    const manifest = readPackage(cwd);
+    return !!(manifest.dependencies?.[pkg] ?? manifest.devDependencies?.[pkg]);
+}
+/** Declared in package.json but absent from node_modules: a checkout that cannot prove anything fails; a tool never declared is skipped. */
+function notInstalled(tool, cwd, pkg) {
+    return declared(cwd, pkg)
+        ? { tool, status: 'fail', command: `${pkg} is in package.json but not installed`, output: `node_modules has no ${pkg}: install the dependencies (npm install, pnpm install, …) and run again` }
+        : skipped(tool, `${pkg} is not installed`);
+}
 function readPackage(cwd) {
     try {
         return JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
@@ -85,7 +167,7 @@ function readPackage(cwd) {
 async function relatedTests(cwd, files) {
     const bin = installedBin(cwd, cwd, 'vitest');
     if (!bin)
-        return skipped('test', 'vitest is not installed');
+        return notInstalled('test', cwd, 'vitest');
     if (files.length === 0)
         return { tool: 'test', status: 'pass', command: 'no code files' };
     const first = await once('test', cwd, bin, ['related', '--run', '--passWithNoTests', ...files]);

package/dist/review/toolchain.test.js

@@ -25,7 +25,45 @@ afterEach(() => { fs.rmSync(dir, { recursive: true, force: true }); });
 describe('runToolchain', () => {
     it('reports every tool the project did not install as skipped, never downloading one', async () => {
         const results = await runToolchain(dir, ['src/a.ts'], config());
-        expect(results.map(r => [r.tool, r.status])).toEqual([['format', 'skipped'], ['lint', 'skipped'], ['typecheck', 'skipped'], ['test', 'skipped']]);
+        expect(results.map(r => [r.tool, r.status])).toEqual([['format', 'skipped'], ['lint', 'skipped'], ['overlay', 'skipped'], ['typecheck', 'skipped'], ['test', 'skipped'], ['knip', 'skipped']]);
+    });
+    it('fails, not skips, a tool the project declares but has not installed: a checkout without its dependencies proves nothing', async () => {
+        fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ devDependencies: { eslint: '^9', typescript: '^5' } }));
+        const results = await runToolchain(dir, ['src/a.ts'], config());
+        expect(results.map(r => [r.tool, r.status])).toEqual([['format', 'skipped'], ['lint', 'fail'], ['overlay', 'skipped'], ['typecheck', 'fail'], ['test', 'skipped'], ['knip', 'skipped']]);
+        expect(results.find(r => r.tool === 'lint')).toMatchObject({ command: 'eslint is in package.json but not installed', output: expect.stringContaining('install the dependencies') });
+    });
+    it('runs type-checked rules the project does not enable, blocking on changed lines only, with the project\'s own eslint and config', async () => {
+        fs.writeFileSync(path.join(dir, 'eslint.config.js'), 'export default [];\n');
+        fs.mkdirSync(path.join(dir, 'node_modules/typescript-eslint'), { recursive: true });
+        fs.writeFileSync(path.join(dir, 'node_modules/typescript-eslint/package.json'), '{"name":"typescript-eslint","main":"index.js"}');
+        fs.writeFileSync(path.join(dir, 'node_modules/typescript-eslint/index.js'), 'module.exports = {};');
+        const report = JSON.stringify([{ filePath: path.join(dir, 'src/a.ts'), messages: [
+                    { line: 2, column: 5, ruleId: '@typescript-eslint/no-unnecessary-condition', message: 'Unnecessary conditional, value is always truthy.' },
+                    { line: 9, column: 1, ruleId: '@typescript-eslint/no-floating-promises', message: 'Promises must be awaited.' },
+                ] }]);
+        tool('eslint', `if (args[0] === '--version') { console.log('v9.0.0'); process.exit(0); }\nif (args.includes('--format')) { console.log(${JSON.stringify(report)}); process.exit(1); }\nprocess.exit(0);`);
+        const results = await runToolchain(dir, ['src/a.ts'], config(), { 'src/a.ts': new Set([1, 2, 3]) });
+        const overlay = results.find(r => r.tool === 'overlay');
+        expect(overlay).toMatchObject({ status: 'fail', lines: ['src/a.ts:2:5 @typescript-eslint/no-unnecessary-condition: Unnecessary conditional, value is always truthy.'] });
+        expect(overlay.command).toContain('1 on changed lines, 1 pre-existing (not blocking)');
+        const call = calls().split('\n').find(line => line.includes('--format json'));
+        expect(call).toMatch(/eslint --config \S+eslint\.overlay\.config\.mjs --no-warn-ignored --format json src\/a\.ts/);
+        expect(fs.readdirSync(dir)).not.toContain('eslint.overlay.config.mjs'); // never written into the repository
+        // Nothing on a changed line: pass, backlog counted.
+        const clean = await runToolchain(dir, ['src/a.ts'], config(), { 'src/a.ts': new Set([7]) });
+        expect(clean.find(r => r.tool === 'overlay')).toMatchObject({ status: 'pass', command: expect.stringContaining('0 on changed lines, 2 pre-existing') });
+    });
+    it('runs knip when the project installs it, and reports only what is in the changed files', async () => {
+        const report = JSON.stringify({ files: [path.join(dir, 'src/dead.ts'), 'src/elsewhere.ts'], issues: [
+                { file: 'src/a.ts', exports: [{ name: 'spare', line: 3, col: 1 }], types: [{ name: 'Spare', line: 4, col: 1 }] },
+                { file: 'src/other.ts', exports: [{ name: 'old', line: 1, col: 1 }], types: [] },
+            ] });
+        tool('knip', `console.log(${JSON.stringify(report)}); process.exit(1);`);
+        fs.writeFileSync(path.join(dir, 'src/dead.ts'), 'export const dead = 1;\n');
+        const results = await runToolchain(dir, ['src/a.ts', 'src/dead.ts'], config());
+        expect(results.find(r => r.tool === 'knip')).toMatchObject({ status: 'fail', lines: ['src/dead.ts: nothing imports or runs this file', 'src/a.ts:3: unused export spare', 'src/a.ts:4: unused export Spare'] });
+        expect(calls()).toContain('knip --production --no-progress --reporter json');
     });
     it('runs the formatter on changed files only and reports what it said', async () => {
         tool('prettier', "const bad = args.filter(a => a.endsWith('.ts') && fs.readFileSync(a, 'utf8').includes('BAD'));\nif (bad.length) { console.log('[warn] ' + bad.join(' ')); process.exit(1); }");
@@ -35,12 +73,15 @@ describe('runToolchain', () => {
         expect(calls()).toContain('prettier --check --ignore-unknown src/a.ts src/bad.ts');
         expect(calls()).not.toContain('gone.ts');
     });
-    it('quiets ESLint 9 about ignored files, and leaves a tool set under commands: to that command', async () => {
+    it('quiets ESLint 9 about ignored files, and runs a tool set under commands: as that command, whose failure fails the push', async () => {
         tool('eslint', "if (args[0] === '--version') { console.log('v9.1.0'); process.exit(0); }");
-        const results = await runToolchain(dir, ['src/a.ts'], config({ format: 'npm run fmt' }));
+        tool('prettier', 'process.exit(0);');
+        const results = await runToolchain(dir, ['src/a.ts'], config({ format: 'node -e "process.exit(4)"', test: 'node -e "process.exit(0)"' }));
         expect(results.find(r => r.tool === 'lint')).toMatchObject({ status: 'pass' });
         expect(calls()).toContain('eslint --max-warnings=0 --no-warn-ignored src/a.ts');
-        expect(results.find(r => r.tool === 'format')).toMatchObject({ status: 'skipped', command: 'commands.format runs it' });
+        expect(results.find(r => r.tool === 'format')).toMatchObject({ status: 'fail', command: expect.stringContaining('node -e') });
+        expect(calls()).not.toContain('prettier'); // the team's command replaces the detected tool
+        expect(results.find(r => r.tool === 'test')).toMatchObject({ status: 'pass' });
     });
     it("uses the project's own check script for types, and never hands a tool Rigour's own files", async () => {
         fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ scripts: { check: 'node -e "process.exit(3)"' } }));

package/dist/review/typed/program.d.ts

@@ -0,0 +1,26 @@
+import type * as TS from 'typescript';
+export interface TextFile {
+    file: string;
+    text: string;
+}
+export interface TypedProgram {
+    ts: typeof TS;
+    program: TS.Program;
+    checker: TS.TypeChecker;
+    root: string;
+    /** A source file's path relative to the root, posix. */
+    rel(sf: TS.SourceFile): string;
+    /** The sources (outside node_modules, no declaration files) that are not tests: where a host or a reader counts. */
+    appSources: TS.SourceFile[];
+    /** Files the program does not type, as text. */
+    textFiles: TextFile[];
+    inProgram: Set<string>;
+}
+/** The program, `skip` when this is not a TypeScript project, or `error` when it is one that cannot be loaded. */
+export declare function loadProgram(root: string): {
+    program: TypedProgram;
+} | {
+    skip: string;
+} | {
+    error: string;
+};

package/dist/review/typed/program.js

@@ -0,0 +1,90 @@
+/**
+ * The project's TypeScript program, built once per review from its own tsconfig.json and its own
+ * `typescript` (the compiler version and options then match what the project type-checks with;
+ * Rigour's bundled compiler is the fallback). What the type checker knows (which literal is typed
+ * as T, which property is read where) is what the typed checks reason from. Files outside the
+ * program (.svelte, a package under its own tsconfig) are kept as text and scanned by name only,
+ * which can suppress a finding and never adds one.
+ */
+import { spawnSync } from 'child_process';
+import fs from 'fs';
+import { createRequire } from 'module';
+import path from 'path';
+import ownTs from 'typescript';
+import { installedBin } from '../../utils/installed-bin.js';
+import { isTestFile } from '../test-files.js';
+const GIT_TIMEOUT_MS = 10_000;
+/** The program, `skip` when this is not a TypeScript project, or `error` when it is one that cannot be loaded. */
+export function loadProgram(root) {
+    const tsconfig = path.join(root, 'tsconfig.json');
+    if (!fs.existsSync(tsconfig))
+        return { skip: 'no tsconfig.json' };
+    const ts = projectTypescript(root);
+    let parsed = parseConfig(ts, tsconfig);
+    if ('error' in parsed && /\.svelte-kit\//.test(parsed.error) && syncSvelteKit(root))
+        parsed = parseConfig(ts, tsconfig);
+    if ('error' in parsed)
+        return { error: `tsconfig.json cannot be loaded: ${parsed.error}` };
+    const program = ts.createProgram({ rootNames: parsed.config.fileNames, options: { ...parsed.config.options, noEmit: true } });
+    const rel = (sf) => path.relative(root, sf.fileName).split(path.sep).join('/');
+    const sources = program.getSourceFiles().filter(sf => !sf.isDeclarationFile && !sf.fileName.includes('/node_modules/'));
+    const inProgram = new Set(sources.map(rel));
+    return {
+        program: {
+            ts, program, checker: program.getTypeChecker(), root, rel,
+            appSources: sources.filter(sf => !isTestFile(rel(sf))),
+            textFiles: textFiles(root, inProgram),
+            inProgram,
+        },
+    };
+}
+function projectTypescript(root) {
+    try {
+        return createRequire(path.join(root, 'package.json'))('typescript');
+    }
+    catch {
+        return ownTs;
+    }
+}
+function parseConfig(ts, tsconfig) {
+    try {
+        const config = ts.getParsedCommandLineOfConfigFile(tsconfig, {}, {
+            ...ts.sys,
+            onUnRecoverableConfigFileDiagnostic: diagnostic => {
+                throw new Error(ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n'));
+            },
+        });
+        if (!config)
+            return { error: 'unreadable' };
+        // A missing `extends` target or an unknown option is a diagnostic, not an exception; tsc would fail on it too.
+        const errors = config.errors.filter(d => d.category === ts.DiagnosticCategory.Error).map(d => ts.flattenDiagnosticMessageText(d.messageText, '\n'));
+        return errors.length ? { error: errors.join('; ') } : { config };
+    }
+    catch (error) {
+        return { error: String(error.message ?? error) };
+    }
+}
+/** A SvelteKit tsconfig extends a generated one; `svelte-kit sync` writes it (never downloaded: the project's own binary or nothing). */
+function syncSvelteKit(root) {
+    const bin = installedBin(root, root, 'svelte-kit');
+    if (!bin)
+        return false;
+    return spawnSync(bin, ['sync'], { cwd: root, stdio: 'ignore', timeout: 120_000 }).status === 0;
+}
+function textFiles(root, inProgram) {
+    const listed = spawnSync('git', ['ls-files', '--', '*.svelte', '*.ts', '*.js'], { cwd: root, encoding: 'utf8', timeout: GIT_TIMEOUT_MS, maxBuffer: 64 * 1024 * 1024 });
+    if (listed.status !== 0)
+        return [];
+    const files = [];
+    for (const file of listed.stdout.split('\n')) {
+        if (!file || inProgram.has(file) || file.endsWith('.d.ts') || isTestFile(file))
+            continue;
+        try {
+            files.push({ file, text: fs.readFileSync(path.join(root, file), 'utf8') });
+        }
+        catch {
+            // deleted in the working tree
+        }
+    }
+    return files;
+}

package/dist/review/typed/redundancy.d.ts

@@ -0,0 +1,10 @@
+import type { Config, Failure } from '../../types/index.js';
+export interface Redundancy {
+    failures: Failure[];
+    hints: string[];
+    /** A TypeScript project whose program cannot be built: the checks could not run, which is never a pass (review.ts turns it into a gate error). */
+    error?: string;
+}
+export declare const TYPED_CHECKS = "typed-checks-unavailable";
+/** The typed checks on a change: nothing when it touches no TypeScript or the project has no tsconfig. */
+export declare function typedChecks(cwd: string, changedLines: Record<string, Set<number>>, config: Config): Redundancy;