@0xcraft/powershot 1.0.0

package/dist/manifest.js

@@ -0,0 +1,209 @@
+import { createHash } from 'node:crypto';
+import { mkdirSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const SCHEMA = 'powershot.run/v1';
+/** The single state machine behind manifests, benches, renderers and exit codes. */
+export function completionOf(parts) {
+    const waivedUnits = parts.units.filter((unit) => unit.outcome === 'waived').length;
+    const failedUnits = parts.units.filter((unit) => unit.outcome === 'failed').length;
+    const failedFiles = parts.files.filter((file) => file.disposition === 'failed').length;
+    const limitedFiles = parts.files.filter((file) => file.disposition === 'selected' && file.missing?.length).length;
+    const state = parts.failures.length > 0 || failedUnits > 0 || failedFiles > 0
+        ? 'failed'
+        : parts.cancelled || parts.budgetStop || waivedUnits > 0 || limitedFiles > 0 || parts.skippedChecks.length > 0
+            ? 'partial'
+            : 'complete';
+    return {
+        state,
+        notLookedAt: reasons(parts.files, parts.units, parts.skippedChecks, parts.failures, parts.cancelled, parts.budgetStop),
+    };
+}
+/**
+ * The one authoritative record of a run.
+ *
+ * Every renderer, exit code, session and approval decision should read this rather
+ * than re-derive its own idea of what happened. The point is not bookkeeping: a run
+ * that turned files away, skipped checks it could not supply, or stopped on a budget
+ * still produces a findings list, and a findings list on its own cannot tell a reader
+ * which of those it is. `selected = completed ∪ reused ∪ failed ∪ waived` is the
+ * invariant that makes "no findings" mean something.
+ */
+export class RunManifest {
+    id;
+    units = [];
+    ranChecks = [];
+    startedAt = new Date().toISOString();
+    constructor(id) {
+        this.id = id;
+    }
+    unit(record) {
+        this.units.push(record);
+    }
+    ran(check) {
+        this.ranChecks.push(check);
+    }
+    build(parts) {
+        const completion = completionOf({
+            files: parts.files,
+            units: this.units,
+            skippedChecks: parts.skippedChecks,
+            failures: parts.failures,
+            cancelled: parts.cancelled,
+            budgetStop: parts.budgetStop,
+        });
+        return {
+            schema: SCHEMA,
+            id: this.id,
+            operation: parts.operation,
+            started: this.startedAt,
+            ended: new Date().toISOString(),
+            repository: { head: parts.repositoryHead },
+            target: parts.target,
+            policy: parts.policy,
+            engine: parts.engine,
+            files: parts.files.map((file) => ({
+                ...file,
+                checks: [...file.checks],
+                missing: file.missing ? [...file.missing] : undefined,
+            })),
+            units: this.units.map((unit) => ({ ...unit })),
+            checks: {
+                ran: [...this.ranChecks],
+                skipped: parts.skippedChecks.map((check) => ({ ...check })),
+            },
+            findings: { ...parts.findings },
+            usage: { ...parts.usage },
+            state: completion.state,
+            failures: [...parts.failures],
+            notLookedAt: [...completion.notLookedAt],
+        };
+    }
+}
+/** Why this run is less than a full review, said once in words a reader can act on. */
+function reasons(files, units, skipped, failures, cancelled, budgetStop) {
+    const out = [...failures];
+    if (cancelled)
+        out.push('cancelled before every unit was judged');
+    if (budgetStop)
+        out.push('stopped early: ' + budgetStop);
+    const group = (items, label) => {
+        if (items.length > 0)
+            out.push(label(items.length) + ': ' + items.slice(0, 5).join(', ') + (items.length > 5 ? ', …' : ''));
+    };
+    group(files.filter((f) => f.disposition === 'failed').map((f) => f.path), (n) => n + ' file(s) could not be read');
+    group(files.filter((f) => f.disposition === 'selected' && f.missing?.length).map((f) => f.path + ' (no ' + f.missing.join(', ') + ')'), (n) => n + ' file(s) reviewed with fewer checks than the rest');
+    group(units.filter((u) => u.outcome === 'failed' || u.outcome === 'waived').map((u) => u.judge + ' · ' + u.unit), (n) => n + ' judge unit(s) never answered');
+    group(skipped.map((s) => s.check + ' (no ' + s.missing + ')'), (n) => n + ' check(s) had no oracle to run against');
+    return [...new Set(out)];
+}
+/**
+ * The coverage contract, checked rather than asserted in prose.
+ *
+ * Returns what is wrong, empty when the manifest accounts for everything it selected.
+ * A manifest that fails this is a bug in PowerShot, not a finding about the code.
+ */
+export function coverageProblems(m) {
+    const problems = [];
+    const dispositions = new Set(['selected', 'waived', 'failed']);
+    const checksByFile = new Set();
+    for (const f of m.files) {
+        if (!dispositions.has(f.disposition))
+            problems.push(f.path + ': unknown disposition ' + f.disposition);
+        if (f.disposition !== 'selected' && !f.reason)
+            problems.push(f.path + ': ' + f.disposition + ' without a reason');
+        if (!Array.isArray(f.checks)) {
+            problems.push(f.path + ': missing per-file checks');
+            continue;
+        }
+        if (f.disposition !== 'selected' && f.checks.length > 0) {
+            problems.push(f.path + ': ' + f.disposition + ' file received checks');
+        }
+        const local = new Set();
+        for (const check of f.checks) {
+            if (local.has(check))
+                problems.push(f.path + ': received check twice: ' + check);
+            local.add(check);
+            checksByFile.add(check);
+        }
+    }
+    const seen = new Set();
+    for (const u of m.units) {
+        const key = u.judge + '|' + u.unit;
+        if (seen.has(key))
+            problems.push('unit counted twice: ' + key);
+        seen.add(key);
+        if (u.outcome !== 'completed' && !u.reason)
+            problems.push(key + ': ' + u.outcome + ' without a reason');
+    }
+    const ran = new Set();
+    for (const check of m.checks.ran) {
+        if (ran.has(check))
+            problems.push('check counted twice as ran: ' + check);
+        ran.add(check);
+    }
+    for (const check of checksByFile) {
+        if (!ran.has(check))
+            problems.push('file received a check not recorded as ran: ' + check);
+    }
+    for (const check of ran) {
+        if (!checksByFile.has(check))
+            problems.push('ran check received no selected file: ' + check);
+    }
+    const skipped = new Set();
+    for (const check of m.checks.skipped) {
+        if (skipped.has(check.check))
+            problems.push('check counted twice as skipped: ' + check.check);
+        skipped.add(check.check);
+        if (ran.has(check.check))
+            problems.push('check counted as both ran and skipped: ' + check.check);
+    }
+    // a judged run that reports complete must have reached every unit it selected
+    const unreached = m.units.filter((u) => u.outcome === 'failed' || u.outcome === 'waived');
+    if (m.state === 'complete' && unreached.length > 0) {
+        problems.push('state is complete but ' + unreached.length + ' unit(s) were never judged');
+    }
+    if (m.state === 'complete' && m.files.some((f) => f.disposition === 'failed')) {
+        problems.push('state is complete but a file failed selection');
+    }
+    const limited = m.files.filter((f) => f.disposition === 'selected' && f.missing?.length);
+    if (m.state === 'complete' && limited.length > 0) {
+        problems.push('state is complete but ' + limited.length + ' file(s) were reviewed with fewer checks');
+    }
+    if (m.state === 'complete' && m.checks.skipped.length > 0) {
+        problems.push('state is complete but ' + m.checks.skipped.length + ' check(s) had no oracle');
+    }
+    if (m.state === 'complete' && m.notLookedAt.length > 0) {
+        problems.push('state is complete but notLookedAt is not empty');
+    }
+    if (m.state === 'complete' && m.failures.length > 0) {
+        problems.push('state is complete but failures are not empty');
+    }
+    if (m.state !== 'complete' && m.notLookedAt.length === 0) {
+        problems.push('state is ' + m.state + ' but notLookedAt is empty');
+    }
+    return problems;
+}
+/** Manifests hold paths and reasons from the reviewed tree; keep the last few. */
+const KEEP = 100;
+export function writeManifest(root, m) {
+    const dir = join(root, '.powershot', 'runs');
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    try {
+        const old = readdirSync(dir)
+            .filter((n) => n.endsWith('.json'))
+            .map((name) => ({ name, at: statSync(join(dir, name)).mtimeMs }))
+            .sort((a, b) => a.at - b.at);
+        for (const { name } of old.slice(0, Math.max(0, old.length - KEEP + 1)))
+            rmSync(join(dir, name), { force: true });
+    }
+    catch {
+        // housekeeping must never be the reason a finished review fails to record itself
+    }
+    const file = join(dir, m.id + '.json');
+    writeFileSync(file, JSON.stringify(m, null, 2), { mode: 0o600 });
+    return file;
+}
+export function hashOf(text) {
+    return createHash('sha256').update(text).digest('hex').slice(0, 16);
+}
+//# sourceMappingURL=manifest.js.map

package/dist/otel.js

@@ -0,0 +1,75 @@
+import { randomBytes } from 'node:crypto';
+import { PACKAGE_VERSION } from './package-meta.js';
+const HEX = (n) => randomBytes(n).toString('hex');
+export class Trace {
+    spans = [];
+    traceId = HEX(16);
+    endpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+    get enabled() {
+        return Boolean(this.endpoint);
+    }
+    /** Returns a function that closes the span; a no-op when tracing is off. */
+    span(name, attrs = {}) {
+        if (!this.enabled)
+            return () => { };
+        const s = { name, start: Date.now(), attrs };
+        this.spans.push(s);
+        return (extra) => {
+            s.end = Date.now();
+            Object.assign(s.attrs, extra ?? {});
+        };
+    }
+    /**
+     * Never throws and never blocks a review: a collector that is down, slow, or absent
+     * must not turn a completed review into a failed command.
+     */
+    async flush() {
+        if (!this.enabled || this.spans.length === 0)
+            return;
+        const url = this.endpoint.replace(/\/+$/, '') + '/v1/traces';
+        const body = {
+            resourceSpans: [
+                {
+                    resource: {
+                        attributes: [
+                            { key: 'service.name', value: { stringValue: 'powershot' } },
+                            { key: 'service.version', value: { stringValue: PACKAGE_VERSION } },
+                        ],
+                    },
+                    scopeSpans: [
+                        {
+                            scope: { name: 'powershot' },
+                            spans: this.spans.map((s) => ({
+                                traceId: this.traceId,
+                                spanId: HEX(8),
+                                name: s.name,
+                                kind: 1,
+                                startTimeUnixNano: String(s.start * 1_000_000),
+                                endTimeUnixNano: String((s.end ?? Date.now()) * 1_000_000),
+                                attributes: Object.entries(s.attrs).map(([key, v]) => ({
+                                    key,
+                                    value: typeof v === 'number' ? { intValue: String(Math.round(v)) } : { stringValue: String(v) },
+                                })),
+                            })),
+                        },
+                    ],
+                },
+            ],
+        };
+        try {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), 3000);
+            await fetch(url, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+            clearTimeout(timer);
+        }
+        catch {
+            // telemetry is never worth failing a review over
+        }
+    }
+}
+//# sourceMappingURL=otel.js.map

package/dist/package-meta.js

@@ -0,0 +1,13 @@
+import { createRequire } from 'node:module';
+const metadata = (() => {
+    try {
+        return createRequire(import.meta.url)('../package.json');
+    }
+    catch {
+        return {};
+    }
+})();
+export const PACKAGE_NAME = metadata.name ?? '@0xcraft/powershot';
+export const PACKAGE_VERSION = metadata.version ?? 'unknown';
+export const PACKAGE_HOMEPAGE = metadata.homepage ?? 'https://github.com/xcrft/powershot';
+//# sourceMappingURL=package-meta.js.map

package/dist/package-smoke.js

@@ -0,0 +1,110 @@
+// Install one tarball into an empty project and exercise the public binary. When a
+// path is supplied, this script never packs again: release can test and publish the
+// exact bytes whose checksum it recorded.
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+const repo = process.cwd();
+const dir = mkdtempSync(join(tmpdir(), 'powershot-smoke-'));
+const supplied = process.argv[2];
+const packageName = JSON.parse(readFileSync(join(repo, 'package.json'), 'utf8')).name;
+const run = (command, args, cwd = dir) => execFileSync(command, args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+let failed = 0;
+const check = (name, fn) => {
+    try {
+        fn();
+        console.log('  ok   ' + name);
+    }
+    catch (error) {
+        failed++;
+        const failure = error;
+        console.log('  FAIL ' + name + '\n       ' + String(failure.stderr ?? failure.message));
+    }
+};
+try {
+    let tarball;
+    if (supplied) {
+        tarball = resolve(repo, supplied);
+        if (!existsSync(tarball))
+            throw new Error('tarball does not exist: ' + tarball);
+        console.log('using ' + tarball);
+    }
+    else {
+        console.log('packing');
+        run('npm', ['pack', '--pack-destination', dir], repo);
+        const packed = readdirSync(dir).find((file) => file.endsWith('.tgz'));
+        if (!packed)
+            throw new Error('npm pack produced no tarball');
+        tarball = join(dir, packed);
+    }
+    console.log('installing into a clean tree');
+    writeFileSync(join(dir, 'package.json'), '{"name":"smoke","private":true}');
+    run('npm', ['install', '--silent', '--no-audit', '--no-fund', tarball]);
+    run('git', ['init', '-q', '.']);
+    run('git', ['config', 'user.email', 'smoke@test']);
+    run('git', ['config', 'user.name', 'smoke']);
+    writeFileSync(join(dir, 'tsconfig.json'), '{"compilerOptions":{"strict":true},"include":["*.ts"]}');
+    writeFileSync(join(dir, 'a.ts'), 'export function f() {\n  try { JSON.parse("{}") } catch {}\n}\n');
+    run('git', ['add', '-A']);
+    run('git', ['commit', '-qm', 'seed']);
+    const bin = (name) => join(dir, 'node_modules', '.bin', process.platform === 'win32' ? name + '.cmd' : name);
+    const psh = bin('psh');
+    const powershot = bin('powershot');
+    console.log('\nsmoke');
+    check('both public commands are linked and print help', () => {
+        if (!run(psh, ['--help']).includes('psh review'))
+            throw new Error('unexpected help output');
+        if (!run(powershot, ['--help']).includes('psh review'))
+            throw new Error('unexpected long-command help output');
+    });
+    check('the package ships architecture and CI examples', () => {
+        const installed = join(dir, 'node_modules', ...packageName.split('/'));
+        if (!existsSync(join(installed, 'docs', 'architecture.md')))
+            throw new Error('architecture guide is missing');
+        if (!existsSync(join(installed, 'docs', 'ci.md')))
+            throw new Error('CI guide is missing');
+        if (!existsSync(join(installed, 'examples', 'github-actions', 'cli.yml')))
+            throw new Error('CI example is missing');
+        if (!existsSync(join(installed, 'examples', 'gitlab', '.gitlab-ci.yml')))
+            throw new Error('GitLab example is missing');
+    });
+    check('a scan from the installed package finds a real defect', () => {
+        try {
+            run(psh, ['scan', 'a.ts', '--verify-only', '--format', 'compact']);
+            throw new Error('expected exit 1 for a finding');
+        }
+        catch (error) {
+            const failure = error;
+            if (failure.status !== 1)
+                throw error;
+            if (!String(failure.stdout).includes('swallowed-error'))
+                throw new Error('no finding: ' + String(failure.stdout));
+        }
+    });
+    check('a clean tree exits 0', () => {
+        writeFileSync(join(dir, 'b.ts'), 'export const b = 1\n');
+        run(psh, ['scan', 'b.ts', '--verify-only']);
+    });
+    check('a bundled foreign-language pack loads', () => {
+        writeFileSync(join(dir, 'c.py'), 'def f():\n    try:\n        g()\n    except Exception:\n        pass\n');
+        try {
+            run(psh, ['scan', 'c.py', '--verify-only', '--checks', 'foreign-swallowed-error', '--format', 'compact']);
+            throw new Error('expected a finding from the python pack');
+        }
+        catch (error) {
+            if (error.status !== 1)
+                throw error;
+        }
+    });
+}
+finally {
+    rmSync(dir, { recursive: true, force: true });
+}
+console.log('');
+if (failed > 0) {
+    console.error(failed + ' smoke check(s) failed');
+    process.exit(1);
+}
+console.log('the package artifact works');
+//# sourceMappingURL=package-smoke.js.map

package/dist/plan.js

@@ -0,0 +1,134 @@
+import { statSync } from 'node:fs';
+import { insideRepo, isSymlink } from './fspolicy.js';
+import { matchesAny } from './config.js';
+import { packFor } from './lang/packs.js';
+import { pyrightAvailable } from './lang/pyright.js';
+/**
+ * Past this a file is generated, minified or vendored rather than written. What is
+ * turned away is recorded as an outcome, not printed and forgotten.
+ */
+const MAX_FILE_BYTES = 512 * 1024;
+const TS = /\.(ts|tsx|mts|cts|js|jsx|mjs|cjs)$/;
+/**
+ * One answer to "what is this run about", shared by everything that needs it.
+ *
+ * Every file the change touches ends in exactly one disposition: reviewed, waived by
+ * a policy someone wrote down, or failed because we could not look. Scattering those
+ * decisions across the pipeline is what let a run turn a file away in a progress line
+ * and still report the result as clean — the reader saw a summary that had no idea
+ * the file existed.
+ */
+export class SelectionPlan {
+    rows;
+    constructor(rows) {
+        this.rows = rows;
+    }
+    static build(root, changed, config) {
+        const rows = new Map();
+        for (const c of changed) {
+            const abs = insideRepo(root, c.path);
+            const bytes = abs ? (statSync(abs, { throwIfNoEntry: false })?.size ?? 0) : 0;
+            const item = {
+                path: c.path,
+                disposition: 'selected',
+                bytes,
+                addedLines: c.added.size,
+                language: packFor(c.path)?.name ?? (TS.test(c.path) ? 'typescript' : 'other'),
+                checks: [],
+            };
+            if (!abs || isSymlink(abs)) {
+                item.disposition = 'failed';
+                item.reason = 'outside the repository, or a link that leaves it';
+            }
+            else if (matchesAny(c.path, config.ignore)) {
+                item.disposition = 'waived';
+                item.reason = 'ignored by config';
+            }
+            else if (bytes > MAX_FILE_BYTES) {
+                item.disposition = 'waived';
+                item.reason = 'over ' + Math.round(MAX_FILE_BYTES / 1024) + 'KB — generated or minified, not written';
+            }
+            rows.set(c.path, item);
+        }
+        return new SelectionPlan(rows);
+    }
+    /** A policy decision: it was not reviewed, and that is the intended outcome. */
+    waive(path, reason) {
+        const row = this.rows.get(path);
+        if (row && row.disposition === 'selected') {
+            row.disposition = 'waived';
+            row.reason = reason;
+        }
+    }
+    /** Reviewed, but with less than the run's full check set. */
+    limit(path, missing) {
+        const row = this.rows.get(path);
+        if (row && row.disposition === 'selected' && missing.length > 0) {
+            row.missing = [...new Set([...(row.missing ?? []), ...missing])];
+        }
+    }
+    /** Record coverage at the same file granularity used to decide applicability. */
+    checked(path, check) {
+        const row = this.rows.get(path);
+        if (row && row.disposition === 'selected') {
+            row.checks = [...new Set([...row.checks, check])];
+        }
+    }
+    /** We meant to review it and could not. This is what makes a run incomplete. */
+    fail(path, reason) {
+        const row = this.rows.get(path);
+        if (row) {
+            row.disposition = 'failed';
+            row.reason = reason;
+        }
+    }
+    keep(changed) {
+        return changed.filter((c) => this.rows.get(c.path)?.disposition === 'selected');
+    }
+    items() {
+        return [...this.rows.values()];
+    }
+    of(disposition) {
+        return this.items().filter((i) => i.disposition === disposition);
+    }
+    /** What a reader should be told about, grouped so one line covers many files. */
+    summary() {
+        const byReason = new Map();
+        for (const i of this.items()) {
+            if (i.disposition === 'selected')
+                continue;
+            const key = i.disposition + ': ' + (i.reason ?? 'unknown');
+            byReason.set(key, (byReason.get(key) ?? 0) + 1);
+        }
+        const limited = this.items().filter((i) => i.disposition === 'selected' && i.missing?.length);
+        const out = [...byReason].map(([reason, n]) => n + ' file(s) ' + reason);
+        if (limited.length > 0) {
+            out.push(limited.length + ' file(s) reviewed without ' + [...new Set(limited.flatMap((i) => i.missing))].join(', '));
+        }
+        return out;
+    }
+}
+/**
+ * What the ground can actually answer, which is not always what was asked for.
+ *
+ * A repository with no tsconfig has no member resolution and no reference graph; a
+ * scan has no base version to compare against. Working this out once, here, is what
+ * lets a check declare `needs` instead of each one rediscovering it.
+ */
+export function capabilitiesOf(g) {
+    const caps = new Set(['syntax']);
+    if (g.typed) {
+        caps.add('types');
+        caps.add('references');
+    }
+    // Kept apart from `types` on purpose. A repository with a tsconfig and some Python
+    // in it would otherwise satisfy the Python check through the TypeScript checker,
+    // and the check would be recorded as run and satisfied with no oracle behind it.
+    if (g.foreign.some((f) => f.pack.name === 'python') && pyrightAvailable(g.root)) {
+        caps.add('python-types');
+    }
+    if (g.changed.some((c) => c.before !== undefined))
+        caps.add('base');
+    return caps;
+}
+//# sourceMappingURL=plan.js.map

package/dist/position.js

@@ -0,0 +1,94 @@
+import { reviewables, shownLines } from './bundle.js';
+import { lines as splitLines } from './text.js';
+const CONTEXT_LINES = 1;
+/** undefined when the span cannot be pointed at: a caret in the wrong column accuses
+ *  the wrong token. */
+export function caretFor(span, lineText, dedent) {
+    if (!span || lineText === undefined)
+        return undefined;
+    const offset = span.column - 1 - dedent;
+    if (offset < 0 || offset >= lineText.length)
+        return undefined;
+    return { offset, length: Math.max(1, Math.min(span.length, lineText.length - offset)) };
+}
+/**
+ * A model writes its own file and line, so it can point anywhere.
+ *
+ * Being inside the file is not enough: a judge is only shown the changed lines and a
+ * little context, so a finding outside that window is about code the model never saw.
+ * Which of the two justified it is recorded, because "the change did this" and "the
+ * change sits next to this" are different claims for a reader to weigh.
+ */
+export function positionable(findings, g) {
+    const files = reviewables(g);
+    const lineCount = new Map(files.map((r) => [r.path, splitLines(r.text).length]));
+    const added = new Map(files.map((r) => [r.path, r.added]));
+    const shown = shownLines(files);
+    const kept = [];
+    for (const f of findings) {
+        if (f.class === 'verified') {
+            kept.push(f);
+            continue;
+        }
+        const total = lineCount.get(f.file);
+        if (total === undefined || f.line < 1 || f.line > total)
+            continue;
+        if (added.get(f.file)?.has(f.line))
+            kept.push({ ...f, positioning: 'added' });
+        else if (shown.get(f.file)?.has(f.line))
+            kept.push({ ...f, positioning: 'context' });
+    }
+    return { kept, dropped: findings.length - kept.length };
+}
+/** From the source that was analysed, not from disk — an old commit differs. */
+export function attachFrames(findings, g) {
+    const byFile = new Map();
+    for (const { sf, changed } of g.files)
+        byFile.set(changed.path, splitLines(sf.getFullText()));
+    for (const f of g.foreign)
+        byFile.set(f.path, splitLines(f.tree.rootNode.text));
+    return findings.map((f) => {
+        const lines = byFile.get(f.file);
+        if (!lines || f.line < 1 || f.line > lines.length)
+            return f;
+        const firstLine = Math.max(1, f.line - CONTEXT_LINES);
+        const lastLine = Math.min(lines.length, f.line + CONTEXT_LINES);
+        let start = firstLine;
+        let slice = lines.slice(firstLine - 1, lastLine).map((l) => l.replace(/\s+$/, ''));
+        while (slice.length > 1 && slice[0] === '' && start < f.line) {
+            slice = slice.slice(1);
+            start++;
+        }
+        while (slice.length > 1 && slice[slice.length - 1] === '')
+            slice = slice.slice(0, -1);
+        const indents = slice.filter((l) => l.trim() !== '').map((l) => l.length - l.trimStart().length);
+        const dedent = indents.length > 0 ? Math.min(...indents) : 0;
+        const rendered = slice.map((l) => l.slice(dedent));
+        // dedented coordinates, so the renderer only counts characters
+        const caret = caretFor(f.span, rendered[f.line - start], dedent);
+        // the whole line as it would be committed: untouched source, not the frame
+        let suggestion;
+        const original = lines[f.line - 1];
+        if (f.replacement !== undefined && f.span && original !== undefined) {
+            const from = f.span.column - 1;
+            if (from >= 0 && from + f.span.length <= original.length) {
+                suggestion = original.slice(0, from) + f.replacement + original.slice(from + f.span.length);
+            }
+        }
+        else if (f.suggestion !== undefined && original !== undefined) {
+            suggestion = validateSuggestion(f.suggestion, original);
+        }
+        return { ...f, suggestion, frame: { firstLine: start, lines: rendered, caret } };
+    });
+}
+/**
+ * Indentation always from the file, never the model: measured, a judge that got the
+ * fix exactly right returned it at four spaces where the file used two.
+ */
+export function validateSuggestion(suggested, original) {
+    const body = suggested.trim();
+    if (body === '' || body === original.trim())
+        return undefined;
+    return (/^\s*/.exec(original)?.[0] ?? '') + body;
+}
+//# sourceMappingURL=position.js.map

package/dist/report/ansi.js

@@ -0,0 +1,18 @@
+/**
+ * Colour is opt-out via NO_COLOR and off automatically when piped, so redirecting
+ * to a file or a PR comment never lands escape codes in the output.
+ */
+export const COLOR = process.env.NO_COLOR === undefined &&
+    (process.env.FORCE_COLOR !== undefined || process.stdout.isTTY === true);
+const ESC = '[';
+export const paint = (code) => (s) => (COLOR ? ESC + code + 'm' + s + ESC + '0m' : s);
+export const dim = paint('2');
+export const bold = paint('1');
+export const red = paint('31');
+export const brightRed = paint('91');
+export const green = paint('32');
+export const steel = paint('36');
+export const yellow = paint('33');
+export const magenta = paint('35');
+export const gray = paint('90');
+//# sourceMappingURL=ansi.js.map

package/dist/report/codequality.js

@@ -0,0 +1,19 @@
+import { createHash } from 'node:crypto';
+function level(s) {
+    return s === 'critical' ? 'blocker' : s === 'high' ? 'major' : s === 'medium' ? 'minor' : 'info';
+}
+/**
+ * GitLab Code Quality — the format that renders findings inside a merge request
+ * rather than in a job log. The fingerprint must be stable across runs, or GitLab
+ * reports every finding as new on each pipeline.
+ */
+export function codeQuality(findings) {
+    return (JSON.stringify(findings.map((f) => ({
+        description: f.title,
+        check_name: f.check,
+        fingerprint: createHash('sha1').update(f.check + f.file + f.line + f.title).digest('hex'),
+        severity: level(f.severity),
+        location: { path: f.file, lines: { begin: f.line } },
+    })), null, 2) + '\n');
+}
+//# sourceMappingURL=codequality.js.map