samey-cli 0.0.0-stage → 0.1.0

package/dist/rules/functional.js

@@ -0,0 +1,467 @@
+import { truncate } from '../util/text.js';
+import { el, pagesWith, plural, uniqueRoutes } from './helpers.js';
+export const pageLoadFailed = {
+    id: 'page-load-failed',
+    title: 'Page failed to load',
+    category: 'functional',
+    needs: 'rendered',
+    verified: true,
+    penalty: 80,
+    description: 'A page timed out or errored during navigation.',
+    run({ crawl }) {
+        return (crawl?.pages ?? [])
+            .filter((p) => p.error && !p.desktop)
+            .map((p) => ({
+            title: `Page failed to load: ${p.path}`,
+            severity: 'critical',
+            confidence: 0.9,
+            description: `Navigating to ${p.url} failed: ${p.error}`,
+            recommendation: 'Open the page locally and check the server log. If it is slow rather than broken, raise --timeout.',
+            evidence: [{ type: 'network', route: p.path, detail: p.error }],
+            routes: [p.path],
+        }));
+    },
+};
+export const brokenLinks = {
+    id: 'broken-internal-links',
+    title: 'Broken internal links',
+    category: 'functional',
+    needs: 'rendered',
+    verified: true,
+    penalty: 50,
+    description: 'Internal links that return an error status or fail to load.',
+    run({ crawl }) {
+        const links = (crawl?.brokenLinks ?? []).filter((l) => l.from !== '(route hint)');
+        if (!links.length)
+            return [];
+        const ev = links.map((l) => ({
+            type: 'network',
+            route: l.from.startsWith('/') ? l.from : undefined,
+            excerpt: l.url,
+            detail: l.status ? `HTTP ${l.status}` : (l.error ?? 'request failed'),
+        }));
+        return [
+            {
+                severity: 'high',
+                confidence: 0.9,
+                description: `${plural(links.length, 'internal link')} lead to pages that do not load.`,
+                recommendation: 'Fix the target route or update the link. Remove navigation entries for pages that do not exist yet.',
+                evidence: ev,
+                routes: uniqueRoutes(ev),
+            },
+        ];
+    },
+};
+export const consoleErrors = {
+    id: 'console-errors',
+    title: 'JavaScript errors in the console',
+    category: 'functional',
+    needs: 'rendered',
+    verified: true,
+    penalty: 45,
+    description: 'Uncaught exceptions and console.error output during page load.',
+    run({ crawl }) {
+        const ev = [];
+        for (const p of crawl?.pages ?? [])
+            for (const e of p.consoleErrors.slice(0, 5))
+                ev.push({ type: 'console', route: p.path, excerpt: truncate(e, 220) });
+        if (!ev.length)
+            return [];
+        const uncaught = ev.filter((e) => e.excerpt?.startsWith('Uncaught')).length;
+        return [
+            {
+                severity: uncaught ? 'high' : 'medium',
+                confidence: 0.9,
+                description: `${plural(ev.length, 'console error')} on ${plural(uniqueRoutes(ev).length, 'page')}${uncaught ? `, including ${uncaught} uncaught exception${uncaught === 1 ? '' : 's'}` : ''}.`,
+                recommendation: 'Open the browser console on each listed page and fix the errors; uncaught exceptions often mean a feature silently does not work.',
+                evidence: ev,
+                routes: uniqueRoutes(ev),
+            },
+        ];
+    },
+};
+export const failedRequests = {
+    id: 'failed-requests',
+    title: 'Failed asset requests',
+    category: 'functional',
+    needs: 'rendered',
+    verified: true,
+    description: 'Scripts, styles, images, or API calls that returned errors or failed.',
+    run({ crawl }) {
+        const ev = [];
+        let critical = 0;
+        for (const p of crawl?.pages ?? []) {
+            for (const r of p.failedRequests) {
+                if (r.resourceType === 'document' && r.url.replace(/\/$/, '') === p.url.replace(/\/$/, ''))
+                    continue; // reported as a broken page
+                if (/favicon\.ico$/.test(r.url))
+                    continue;
+                if (['script', 'stylesheet', 'document'].includes(r.resourceType))
+                    critical++;
+                ev.push({ type: 'network', route: p.path, excerpt: truncate(r.url, 140), detail: `${r.resourceType}: ${r.status ? `HTTP ${r.status}` : r.failure}` });
+            }
+        }
+        if (!ev.length)
+            return [];
+        return [
+            {
+                severity: critical ? 'high' : 'medium',
+                confidence: 0.9,
+                description: `${plural(ev.length, 'request')} failed while loading pages${critical ? `, ${critical} of them scripts, styles, or documents` : ''}.`,
+                recommendation: 'Fix the asset paths or remove references to files that do not exist.',
+                evidence: ev,
+                routes: uniqueRoutes(ev),
+            },
+        ];
+    },
+};
+export const deadLinks = {
+    id: 'placeholder-links',
+    title: 'Links that go nowhere',
+    category: 'functional',
+    needs: 'rendered',
+    verified: true,
+    description: 'Links with href="#", an empty href, or javascript: URLs.',
+    run({ crawl }) {
+        const ev = [];
+        for (const { page, facts } of pagesWith(crawl, 'desktop')) {
+            for (const l of facts.links) {
+                const h = l.href.trim();
+                if (h === '#' || h === '' || /^javascript:(?:void\(0\);?|;)?$/i.test(h))
+                    ev.push(el(page, 'desktop', l, l.text || '(no text)', `href="${h}"`));
+            }
+        }
+        if (!ev.length)
+            return [];
+        return [
+            {
+                severity: ev.length >= 5 ? 'high' : 'medium',
+                confidence: 0.9,
+                description: `${plural(ev.length, 'link')} point to "#" or nowhere. These look clickable and do nothing, which is common in generated navigation and footers.`,
+                recommendation: 'Point each link at a real page, turn it into a button if it triggers an action, or remove it.',
+                evidence: ev,
+                routes: uniqueRoutes(ev),
+            },
+        ];
+    },
+};
+export const unresponsiveButtons = {
+    id: 'unresponsive-buttons',
+    title: 'Buttons that do nothing',
+    category: 'functional',
+    needs: 'rendered',
+    verified: false,
+    description: 'Safe-to-click buttons that produced no navigation, DOM change, or error when clicked.',
+    run({ crawl }) {
+        const ev = [];
+        const errors = [];
+        for (const p of crawl?.pages ?? []) {
+            for (const i of p.interactions) {
+                if (i.outcome === 'no-effect')
+                    ev.push({ type: 'dom', route: p.path, viewport: 'desktop', selector: i.selector, rect: i.rect, excerpt: i.text });
+                if (i.outcome === 'error')
+                    errors.push({ type: 'dom', route: p.path, viewport: 'desktop', selector: i.selector, rect: i.rect, excerpt: i.text, detail: i.detail });
+            }
+        }
+        const out = [];
+        if (ev.length)
+            out.push({
+                severity: 'medium',
+                confidence: 0.6,
+                description: `${plural(ev.length, 'button')} produced no visible change when clicked (no navigation, no DOM update). Hover-only or CSS-only effects can cause false positives, so confirm by hand.`,
+                recommendation: 'Wire the button to its action, or remove it. If it is a placeholder for a future feature, hide it until the feature exists.',
+                evidence: ev,
+                routes: uniqueRoutes(ev),
+            });
+        if (errors.length)
+            out.push({
+                title: 'Buttons that throw errors',
+                severity: 'high',
+                confidence: 0.9,
+                description: `${plural(errors.length, 'button')} threw a JavaScript error when clicked.`,
+                recommendation: 'Fix the click handler; the error message is shown with each item.',
+                evidence: errors,
+                routes: uniqueRoutes(errors),
+            });
+        return out;
+    },
+};
+export const emptyControls = {
+    id: 'empty-controls',
+    title: 'Buttons and links without an accessible name',
+    category: 'accessibility',
+    needs: 'rendered',
+    verified: true,
+    description: 'Interactive elements with no text, aria-label, or title.',
+    run({ crawl }) {
+        const ev = [];
+        for (const { page, facts } of pagesWith(crawl, 'desktop')) {
+            for (const c of facts.controls)
+                if (!c.name.trim())
+                    ev.push(el(page, 'desktop', c, `<${c.tag}>`));
+            for (const l of facts.links)
+                if (!l.text.trim() && !facts.controls.some((c) => c.selector === l.selector))
+                    ev.push(el(page, 'desktop', l, `<a href="${truncate(l.href, 60)}">`));
+        }
+        if (!ev.length)
+            return [];
+        return [
+            {
+                severity: 'high',
+                confidence: 0.9,
+                description: `${plural(ev.length, 'interactive element')} have no accessible name. Screen readers announce them as just "button" or "link". Icon-only buttons are the usual cause.`,
+                recommendation: 'Add an aria-label to icon-only buttons and links, or include visually hidden text.',
+                evidence: ev,
+                routes: uniqueRoutes(ev),
+            },
+        ];
+    },
+};
+export const brokenImages = {
+    id: 'broken-images',
+    title: 'Broken images',
+    category: 'functional',
+    needs: 'rendered',
+    verified: true,
+    description: 'Images that failed to load.',
+    run({ crawl }) {
+        const ev = [];
+        for (const { page, facts } of pagesWith(crawl, 'desktop'))
+            for (const i of facts.images)
+                if (i.broken)
+                    ev.push(el(page, 'desktop', i, truncate(i.src, 120)));
+        if (!ev.length)
+            return [];
+        return [
+            {
+                severity: 'medium',
+                confidence: 0.9,
+                description: `${plural(ev.length, 'image')} failed to load.`,
+                recommendation: 'Fix the image paths or remove the images.',
+                evidence: ev,
+                routes: uniqueRoutes(ev),
+            },
+        ];
+    },
+};
+export const missingAlt = {
+    id: 'missing-alt',
+    title: 'Images without alt text',
+    category: 'accessibility',
+    needs: 'rendered',
+    verified: true,
+    description: 'Images with no alt attribute.',
+    run({ crawl }) {
+        const ev = [];
+        for (const { page, facts } of pagesWith(crawl, 'desktop'))
+            for (const i of facts.images)
+                if (i.alt === null && !i.decorative)
+                    ev.push(el(page, 'desktop', i, truncate(i.src, 120)));
+        if (!ev.length)
+            return [];
+        return [
+            {
+                severity: 'medium',
+                confidence: 0.9,
+                description: `${plural(ev.length, 'image')} have no alt attribute.`,
+                recommendation: 'Describe informative images in alt text; use alt="" for purely decorative ones.',
+                evidence: ev,
+                routes: uniqueRoutes(ev),
+            },
+        ];
+    },
+};
+export const unlabeledInputs = {
+    id: 'unlabeled-inputs',
+    title: 'Form fields without labels',
+    category: 'accessibility',
+    needs: 'rendered',
+    verified: true,
+    description: 'Inputs with no associated label or aria-label. Placeholders are not labels.',
+    run({ crawl }) {
+        const ev = [];
+        for (const { page, facts } of pagesWith(crawl, 'desktop'))
+            for (const i of facts.unlabeledInputs)
+                ev.push(el(page, 'desktop', i, `<${i.type}>`));
+        if (!ev.length)
+            return [];
+        return [
+            {
+                severity: 'medium',
+                confidence: 0.9,
+                description: `${plural(ev.length, 'form field')} have no label. Placeholder text disappears on input and is not announced reliably.`,
+                recommendation: 'Add a visible <label for=...> to each field, or aria-label where a visible label truly does not fit.',
+                evidence: ev,
+                routes: uniqueRoutes(ev),
+            },
+        ];
+    },
+};
+export const headingStructure = {
+    id: 'heading-structure',
+    title: 'Heading structure problems',
+    category: 'accessibility',
+    needs: 'rendered',
+    verified: true,
+    description: 'Pages with no h1, several h1s, or skipped heading levels.',
+    run({ crawl }) {
+        const ev = [];
+        for (const { page, facts } of pagesWith(crawl, 'desktop')) {
+            const h1 = facts.headings.filter((h) => h.level === 1);
+            if (h1.length === 0)
+                ev.push({ type: 'metric', route: page.path, detail: 'no h1' });
+            if (h1.length > 1)
+                ev.push({ type: 'metric', route: page.path, detail: `${h1.length} h1 elements` });
+            let prev = 0;
+            for (const h of facts.headings) {
+                if (prev && h.level > prev + 1) {
+                    ev.push(el(page, 'desktop', h, truncate(h.text, 60), `h${prev} followed by h${h.level}`));
+                    break;
+                }
+                prev = h.level;
+            }
+        }
+        if (!ev.length)
+            return [];
+        return [
+            {
+                severity: 'low',
+                confidence: 0.9,
+                description: `${plural(uniqueRoutes(ev).length, 'page')} have heading structure problems. Headings are how assistive technology users skim a page.`,
+                recommendation: 'Use exactly one h1 per page and do not skip levels; style headings with CSS instead of picking tags for their size.',
+                evidence: ev,
+                routes: uniqueRoutes(ev),
+            },
+        ];
+    },
+};
+export const missingMetadata = {
+    id: 'missing-metadata',
+    title: 'Missing page metadata',
+    category: 'technical',
+    needs: 'rendered',
+    verified: true,
+    penalty: 25,
+    description: 'Missing <title>, meta description, or html lang attribute.',
+    run({ crawl }) {
+        const ev = [];
+        const titles = new Map();
+        for (const { page, facts } of pagesWith(crawl, 'desktop')) {
+            if (!facts.title.trim())
+                ev.push({ type: 'metric', route: page.path, detail: 'no <title>' });
+            else
+                titles.set(facts.title, [...(titles.get(facts.title) ?? []), page.path]);
+            if (!facts.metaDescription)
+                ev.push({ type: 'metric', route: page.path, detail: 'no meta description' });
+            if (!facts.lang)
+                ev.push({ type: 'metric', route: page.path, detail: 'no lang attribute on <html>' });
+        }
+        for (const [t, pages] of titles)
+            if (pages.length >= 3)
+                ev.push({ type: 'metric', route: pages[0], detail: `${pages.length} pages share the title "${truncate(t, 60)}"` });
+        if (!ev.length)
+            return [];
+        return [
+            {
+                severity: 'low',
+                confidence: 0.9,
+                description: `${plural(ev.length, 'metadata gap')} across ${plural(uniqueRoutes(ev).length, 'page')}.`,
+                recommendation: 'Give each page a unique title and description, and set <html lang>.',
+                evidence: ev,
+                routes: uniqueRoutes(ev),
+            },
+        ];
+    },
+};
+export const horizontalOverflow = {
+    id: 'horizontal-overflow',
+    title: 'Horizontal scrolling on mobile',
+    category: 'functional',
+    needs: 'rendered',
+    verified: true,
+    description: 'Content wider than the viewport, which causes sideways scrolling.',
+    run({ crawl }) {
+        const ev = [];
+        for (const vp of ['mobile', 'desktop']) {
+            for (const { page, facts } of pagesWith(crawl, vp)) {
+                if (facts.scrollWidth <= facts.width + 1)
+                    continue;
+                const offenders = facts.overflowing.slice(0, 3);
+                if (!offenders.length)
+                    ev.push({ type: 'metric', route: page.path, viewport: vp, detail: `page is ${facts.scrollWidth}px wide in a ${facts.width}px viewport` });
+                for (const o of offenders)
+                    ev.push(el(page, vp, o, undefined, `extends to ${o.right}px in a ${facts.width}px viewport`));
+            }
+        }
+        if (!ev.length)
+            return [];
+        const mobile = ev.filter((e) => e.viewport === 'mobile');
+        return [
+            {
+                severity: 'high',
+                confidence: 0.9,
+                description: `${plural(uniqueRoutes(ev).length, 'page')} scroll sideways${mobile.length ? ' on mobile' : ''}. Elements are wider than the screen.`,
+                recommendation: 'Find the listed elements and constrain them: max-width: 100%, flex-wrap, min-width: 0 on flex children, or overflow-x: auto on wide tables and code blocks.',
+                evidence: ev,
+                routes: uniqueRoutes(ev),
+            },
+        ];
+    },
+};
+export const smallTargets = {
+    id: 'small-touch-targets',
+    title: 'Touch targets too small',
+    category: 'accessibility',
+    needs: 'rendered',
+    verified: true,
+    description: 'Buttons and links smaller than 24x24 CSS pixels on mobile.',
+    run({ crawl }) {
+        const ev = [];
+        for (const { page, facts } of pagesWith(crawl, 'mobile'))
+            for (const t of facts.smallTargets)
+                ev.push(el(page, 'mobile', t, t.text || undefined, `${t.w}x${t.h}px`));
+        if (!ev.length)
+            return [];
+        return [
+            {
+                severity: ev.length >= 6 ? 'medium' : 'low',
+                confidence: 0.9,
+                description: `${plural(ev.length, 'control')} are smaller than 24x24px on mobile (WCAG 2.5.8 minimum).`,
+                recommendation: 'Increase padding on small controls so the tappable area is at least 24px, ideally 44px.',
+                evidence: ev,
+                routes: uniqueRoutes(ev),
+            },
+        ];
+    },
+};
+export const tinyText = {
+    id: 'tiny-text',
+    title: 'Text too small to read on mobile',
+    category: 'accessibility',
+    needs: 'rendered',
+    verified: true,
+    penalty: 25,
+    description: 'Text set below 12px on mobile.',
+    run({ crawl }) {
+        const ev = [];
+        for (const { page, facts } of pagesWith(crawl, 'mobile'))
+            for (const t of facts.tinyText)
+                ev.push(el(page, 'mobile', t, truncate(t.text, 60), `${t.size}px`));
+        if (ev.length < 3)
+            return [];
+        return [
+            {
+                severity: 'low',
+                confidence: 0.9,
+                description: `${plural(ev.length, 'text element')} are smaller than 12px on mobile.`,
+                recommendation: 'Keep body text at 16px and secondary text at 13 to 14px or larger on small screens.',
+                evidence: ev,
+                routes: uniqueRoutes(ev),
+            },
+        ];
+    },
+};
+export const functionalRules = [
+    pageLoadFailed, brokenLinks, consoleErrors, failedRequests, deadLinks, unresponsiveButtons, emptyControls, brokenImages,
+    missingAlt, unlabeledInputs, headingStructure, missingMetadata, horizontalOverflow, smallTargets, tinyText,
+];

package/dist/rules/helpers.d.ts

@@ -0,0 +1,11 @@
+import type { CrawlResult, ElementRef, Evidence, PageFacts, ViewportFacts, ViewportName } from '../types.js';
+export declare function pagesWith(crawl: CrawlResult | undefined, vp: ViewportName): {
+    page: PageFacts;
+    facts: ViewportFacts;
+}[];
+export declare function el(page: PageFacts, vp: ViewportName, ref: ElementRef, excerpt?: string, detail?: string): Evidence;
+export declare function plural(n: number, word: string, pluralWord?: string): string;
+export declare function uniqueRoutes(evidence: Evidence[]): string[];
+/** True if the element sits inside a header/nav/footer section of the page. */
+export declare function inChrome(facts: ViewportFacts, ref: ElementRef): boolean;
+export declare function topEntries(rec: Record<string, number>, n: number): [string, number][];

package/dist/rules/helpers.js

@@ -0,0 +1,29 @@
+export function pagesWith(crawl, vp) {
+    if (!crawl)
+        return [];
+    const out = [];
+    for (const page of crawl.pages) {
+        const facts = page[vp];
+        if (facts)
+            out.push({ page, facts });
+    }
+    return out;
+}
+export function el(page, vp, ref, excerpt, detail) {
+    return { type: 'dom', route: page.path, viewport: vp, selector: ref.selector, rect: ref.rect, excerpt, detail };
+}
+export function plural(n, word, pluralWord = word + 's') {
+    return `${n} ${n === 1 ? word : pluralWord}`;
+}
+export function uniqueRoutes(evidence) {
+    return [...new Set(evidence.map((e) => e.route).filter((p) => !!p))];
+}
+/** True if the element sits inside a header/nav/footer section of the page. */
+export function inChrome(facts, ref) {
+    return facts.sections.some((s) => s.isChrome && ref.rect.y >= s.rect.y - 1 && ref.rect.y + ref.rect.height <= s.rect.y + s.rect.height + 1);
+}
+export function topEntries(rec, n) {
+    return Object.entries(rec)
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, n);
+}

package/dist/rules/index.d.ts

@@ -0,0 +1,13 @@
+import type { Finding } from '../types.js';
+import { type Rule, type RuleContext } from './types.js';
+export declare const allRules: Rule[];
+export declare const ruleVersions: () => Record<string, number>;
+export declare const rulePenalties: () => Record<string, number | undefined>;
+export interface RuleRun {
+    findings: Finding[];
+    errors: {
+        ruleId: string;
+        message: string;
+    }[];
+}
+export declare function runRules(ctx: RuleContext, ignore?: string[]): RuleRun;

package/dist/rules/index.js

@@ -0,0 +1,100 @@
+import { locateText } from '../static/scan.js';
+import { contentRules } from './content.js';
+import { functionalRules } from './functional.js';
+import { normalizeFindings, validateDraft } from './normalize.js';
+import { staticRules } from './static.js';
+import { toDraft } from './types.js';
+import { visualRules } from './visual.js';
+export const allRules = [...visualRules, ...contentRules, ...functionalRules, ...staticRules];
+export const ruleVersions = () => Object.fromEntries(allRules.map((r) => [r.id, r.version ?? 1]));
+export const rulePenalties = () => Object.fromEntries(allRules.map((r) => [r.id, r.penalty]));
+/** Rendered rules whose element evidence carries visible text worth tracing back to source. */
+const TRACEABLE = new Set(['stock-copy', 'placeholder-content', 'duplicate-copy', 'unverified-claims', 'emoji-icons', 'generic-link-text']);
+export function runRules(ctx, ignore = []) {
+    const drafts = [];
+    const errors = [];
+    const ignored = new Set(ignore);
+    const deferred = [];
+    for (const rule of allRules) {
+        if (ignored.has(rule.id) || (rule.mergeInto && ignored.has(rule.mergeInto)))
+            continue;
+        if (rule.needs === 'rendered' && !ctx.crawl)
+            continue;
+        if (rule.needs === 'static' && !ctx.repo)
+            continue;
+        let inputs;
+        try {
+            inputs = rule.run(ctx);
+        }
+        catch (err) {
+            errors.push({ ruleId: rule.id, message: err.message });
+            continue;
+        }
+        for (const input of inputs) {
+            const d = toDraft(rule, input, rule.needs === 'static' ? 'static' : 'rendered');
+            if (rule.mergeInto)
+                deferred.push({ rule, draft: d });
+            else
+                drafts.push(d);
+        }
+    }
+    // Attach source locations to rendered text findings when the exact text is found in the repo.
+    if (ctx.repo) {
+        for (const d of drafts) {
+            if (!TRACEABLE.has(d.ruleId))
+                continue;
+            for (const e of d.evidence) {
+                if (!e.excerpt || e.file)
+                    continue;
+                const text = e.excerpt.replace(/^…/, '').replace(/…$/, '');
+                const loc = locateText(ctx.repo.files, text, 1, e.route)[0];
+                if (loc) {
+                    e.file = loc.file;
+                    e.line = loc.line;
+                }
+            }
+        }
+    }
+    // Fold static mirrors into their rendered counterpart when it fired; otherwise keep them standalone.
+    for (const { rule, draft } of deferred) {
+        const target = drafts.find((f) => f.ruleId === rule.mergeInto);
+        if (target) {
+            const have = new Set(target.evidence.filter((e) => e.file).map((e) => `${e.file}:${e.line}`));
+            const extra = draft.evidence.filter((e) => !have.has(`${e.file}:${e.line}`)).slice(0, 8);
+            target.evidence.push(...extra);
+            if (extra.length)
+                target.description += ` Source locations: ${draft.evidence.length} matching line${draft.evidence.length === 1 ? '' : 's'} in the repository.`;
+        }
+        else {
+            drafts.push(draft);
+        }
+    }
+    // Screenshot references for element evidence, so each item points at an image of where it is.
+    if (ctx.crawl) {
+        const shots = new Map();
+        for (const p of ctx.crawl.pages)
+            for (const vp of ['desktop', 'mobile']) {
+                const file = p[vp]?.screenshot;
+                if (file)
+                    shots.set(`${p.path}|${vp}`, `shots/${file}`);
+            }
+        for (const d of drafts)
+            for (const e of d.evidence) {
+                if (e.route && e.viewport && !e.screenshotPath)
+                    e.screenshotPath = shots.get(`${e.route}|${e.viewport}`);
+            }
+    }
+    // A rule bug (say, confidence out of range) drops that one finding, not the whole audit.
+    const valid = drafts.filter((d) => {
+        try {
+            validateDraft(d);
+            return true;
+        }
+        catch (err) {
+            errors.push({ ruleId: d.ruleId, message: err.message });
+            return false;
+        }
+    });
+    const findings = normalizeFindings(valid, ctx.repo ? new Set(ctx.repo.files.map((f) => f.path)) : undefined);
+    return { findings, errors };
+}

package/dist/rules/normalize.d.ts

@@ -0,0 +1,18 @@
+import type { Evidence, Finding } from '../types.js';
+import type { DraftFinding } from './types.js';
+export declare function redact(text: string): string;
+/** A source path is kept only if it is relative, inside the project, and in the scanned file set. */
+export declare function safeSourcePath(file: string, known?: Set<string>): string | undefined;
+/**
+ * Identical evidence on several routes (the same footer link on every page) is one problem
+ * in one shared component. Keep the first occurrence and list the other routes.
+ */
+export declare function collapseEvidence(evidence: Evidence[]): Evidence[];
+/** Stable hash of rule identity and evidence identity, independent of routes and order. */
+export declare function fingerprint(ruleId: string, evidence: Evidence[]): string;
+export declare function validateDraft(d: DraftFinding): void;
+/**
+ * Validates drafts, cleans evidence, assigns fingerprints and ids, and merges findings that
+ * share a fingerprint (same rule, same evidence), keeping the higher severity and confidence.
+ */
+export declare function normalizeFindings(drafts: DraftFinding[], knownFiles?: Set<string>): Finding[];