@qaguardian/playwright-score 2.2.0 → 2.3.0

package/dist/formatters/report.js

@@ -0,0 +1,279 @@
+import { PROFILE_WEIGHTS } from '../profiles.js';
+import { CONFIDENCE_LABEL, compareFindings, isNeedsCheck } from '../confidence.js';
+import { copyFor } from '../rule-copy.js';
+import { REPORT_CSS } from './report-css.js';
+import { DIMENSIONS, barText, cleanCheckCalls, gradeBandText, mostAffectedFile, notScoredHeadline, notScoredState, plural, rankGroups, summaryTop, INCOMPLETE_NOTE, } from '../report-model.js';
+export { rankTopFindings, compareGroups } from '../report-model.js';
+/** Rules that make a test flaky rather than merely untidy. */
+export const FLAKE_RULES = [
+    'playwright/no-wait-for-timeout',
+    'pwscore/no-timer-sleep',
+    'playwright/no-networkidle',
+    'playwright/no-force-option',
+    'playwright/no-wait-for-selector',
+    'playwright/missing-playwright-await',
+];
+const DETAIL_CARDS = 5;
+const LEGEND = 'Definite: the code does this for certain. Likely: usually a problem, but there are legitimate uses. None of these are confirmed bugs in your product; they are patterns that make bugs easier to miss or tests less reliable.';
+export function escapeHtml(s) {
+    return s
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+function longDate(iso) {
+    const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(iso);
+    const mon = m ? MONTHS[Number(m[2]) - 1] : undefined;
+    return m && mon ? `${Number(m[3])} ${mon} ${m[1]}` : iso;
+}
+function excerpt(source, line) {
+    const lines = source.split(/\r?\n/);
+    if (line < 1 || line > lines.length)
+        return [];
+    const from = Math.max(1, line - 3);
+    const to = Math.min(lines.length, line + 3);
+    const out = [];
+    for (let n = from; n <= to; n++) {
+        let text = (lines[n - 1] ?? '').replace(/\t/g, '  ');
+        if (text.length > 140)
+            text = text.slice(0, 137) + '...';
+        out.push({ n, text, hit: n === line });
+    }
+    return out;
+}
+function renderExcerpt(f, readSource) {
+    if (!f.line || !readSource)
+        return '';
+    const src = readSource(f.file);
+    if (src === undefined)
+        return '';
+    const rows = excerpt(src, f.line);
+    if (!rows.length)
+        return '';
+    const body = rows
+        .map((r) => r.hit
+        ? `<span class="ln hit"><i>&#9656;${r.n}</i><span class="sr-only">flagged line: </span>${escapeHtml(r.text) || ' '}</span>`
+        : `<span class="ln"><i>${r.n}</i>${escapeHtml(r.text) || ' '}</span>`)
+        .join('');
+    return `<pre class="code" aria-label="Code excerpt">${body}</pre>`;
+}
+function loc(f) {
+    return f.line ? `${f.file}:${f.line}` : f.file;
+}
+function baseName(p) {
+    return p.split(/[/\\]/).pop() || p;
+}
+function tag(g) {
+    return `<span class="tag">${CONFIDENCE_LABEL[g.confidence]}</span>`;
+}
+function renderTop3(groups) {
+    const items = groups
+        .map((g, i) => {
+        const c = copyFor(g.rule);
+        const most = mostAffectedFile(g);
+        const places = `${plural(g.findings.length, 'place')} in ${plural(g.testsAffected, 'test')}`;
+        const where = `<code>${escapeHtml(baseName(most.file))}</code>${most.line ? ` (line ${most.line})` : ''}`;
+        const sameFile = most.count === g.findings.length;
+        const count = g.findings.length === 1
+            ? `${places}: ${where}.`
+            : `${places}. ${sameFile ? 'All in' : 'Most in'} ${where}.`;
+        return `<li class="top"><span class="rank" aria-hidden="true">${i + 1}</span>
+<div><h3>${escapeHtml(c.title)} ${tag(g)}</h3>
+<p class="count">${count}</p>
+<p class="why">${escapeHtml(c.why)}</p></div></li>`;
+    })
+        .join('\n');
+    return `<ol class="top3" role="list">\n${items}\n</ol>`;
+}
+function renderDetailCards(groups, readSource) {
+    return groups
+        .map((g, i) => {
+        const c = copyFor(g.rule);
+        const others = g.findings.length - 1;
+        return `<article class="finding sev-${g.severity}">
+<h3><span class="rank" aria-hidden="true">${i + 1}</span>${escapeHtml(c.title)} ${tag(g)}</h3>
+<p class="where"><code>${escapeHtml(loc(g.example))}</code></p>
+${renderExcerpt(g.example, readSource)}
+<p class="why">${escapeHtml(c.why)}</p>
+<p class="muted">${others > 0 ? `${plural(g.findings.length, 'occurrence')} across ${plural(g.testsAffected, 'test')}.` : 'One occurrence.'}</p>
+</article>`;
+    })
+        .join('\n');
+}
+function flakeFilesLine(findings) {
+    const files = new Map();
+    for (const f of findings) {
+        if (FLAKE_RULES.includes(f.rule) && !isNeedsCheck(f))
+            files.set(f.file, (files.get(f.file) ?? 0) + 1);
+    }
+    if (!files.size)
+        return '';
+    const worst = [...files.entries()]
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+        .slice(0, 3)
+        .map(([file, n]) => `<code>${escapeHtml(file)}</code> (${n})`)
+        .join(', ');
+    return `<p class="muted">Most flake-prone files: ${worst}.</p>`;
+}
+function renderNeedsCheck(findings) {
+    const items = findings.filter(isNeedsCheck).sort(compareFindings);
+    if (!items.length)
+        return '';
+    const byFile = new Map();
+    for (const f of items) {
+        const list = byFile.get(f.file);
+        if (list)
+            list.push(f);
+        else
+            byFile.set(f.file, [f]);
+    }
+    const files = [...byFile.entries()];
+    const shown = files.slice(0, 6);
+    const rows = shown
+        .map(([file, list]) => {
+        const lines = list.filter((f) => f.line).map((f) => f.line).join(', ');
+        const calls = cleanCheckCalls(list[0].message);
+        const what = calls
+            ? `Calls ${calls} from a helper we could not read.`
+            : 'Its checks could not be seen.';
+        return `<li><code>${escapeHtml(file)}</code> <span class="muted">${plural(list.length, 'test')}${lines ? `, line${list.length === 1 ? '' : 's'} ${escapeHtml(lines)}` : ''}</span><br><span class="muted">${escapeHtml(what)}</span></li>`;
+    })
+        .join('');
+    const hidden = items.length - shown.reduce((n, [, l]) => n + l.length, 0);
+    const more = hidden > 0 ? `<p class="muted">and ${plural(hidden, 'more test')} in ${plural(files.length - shown.length, 'other file')}.</p>` : '';
+    return `<h3 id="human-check">Needs a human check</h3>
+<p class="note">${plural(items.length, 'test')} ${items.length === 1 ? 'relies' : 'rely'} on helpers we could not read (page objects, fixtures or imported functions). The checks probably live there, but the score cannot see them, so ${items.length === 1 ? 'this test is' : 'these tests are'} left out of the score. Ask someone to confirm each helper really checks the page.</p><ul class="plain">${rows}</ul>${more}`;
+}
+const GENERIC_STEPS = [
+    'Re-run the score in CI with --threshold so the number cannot slip back unnoticed.',
+    'Keep new specs on role, label and test-id locators with web-first assertions.',
+    'Review any items under "Needs a human check" by hand.',
+];
+function nextSteps(groups, extra = []) {
+    const steps = [];
+    const fixes = groups.map((g) => copyFor(g.rule).fix).filter((f, i, a) => a.indexOf(f) === i);
+    const maxFromFindings = 3 - Math.min(extra.length, 2);
+    for (const fix of fixes.slice(0, maxFromFindings))
+        steps.push(fix);
+    for (const e of extra) {
+        if (steps.length < 3)
+            steps.push(e);
+    }
+    for (const s of GENERIC_STEPS) {
+        if (steps.length >= 3)
+            break;
+        steps.push(s);
+    }
+    return steps;
+}
+function renderBars(result) {
+    const weights = PROFILE_WEIGHTS[result.profile] ?? PROFILE_WEIGHTS.standard;
+    const bars = DIMENSIONS.map((d) => {
+        const v = result.dimensions[d.key] ?? 0;
+        const w = weights[d.key];
+        return `<div class="dim" title="${escapeHtml(d.meaning)}"><div class="dimhead"><span>${d.label}${w ? ` <span class="muted">${w}% of score</span>` : ''}</span><strong>${v}</strong></div>
+<div class="bar" role="img" aria-label="${d.label} ${v} out of 100"><span style="width:${Math.max(0, Math.min(100, v))}%"></span></div>
+<p class="muted sr-only">${escapeHtml(d.meaning)}</p></div>`;
+    }).join('\n');
+    return `<h2>Score by area</h2>\n<div class="dims">\n${bars}\n</div>`;
+}
+export function formatReport(result, opts) {
+    const { summary } = result;
+    const state = notScoredState(result);
+    const clean = summary.cleanTests;
+    const all = rankGroups(result.findings);
+    const top = summaryTop(all, result.dimensions);
+    const detail = [...new Set([...top, ...all.slice(0, DETAIL_CARDS)])];
+    const humanItems = result.findings.filter(isNeedsCheck);
+    const humanHtml = renderNeedsCheck(result.findings);
+    let headline;
+    let explain;
+    let scoreBox;
+    if (state) {
+        const ns = notScoredHeadline(result);
+        headline = ns.headline;
+        explain = ns.line;
+        scoreBox = `<div class="score notscored" role="img" aria-label="Not scored"><span class="big">--</span><span class="grade">Not scored</span></div>`;
+    }
+    else {
+        headline = `${clean} of ${summary.tests} ${summary.tests === 1 ? 'test has' : 'tests have'} no issues.`;
+        explain = `A weighted average of four areas below. ${gradeBandText(result.grade, result.pass)} ${barText(result.threshold, opts.customThreshold === true, result.pass)}`;
+        scoreBox = `<div class="score g-${result.grade}" aria-hidden="true"><span class="big">${result.score}</span><span class="of">/100</span><span class="grade">${result.grade}</span></div>`;
+    }
+    const srScore = state ? '' : `<span class="sr-only">Score ${result.score} out of 100, grade ${result.grade}. </span>`;
+    const humanCount = summary.unverifiedTests;
+    const humanLine = humanCount > 0 && !state
+        ? `\n<p class="check">${humanItems.length ? '<a href="#human-check">' : ''}${plural(humanCount, 'test')} ${humanCount === 1 ? 'needs' : 'need'} a human check and ${humanCount === 1 ? 'is' : 'are'} left out of the score.${humanItems.length ? '</a>' : ''}</p>`
+        : '';
+    const crashLine = result.ruleCrashes?.length ? `\n<p class="check">${escapeHtml(INCOMPLETE_NOTE)}</p>` : '';
+    const meta = state
+        ? plural(summary.files, 'file')
+        : `${plural(summary.tests, 'test')} in ${plural(summary.files, 'file')}`;
+    const header = `<header>
+<p class="eyebrow">Playwright suite score</p>
+<p class="suite">${escapeHtml(opts.suiteName)}</p>
+<div class="hd">
+${scoreBox}
+<div>
+<h1>${srScore}${escapeHtml(headline)}</h1>
+<p class="explain">${escapeHtml(explain)}</p>${humanLine}${crashLine}
+<p class="meta">${meta} · scored ${escapeHtml(longDate(opts.date))}</p>
+</div>
+</div>
+</header>`;
+    const footer = `<footer>Scored by QA Guardian playwright-score ${escapeHtml(opts.version)} (rules ${escapeHtml(result.scoreVersion)}) on ${escapeHtml(opts.date)}. Static analysis of the test code: the same files always give the same score. Nothing was run against your product.</footer>`;
+    const head = `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="color-scheme" content="light dark">
+<title>Playwright suite score: ${escapeHtml(opts.suiteName)}</title>
+<style>${REPORT_CSS}</style>
+</head>
+<body>
+<main>
+`;
+    if (state === 'no-tests') {
+        return `${head}<section class="summary">\n${header}\n</section>\n${footer}\n</main>\n</body>\n</html>\n`;
+    }
+    const clearSuite = all.length === 0 && humanItems.length === 0 && !state;
+    const topHtml = all.length
+        ? `<h2>${top.length > 1 ? `Top ${top.length} to fix` : 'Fix first'}</h2>\n<p class="muted legend">${escapeHtml(LEGEND)}</p>\n${renderTop3(top)}`
+        : '<h2>Issues</h2>\n<p>No issues found. Keep it that way by adding the score to CI with --threshold.</p>';
+    const extraSteps = [];
+    if (humanItems.length) {
+        extraSteps.push('Have someone confirm that the tests under "Needs a human check" really assert, since the score cannot tell.');
+    }
+    if ((result.dimensions.locators ?? 100) < 75 && !top.some((g) => g.dimension === 'locators')) {
+        extraSteps.push('Move CSS and XPath selectors to role, label or test-id locators, starting with the busiest page objects.');
+    }
+    const steps = nextSteps(top, extraSteps)
+        .map((s) => `<li>${escapeHtml(s)}</li>`)
+        .join('');
+    const nextHtml = clearSuite ? '' : `\n<h2>What to do next</h2>\n<ol>${steps}</ol>`;
+    const moreTypes = all.length - detail.length;
+    const detailsHtml = detail.length || humanHtml
+        ? `<section class="details">
+<h2>Details</h2>
+${flakeFilesLine(result.findings)}
+${renderDetailCards(detail, opts.readSource)}
+${moreTypes > 0 ? `<p class="muted">${plural(moreTypes, 'more issue type')} not shown. Use --format json for every occurrence.</p>` : ''}
+${humanHtml}
+</section>
+`
+        : '';
+    return `${head}<section class="summary">
+${header}
+${state ? '' : renderBars(result)}
+${topHtml}${nextHtml}
+</section>
+${detailsHtml}${footer}
+</main>
+</body>
+</html>
+`;
+}

package/dist/formatters/text.d.ts

@@ -1,2 +1,7 @@
 import type { ScoreResult } from '../types.js';
-export declare function formatText(result: ScoreResult): string;
+export interface TextOptions {
+    suiteName?: string;
+    version?: string;
+    customThreshold?: boolean;
+}
+export declare function formatText(result: ScoreResult, opts?: TextOptions): string;

package/dist/formatters/text.js

@@ -1,32 +1,77 @@
-export function formatText(result) {
+import { CONFIDENCE_LABEL, compareFindings, isNeedsCheck } from '../confidence.js';
+import { copyFor } from '../rule-copy.js';
+import { DIMENSIONS, notScoredHeadline, notScoredState, plural, rankGroups, INCOMPLETE_NOTE, } from '../report-model.js';
+/** Groups shown, and locations shown per group; the rest collapse into "+N more". */
+const MAX_GROUPS = 10;
+const MAX_LOCATIONS = 3;
+const MAX_PATH = 100;
+/** Relative path, shortened in the middle to MAX_PATH. An absolute path never gets through. */
+function shortPath(file, line) {
+    let p = file.replace(/\\/g, '/');
+    if (p.startsWith('/') || /^[A-Za-z]:\//.test(p))
+        p = p.split('/').filter(Boolean).slice(-3).join('/');
+    const suffix = line ? `:${line}` : '';
+    const budget = MAX_PATH - suffix.length;
+    if (p.length > budget) {
+        const tail = p.split('/').pop() ?? p;
+        const keep = Math.max(10, budget - tail.length - 5);
+        p = tail.length >= budget ? '...' + tail.slice(-(budget - 3)) : `${p.slice(0, keep)}/.../${tail}`;
+    }
+    return p + suffix;
+}
+export function formatText(result, opts = {}) {
+    const { summary } = result;
+    const state = notScoredState(result);
     const lines = [];
-    lines.push(`Playwright Spec Score ${result.scoreVersion} · profile=${result.profile}`);
-    lines.push(`Score: ${result.score}/100 (${result.grade}) · ${result.pass ? 'PASS' : 'FAIL'} (threshold ${result.threshold})`);
-    lines.push('');
-    lines.push('Dimensions:');
-    for (const [k, v] of Object.entries(result.dimensions)) {
-        if (v === undefined)
-            continue;
-        lines.push(`  ${k}: ${v}`);
+    const counts = state
+        ? plural(summary.files, 'file')
+        : `${plural(summary.tests, 'test')} in ${plural(summary.files, 'file')}`;
+    lines.push(opts.suiteName ? `${opts.suiteName}  ·  ${counts}` : counts);
+    if (state) {
+        lines.push(`Not scored: ${notScoredHeadline(result).headline.replace(/, so this suite could not be scored\.$/, '')}.`);
+        const first = result.findings.find((f) => f.rule === 'playwright-score/parse-error');
+        if (first)
+            lines.push(`  ${shortPath(first.file, first.line)}`);
+        lines.push(notScoredHeadline(result).line);
     }
-    lines.push('');
-    lines.push(`Summary: files=${result.summary.files} tests=${result.summary.tests} sloc=${result.summary.sloc} ` +
-        `findings=${result.summary.findings} (errors=${result.summary.errors} warnings=${result.summary.warnings}) ` +
-        `locators native/raw=${result.summary.nativeLocators}/${result.summary.rawLocators} ` +
-        `tests asserting=${result.summary.tests - result.summary.unassertedTests - result.summary.unverifiedTests}/${result.summary.tests}` +
-        `${result.summary.unverifiedTests ? ` (unverified=${result.summary.unverifiedTests})` : ''} ` +
-        `clean tests=${result.summary.cleanTests}/${result.summary.tests}`);
-    if (result.findings.length) {
+    else {
+        const clean = summary.cleanTests;
+        lines.push(`Score ${result.score}/100 (${result.grade})  ·  ${result.pass ? 'PASS' : 'FAIL'} (${opts.customThreshold ? 'your bar' : 'bar'} ${result.threshold})  ·  ${clean} ${clean === 1 ? 'test has' : 'tests have'} no issues`);
+        lines.push(DIMENSIONS.filter((d) => result.dimensions[d.key] !== undefined)
+            .map((d) => `${d.label} ${result.dimensions[d.key]}`)
+            .join(' · '));
+    }
+    // 'no-tests' hard-fail findings carry the absolute working directory as their file.
+    const groups = state === 'no-tests' ? [] : rankGroups(result.findings);
+    if (groups.length) {
         lines.push('');
-        lines.push('Findings:');
-        for (const f of result.findings.slice(0, 50)) {
-            const loc = f.line ? `:${f.line}` : '';
-            lines.push(`  [${f.severity}] ${f.rule} ${pathBasename(f.file)}${loc} — ${f.message}`);
-        }
-        if (result.findings.length > 50) {
-            lines.push(`  … and ${result.findings.length - 50} more`);
+        lines.push('Top issues (worst first)');
+        groups.slice(0, MAX_GROUPS).forEach((g, i) => {
+            const where = `${g.findings.length} in ${plural(g.testsAffected, 'test')}`;
+            lines.push(` ${i + 1}. ${copyFor(g.rule).title}   ${where}   ${CONFIDENCE_LABEL[g.confidence]}`);
+            for (const f of g.findings.slice(0, MAX_LOCATIONS))
+                lines.push(`    ${shortPath(f.file, f.line)}`);
+            if (g.findings.length > MAX_LOCATIONS)
+                lines.push(`    + ${g.findings.length - MAX_LOCATIONS} more`);
+        });
+        if (groups.length > MAX_GROUPS) {
+            lines.push(` + ${plural(groups.length - MAX_GROUPS, 'more issue type')}. Full list: playwright-score <path> --format report --out report.html`);
         }
     }
+    const human = result.findings.filter(isNeedsCheck).sort(compareFindings);
+    if (human.length && !state) {
+        const files = [...new Set(human.map((f) => f.file))];
+        lines.push('');
+        lines.push(`Needs a human check (not in the score): ${plural(human.length, 'test')} in ${plural(files.length, 'file')} ${human.length === 1 ? 'relies' : 'rely'} on helpers we could not read.`);
+        for (const f of files.slice(0, 5))
+            lines.push(`    ${shortPath(f)}`);
+        if (files.length > 5)
+            lines.push(`    + ${files.length - 5} more`);
+    }
+    if (result.ruleCrashes?.length) {
+        lines.push('');
+        lines.push(INCOMPLETE_NOTE);
+    }
     if (result.skippedFiles?.length) {
         lines.push('');
         lines.push(`Skipped (looks like a non-Playwright test — Jest/Vitest/RTL/Cypress — ${result.skippedFiles.length}):`);
@@ -44,9 +89,9 @@ export function formatText(result) {
             lines.push(`  ${w}`);
         }
     }
+    lines.push('');
+    if (!state)
+        lines.push(`Score ${result.score}/100 (${result.grade})  ·  ${result.pass ? 'PASS' : 'FAIL'}`);
+    lines.push(`${opts.version ? `QA Guardian playwright-score ${opts.version} (rules ${result.scoreVersion})` : `QA Guardian playwright-score (rules ${result.scoreVersion})`}`);
     return lines.join('\n');
 }
-function pathBasename(p) {
-    const parts = p.split(/[/\\]/);
-    return parts[parts.length - 1] ?? p;
-}

package/dist/index.js

@@ -10,6 +10,7 @@ import { detectExtendedTestAliases } from './test-aliases.js';
 import { findPlaywrightConfig, findRepoBoundary, importsPlaywrightTestTransitively, isAncestorOrSame, parsePlaywrightConfig, resolveConfigScopedRoot, safeRealpath, testDirEscapesRepo, } from './playwright-config.js';
 import { DEFAULT_THRESHOLDS } from './profiles.js';
 import { computeScore } from './score-engine.js';
+import { resetRuleCrashes, summarizeRuleCrashes } from './rules/base-plugin.js';
 export { computeScore, MODEL, locatorsScore, gradeFromScore, ratioDimensionScore, } from './score-engine.js';
 export { countSloc } from './sloc.js';
 export { countLocators, analyzeSource, attributeFindingScopes, getTestSpans, } from './metrics.js';
@@ -427,6 +428,12 @@ function hardFail(profile, threshold, findings, extra = {}, skippedFiles, config
  * Score Playwright spec files. Deterministic and AI-free.
  */
 export async function scorePaths(options) {
+    resetRuleCrashes();
+    const result = await scorePathsInner(options);
+    const crashes = summarizeRuleCrashes();
+    return crashes.length > 0 ? { ...result, ruleCrashes: crashes } : result;
+}
+async function scorePathsInner(options) {
     const cwd = options.cwd ?? process.cwd();
     const profile = options.profile ?? 'standard';
     const threshold = options.threshold ?? DEFAULT_THRESHOLDS[profile] ?? 80;
@@ -563,12 +570,15 @@ export async function scorePaths(options) {
         // (a handful of exp-decay points on an otherwise large, clean batch)
         // would let a broken file hide inside a passing score. Hard-fail
         // instead, same as the no-matching-files case.
-        return hardFail(profile, threshold, findings, {
-            files: files.length,
-            sloc: Math.max(totalSloc, 1),
-            nativeLocators: native,
-            rawLocators: raw,
-        }, skippedFiles);
+        return {
+            ...hardFail(profile, threshold, findings, {
+                files: files.length,
+                sloc: Math.max(totalSloc, 1),
+                nativeLocators: native,
+                rawLocators: raw,
+            }, skippedFiles),
+            baseDir: filesBase,
+        };
     }
     const result = computeScore({
         profile,
@@ -583,6 +593,7 @@ export async function scorePaths(options) {
     });
     return {
         ...result,
+        baseDir: filesBase,
         ...(skippedFiles.length > 0 ? { skippedFiles } : {}),
         ...(configWarnings.length > 0 ? { configWarnings } : {}),
     };

package/dist/profiles.js

@@ -113,6 +113,18 @@ export const ESLINT_RULE_MAP = {
     'pwscore/no-coordinate-click': { dimension: 'playwrightHygiene', severityOverride: 'warning' },
     'pwscore/no-trivial-assertion': { dimension: 'assertions' },
     'pwscore/no-soft-assertion-only-test': { dimension: 'assertions', severityOverride: 'warning' },
+    // QAG-287 slice 2b. no-brittle-selector is report-only: the locators ratio already counts every raw call.
+    'pwscore/no-unawaited-action': { dimension: 'playwrightHygiene' },
+    'pwscore/no-brittle-selector': { dimension: 'locators', severityOverride: 'warning', reportOnly: true },
+    'pwscore/no-shared-mutable-state': { dimension: 'structure', severityOverride: 'warning' },
+    'pwscore/serial-mode-dependency': { dimension: 'structure', severityOverride: 'info', reportOnly: true },
+    'pwscore/no-excessive-timeout': { dimension: 'playwrightHygiene', severityOverride: 'warning' },
+    // QAG-287 slice 2a: tests that would miss a real bug.
+    'pwscore/no-fixme-test': { dimension: 'structure' },
+    'pwscore/no-swallowed-assertion': { dimension: 'assertions', severityOverride: 'warning' },
+    'pwscore/no-weak-assertion': { dimension: 'assertions' },
+    'pwscore/no-unawaited-expect-value': { dimension: 'assertions' },
+    'pwscore/no-self-fulfilling-fallback': { dimension: 'assertions', severityOverride: 'info', reportOnly: true },
 };
 export function mapRule(ruleId) {
     if (ESLINT_RULE_MAP[ruleId])

package/dist/report-model.d.ts

@@ -0,0 +1,52 @@
+import type { DimensionName, Finding, ScoreResult } from './types.js';
+import { type Confidence } from './confidence.js';
+/** Shared by the HTML report and the terminal output. */
+export declare const INCOMPLETE_NOTE = "Some checks could not run on this suite; results may be incomplete.";
+export declare const PARSE_ERROR_RULE = "playwright-score/parse-error";
+export declare const DIMENSIONS: ReadonlyArray<{
+    key: DimensionName;
+    label: string;
+    meaning: string;
+}>;
+export interface RuleGroup {
+    rule: string;
+    /** Worst severity among the group's findings. */
+    severity: Finding['severity'];
+    confidence: Confidence;
+    /** Tests affected: distinct tests for test-scoped findings, plus one per file for hook/module-scoped ones. */
+    testsAffected: number;
+    findings: Finding[];
+    /** The occurrence shown as the example (first by severity, file, line). */
+    example: Finding;
+    dimension: DimensionName;
+}
+export declare function groupByRule(findings: readonly Finding[]): RuleGroup[];
+/** Severity, then confidence, then tests affected (desc), then rule id. */
+export declare function compareGroups(a: RuleGroup, b: RuleGroup): number;
+/** Every rule group, worst first. Never includes needs-check findings. A file that does not parse always leads. */
+export declare function rankGroups(findings: readonly Finding[]): RuleGroup[];
+/** Up to `max` rule groups. Never includes needs-check findings. */
+export declare function rankTopFindings(findings: readonly Finding[], max?: number): RuleGroup[];
+/**
+ * The summary's top three. When the weakest area scores under 75 and none of
+ * the three belongs to it, the third slot goes to that area's best-ranked group.
+ */
+export declare function summaryTop(all: readonly RuleGroup[], dimensions: ScoreResult['dimensions'], n?: number): RuleGroup[];
+/** The file with the most occurrences in the group, with the line of its first one. */
+export declare function mostAffectedFile(g: RuleGroup): {
+    file: string;
+    line?: number;
+    count: number;
+};
+export declare function plural(n: number, one: string, many?: string): string;
+export type NotScored = 'parse-error' | 'no-tests' | undefined;
+export declare function parseErrorFileCount(result: ScoreResult): number;
+export declare function notScoredState(result: ScoreResult): NotScored;
+/** "B means 80-89; A is 90 and up." Built from the engine's own grade bands. */
+export declare function gradeBandText(grade: string, pass: boolean): string;
+export declare function barText(threshold: number, custom: boolean, pass: boolean): string;
+export declare function notScoredHeadline(result: ScoreResult): {
+    headline: string;
+    line: string;
+};
+export declare function cleanCheckCalls(m: string): string | undefined;