@rigour-labs/cli 3.0.4 → 3.0.6

package/README.md

@@ -12,6 +12,7 @@ Rigour forces AI agents to meet strict engineering standards before marking task
 ## 🚀 Quick Start
 
 ```bash
+npx rigour scan     # Zero-config scan (auto-detect stack)
 npx rigour init     # Initialize quality gates
 npx rigour check    # Verify code quality
 npx rigour run -- claude "Build feature X"  # Agent loop
@@ -62,6 +63,7 @@ All gates support **TypeScript, JavaScript, Python, Go, Ruby, and C#/.NET**.
 
 | Command | Purpose |
 |:---|:---|
+| `rigour scan` | Zero-config stack-aware scan using existing gates |
 | `rigour init` | Setup Rigour in your project |
 | `rigour check` | Validate code against quality gates |
 | `rigour check --ci` | CI mode with appropriate output |

package/dist/cli.js

@@ -2,6 +2,7 @@
 import { Command } from 'commander';
 import { initCommand } from './commands/init.js';
 import { checkCommand } from './commands/check.js';
+import { scanCommand } from './commands/scan.js';
 import { explainCommand } from './commands/explain.js';
 import { runLoop } from './commands/run.js';
 import { guideCommand } from './commands/guide.js';
@@ -69,6 +70,23 @@ Examples:
     .action(async (files, options) => {
     await checkCommand(process.cwd(), files, options);
 });
+program
+    .command('scan')
+    .description('Run zero-config scan with auto-detected stack and existing gates')
+    .argument('[files...]', 'Specific files or directories to scan')
+    .option('--ci', 'CI mode (minimal output, non-zero exit on fail)')
+    .option('--json', 'Output report in JSON format')
+    .option('-c, --config <path>', 'Path to custom rigour.yml configuration (optional)')
+    .addHelpText('after', `
+Examples:
+  $ rigour scan                       # Zero-config scan in current repo
+  $ rigour scan ./src                 # Scan only src
+  $ rigour scan --json                # Machine-readable output
+  $ rigour scan --ci                  # CI-friendly output
+    `)
+    .action(async (files, options) => {
+    await scanCommand(process.cwd(), files, options);
+});
 program
     .command('explain')
     .description('Explain the last quality gate report with actionable bullets')

package/dist/commands/demo-display.d.ts

@@ -0,0 +1,11 @@
+import type { DemoOptions } from './demo-helpers.js';
+export declare function simulateCodeWrite(filename: string, lines: string[], options: DemoOptions): Promise<void>;
+export declare function simulateHookCatch(gate: string, file: string, message: string, severity: string, options: DemoOptions): Promise<void>;
+export declare function renderScoreBar(score: number, label: string, width?: number): string;
+export declare function renderTrendChart(scores: number[]): string;
+export declare function printBanner(cinematic: boolean): void;
+export declare function printPlantedIssues(): void;
+export declare function displayGateResults(report: any, cinematic: boolean): void;
+export declare function printSeverityBreakdown(stats: any): void;
+export declare function printFailure(failure: any): void;
+export declare function printClosing(cinematic: boolean): void;

package/dist/commands/demo-display.js

@@ -0,0 +1,181 @@
+import chalk from 'chalk';
+import { pause, getMultiplier, sleep } from './demo-helpers.js';
+// ── Simulated code writing ──────────────────────────────────────────
+export async function simulateCodeWrite(filename, lines, options) {
+    const isCinematic = !!options.cinematic;
+    const lineDelay = isCinematic ? 40 * getMultiplier(options) : 0;
+    console.log(chalk.dim(`\n  ${chalk.white('▸')} Writing ${chalk.cyan(filename)}...`));
+    if (isCinematic) {
+        await pause(200, options);
+    }
+    for (const line of lines) {
+        if (isCinematic) {
+            process.stdout.write(chalk.dim(`    ${line}\n`));
+            await sleep(lineDelay);
+        }
+    }
+    if (!isCinematic) {
+        const preview = lines.slice(0, 3).join('\n    ');
+        console.log(chalk.dim(`    ${preview}`));
+        if (lines.length > 3) {
+            console.log(chalk.dim(`    ... (${lines.length} lines)`));
+        }
+    }
+}
+// ── Hook simulation ─────────────────────────────────────────────────
+export async function simulateHookCatch(gate, file, message, severity, options) {
+    if (options.cinematic) {
+        await pause(300, options);
+    }
+    const sevColor = severity === 'critical' ? chalk.red.bold
+        : severity === 'high' ? chalk.red
+            : chalk.yellow;
+    const hookPrefix = chalk.magenta.bold('[rigour/hook]');
+    const sevLabel = sevColor(severity.toUpperCase());
+    const gateLabel = chalk.red(`[${gate}]`);
+    console.log(`  ${hookPrefix} ${sevLabel} ${gateLabel} ${chalk.white(file)}`);
+    console.log(`    ${chalk.dim('→')} ${message}`);
+    if (options.cinematic) {
+        await pause(400, options);
+    }
+}
+// ── ASCII score bar ─────────────────────────────────────────────────
+export function renderScoreBar(score, label, width = 30) {
+    const filled = Math.round((score / 100) * width);
+    const empty = width - filled;
+    const color = score >= 80 ? chalk.green : score >= 50 ? chalk.yellow : chalk.red;
+    const bar = color('█'.repeat(filled)) + chalk.dim('░'.repeat(empty));
+    return `  ${label.padEnd(14)} ${bar} ${color.bold(`${score}/100`)}`;
+}
+// ── ASCII trend chart ───────────────────────────────────────────────
+export function renderTrendChart(scores) {
+    const height = 8;
+    const lines = [];
+    const maxScore = 100;
+    lines.push(chalk.dim('  Score Trend:'));
+    for (let row = height; row >= 0; row--) {
+        const threshold = (row / height) * maxScore;
+        let line = chalk.dim(String(Math.round(threshold)).padStart(3) + ' │');
+        for (const score of scores) {
+            if (score >= threshold) {
+                const color = score >= 80 ? chalk.green : score >= 50 ? chalk.yellow : chalk.red;
+                line += color(' ██');
+            }
+            else {
+                line += '   ';
+            }
+        }
+        lines.push(line);
+    }
+    lines.push(chalk.dim('    └' + '───'.repeat(scores.length)));
+    const labels = scores.map((_, i) => ` R${i + 1}`);
+    lines.push(chalk.dim('     ' + labels.join('')));
+    return lines.join('\n');
+}
+// ── Banner ───────────────────────────────────────────────────────────
+export function printBanner(cinematic) {
+    const banner = chalk.bold.cyan(`
+   ____  _
+  / __ \\(_)____ ___  __  __ _____
+ / /_/ // // __ \`/ / / / / // ___/
+/ _, _// // /_/ // /_/ / / // /
+/_/ |_|/_/ \\__, / \\__,_/_/ /_/
+          /____/
+    `);
+    console.log(banner);
+}
+// ── Planted issues (non-cinematic) ──────────────────────────────────
+export function printPlantedIssues() {
+    console.log(chalk.bold.yellow('Planted issues:'));
+    console.log(chalk.dim('  1. src/auth.ts         — Hardcoded API key (security)'));
+    console.log(chalk.dim('  2. src/api-handler.ts  — Unhandled promise (AI drift)'));
+    console.log(chalk.dim('  3. src/data-loader.ts  — Hallucinated import (AI drift)'));
+    console.log(chalk.dim('  4. src/utils.ts        — TODO marker left by AI'));
+    console.log(chalk.dim('  5. src/god-file.ts     — 350+ lines (structural)'));
+    console.log('');
+}
+// ── Hooks demo: simulate AI agent → hook catches ────────────────────
+// ── Closing section ─────────────────────────────────────────────────
+export function displayGateResults(report, cinematic) {
+    const stats = report.stats;
+    if (report.status === 'FAIL') {
+        console.log(chalk.red.bold('✘ FAIL — Quality gate violations found.\n'));
+        // Score bars
+        if (stats.score !== undefined) {
+            console.log(renderScoreBar(stats.score, 'Overall'));
+        }
+        if (stats.ai_health_score !== undefined) {
+            console.log(renderScoreBar(stats.ai_health_score, 'AI Health'));
+        }
+        if (stats.structural_score !== undefined) {
+            console.log(renderScoreBar(stats.structural_score, 'Structural'));
+        }
+        console.log('');
+        // Severity breakdown
+        printSeverityBreakdown(stats);
+        // Violations list
+        for (const failure of report.failures) {
+            printFailure(failure);
+        }
+        console.log('');
+    }
+    else {
+        console.log(chalk.green.bold('✔ PASS — All quality gates satisfied.\n'));
+    }
+    console.log(chalk.dim(`Finished in ${stats.duration_ms}ms\n`));
+}
+export function printSeverityBreakdown(stats) {
+    if (!stats.severity_breakdown) {
+        return;
+    }
+    const parts = Object.entries(stats.severity_breakdown)
+        .filter(([, count]) => count > 0)
+        .map(([sev, count]) => {
+        const color = sev === 'critical' ? chalk.red.bold
+            : sev === 'high' ? chalk.red
+                : sev === 'medium' ? chalk.yellow
+                    : chalk.dim;
+        return color(`${sev}: ${count}`);
+    });
+    if (parts.length > 0) {
+        console.log('Severity: ' + parts.join(', ') + '\n');
+    }
+}
+export function printFailure(failure) {
+    const sevLabel = failure.severity === 'critical' ? chalk.red.bold('CRIT')
+        : failure.severity === 'high' ? chalk.red('HIGH')
+            : failure.severity === 'medium' ? chalk.yellow('MED ')
+                : chalk.dim('LOW ');
+    const prov = failure.provenance ? chalk.dim(`[${failure.provenance}]`) : '';
+    console.log(`  ${sevLabel} ${prov} ${chalk.red(`[${failure.id}]`)} ${failure.title}`);
+    if (failure.hint) {
+        console.log(chalk.cyan(`        ${failure.hint}`));
+    }
+}
+export function printClosing(cinematic) {
+    const divider = chalk.bold.cyan('━'.repeat(50));
+    console.log(divider);
+    console.log(chalk.bold('What Rigour does:'));
+    console.log(chalk.dim('  Catches AI drift (hallucinated imports, unhandled promises)'));
+    console.log(chalk.dim('  Blocks security issues (hardcoded keys, injection patterns)'));
+    console.log(chalk.dim('  Enforces structure (file size, complexity, documentation)'));
+    console.log(chalk.dim('  Generates audit-ready evidence (scores, trends, reports)'));
+    console.log(chalk.dim('  Real-time hooks for Claude, Cursor, Cline, Windsurf'));
+    console.log(divider);
+    console.log('');
+    if (cinematic) {
+        console.log(chalk.bold('Peer-reviewed research:'));
+        console.log(chalk.white('  Deterministic Quality Gates for AI-Generated Code'));
+        console.log(chalk.dim('  https://zenodo.org/records/18673564'));
+        console.log('');
+    }
+    console.log(chalk.bold('Get started:'));
+    console.log(chalk.white('  $ npx @rigour-labs/cli init'));
+    console.log(chalk.white('  $ npx @rigour-labs/cli check'));
+    console.log(chalk.white('  $ npx @rigour-labs/cli hooks init'));
+    console.log('');
+    console.log(chalk.dim('GitHub: https://github.com/rigour-labs/rigour'));
+    console.log(chalk.dim('Docs:   https://docs.rigour.run'));
+    console.log(chalk.dim('Paper:  https://zenodo.org/records/18673564\n'));
+    console.log(chalk.dim.italic('If this saved you from a bad commit, star the repo ⭐'));
+}

package/dist/commands/demo-helpers.d.ts

@@ -0,0 +1,9 @@
+export interface DemoOptions {
+    cinematic?: boolean;
+    hooks?: boolean;
+    speed?: 'fast' | 'normal' | 'slow';
+}
+export declare function getMultiplier(options: DemoOptions): number;
+export declare function sleep(ms: number): Promise<void>;
+export declare function pause(ms: number, options: DemoOptions): Promise<void>;
+export declare function typewrite(text: string, options: DemoOptions, charDelay?: number): Promise<void>;

package/dist/commands/demo-helpers.js

@@ -0,0 +1,28 @@
+const SPEED_MULTIPLIERS = {
+    fast: 0.3,
+    normal: 1.0,
+    slow: 1.8,
+};
+// ── Timing helpers ──────────────────────────────────────────────────
+export function getMultiplier(options) {
+    return SPEED_MULTIPLIERS[options.speed || 'normal'] || 1.0;
+}
+export function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+export async function pause(ms, options) {
+    await sleep(ms * getMultiplier(options));
+}
+// ── Typewriter effect ───────────────────────────────────────────────
+export async function typewrite(text, options, charDelay = 18) {
+    if (!options.cinematic) {
+        process.stdout.write(text + '\n');
+        return;
+    }
+    const delay = charDelay * getMultiplier(options);
+    for (const char of text) {
+        process.stdout.write(char);
+        await sleep(delay);
+    }
+    process.stdout.write('\n');
+}

package/dist/commands/demo-scenarios.d.ts

@@ -0,0 +1,11 @@
+import type { DemoOptions } from './demo-helpers.js';
+export declare function runHooksDemo(demoDir: string, options: DemoOptions): Promise<void>;
+export declare function simulateAgentWrite(filename: string, codeLines: string[], gate: string, file: string, message: string, severity: string, options: DemoOptions): Promise<void>;
+export declare function runFullGates(demoDir: string, options: DemoOptions): Promise<void>;
+export declare function runBeforeAfterDemo(demoDir: string, options: DemoOptions): Promise<void>;
+export declare function scaffoldDemoProject(dir: string): Promise<void>;
+export declare function buildDemoConfig(): Record<string, unknown>;
+export declare function buildDemoPackageJson(): Record<string, unknown>;
+export declare function writeIssueFiles(dir: string): Promise<void>;
+export declare function writeGodFile(dir: string): Promise<void>;
+export declare function generateDemoAudit(dir: string, report: any, outputPath: string): Promise<void>;

package/dist/commands/demo-scenarios.js

@@ -0,0 +1,356 @@
+import fs from 'fs-extra';
+import path from 'path';
+import chalk from 'chalk';
+import yaml from 'yaml';
+import { GateRunner, ConfigSchema } from '@rigour-labs/core';
+import { recordScore } from '@rigour-labs/core';
+import { pause, typewrite } from './demo-helpers.js';
+import { simulateCodeWrite, simulateHookCatch, renderScoreBar, renderTrendChart, displayGateResults, } from './demo-display.js';
+// ── Hooks demo: simulate AI agent → hook catches ────────────────────
+export async function runHooksDemo(demoDir, options) {
+    const divider = chalk.cyan('━'.repeat(50));
+    console.log(divider);
+    console.log(chalk.bold.magenta('  Simulating AI agent writing code with hooks active...\n'));
+    if (options.cinematic) {
+        await pause(600, options);
+    }
+    // Step 1: AI writes auth.ts with hardcoded key
+    await simulateAgentWrite('src/auth.ts', [
+        'import express from \'express\';',
+        '',
+        'const API_KEY = "sk-live-4f3c2b1a0987654321abcdef";',
+        '',
+        'export function authenticate(req: express.Request) {',
+        '    return req.headers.authorization === API_KEY;',
+        '}',
+    ], 'security-patterns', 'src/auth.ts:3', 'Possible hardcoded secret or API key', 'critical', options);
+    // Step 2: AI writes data-loader.ts with hallucinated import
+    await simulateAgentWrite('src/data-loader.ts', [
+        'import { z } from \'zod\';',
+        'import { magicParser } from \'ai-data-magic\';',
+        '',
+        'export function loadData(raw: unknown) {',
+        '    return z.object({ name: z.string() }).parse(raw);',
+        '}',
+    ], 'hallucinated-imports', 'src/data-loader.ts:2', 'Import \'ai-data-magic\' does not resolve to an existing package', 'high', options);
+    // Step 3: AI writes api-handler.ts with unhandled promise
+    await simulateAgentWrite('src/api-handler.ts', [
+        'export async function fetchUser(id: string) {',
+        '    const res = await fetch(`/api/users/${id}`);',
+        '    return res.json();',
+        '}',
+        '',
+        'export function handleRequest(req: any, res: any) {',
+        '    fetchUser(req.params.id);  // floating promise',
+        '    res.send(\'Processing...\');',
+        '}',
+    ], 'promise-safety', 'src/api-handler.ts:7', 'Unhandled promise — fetchUser() called without await or .catch()', 'medium', options);
+    console.log('');
+    console.log(chalk.magenta.bold(`  Hooks caught 3 issues in real time — before the agent finished.`));
+    console.log(divider);
+    console.log('');
+    if (options.cinematic) {
+        await pause(1000, options);
+    }
+}
+export async function simulateAgentWrite(filename, codeLines, gate, file, message, severity, options) {
+    console.log(chalk.blue.bold(`  Agent: Write → ${filename}`));
+    await simulateCodeWrite(filename, codeLines, options);
+    await simulateHookCatch(gate, file, message, severity, options);
+    console.log('');
+}
+// ── Full gate run ───────────────────────────────────────────────────
+export async function runFullGates(demoDir, options) {
+    const isCinematic = !!options.cinematic;
+    console.log(chalk.bold.blue('Running full Rigour quality gates...\n'));
+    if (isCinematic) {
+        await pause(500, options);
+    }
+    try {
+        const configContent = await fs.readFile(path.join(demoDir, 'rigour.yml'), 'utf-8');
+        const rawConfig = yaml.parse(configContent);
+        const config = ConfigSchema.parse(rawConfig);
+        const runner = new GateRunner(config);
+        const report = await runner.run(demoDir);
+        recordScore(demoDir, report);
+        const reportPath = path.join(demoDir, config.output.report_path);
+        await fs.writeJson(reportPath, report, { spaces: 2 });
+        displayGateResults(report, isCinematic);
+        await generateArtifacts(demoDir, report, config);
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        console.error(chalk.red(`Demo error: ${msg}`));
+    }
+}
+async function generateArtifacts(demoDir, report, config) {
+    if (report.status === 'FAIL') {
+        const { FixPacketService } = await import('@rigour-labs/core');
+        const fixPacketService = new FixPacketService();
+        const fixPacket = fixPacketService.generate(report, config);
+        const fixPacketPath = path.join(demoDir, 'rigour-fix-packet.json');
+        await fs.writeJson(fixPacketPath, fixPacket, { spaces: 2 });
+        console.log(chalk.green('✓ Fix packet generated: rigour-fix-packet.json'));
+    }
+    const auditPath = path.join(demoDir, 'rigour-audit-report.md');
+    await generateDemoAudit(demoDir, report, auditPath);
+    console.log(chalk.green('✓ Audit report exported: rigour-audit-report.md'));
+    console.log('');
+}
+// ── Before/After improvement demo ───────────────────────────────────
+export async function runBeforeAfterDemo(demoDir, options) {
+    console.log(chalk.bold.green('Simulating agent fixing issues...\n'));
+    await pause(600, options);
+    // Fix the auth.ts — remove hardcoded key
+    await typewrite(chalk.dim('  Agent: Removing hardcoded API key from src/auth.ts...'), options);
+    await fs.writeFile(path.join(demoDir, 'src', 'auth.ts'), `
+import express from 'express';
+
+export function authenticate(req: express.Request) {
+    const token = req.headers.authorization;
+    if (!token) {
+        return { authenticated: false };
+    }
+    // Validate against secure key store
+    return { authenticated: validateToken(token) };
+}
+
+function validateToken(token: string): boolean {
+    return token.startsWith('Bearer ') && token.length > 20;
+}
+`.trim());
+    console.log(chalk.green('  ✓ Fixed: API key moved to environment variable'));
+    await pause(300, options);
+    // Fix data-loader.ts — remove hallucinated import
+    await typewrite(chalk.dim('  Agent: Removing hallucinated import from src/data-loader.ts...'), options);
+    await fs.writeFile(path.join(demoDir, 'src', 'data-loader.ts'), `
+import { z } from 'zod';
+
+const schema = z.object({
+    name: z.string(),
+    email: z.string().email(),
+});
+
+export function loadData(raw: unknown) {
+    return schema.parse(raw);
+}
+`.trim());
+    console.log(chalk.green('  ✓ Fixed: Removed non-existent package imports'));
+    await pause(300, options);
+    // Fix api-handler.ts — add error handling
+    await typewrite(chalk.dim('  Agent: Adding error handling to src/api-handler.ts...'), options);
+    await fs.writeFile(path.join(demoDir, 'src', 'api-handler.ts'), `
+import express from 'express';
+
+export async function fetchUserData(userId: string) {
+    const response = await fetch(\`https://api.example.com/users/\${userId}\`);
+    if (!response.ok) {
+        throw new Error(\`Failed to fetch user: \${response.status}\`);
+    }
+    return response.json();
+}
+
+export async function handleRequest(req: express.Request, res: express.Response) {
+    try {
+        const data = await fetchUserData(req.params.id);
+        res.json(data);
+    } catch (error) {
+        res.status(500).json({ error: 'Failed to fetch user data' });
+    }
+}
+`.trim());
+    console.log(chalk.green('  ✓ Fixed: Added proper await and error handling'));
+    console.log('');
+    await pause(500, options);
+    // Re-run gates to show improvement
+    console.log(chalk.bold.blue('Re-running quality gates after fixes...\n'));
+    await pause(400, options);
+    try {
+        const configContent = await fs.readFile(path.join(demoDir, 'rigour.yml'), 'utf-8');
+        const rawConfig = yaml.parse(configContent);
+        const config = ConfigSchema.parse(rawConfig);
+        const runner = new GateRunner(config);
+        const report2 = await runner.run(demoDir);
+        recordScore(demoDir, report2);
+        const score1 = 35; // approximate first-run score
+        const score2 = report2.stats.score ?? 75;
+        const remaining = report2.failures.length;
+        console.log(chalk.bold('Score improvement:\n'));
+        console.log(renderScoreBar(score1, 'Before'));
+        console.log(renderScoreBar(score2, 'After'));
+        console.log('');
+        // Trend chart
+        console.log(renderTrendChart([score1, score2]));
+        console.log('');
+        if (remaining > 0) {
+            console.log(chalk.yellow(`  ${remaining} issue(s) remaining (structural, TODOs)`));
+        }
+        else {
+            console.log(chalk.green.bold('  All issues resolved!'));
+        }
+        console.log('');
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        console.error(chalk.red(`Re-check error: ${msg}`));
+    }
+}
+// ── Scaffold demo project ───────────────────────────────────────────
+export async function scaffoldDemoProject(dir) {
+    const config = buildDemoConfig();
+    await fs.writeFile(path.join(dir, 'rigour.yml'), yaml.stringify(config));
+    await fs.writeJson(path.join(dir, 'package.json'), buildDemoPackageJson(), { spaces: 2 });
+    await fs.ensureDir(path.join(dir, 'src'));
+    await fs.ensureDir(path.join(dir, 'docs'));
+    await writeIssueFiles(dir);
+    await writeGodFile(dir);
+    await fs.writeFile(path.join(dir, 'README.md'), '# Demo Project\n\nThis is a demo project for Rigour.\n');
+}
+export function buildDemoConfig() {
+    return {
+        version: 1,
+        preset: 'api',
+        gates: {
+            max_file_lines: 300,
+            forbid_todos: true,
+            forbid_fixme: true,
+            ast: { complexity: 10, max_params: 5 },
+            security: { enabled: true, block_on_severity: 'high' },
+            hallucinated_imports: { enabled: true, severity: 'critical' },
+            promise_safety: { enabled: true, severity: 'high' },
+        },
+        hooks: { enabled: true, tools: ['claude'] },
+        ignore: ['.git/**', 'node_modules/**'],
+        output: { report_path: 'rigour-report.json' },
+    };
+}
+export function buildDemoPackageJson() {
+    return {
+        name: 'rigour-demo',
+        version: '1.0.0',
+        dependencies: { express: '^4.18.0', zod: '^3.22.0' },
+    };
+}
+export async function writeIssueFiles(dir) {
+    // Issue 1: Hardcoded API key
+    await fs.writeFile(path.join(dir, 'src', 'auth.ts'), `
+import express from 'express';
+
+const API_KEY = "sk-live-4f3c2b1a0987654321abcdef";
+const DB_PASSWORD = "super_secret_p@ssw0rd!";
+
+export function authenticate(req: express.Request) {
+    const token = req.headers.authorization;
+    if (token === API_KEY) {
+        return { authenticated: true };
+    }
+    return { authenticated: false };
+}
+
+export function connectDatabase() {
+    return { host: 'prod-db.internal', password: DB_PASSWORD };
+}
+`.trim());
+    // Issue 2: Unhandled promise
+    await fs.writeFile(path.join(dir, 'src', 'api-handler.ts'), `
+import express from 'express';
+
+export async function fetchUserData(userId: string) {
+    const response = await fetch(\`https://api.example.com/users/\${userId}\`);
+    return response.json();
+}
+
+export function handleRequest(req: express.Request, res: express.Response) {
+    fetchUserData(req.params.id);
+    res.send('Processing...');
+}
+
+export function batchProcess(ids: string[]) {
+    ids.forEach(id => fetchUserData(id));
+}
+`.trim());
+    // Issue 3: Hallucinated import
+    await fs.writeFile(path.join(dir, 'src', 'data-loader.ts'), `
+import { z } from 'zod';
+import { magicParser } from 'ai-data-magic';
+import { ultraCache } from 'quantum-cache-pro';
+
+const schema = z.object({
+    name: z.string(),
+    email: z.string().email(),
+});
+
+export function loadData(raw: unknown) {
+    const parsed = schema.parse(raw);
+    return parsed;
+}
+`.trim());
+    // Issue 4: TODO markers
+    await fs.writeFile(path.join(dir, 'src', 'utils.ts'), `
+// TODO: Claude suggested this but I need to review
+// FIXME: This function has edge cases
+export function formatDate(date: Date): string {
+    return date.toISOString().split('T')[0];
+}
+
+export function sanitizeInput(input: string): string {
+    // TODO: Add proper sanitization
+    return input.trim();
+}
+`.trim());
+}
+export async function writeGodFile(dir) {
+    const lines = [
+        '// Auto-generated data processing module',
+        'export class DataProcessor {',
+    ];
+    for (let i = 0; i < 60; i++) {
+        lines.push(`    process${i}(data: any) {`);
+        lines.push(`        const result = data.map((x: any) => x * ${i + 1});`);
+        lines.push(`        if (result.length > ${i * 10}) {`);
+        lines.push(`            return result.slice(0, ${i * 10});`);
+        lines.push(`        }`);
+        lines.push(`        return result;`);
+        lines.push(`    }`);
+    }
+    lines.push('}');
+    await fs.writeFile(path.join(dir, 'src', 'god-file.ts'), lines.join('\n'));
+}
+// ── Audit report generator ──────────────────────────────────────────
+export async function generateDemoAudit(dir, report, outputPath) {
+    const stats = report.stats || {};
+    const failures = report.failures || [];
+    const lines = [];
+    lines.push('# Rigour Audit Report — Demo');
+    lines.push('');
+    lines.push(`**Generated:** ${new Date().toISOString()}`);
+    lines.push(`**Status:** ${report.status}`);
+    lines.push(`**Score:** ${stats.score ?? 100}/100`);
+    if (stats.ai_health_score !== undefined) {
+        lines.push(`**AI Health:** ${stats.ai_health_score}/100`);
+    }
+    if (stats.structural_score !== undefined) {
+        lines.push(`**Structural:** ${stats.structural_score}/100`);
+    }
+    lines.push('');
+    lines.push('## Violations');
+    lines.push('');
+    for (let i = 0; i < failures.length; i++) {
+        const f = failures[i];
+        lines.push(`### ${i + 1}. [${(f.severity || 'medium').toUpperCase()}] ${f.title}`);
+        lines.push(`- **ID:** \`${f.id}\``);
+        lines.push(`- **Provenance:** ${f.provenance || 'traditional'}`);
+        lines.push(`- **Details:** ${f.details}`);
+        if (f.files?.length) {
+            lines.push(`- **Files:** ${f.files.join(', ')}`);
+        }
+        if (f.hint) {
+            lines.push(`- **Hint:** ${f.hint}`);
+        }
+        lines.push('');
+    }
+    lines.push('---');
+    lines.push('*Generated by Rigour — https://rigour.run*');
+    lines.push('*Research: https://zenodo.org/records/18673564*');
+    await fs.writeFile(outputPath, lines.join('\n'));
+}

package/dist/commands/demo.d.ts

@@ -3,21 +3,8 @@
  *
  * Creates a temp project with intentional AI-generated code issues,
  * runs Rigour against it, and shows the full experience.
- *
- * Modes:
- *   Default:    Fast demo — scaffold → check → results
- *   --cinematic: Screen-recording optimized — typewriter effects, pauses,
- *                simulated AI agent writing code, hooks catching issues
- *   --hooks:     Focus on the real-time hooks experience
- *   --speed:     Control pacing (fast / normal / slow)
- *
- * The "flagship demo" — one command to understand Rigour.
- *
  * @since v2.17.0 (extended v3.0.0)
  */
-export interface DemoOptions {
-    cinematic?: boolean;
-    hooks?: boolean;
-    speed?: 'fast' | 'normal' | 'slow';
-}
+import type { DemoOptions } from './demo-helpers.js';
+export type { DemoOptions } from './demo-helpers.js';
 export declare function demoCommand(options?: DemoOptions): Promise<void>;