@qaguardian/playwright-score 0.1.0

package/dist/rules/guardian-plugin.js

@@ -0,0 +1,285 @@
+const DUMMY_SECRETS = new Set([
+    'password',
+    'password123',
+    'test',
+    'test123',
+    'secret',
+    'changeme',
+    'admin',
+    'admin123',
+    'pass',
+    'pwd',
+    '123456',
+    'qwerty',
+    '',
+].map((s) => s.toLowerCase()));
+function hasDisableNextLine(sourceCode, line, ruleId) {
+    const lines = sourceCode.getText().split(/\r?\n/);
+    if (line < 2)
+        return false;
+    const prev = lines[line - 2] ?? '';
+    return (prev.includes('spec-score-disable-next-line') &&
+        (prev.includes(ruleId) || prev.includes('guardian/')));
+}
+const noWaitForLoadState = {
+    meta: {
+        type: 'problem',
+        docs: { description: 'Disallow page.waitForLoadState()' },
+        messages: {
+            banned: 'waitForLoadState is banned under guardian profile. Use web-first assertions.',
+        },
+        schema: [],
+    },
+    create(context) {
+        return {
+            CallExpression(node) {
+                const callee = node.callee;
+                if (callee.type === 'MemberExpression' &&
+                    !callee.computed &&
+                    callee.property.type === 'Identifier' &&
+                    callee.property.name === 'waitForLoadState') {
+                    context.report({ node, messageId: 'banned' });
+                }
+            },
+        };
+    },
+};
+const noDateNowId = {
+    meta: {
+        type: 'problem',
+        docs: { description: 'Disallow Date.now() for unique ids' },
+        messages: {
+            banned: 'Date.now() is banned for unique ids. Use crypto.randomUUID().split("-")[0].',
+        },
+        schema: [],
+    },
+    create(context) {
+        return {
+            CallExpression(node) {
+                const callee = node.callee;
+                if (callee.type === 'MemberExpression' &&
+                    !callee.computed &&
+                    callee.object.type === 'Identifier' &&
+                    callee.object.name === 'Date' &&
+                    callee.property.type === 'Identifier' &&
+                    callee.property.name === 'now') {
+                    context.report({ node, messageId: 'banned' });
+                }
+            },
+        };
+    },
+};
+const noHardcodedSecrets = {
+    meta: {
+        type: 'suggestion',
+        docs: { description: 'Flag likely hardcoded secrets (with allowlist)' },
+        messages: {
+            secret: 'Possible hardcoded secret value. Use env/fixtures or allowlist dummy data.',
+        },
+        schema: [],
+    },
+    create(context) {
+        const sourceCode = context.sourceCode ?? context.getSourceCode();
+        const keyRe = /password|passwd|secret|token|api[_-]?key|auth/i;
+        function check(node, rawKey) {
+            if (node.type !== 'Literal' || typeof node.value !== 'string')
+                return;
+            const value = String(node.value);
+            if (DUMMY_SECRETS.has(value.toLowerCase()))
+                return;
+            if (value.length < 6)
+                return;
+            if (!keyRe.test(rawKey ?? ''))
+                return;
+            const line = node.loc?.start.line ?? 1;
+            if (hasDisableNextLine(sourceCode, line, 'guardian/no-hardcoded-secrets'))
+                return;
+            context.report({ node: node, messageId: 'secret' });
+        }
+        return {
+            Property(node) {
+                if (node.key.type === 'Identifier') {
+                    check(node.value, node.key.name);
+                }
+                else if (node.key.type === 'Literal') {
+                    check(node.value, String(node.key.value));
+                }
+            },
+            VariableDeclarator(node) {
+                if (node.id.type === 'Identifier' && node.init) {
+                    check(node.init, node.id.name);
+                }
+            },
+        };
+    },
+};
+const noGenericLongTimeout = {
+    meta: {
+        type: 'suggestion',
+        docs: { description: 'Only allow timeout 2000 or 20000' },
+        messages: {
+            timeout: 'Avoid generic timeouts; allowed values under guardian: 2000 (audit) or 20000 (backend).',
+        },
+        schema: [],
+    },
+    create(context) {
+        const allowed = new Set([2000, 20000]);
+        return {
+            Property(node) {
+                if (node.key.type === 'Identifier' &&
+                    node.key.name === 'timeout' &&
+                    node.value.type === 'Literal' &&
+                    typeof node.value.value === 'number' &&
+                    !allowed.has(node.value.value)) {
+                    context.report({ node, messageId: 'timeout' });
+                }
+            },
+        };
+    },
+};
+const oneDescribeOneTest = {
+    meta: {
+        type: 'suggestion',
+        docs: { description: 'Prefer one test.describe and one test per file' },
+        messages: {
+            describes: 'Guardian profile prefers exactly one test.describe() per file (found {{count}}).',
+            tests: 'Guardian profile prefers exactly one test() per file (found {{count}}).',
+        },
+        schema: [],
+    },
+    create(context) {
+        let describes = 0;
+        let tests = 0;
+        return {
+            CallExpression(node) {
+                if (node.callee.type === 'MemberExpression' && !node.callee.computed) {
+                    if (node.callee.object.type === 'Identifier' &&
+                        node.callee.object.name === 'test' &&
+                        node.callee.property.type === 'Identifier' &&
+                        node.callee.property.name === 'describe') {
+                        describes++;
+                    }
+                }
+                if (node.callee.type === 'Identifier' && node.callee.name === 'test') {
+                    tests++;
+                }
+                if (node.callee.type === 'MemberExpression' &&
+                    !node.callee.computed &&
+                    node.callee.object.type === 'Identifier' &&
+                    node.callee.object.name === 'test' &&
+                    node.callee.property.type === 'Identifier' &&
+                    ['only', 'skip', 'fix', 'slow'].includes(node.callee.property.name)) {
+                    tests++;
+                }
+            },
+            'Program:exit'() {
+                if (describes > 1) {
+                    context.report({
+                        loc: { line: 1, column: 0 },
+                        messageId: 'describes',
+                        data: { count: String(describes) },
+                    });
+                }
+                if (tests > 1) {
+                    context.report({
+                        loc: { line: 1, column: 0 },
+                        messageId: 'tests',
+                        data: { count: String(tests) },
+                    });
+                }
+            },
+        };
+    },
+};
+const requireTestStep = {
+    meta: {
+        type: 'suggestion',
+        docs: { description: 'Warn when file uses test() but no test.step()' },
+        messages: {
+            missing: 'Consider wrapping actions in test.step() for clearer structure.',
+        },
+        schema: [],
+    },
+    create(context) {
+        let hasTest = false;
+        let hasStep = false;
+        return {
+            CallExpression(node) {
+                if (node.callee.type === 'Identifier' && node.callee.name === 'test') {
+                    hasTest = true;
+                }
+                if (node.callee.type === 'MemberExpression' &&
+                    !node.callee.computed &&
+                    node.callee.object.type === 'Identifier' &&
+                    node.callee.object.name === 'test' &&
+                    node.callee.property.type === 'Identifier') {
+                    if (['only', 'skip', 'fix', 'slow'].includes(node.callee.property.name)) {
+                        hasTest = true;
+                    }
+                    if (node.callee.property.name === 'step')
+                        hasStep = true;
+                }
+            },
+            'Program:exit'() {
+                if (hasTest && !hasStep) {
+                    context.report({ loc: { line: 1, column: 0 }, messageId: 'missing' });
+                }
+            },
+        };
+    },
+};
+const requireExpect = {
+    meta: {
+        type: 'problem',
+        docs: { description: 'Require expect() in files with test()' },
+        messages: {
+            missing: 'Guardian profile requires at least one expect() in the spec.',
+        },
+        schema: [],
+    },
+    create(context) {
+        let hasTest = false;
+        let hasExpect = false;
+        return {
+            CallExpression(node) {
+                if (node.callee.type === 'Identifier' && node.callee.name === 'test') {
+                    hasTest = true;
+                }
+                if (node.callee.type === 'Identifier' && node.callee.name === 'expect') {
+                    hasExpect = true;
+                }
+                if (node.callee.type === 'MemberExpression' &&
+                    node.callee.object.type === 'Identifier' &&
+                    node.callee.object.name === 'expect') {
+                    hasExpect = true;
+                }
+            },
+            'Program:exit'() {
+                if (hasTest && !hasExpect) {
+                    context.report({ loc: { line: 1, column: 0 }, messageId: 'missing' });
+                }
+            },
+        };
+    },
+};
+export const guardianPlugin = {
+    meta: { name: 'guardian', version: '0.1.0' },
+    rules: {
+        'no-wait-for-load-state': noWaitForLoadState,
+        'no-date-now-id': noDateNowId,
+        'no-hardcoded-secrets': noHardcodedSecrets,
+        'no-generic-long-timeout': noGenericLongTimeout,
+        'one-describe-one-test': oneDescribeOneTest,
+        'require-test-step': requireTestStep,
+        'require-expect': requireExpect,
+    },
+};
+export const guardianRuleConfigs = {
+    'guardian/no-wait-for-load-state': 'error',
+    'guardian/no-date-now-id': 'error',
+    'guardian/no-hardcoded-secrets': 'warn',
+    'guardian/no-generic-long-timeout': 'warn',
+    'guardian/one-describe-one-test': 'warn',
+    'guardian/require-test-step': 'warn',
+    'guardian/require-expect': 'error',
+};

package/dist/score-engine.d.ts

@@ -0,0 +1,29 @@
+import type { DimensionName, Finding, Grade, ProfileName, ScoreResult } from './types.js';
+/** sqs-v1 frozen constants — change requires sqs-v2 */
+export declare const SQS_V1: {
+    readonly scoreVersion: "sqs-v1";
+    readonly ERROR_UNIT: 1;
+    readonly WARNING_UNIT: 0.4;
+    readonly INFO_UNIT: 0;
+    readonly MAX_FINDINGS_PER_RULE_PER_FILE: 3;
+    readonly SLOT_DIVISOR: 25;
+    readonly MIN_SLOTS: 4;
+    readonly K: 0.4;
+};
+declare const PENALTY_DIMENSIONS: DimensionName[];
+export declare function gradeFromScore(score: number): Grade;
+export declare function locatorsScore(native: number, raw: number): number;
+/** Cap findings per (file, rule) for penalty math only */
+export declare function applyPerRuleCap(findings: Finding[]): Finding[];
+export declare function penaltyDimensionScore(findings: Finding[], dimension: DimensionName, sloc: number): number;
+export declare function computeScore(input: {
+    profile: ProfileName;
+    threshold: number;
+    findings: Finding[];
+    sloc: number;
+    files: number;
+    tests: number;
+    nativeLocators: number;
+    rawLocators: number;
+}): ScoreResult;
+export { PENALTY_DIMENSIONS };

package/dist/score-engine.js

@@ -0,0 +1,114 @@
+import { PROFILE_WEIGHTS } from './profiles.js';
+/** sqs-v1 frozen constants — change requires sqs-v2 */
+export const SQS_V1 = {
+    scoreVersion: 'sqs-v1',
+    ERROR_UNIT: 1.0,
+    WARNING_UNIT: 0.4,
+    INFO_UNIT: 0.0,
+    MAX_FINDINGS_PER_RULE_PER_FILE: 3,
+    SLOT_DIVISOR: 25,
+    MIN_SLOTS: 4,
+    K: 0.4,
+};
+const PENALTY_DIMENSIONS = [
+    'playwrightHygiene',
+    'assertions',
+    'structure',
+    'guardianConventions',
+];
+export function gradeFromScore(score) {
+    if (score >= 90)
+        return 'A';
+    if (score >= 80)
+        return 'B';
+    if (score >= 70)
+        return 'C';
+    if (score >= 60)
+        return 'D';
+    return 'F';
+}
+export function locatorsScore(native, raw) {
+    const total = native + raw;
+    if (total === 0)
+        return 100;
+    return Math.round((100 * native) / total);
+}
+function severityUnit(severity) {
+    if (severity === 'error')
+        return SQS_V1.ERROR_UNIT;
+    if (severity === 'warning')
+        return SQS_V1.WARNING_UNIT;
+    return SQS_V1.INFO_UNIT;
+}
+/** Cap findings per (file, rule) for penalty math only */
+export function applyPerRuleCap(findings) {
+    const counts = new Map();
+    const out = [];
+    for (const f of findings) {
+        if (f.reportOnly)
+            continue;
+        const key = `${f.file}::${f.rule}`;
+        const n = counts.get(key) ?? 0;
+        if (n >= SQS_V1.MAX_FINDINGS_PER_RULE_PER_FILE)
+            continue;
+        counts.set(key, n + 1);
+        out.push(f);
+    }
+    return out;
+}
+export function penaltyDimensionScore(findings, dimension, sloc) {
+    const dimFindings = findings.filter((f) => f.dimension === dimension);
+    const capped = applyPerRuleCap(dimFindings);
+    let rawUnits = 0;
+    for (const f of capped) {
+        rawUnits += severityUnit(f.severity);
+    }
+    const slots = Math.max(sloc / SQS_V1.SLOT_DIVISOR, SQS_V1.MIN_SLOTS);
+    const load = rawUnits / slots;
+    const score = Math.round(100 * Math.exp(-SQS_V1.K * load));
+    return Math.min(100, Math.max(0, score));
+}
+export function computeScore(input) {
+    const weights = PROFILE_WEIGHTS[input.profile];
+    const dims = {
+        playwrightHygiene: penaltyDimensionScore(input.findings, 'playwrightHygiene', input.sloc),
+        assertions: penaltyDimensionScore(input.findings, 'assertions', input.sloc),
+        locators: locatorsScore(input.nativeLocators, input.rawLocators),
+        structure: penaltyDimensionScore(input.findings, 'structure', input.sloc),
+    };
+    if (input.profile === 'guardian') {
+        dims.guardianConventions = penaltyDimensionScore(input.findings, 'guardianConventions', input.sloc);
+    }
+    let score = 0;
+    for (const [dim, weight] of Object.entries(weights)) {
+        const key = dim;
+        const value = dims[key];
+        if (value === undefined)
+            continue;
+        score += (weight / 100) * value;
+    }
+    score = Math.round(score);
+    const errors = input.findings.filter((f) => f.severity === 'error').length;
+    const warnings = input.findings.filter((f) => f.severity === 'warning').length;
+    return {
+        scoreVersion: SQS_V1.scoreVersion,
+        profile: input.profile,
+        score,
+        grade: gradeFromScore(score),
+        pass: score >= input.threshold,
+        threshold: input.threshold,
+        summary: {
+            files: input.files,
+            tests: input.tests,
+            sloc: input.sloc,
+            findings: input.findings.length,
+            errors,
+            warnings,
+            nativeLocators: input.nativeLocators,
+            rawLocators: input.rawLocators,
+        },
+        dimensions: dims,
+        findings: input.findings,
+    };
+}
+export { PENALTY_DIMENSIONS };

package/dist/sloc.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Count source lines of code: exclude blank and pure-comment lines.
+ */
+export declare function countSloc(source: string): number;

package/dist/sloc.js

@@ -0,0 +1,38 @@
+/**
+ * Count source lines of code: exclude blank and pure-comment lines.
+ */
+export function countSloc(source) {
+    const lines = source.split(/\r?\n/);
+    let sloc = 0;
+    let inBlockComment = false;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        if (inBlockComment) {
+            if (trimmed.includes('*/')) {
+                inBlockComment = false;
+                const after = trimmed.slice(trimmed.indexOf('*/') + 2).trim();
+                if (after && !after.startsWith('//'))
+                    sloc++;
+            }
+            continue;
+        }
+        if (trimmed.startsWith('/*')) {
+            if (!trimmed.includes('*/')) {
+                inBlockComment = true;
+                continue;
+            }
+            // single-line block comment /* ... */
+            const after = trimmed.replace(/\/\*.*?\*\//g, '').trim();
+            if (!after || after.startsWith('//'))
+                continue;
+            sloc++;
+            continue;
+        }
+        if (trimmed.startsWith('//'))
+            continue;
+        sloc++;
+    }
+    return Math.max(sloc, 1);
+}

package/dist/types.d.ts

@@ -0,0 +1,61 @@
+export type ScoreVersion = 'sqs-v1';
+export type ProfileName = 'standard' | 'guardian';
+export type Grade = 'A' | 'B' | 'C' | 'D' | 'F';
+export type Severity = 'error' | 'warning' | 'info';
+export type DimensionName = 'playwrightHygiene' | 'assertions' | 'locators' | 'structure' | 'guardianConventions';
+export interface Finding {
+    rule: string;
+    severity: Severity;
+    message: string;
+    file: string;
+    line?: number;
+    column?: number;
+    dimension: DimensionName;
+    /** When true, finding is listed but does not contribute penalty units */
+    reportOnly?: boolean;
+}
+export interface ScoreDimensions {
+    playwrightHygiene: number;
+    assertions: number;
+    locators: number;
+    structure: number;
+    guardianConventions?: number;
+}
+export interface ScoreSummary {
+    files: number;
+    tests: number;
+    sloc: number;
+    findings: number;
+    errors: number;
+    warnings: number;
+    nativeLocators: number;
+    rawLocators: number;
+}
+export interface ScoreResult {
+    scoreVersion: ScoreVersion;
+    profile: ProfileName;
+    score: number;
+    grade: Grade;
+    pass: boolean;
+    threshold: number;
+    summary: ScoreSummary;
+    dimensions: ScoreDimensions;
+    findings: Finding[];
+}
+export interface ScoreOptions {
+    paths: string[];
+    profile?: ProfileName;
+    threshold?: number;
+    cwd?: string;
+}
+export interface LocatorCounts {
+    native: number;
+    raw: number;
+}
+export interface FileMetrics {
+    file: string;
+    sloc: number;
+    tests: number;
+    locators: LocatorCounts;
+    findings: Finding[];
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@qaguardian/playwright-score",
+  "version": "0.1.0",
+  "description": "Deterministic, AI-free Playwright spec quality score (sqs-v1). Lint + score with standard and guardian profiles.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "playwright-score": "bin/playwright-score.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "bin",
+    "dist",
+    "METHODOLOGY.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc && node -e \"require('fs').chmodSync('dist/cli.js',0o755); require('fs').chmodSync('bin/playwright-score.js',0o755)\"",
+    "build:tests": "tsc -p tsconfig.tests.json",
+    "test": "npm run build && npm run build:tests && node --test dist-tests/tests/*.js",
+    "score": "npm run build && node bin/playwright-score.js",
+    "dogfood": "npm run build && bash scripts/dogfood.sh",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "playwright",
+    "eslint",
+    "testing",
+    "quality",
+    "score",
+    "lint",
+    "e2e"
+  ],
+  "license": "MIT",
+  "author": "QA Guardian <qag@qaguardian.com> (https://qaguardian.com)",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/qa-guardian/playwright-score.git"
+  },
+  "bugs": {
+    "url": "https://github.com/qa-guardian/playwright-score/issues"
+  },
+  "homepage": "https://qaguardian.com/open-source/playwright-score",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@typescript-eslint/parser": "^8.18.0",
+    "eslint": "^9.17.0",
+    "eslint-plugin-playwright": "^2.1.0",
+    "glob": "^11.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.2"
+  }
+}