@qaguardian/playwright-score 0.1.0 → 0.1.9

package/README.md

@@ -1,5 +1,9 @@
 # @qaguardian/playwright-score
 
+[![CI](https://github.com/qa-guardian/playwright-score/actions/workflows/ci.yml/badge.svg)](https://github.com/qa-guardian/playwright-score/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@qaguardian/playwright-score.svg)](https://www.npmjs.com/package/@qaguardian/playwright-score)
+[![license](https://img.shields.io/npm/l/@qaguardian/playwright-score.svg)](./LICENSE)
+
 **Deterministic, AI-free quality score for Playwright specs** (`sqs-v1`).
 
 **Website:** [qaguardian.com/open-source/playwright-score](https://qaguardian.com/open-source/playwright-score)  
@@ -18,15 +22,18 @@ See [METHODOLOGY.md](./METHODOLOGY.md) for the frozen formula, or the full produ
 
 ```bash
 npm install -D @qaguardian/playwright-score
-# or run from this package
-npm install && npm run build
 ```
 
+Package: [@qaguardian/playwright-score](https://www.npmjs.com/package/@qaguardian/playwright-score) on npm.
+
 ## CLI
 
 ```bash
-npx @qaguardian/playwright-score ./tests --profile standard --threshold 80
-npx @qaguardian/playwright-score ./flow.spec.ts --profile guardian --format json --out report.json
+# One-shot (scoped package — use -p so the playwright-score binary is resolved)
+npx -p @qaguardian/playwright-score playwright-score ./tests --profile standard --threshold 80
+
+# After local install
+npx playwright-score ./flow.spec.ts --profile guardian --format json --out report.json
 ```
 
 | Flag | Description |
@@ -35,8 +42,9 @@ npx @qaguardian/playwright-score ./flow.spec.ts --profile guardian --format json
 | `--threshold <n>` | Pass bar 0–100 |
 | `--format text\|json\|markdown\|sarif` | Output format |
 | `--out <file>` | Write report to file |
+| `--version` | Print version |
 
-**Exit codes:** `0` pass · `1` below threshold · `2` tool error  
+**Exit codes:** `0` pass · `1` below threshold **or no files matched** · `2` tool error  
 
 ## Library
 
@@ -52,11 +60,39 @@ const result = await scorePaths({
 console.log(result.score, result.grade, result.pass, result.findings);
 ```
 
-## CI example
+## GitHub Action
+
+Drop this into a workflow to gate PRs on the score, post a job summary, and
+keep a sticky PR comment with the full findings up to date:
+
+```yaml
+- uses: qa-guardian/playwright-score@v1
+  with:
+    paths: tests e2e
+    profile: standard      # or guardian
+    # threshold: 80        # defaults to the profile's default
+    mode: gate              # gate: fail CI below threshold · warn: report only
+```
+
+| Input | Description | Default |
+|---|---|---|
+| `paths` | Space-separated paths/globs to score | `tests` |
+| `profile` | `standard` \| `guardian` | `standard` |
+| `threshold` | Pass bar 0–100 | profile default (80 / 75) |
+| `mode` | `gate` (fail CI below threshold) \| `warn` (report only) | `gate` |
+| `comment` | Post/update a sticky PR comment | `true` |
+| `version` | `@qaguardian/playwright-score` version to run | `latest` |
+| `github-token` | Token for the PR comment | `${{ github.token }}` |
+
+Outputs: `score`, `grade`, `pass` — usable by downstream steps (e.g. a
+custom badge, a Slack notification on regression, etc).
+
+Prefer a raw CLI call, or a non-GitHub CI system? See the [CLI](#cli)
+section above — same score, same exit codes:
 
 ```yaml
 - name: Playwright Spec Score
-  run: npx playwright-score ./tests --profile standard --threshold 80 --format text
+  run: npx -p @qaguardian/playwright-score playwright-score ./tests --profile standard --threshold 80 --format text
 ```
 
 ## QA Guardian integration

package/dist/cli.js

@@ -10,28 +10,44 @@ import { formatText } from './formatters/text.js';
 import { formatMarkdown } from './formatters/markdown.js';
 import { formatSarif } from './formatters/sarif.js';
 function printHelp() {
-    console.log(`playwright-score — deterministic Playwright spec quality score (sqs-v1)
+    console.log(`@qaguardian/playwright-score — deterministic Playwright spec quality score (sqs-v1)
 
 Usage:
-  playwright-score <paths...> [options]
+  npx -p @qaguardian/playwright-score playwright-score <paths...> [options]
+  # after npm install -D @qaguardian/playwright-score:
+  npx playwright-score <paths...> [options]
 
 Options:
   --profile <standard|guardian>   Scoring profile (default: standard)
   --threshold <n>                 Pass threshold 0-100 (default: 80 standard / 75 guardian)
   --format <text|json|markdown|sarif>  Output format (default: text)
   --out <file>                    Write report to file
+  --version                       Print version
   --help                          Show help
 
 Exit codes:
   0  score >= threshold
-  1  score < threshold
+  1  score < threshold (or no files matched)
   2  tool error
 
-See METHODOLOGY.md for sqs-v1 formula.
+Website: https://qaguardian.com/open-source/playwright-score
+Methodology: METHODOLOGY.md (sqs-v1)
 `);
 }
 async function main() {
     const args = process.argv.slice(2);
+    if (args.includes('--version') || args.includes('-v')) {
+        try {
+            const { createRequire } = await import('node:module');
+            const require = createRequire(import.meta.url);
+            const pkg = require('../package.json');
+            console.log(pkg.version ?? '0.0.0');
+        }
+        catch {
+            console.log('0.1.8');
+        }
+        process.exit(0);
+    }
     if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
         printHelp();
         process.exit(args.length === 0 ? 2 : 0);
@@ -68,6 +84,9 @@ async function main() {
         else if (a === '--out') {
             out = args[++i];
         }
+        else if (a === '--version' || a === '-v') {
+            continue;
+        }
         else if (a.startsWith('-')) {
             console.error(`Unknown option: ${a}`);
             process.exit(2);

package/dist/eslint-runner.d.ts

@@ -7,4 +7,6 @@ export declare function runEslint(options: {
     files: string[];
     profile: ProfileName;
     cwd?: string;
+    /** See findLocalAssertionHelperNames in metrics.ts. */
+    assertFunctionNames?: string[];
 }): Promise<Finding[]>;

package/dist/eslint-runner.js

@@ -1,9 +1,11 @@
 import path from 'node:path';
 import { ESLint } from 'eslint';
+import { commonAncestorDir } from './fs-util.js';
 import playwright from 'eslint-plugin-playwright';
 import { guardianPlugin, guardianRuleConfigs, } from './rules/guardian-plugin.js';
+import { basePlugin } from './rules/base-plugin.js';
 import { mapRule } from './profiles.js';
-function buildConfig(profile) {
+function buildConfig(profile, assertFunctionNames) {
     const playwrightRecommended = playwright.configs?.['flat/recommended'] ??
         playwright.configs?.recommended;
     const base = [
@@ -16,21 +18,79 @@ function buildConfig(profile) {
             },
             plugins: {
                 playwright,
+                pwscore: basePlugin,
                 ...(profile === 'guardian' ? { guardian: guardianPlugin } : {}),
             },
             rules: {
-                // Ensure key hygiene rules even if recommended set differs by version
+                // Ensure key hygiene rules even if recommended set differs by
+                // version. A few (no-wait-for-timeout, no-force-option,
+                // no-wait-for-selector, expect-expect) are intentionally stricter
+                // than eslint-plugin-playwright's own "recommended" severity —
+                // these are patterns Playwright's own docs call out as anti-
+                // patterns (see playwright.dev/docs/best-practices), so sqs-v1
+                // treats them as errors rather than warnings. no-networkidle and
+                // no-raw-locators aren't part of upstream "recommended" at all but
+                // are enabled here for the same reason.
                 'playwright/no-wait-for-timeout': 'error',
                 'playwright/no-networkidle': 'error',
                 'playwright/no-force-option': 'error',
                 'playwright/no-wait-for-selector': 'error',
                 'playwright/no-wait-for-navigation': 'error',
                 'playwright/missing-playwright-await': 'error',
-                'playwright/expect-expect': 'error',
+                // expect-expect can only see expect(...) calls written directly in
+                // the test body — it has no way to trace an assertion made inside
+                // a helper function the test calls. assertFunctionNames is
+                // populated per-run (see index.ts's findLocalAssertionHelperNames)
+                // with every same-file helper whose own body actually contains an
+                // expect(...)-shaped call, so this is name-agnostic for the common
+                // case regardless of what the helper is called. assertFunctionPatterns
+                // is a secondary, name-based fallback for helpers imported from
+                // another file (which we can't inspect the body of) — patterns are
+                // camelCase/exact-anchored so e.g. "checkoutFlow" doesn't collide
+                // with "check*"; the suffix pattern catches any name embedding a
+                // real Playwright matcher name (toBeVisible, toHaveText, ...).
+                // Verified against several real production files using several
+                // different naming conventions for the exact same delegation shape
+                // (audit, expectRealButtonToBeVisible, alertToBeVisible,
+                // checkFlashMessageVisibility) — all previously false-positived as
+                // "no assertions" at error severity.
+                'playwright/expect-expect': [
+                    'error',
+                    {
+                        assertFunctionNames,
+                        assertFunctionPatterns: [
+                            '^(assert|verify|validate|audit|expect)([A-Z]|$)',
+                            '^checkA11y$',
+                            '^checkAccessibility$',
+                            '(ToBe|ToHave|ToContain|ToMatch|ToEqual)[A-Z]',
+                        ],
+                    },
+                ],
                 'playwright/no-focused-test': 'error',
-                'playwright/no-skipped-test': 'warn',
+                // Upstream flags every test.skip(...) form identically, including
+                // Playwright's own documented conditional runtime skip
+                // (test.skip(condition, reason)) — a false positive on entirely
+                // idiomatic cross-browser test code, verified against real-world
+                // suites. pwscore/no-skipped-test-declaration (below) replaces it
+                // with the same severity for the actual anti-pattern (an
+                // always-skipped test declaration) only.
+                'playwright/no-skipped-test': 'off',
+                'pwscore/no-skipped-test-declaration': 'warn',
                 'playwright/no-raw-locators': 'warn',
-                'playwright/prefer-web-first-assertions': 'warn',
+                // Both were mapped in profiles.ts (report-only, so they don't
+                // double-penalize the ratio-based locators dimension) but never
+                // actually enabled anywhere — completely inert. prefer-locator
+                // specifically catches Playwright's older direct-action API
+                // (page.click('#foo') instead of a locator or native locator),
+                // arguably the single most common raw-selector anti-pattern in
+                // naive/AI-generated code — verified against a realistic sample
+                // that scored a perfect 100 on the locators dimension despite
+                // using nothing but page.click(selector)/page.type(selector, ...)
+                // throughout, before this fix.
+                'playwright/prefer-locator': 'warn',
+                'playwright/prefer-native-locators': 'warn',
+                // Matches eslint-plugin-playwright's own recommended severity.
+                'playwright/prefer-web-first-assertions': 'error',
                 ...(profile === 'guardian' ? { ...guardianRuleConfigs } : {}),
             },
         },
@@ -67,8 +127,18 @@ function toSeverity(eslintSeverity, override) {
  * Does not load host-repo eslint.config.js.
  */
 export async function runEslint(options) {
-    const cwd = options.cwd ?? process.cwd();
-    const overrideConfig = buildConfig(options.profile);
+    // ESLint 9 flat config resolves a `basePath` from `cwd` and silently
+    // drops (as an untracked, ruleId-less message) any file that isn't
+    // underneath it — no error, no findings, just a quietly clean score.
+    // The caller's cwd (e.g. a runner process's install dir) has no reason
+    // to contain the spec files being scored, so it can never be trusted
+    // as the ESLint basePath. Derive a basePath that is guaranteed to
+    // contain every file instead; fall back to the caller's cwd only when
+    // there are no files (nothing to lint anyway).
+    const cwd = options.files.length > 0
+        ? commonAncestorDir(options.files)
+        : (options.cwd ?? process.cwd());
+    const overrideConfig = buildConfig(options.profile, options.assertFunctionNames ?? []);
     // Try to attach typescript-eslint parser for .ts files
     try {
         const tsParser = await import('@typescript-eslint/parser');
@@ -99,8 +169,39 @@ export async function runEslint(options) {
     const results = await eslint.lintFiles(options.files);
     const findings = [];
     for (const result of results) {
-        const file = path.resolve(result.filePath);
+        const absFile = path.resolve(result.filePath);
+        const file = path.relative(cwd, absFile) || path.basename(absFile);
         for (const msg of result.messages) {
+            // A `// eslint-disable-next-line some/rule-we-dont-bundle` comment is
+            // extremely common in real-world code (any host project that lints
+            // with plugins we don't embed, e.g. react-hooks, import, sonarjs, or
+            // even @typescript-eslint's own rules — we only bundle its parser,
+            // not its rule set). ESLint reports these with a fixed message
+            // regardless of reportUnusedDisableDirectives config, since it can't
+            // even validate a rule id it has no definition for. This is a
+            // diagnostic about *our* rule coverage, not the spec's quality —
+            // surfacing it as a finding (even report-only) is pure confusion,
+            // not signal.
+            if (/^Definition for rule '.*' was not found\.$/.test(msg.message)) {
+                continue;
+            }
+            if (msg.fatal) {
+                // A file that doesn't parse can't be meaningfully scored at all —
+                // surface it explicitly rather than silently dropping it (it has
+                // no ruleId) and letting an unparseable file default to a clean
+                // 100. scorePaths hard-fails the whole result when this rule id
+                // is present.
+                findings.push({
+                    rule: 'playwright-score/parse-error',
+                    severity: 'error',
+                    message: msg.message,
+                    file,
+                    line: msg.line,
+                    column: msg.column,
+                    dimension: 'structure',
+                });
+                continue;
+            }
             if (!msg.ruleId)
                 continue;
             const mapping = mapRule(msg.ruleId);

package/dist/formatters/markdown.js

@@ -22,5 +22,15 @@ export function formatMarkdown(result) {
             lines.push(`- **${f.severity}** \`${f.rule}\` \`${f.file}${loc}\` — ${f.message}`);
         }
     }
+    if (result.skippedFiles?.length) {
+        lines.push('');
+        lines.push(`<details><summary>Skipped — looks like a non-Playwright test (Jest/Vitest/RTL) (${result.skippedFiles.length})</summary>`);
+        lines.push('');
+        for (const f of result.skippedFiles) {
+            lines.push(`- \`${f}\``);
+        }
+        lines.push('');
+        lines.push('</details>');
+    }
     return lines.join('\n');
 }

package/dist/formatters/sarif.js

@@ -17,7 +17,7 @@ export function formatSarif(result) {
                 tool: {
                     driver: {
                         name: 'playwright-score',
-                        informationUri: 'https://github.com/qaguardian/playwright-score',
+                        informationUri: 'https://github.com/qa-guardian/playwright-score',
                         version: result.scoreVersion,
                         rules: [...rulesMap.values()],
                     },

package/dist/formatters/text.js

@@ -24,6 +24,16 @@ export function formatText(result) {
             lines.push(`  … and ${result.findings.length - 50} more`);
         }
     }
+    if (result.skippedFiles?.length) {
+        lines.push('');
+        lines.push(`Skipped (looks like a non-Playwright test — Jest/Vitest/RTL — ${result.skippedFiles.length}):`);
+        for (const f of result.skippedFiles.slice(0, 20)) {
+            lines.push(`  ${f}`);
+        }
+        if (result.skippedFiles.length > 20) {
+            lines.push(`  … and ${result.skippedFiles.length - 20} more`);
+        }
+    }
     return lines.join('\n');
 }
 function pathBasename(p) {

package/dist/fs-util.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Deepest directory that contains every given absolute file path.
+ * Used as the ESLint flat-config basePath so linting never silently
+ * excludes files that fall outside an unrelated caller cwd.
+ */
+export declare function commonAncestorDir(absoluteFiles: string[]): string;

package/dist/fs-util.js

@@ -0,0 +1,22 @@
+import path from 'node:path';
+/**
+ * Deepest directory that contains every given absolute file path.
+ * Used as the ESLint flat-config basePath so linting never silently
+ * excludes files that fall outside an unrelated caller cwd.
+ */
+export function commonAncestorDir(absoluteFiles) {
+    const dirs = absoluteFiles.map((f) => path.dirname(path.resolve(f)));
+    if (dirs.length === 0)
+        return process.cwd();
+    let common = dirs[0].split(path.sep);
+    for (const dir of dirs.slice(1)) {
+        const parts = dir.split(path.sep);
+        let i = 0;
+        while (i < common.length && i < parts.length && common[i] === parts[i]) {
+            i++;
+        }
+        common = common.slice(0, i);
+    }
+    const joined = common.join(path.sep);
+    return joined || path.sep;
+}

package/dist/index.js

@@ -2,7 +2,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { globSync } from 'glob';
 import { runEslint } from './eslint-runner.js';
-import { analyzeSource } from './metrics.js';
+import { commonAncestorDir } from './fs-util.js';
+import { analyzeSource, findLocalAssertionHelperNames, looksLikeNonPlaywrightTest, } from './metrics.js';
 import { DEFAULT_THRESHOLDS } from './profiles.js';
 import { computeScore } from './score-engine.js';
 export { computeScore, SQS_V1, locatorsScore, gradeFromScore } from './score-engine.js';
@@ -13,28 +14,103 @@ export { formatText } from './formatters/text.js';
 export { formatMarkdown } from './formatters/markdown.js';
 export { formatSarif } from './formatters/sarif.js';
 const SPEC_GLOBS = ['**/*.{spec,test}.{ts,tsx,js,jsx}', '**/*.spec.ts', '**/*.test.ts'];
+// Directory/glob expansion must never sweep in vendored or generated code —
+// verified as a real bug: scanning a project root with a plain node_modules
+// dependency that ships its own *.spec.ts files silently included them
+// alongside real specs. Every other JS tool in this space (ESLint,
+// Prettier, Jest) default-excludes these directories for the same reason;
+// an explicit file path always bypasses this (see `explicit` in
+// expandPaths), so this only affects auto-discovery.
+const DEFAULT_IGNORE_GLOBS = [
+    '**/node_modules/**',
+    '**/.git/**',
+    '**/dist/**',
+    '**/build/**',
+    '**/out/**',
+    '**/coverage/**',
+    '**/.next/**',
+    '**/.nuxt/**',
+    '**/.turbo/**',
+    '**/.cache/**',
+    '**/.svelte-kit/**',
+    '**/playwright-report/**',
+    '**/test-results/**',
+];
+/**
+ * `explicit`: paths the caller named directly (a literal existing file) —
+ * always scored, regardless of whether they look like a Playwright spec.
+ * `expanded`: everything else (matched via a directory scan or a glob
+ * pattern) — subject to the looksLikePlaywrightSpec filter in scorePaths,
+ * since a broad `**\/*.test.ts`-style match can just as easily sweep in
+ * unrelated Jest/Vitest/RTL unit tests sitting in the same repo.
+ */
 function expandPaths(inputs, cwd) {
-    const files = new Set();
+    const explicit = new Set();
+    const expanded = new Set();
     for (const input of inputs) {
         const abs = path.isAbsolute(input) ? input : path.resolve(cwd, input);
         if (fs.existsSync(abs) && fs.statSync(abs).isFile()) {
-            files.add(abs);
+            explicit.add(abs);
             continue;
         }
         if (fs.existsSync(abs) && fs.statSync(abs).isDirectory()) {
             for (const g of SPEC_GLOBS) {
-                for (const f of globSync(g, { cwd: abs, absolute: true, nodir: true })) {
-                    files.add(path.resolve(f));
+                for (const f of globSync(g, {
+                    cwd: abs,
+                    absolute: true,
+                    nodir: true,
+                    ignore: DEFAULT_IGNORE_GLOBS,
+                })) {
+                    expanded.add(path.resolve(f));
                 }
             }
             continue;
         }
         // treat as glob
-        for (const f of globSync(input, { cwd, absolute: true, nodir: true })) {
-            files.add(path.resolve(f));
+        for (const f of globSync(input, {
+            cwd,
+            absolute: true,
+            nodir: true,
+            ignore: DEFAULT_IGNORE_GLOBS,
+        })) {
+            expanded.add(path.resolve(f));
         }
     }
-    return [...files].sort();
+    // A file can be reached both explicitly and via expansion (e.g. an
+    // explicit path plus an overlapping glob); explicit intent wins.
+    for (const f of explicit)
+        expanded.delete(f);
+    return { explicit: [...explicit].sort(), expanded: [...expanded].sort() };
+}
+function hardFail(profile, threshold, findings, extra = {}, skippedFiles) {
+    return {
+        scoreVersion: 'sqs-v1',
+        profile,
+        score: 0,
+        grade: 'F',
+        pass: false,
+        threshold,
+        summary: {
+            files: 0,
+            tests: 0,
+            sloc: 0,
+            findings: findings.length,
+            errors: findings.filter((f) => f.severity === 'error').length,
+            warnings: findings.filter((f) => f.severity === 'warning').length,
+            nativeLocators: 0,
+            rawLocators: 0,
+            ...extra,
+        },
+        dimensions: {
+            playwrightHygiene: 0,
+            assertions: 0,
+            locators: 0,
+            structure: 0,
+            ...(profile === 'guardian' ? { guardianConventions: 0 } : {}),
+        },
+        findings,
+        ...(skippedFiles && skippedFiles.length > 0 ? { skippedFiles } : {}),
+    };
 }
 /**
  * Score Playwright spec files. Deterministic and AI-free (sqs-v1).
@@ -43,36 +119,78 @@ export async function scorePaths(options) {
     const cwd = options.cwd ?? process.cwd();
     const profile = options.profile ?? 'standard';
     const threshold = options.threshold ?? DEFAULT_THRESHOLDS[profile] ?? 80;
-    const files = expandPaths(options.paths, cwd);
+    const { explicit, expanded } = expandPaths(options.paths, cwd);
+    if (explicit.length === 0 && expanded.length === 0) {
+        // Hard-fail: empty match must never look like a healthy suite (was ~99 PASS).
+        return hardFail(profile, threshold, [
+            {
+                rule: 'playwright-score/no-files',
+                severity: 'error',
+                message: `No Playwright spec files matched: ${options.paths.join(', ') || '(no paths)'}`,
+                file: cwd,
+                dimension: 'structure',
+            },
+        ]);
+    }
+    // Directory/glob matches are excluded only on positive evidence of a
+    // non-Playwright test framework — see looksLikeNonPlaywrightTest. Paths
+    // the caller named explicitly are always scored regardless.
+    const skippedFiles = [];
+    const acceptedExpanded = [];
+    const skipBase = commonAncestorDir([...explicit, ...expanded]);
+    for (const f of expanded) {
+        const source = fs.readFileSync(f, 'utf8');
+        if (looksLikeNonPlaywrightTest(source)) {
+            skippedFiles.push(path.relative(skipBase, f) || path.basename(f));
+        }
+        else {
+            acceptedExpanded.push(f);
+        }
+    }
+    const files = [...explicit, ...acceptedExpanded].sort();
     if (files.length === 0) {
-        return computeScore({
-            profile,
-            threshold,
-            findings: [
-                {
-                    rule: 'playwright-score/no-files',
-                    severity: 'error',
-                    message: 'No Playwright spec files matched the given paths',
-                    file: cwd,
-                    dimension: 'structure',
-                },
-            ],
-            sloc: 1,
-            files: 0,
-            tests: 0,
-            nativeLocators: 0,
-            rawLocators: 0,
-        });
+        return hardFail(profile, threshold, [
+            {
+                rule: 'playwright-score/no-files',
+                severity: 'error',
+                message: `${expanded.length} file(s) matched but all look like non-Playwright tests (Jest/Vitest/RTL) — nothing to score.`,
+                file: cwd,
+                dimension: 'structure',
+            },
+        ], {}, skippedFiles);
     }
-    const eslintFindings = await runEslint({ files, profile, cwd });
+    // Relative to the files' own common ancestor (not the caller's cwd, which
+    // may be unrelated) so findings stay portable across machines/CI and
+    // formatters/sarif.ts can emit repo-relative artifactLocation URIs.
+    const filesBase = commonAncestorDir(files);
+    // Read every file once, up front, so (a) we can feed ESLint's
+    // expect-expect a per-run list of local assertion-helper names before
+    // linting (see findLocalAssertionHelperNames) and (b) the metrics loop
+    // below doesn't re-read the same files ESLint already read internally.
+    const sources = new Map();
+    const assertFunctionNames = new Set();
+    for (const file of files) {
+        const source = fs.readFileSync(file, 'utf8');
+        sources.set(file, source);
+        for (const name of findLocalAssertionHelperNames(source, file)) {
+            assertFunctionNames.add(name);
+        }
+    }
+    const eslintFindings = await runEslint({
+        files,
+        profile,
+        cwd,
+        assertFunctionNames: [...assertFunctionNames],
+    });
     let totalSloc = 0;
     let totalTests = 0;
     let native = 0;
     let raw = 0;
     const metricFindings = [];
     for (const file of files) {
-        const source = fs.readFileSync(file, 'utf8');
-        const m = analyzeSource(source, file);
+        const source = sources.get(file) ?? '';
+        const relFile = path.relative(filesBase, file) || path.basename(file);
+        const m = analyzeSource(source, relFile);
         totalSloc += m.sloc;
         totalTests += m.tests;
         native += m.locators.native;
@@ -82,7 +200,21 @@ export async function scorePaths(options) {
     }
     // Dedupe empty-test style: if guardian require-expect already fired, still ok
     const findings = [...eslintFindings, ...metricFindings];
-    return computeScore({
+    const parseErrors = findings.filter((f) => f.rule === 'playwright-score/parse-error');
+    if (parseErrors.length > 0) {
+        // A file that isn't valid JS/TS can't be executed, let alone scored on
+        // its merits. Diluting this into the normal per-dimension penalty math
+        // (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);
+    }
+    const result = computeScore({
         profile,
         threshold,
         findings,
@@ -92,4 +224,5 @@ export async function scorePaths(options) {
         nativeLocators: native,
         rawLocators: raw,
     });
+    return skippedFiles.length > 0 ? { ...result, skippedFiles } : result;
 }