@qaguardian/playwright-score 1.0.0 → 2.1.0

package/dist/score-engine.d.ts

@@ -24,9 +24,17 @@ import type { DimensionName, Finding, Grade, ProfileName, ScoreResult } from './
  * scored e.g. a 3-test suite with two hard-wait errors, two assertion-free
  * tests, and a skipped test at 78/C; model v3 scores it 53/F, which is
  * what it is.
+ *
+ * v4 (2.0.0) keeps this exact formula unchanged — the version bump is
+ * about which findings feed it, not how they're aggregated: the four
+ * QAG-196 gameability rules and the eslint-disable-comment finding are
+ * now unconditional demerits (previously report-only under `standard`,
+ * scored only under the now-removed `strict` profile), and
+ * no-coordinate-click is a warning (0.4), not an error (1.0). See
+ * METHODOLOGY.md's "Why v4" and CHANGELOG.md.
  */
 export declare const MODEL: {
-    readonly scoreVersion: "v3";
+    readonly scoreVersion: "v4";
     readonly ERROR_DEMERIT: 1;
     readonly WARNING_DEMERIT: 0.4;
     readonly INFO_DEMERIT: 0;

package/dist/score-engine.js

@@ -24,9 +24,17 @@ import { PROFILE_WEIGHTS } from './profiles.js';
  * scored e.g. a 3-test suite with two hard-wait errors, two assertion-free
  * tests, and a skipped test at 78/C; model v3 scores it 53/F, which is
  * what it is.
+ *
+ * v4 (2.0.0) keeps this exact formula unchanged — the version bump is
+ * about which findings feed it, not how they're aggregated: the four
+ * QAG-196 gameability rules and the eslint-disable-comment finding are
+ * now unconditional demerits (previously report-only under `standard`,
+ * scored only under the now-removed `strict` profile), and
+ * no-coordinate-click is a warning (0.4), not an error (1.0). See
+ * METHODOLOGY.md's "Why v4" and CHANGELOG.md.
  */
 export const MODEL = {
-    scoreVersion: 'v3',
+    scoreVersion: 'v4',
     ERROR_DEMERIT: 1.0,
     WARNING_DEMERIT: 0.4,
     INFO_DEMERIT: 0.0,

package/dist/test-aliases.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Detects identifiers bound (directly, or via a local import/re-export
+ * chain of any depth) to `<base>.extend(...)` where `<base>` is `test`
+ * imported from `@playwright/test`, or is itself such an extended test.
+ * Returns the flat set of alias name strings (e.g. `loggedTest`,
+ * `testWithAssets`) usable anywhere they're called across the scored
+ * files — callers feed this into `eslint-runner.ts`'s
+ * `settings.playwright.globalAliases.test` and into `metrics.ts`'s
+ * `getTestSpans`/`countTests` and `base-plugin.ts`'s test-name checks.
+ *
+ * `sources`/`importedFiles` are the same maps `index.ts` already builds
+ * (scored spec files, and their transitively-collected local relative
+ * imports — see `collectLocallyImportedFiles`); this function does not
+ * walk the filesystem itself beyond resolving relative specifiers already
+ * present in those files' own import/export statements, and never
+ * escapes `boundaryDir` (same safety rule as `import-graph.ts`).
+ */
+export declare function detectExtendedTestAliases(sources: Map<string, string>, importedFiles: Map<string, string>, boundaryDir: string): string[];

package/dist/test-aliases.js

@@ -0,0 +1,218 @@
+import { parseForESLint } from '@typescript-eslint/parser';
+import { resolveRelativeImport } from './import-graph.js';
+function isRelativeSpecifier(value) {
+    return typeof value === 'string' && value.startsWith('.');
+}
+function parseFileInfo(source, file) {
+    let ast;
+    try {
+        ast = parseForESLint(source, {
+            ecmaVersion: 2022,
+            sourceType: 'module',
+            ecmaFeatures: { jsx: /\.(tsx|jsx)$/.test(file) },
+        }).ast;
+    }
+    catch {
+        return undefined;
+    }
+    const playwrightTestLocalNames = new Set();
+    const extendDeclarations = [];
+    const directExportNames = new Set();
+    const imports = [];
+    const reExports = [];
+    function collectExtendFromVariableDeclaration(decl) {
+        const declarations = (decl.declarations ?? []);
+        for (const d of declarations) {
+            if (d.id?.type !== 'Identifier' || !d.id.name || !d.init)
+                continue;
+            const init = d.init;
+            if (init.type === 'CallExpression' &&
+                init.callee?.type === 'MemberExpression') {
+                const callee = init.callee;
+                const property = callee.property;
+                const object = callee.object;
+                if (!callee.computed &&
+                    property?.type === 'Identifier' &&
+                    property.name === 'extend' &&
+                    object?.type === 'Identifier' &&
+                    object.name) {
+                    extendDeclarations.push({ declaredName: d.id.name, baseName: object.name });
+                }
+            }
+        }
+    }
+    // Generic subtree walk to find `const X = Y.extend(...)` anywhere (not
+    // just top-level) — a fixture module may nest these inside a helper.
+    function walk(node) {
+        if (!node || typeof node !== 'object')
+            return;
+        if (Array.isArray(node)) {
+            for (const item of node)
+                walk(item);
+            return;
+        }
+        const obj = node;
+        if (obj.type === 'VariableDeclaration')
+            collectExtendFromVariableDeclaration(obj);
+        for (const key in obj) {
+            if (key === 'parent')
+                continue;
+            const value = obj[key];
+            if (value && typeof value === 'object')
+                walk(value);
+        }
+    }
+    for (const node of ast.body ?? []) {
+        if (node.type === 'ImportDeclaration') {
+            const src = node.source?.value;
+            if (!isRelativeSpecifier(src)) {
+                if (src === '@playwright/test') {
+                    for (const spec of (node.specifiers ?? [])) {
+                        if (spec.type !== 'ImportSpecifier')
+                            continue;
+                        const importedName = spec.imported?.name ?? spec.imported?.value;
+                        if (importedName === 'test' && spec.local?.name) {
+                            playwrightTestLocalNames.add(spec.local.name);
+                        }
+                    }
+                }
+                continue;
+            }
+            for (const spec of (node.specifiers ?? [])) {
+                if (spec.type !== 'ImportSpecifier')
+                    continue;
+                const importedName = spec.imported?.name ?? spec.imported?.value;
+                if (importedName && spec.local?.name) {
+                    imports.push({ localName: spec.local.name, importedName, source: src });
+                }
+            }
+        }
+        else if (node.type === 'ExportNamedDeclaration') {
+            const declaration = node.declaration;
+            const src = node.source?.value;
+            if (declaration?.type === 'VariableDeclaration') {
+                collectExtendFromVariableDeclaration(declaration);
+                for (const d of (declaration.declarations ?? [])) {
+                    if (d.id?.type === 'Identifier' && d.id.name)
+                        directExportNames.add(d.id.name);
+                }
+            }
+            else {
+                for (const spec of (node.specifiers ?? [])) {
+                    const localName = spec.local?.name ?? spec.local?.value;
+                    const exportedName = spec.exported?.name ?? spec.exported?.value;
+                    if (!localName || !exportedName)
+                        continue;
+                    reExports.push({
+                        exportedName,
+                        localName,
+                        source: isRelativeSpecifier(src) ? src : undefined,
+                    });
+                }
+            }
+        }
+    }
+    // Fixtures modules commonly declare the extend() call inside a nested
+    // scope too (e.g. wrapped in a `(() => {...})()` IIFE is rare, but
+    // multiple top-level `const`s are common) — the top-level pass above
+    // already covers the overwhelming majority; this catches the rest
+    // without a second parse.
+    walk(ast.body ?? []);
+    return {
+        playwrightTestLocalNames,
+        extendDeclarations,
+        directExportNames,
+        imports,
+        reExports,
+    };
+}
+/**
+ * Detects identifiers bound (directly, or via a local import/re-export
+ * chain of any depth) to `<base>.extend(...)` where `<base>` is `test`
+ * imported from `@playwright/test`, or is itself such an extended test.
+ * Returns the flat set of alias name strings (e.g. `loggedTest`,
+ * `testWithAssets`) usable anywhere they're called across the scored
+ * files — callers feed this into `eslint-runner.ts`'s
+ * `settings.playwright.globalAliases.test` and into `metrics.ts`'s
+ * `getTestSpans`/`countTests` and `base-plugin.ts`'s test-name checks.
+ *
+ * `sources`/`importedFiles` are the same maps `index.ts` already builds
+ * (scored spec files, and their transitively-collected local relative
+ * imports — see `collectLocallyImportedFiles`); this function does not
+ * walk the filesystem itself beyond resolving relative specifiers already
+ * present in those files' own import/export statements, and never
+ * escapes `boundaryDir` (same safety rule as `import-graph.ts`).
+ */
+export function detectExtendedTestAliases(sources, importedFiles, boundaryDir) {
+    const allFiles = new Map([...sources, ...importedFiles]);
+    const parsed = new Map();
+    for (const [file, source] of allFiles) {
+        const info = parseFileInfo(source, file);
+        if (info)
+            parsed.set(file, info);
+    }
+    const localAlias = new Map();
+    const exportedAlias = new Map();
+    for (const file of parsed.keys()) {
+        localAlias.set(file, new Set());
+        exportedAlias.set(file, new Set());
+    }
+    const resolve = (fromFile, specifier) => resolveRelativeImport(fromFile, specifier, boundaryDir);
+    // Bounded fixed point: each round can only add names (monotonic), and
+    // there are at most parsed.size * (max names per file) additions total —
+    // capping rounds at file count + a small constant is generous relative
+    // to any real import-chain depth (mirrors import-graph.ts's own
+    // MAX_DEPTH-style bound).
+    const maxRounds = parsed.size + 5;
+    for (let round = 0; round < maxRounds; round++) {
+        let changed = false;
+        for (const [file, info] of parsed) {
+            const known = localAlias.get(file);
+            const exported = exportedAlias.get(file);
+            for (const { declaredName, baseName } of info.extendDeclarations) {
+                if (known.has(declaredName))
+                    continue;
+                if (info.playwrightTestLocalNames.has(baseName) || known.has(baseName)) {
+                    known.add(declaredName);
+                    changed = true;
+                }
+            }
+            for (const { localName, importedName, source } of info.imports) {
+                if (known.has(localName))
+                    continue;
+                const resolved = resolve(file, source);
+                if (!resolved)
+                    continue;
+                if (exportedAlias.get(resolved)?.has(importedName)) {
+                    known.add(localName);
+                    changed = true;
+                }
+            }
+            for (const name of known) {
+                if (info.directExportNames.has(name) && !exported.has(name)) {
+                    exported.add(name);
+                    changed = true;
+                }
+            }
+            for (const { exportedName, localName, source } of info.reExports) {
+                if (exported.has(exportedName))
+                    continue;
+                const isAlias = source
+                    ? !!resolve(file, source) && exportedAlias.get(resolve(file, source))?.has(localName)
+                    : known.has(localName);
+                if (isAlias) {
+                    exported.add(exportedName);
+                    changed = true;
+                }
+            }
+        }
+        if (!changed)
+            break;
+    }
+    const result = new Set();
+    for (const names of localAlias.values()) {
+        for (const name of names)
+            result.add(name);
+    }
+    return [...result].sort();
+}

package/dist/types.d.ts

@@ -1,4 +1,16 @@
-export type ScoreVersion = 'v3';
+export type ScoreVersion = 'v3' | 'v4';
+/**
+ * `standard` is the only public profile, first published as of 2.0.0
+ * (model v4). A separate `strict` profile was planned for 1.1.0 (never
+ * published) to count the QAG-196 gameability rules toward the score
+ * while `standard` only reported them; dropped before publishing once
+ * `standard` started scoring them directly instead — with nothing left
+ * to gate, `strict` would have been identical to `standard`. See
+ * profiles.ts and CHANGELOG.md's 2.0.0 entry. `ProfileName` keeps room
+ * for a future profile; a legacy `'strict'` string degrades gracefully to
+ * `standard` weights via scorePaths (same fallback as the removed
+ * `guardian` profile), and the CLI gives an explicit migration error.
+ */
 export type ProfileName = 'standard';
 export type Grade = 'A' | 'B' | 'C' | 'D' | 'F';
 export type Severity = 'error' | 'warning' | 'info';
@@ -62,6 +74,14 @@ export interface ScoreResult {
      * if they'd otherwise be skipped.
      */
     skippedFiles?: string[];
+    /**
+     * A playwright.config.* was found at or above a scanned directory but
+     * could not be read statically (a dynamic value, e.g. `process.env`, a
+     * spread, or an unsupported export shape) — discovery fell back to
+     * today's filename-suffix behavior for that directory instead of acting
+     * on a partial or guessed reading. See playwright-config.ts.
+     */
+    configWarnings?: string[];
 }
 export interface ScoreOptions {
     paths: string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qaguardian/playwright-score",
-  "version": "1.0.0",
+  "version": "2.1.0",
   "description": "Deterministic, AI-free Playwright spec quality score — the weighted share of your tests that are clean.",
   "type": "module",
   "main": "./dist/index.js",
@@ -19,10 +19,11 @@
     "dist",
     "METHODOLOGY.md",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsc && node -e \"require('fs').chmodSync('dist/cli.js',0o755); require('fs').chmodSync('bin/playwright-score.js',0o755)\"",
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && 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",