@qaguardian/playwright-score 0.1.0

package/dist/formatters/text.js

@@ -0,0 +1,32 @@
+export function formatText(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}`);
+    }
+    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}`);
+    if (result.findings.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`);
+        }
+    }
+    return lines.join('\n');
+}
+function pathBasename(p) {
+    const parts = p.split(/[/\\]/);
+    return parts[parts.length - 1] ?? p;
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+import type { ScoreOptions, ScoreResult } from './types.js';
+export type { ScoreResult, ScoreOptions, Finding, ProfileName } from './types.js';
+export { computeScore, SQS_V1, locatorsScore, gradeFromScore } from './score-engine.js';
+export { countSloc } from './sloc.js';
+export { countLocators, analyzeSource } from './metrics.js';
+export { formatJson } from './formatters/json.js';
+export { formatText } from './formatters/text.js';
+export { formatMarkdown } from './formatters/markdown.js';
+export { formatSarif } from './formatters/sarif.js';
+/**
+ * Score Playwright spec files. Deterministic and AI-free (sqs-v1).
+ */
+export declare function scorePaths(options: ScoreOptions): Promise<ScoreResult>;

package/dist/index.js

@@ -0,0 +1,95 @@
+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 { DEFAULT_THRESHOLDS } from './profiles.js';
+import { computeScore } from './score-engine.js';
+export { computeScore, SQS_V1, locatorsScore, gradeFromScore } from './score-engine.js';
+export { countSloc } from './sloc.js';
+export { countLocators, analyzeSource } from './metrics.js';
+export { formatJson } from './formatters/json.js';
+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'];
+function expandPaths(inputs, cwd) {
+    const files = 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);
+            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));
+                }
+            }
+            continue;
+        }
+        // treat as glob
+        for (const f of globSync(input, { cwd, absolute: true, nodir: true })) {
+            files.add(path.resolve(f));
+        }
+    }
+    return [...files].sort();
+}
+/**
+ * Score Playwright spec files. Deterministic and AI-free (sqs-v1).
+ */
+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);
+    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,
+        });
+    }
+    const eslintFindings = await runEslint({ files, profile, cwd });
+    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);
+        totalSloc += m.sloc;
+        totalTests += m.tests;
+        native += m.locators.native;
+        raw += m.locators.raw;
+        // metrics/no-empty-test duplicates guardian/require-expect under guardian — keep both mild
+        metricFindings.push(...m.findings);
+    }
+    // Dedupe empty-test style: if guardian require-expect already fired, still ok
+    const findings = [...eslintFindings, ...metricFindings];
+    return computeScore({
+        profile,
+        threshold,
+        findings,
+        sloc: Math.max(totalSloc, 1),
+        files: files.length,
+        tests: totalTests,
+        nativeLocators: native,
+        rawLocators: raw,
+    });
+}

package/dist/metrics.d.ts

@@ -0,0 +1,17 @@
+import type { Finding, LocatorCounts } from './types.js';
+/** Count native vs raw locator calls (simple statistical). */
+export declare function countLocators(source: string): LocatorCounts;
+/** Count test( / test.only( / test.skip( style declarations (approx). */
+export declare function countTests(source: string): number;
+/**
+ * Detect test callbacks that appear to have zero expect( calls.
+ * Heuristic: for each test( ... async (...) => { body }, check body for expect.
+ */
+export declare function findEmptyExpectTests(source: string, file: string): Finding[];
+export declare function findOversizedFile(source: string, file: string, maxSloc?: number): Finding[];
+export declare function analyzeSource(source: string, file: string): {
+    sloc: number;
+    tests: number;
+    locators: LocatorCounts;
+    findings: Finding[];
+};

package/dist/metrics.js

@@ -0,0 +1,79 @@
+import { countSloc } from './sloc.js';
+const NATIVE_RE = /\.\s*getBy(?:Role|Label|TestId|Text|Placeholder)\s*\(/g;
+const RAW_RE = /(?:page|frame)\s*\.\s*locator\s*\(/g;
+/** Count native vs raw locator calls (simple statistical). */
+export function countLocators(source) {
+    const native = [...source.matchAll(NATIVE_RE)].length;
+    const raw = [...source.matchAll(RAW_RE)].length;
+    return { native, raw };
+}
+/** Count test( / test.only( / test.skip( style declarations (approx). */
+export function countTests(source) {
+    const re = /\btest(?:\.(?:only|skip|fix|slow))?\s*\(/g;
+    // Exclude test.describe, test.step, test.before*, test.after*, test.use
+    let count = 0;
+    let m;
+    const exclude = /\btest\.(?:describe|step|beforeEach|afterEach|beforeAll|afterAll|use|setTimeout|info|expect)\b/;
+    while ((m = re.exec(source)) !== null) {
+        const start = Math.max(0, m.index - 0);
+        const snippet = source.slice(start, start + 40);
+        if (exclude.test(snippet.split('(')[0] + '(')) {
+            // more precise: check the matched prefix
+        }
+        const before = source.slice(Math.max(0, m.index - 1), m.index + 20);
+        if (/\btest\.(describe|step|beforeEach|afterEach|beforeAll|afterAll|use|setTimeout|info)\b/.test(before)) {
+            continue;
+        }
+        // test.expect is rare as call form
+        if (/\btest\.expect\b/.test(before))
+            continue;
+        count++;
+    }
+    return count;
+}
+/**
+ * Detect test callbacks that appear to have zero expect( calls.
+ * Heuristic: for each test( ... async (...) => { body }, check body for expect.
+ */
+export function findEmptyExpectTests(source, file) {
+    const findings = [];
+    // Rough scan: if file has test( but no expect( at all
+    const hasTest = /\btest(?:\.(?:only|skip|fix))?\s*\(/.test(source);
+    const hasExpect = /\bexpect\s*\(/.test(source);
+    if (hasTest && !hasExpect) {
+        findings.push({
+            rule: 'metrics/no-empty-test',
+            severity: 'error',
+            message: 'Test file has test() but no expect() assertions',
+            file,
+            dimension: 'assertions',
+        });
+    }
+    return findings;
+}
+export function findOversizedFile(source, file, maxSloc = 400) {
+    const sloc = countSloc(source);
+    if (sloc > maxSloc) {
+        return [
+            {
+                rule: 'metrics/oversized-file',
+                severity: 'warning',
+                message: `File has ${sloc} SLOC (limit ${maxSloc})`,
+                file,
+                dimension: 'structure',
+            },
+        ];
+    }
+    return [];
+}
+export function analyzeSource(source, file) {
+    return {
+        sloc: countSloc(source),
+        tests: countTests(source),
+        locators: countLocators(source),
+        findings: [
+            ...findEmptyExpectTests(source, file),
+            ...findOversizedFile(source, file),
+        ],
+    };
+}

package/dist/profiles.d.ts

@@ -0,0 +1,15 @@
+import type { DimensionName, ProfileName } from './types.js';
+export declare const PROFILE_WEIGHTS: Record<ProfileName, Partial<Record<DimensionName, number>>>;
+export declare const DEFAULT_THRESHOLDS: Record<ProfileName, number>;
+/** Map eslint ruleId → dimension + whether report-only for scoring */
+export interface RuleMapping {
+    dimension: DimensionName;
+    /** Override severity for scoring units; undefined keeps ESLint severity */
+    severityOverride?: 'error' | 'warning' | 'info';
+    reportOnly?: boolean;
+}
+/**
+ * ESLint rule → dimension map (plugin rule ids without prefix handled in runner).
+ */
+export declare const ESLINT_RULE_MAP: Record<string, RuleMapping>;
+export declare function mapRule(ruleId: string): RuleMapping;

package/dist/profiles.js

@@ -0,0 +1,130 @@
+export const PROFILE_WEIGHTS = {
+    standard: {
+        playwrightHygiene: 40,
+        assertions: 25,
+        locators: 20,
+        structure: 15,
+    },
+    guardian: {
+        playwrightHygiene: 30,
+        assertions: 15,
+        locators: 15,
+        structure: 15,
+        guardianConventions: 25,
+    },
+};
+export const DEFAULT_THRESHOLDS = {
+    standard: 80,
+    guardian: 75,
+};
+/**
+ * ESLint rule → dimension map (plugin rule ids without prefix handled in runner).
+ */
+export const ESLINT_RULE_MAP = {
+    // Hygiene
+    'playwright/no-wait-for-timeout': { dimension: 'playwrightHygiene' },
+    'playwright/no-networkidle': { dimension: 'playwrightHygiene' },
+    'playwright/no-force-option': { dimension: 'playwrightHygiene' },
+    'playwright/no-wait-for-selector': { dimension: 'playwrightHygiene' },
+    'playwright/no-wait-for-navigation': { dimension: 'playwrightHygiene' },
+    'playwright/missing-playwright-await': { dimension: 'playwrightHygiene' },
+    'playwright/no-element-handle': { dimension: 'playwrightHygiene' },
+    'playwright/no-eval': { dimension: 'playwrightHygiene' },
+    'playwright/no-conditional-in-test': {
+        dimension: 'playwrightHygiene',
+        severityOverride: 'warning',
+    },
+    'playwright/no-conditional-expect': {
+        dimension: 'playwrightHygiene',
+        severityOverride: 'warning',
+    },
+    'playwright/no-page-pause': { dimension: 'playwrightHygiene' },
+    'playwright/no-useless-await': {
+        dimension: 'playwrightHygiene',
+        severityOverride: 'warning',
+    },
+    // Assertions
+    'playwright/expect-expect': { dimension: 'assertions' },
+    'playwright/prefer-web-first-assertions': {
+        dimension: 'assertions',
+        severityOverride: 'warning',
+    },
+    'playwright/valid-expect': { dimension: 'assertions' },
+    'playwright/no-standalone-expect': { dimension: 'assertions' },
+    // Locators — findings for repair, reportOnly so ratio owns locators score
+    'playwright/no-raw-locators': {
+        dimension: 'locators',
+        reportOnly: true,
+        severityOverride: 'warning',
+    },
+    'playwright/prefer-native-locators': {
+        dimension: 'locators',
+        reportOnly: true,
+        severityOverride: 'warning',
+    },
+    'playwright/prefer-locator': {
+        dimension: 'locators',
+        reportOnly: true,
+        severityOverride: 'info',
+    },
+    // Structure
+    'playwright/no-focused-test': { dimension: 'structure' },
+    'playwright/no-skipped-test': {
+        dimension: 'structure',
+        severityOverride: 'warning',
+    },
+    'playwright/max-nested-describe': {
+        dimension: 'structure',
+        severityOverride: 'warning',
+    },
+    'playwright/require-top-level-describe': {
+        dimension: 'structure',
+        severityOverride: 'warning',
+    },
+    // Guardian custom rules
+    'guardian/no-wait-for-load-state': { dimension: 'guardianConventions' },
+    'guardian/no-date-now-id': { dimension: 'guardianConventions' },
+    'guardian/require-expect': { dimension: 'guardianConventions' },
+    'guardian/no-hardcoded-secrets': {
+        dimension: 'guardianConventions',
+        severityOverride: 'warning',
+    },
+    'guardian/require-test-step': {
+        dimension: 'guardianConventions',
+        severityOverride: 'warning',
+    },
+    'guardian/one-describe-one-test': {
+        dimension: 'guardianConventions',
+        severityOverride: 'warning',
+    },
+    'guardian/no-generic-long-timeout': {
+        dimension: 'guardianConventions',
+        severityOverride: 'warning',
+    },
+    'guardian/prefer-uuid': {
+        dimension: 'guardianConventions',
+        severityOverride: 'warning',
+    },
+    'guardian/fixtures-import': {
+        dimension: 'guardianConventions',
+        severityOverride: 'info',
+        reportOnly: true,
+    },
+    // Metrics injected as synthetic findings
+    'metrics/no-empty-test': { dimension: 'assertions' },
+    'metrics/oversized-file': {
+        dimension: 'structure',
+        severityOverride: 'warning',
+    },
+};
+export function mapRule(ruleId) {
+    if (ESLINT_RULE_MAP[ruleId])
+        return ESLINT_RULE_MAP[ruleId];
+    if (ruleId.startsWith('guardian/')) {
+        return { dimension: 'guardianConventions', severityOverride: 'warning' };
+    }
+    if (ruleId.startsWith('playwright/')) {
+        return { dimension: 'playwrightHygiene', severityOverride: 'warning' };
+    }
+    return { dimension: 'playwrightHygiene', severityOverride: 'info', reportOnly: true };
+}

package/dist/rules/guardian-plugin.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Guardian house-style ESLint rules for profile=guardian.
+ * Embedded in playwright-score — not claimed as official Playwright doctrine.
+ */
+import type { Rule } from 'eslint';
+export declare const guardianPlugin: {
+    meta: {
+        name: string;
+        version: string;
+    };
+    rules: {
+        'no-wait-for-load-state': Rule.RuleModule;
+        'no-date-now-id': Rule.RuleModule;
+        'no-hardcoded-secrets': Rule.RuleModule;
+        'no-generic-long-timeout': Rule.RuleModule;
+        'one-describe-one-test': Rule.RuleModule;
+        'require-test-step': Rule.RuleModule;
+        'require-expect': Rule.RuleModule;
+    };
+};
+export declare const guardianRuleConfigs: {
+    readonly 'guardian/no-wait-for-load-state': "error";
+    readonly 'guardian/no-date-now-id': "error";
+    readonly 'guardian/no-hardcoded-secrets': "warn";
+    readonly 'guardian/no-generic-long-timeout': "warn";
+    readonly 'guardian/one-describe-one-test': "warn";
+    readonly 'guardian/require-test-step': "warn";
+    readonly 'guardian/require-expect': "error";
+};