@qaguardian/playwright-score 2.1.1 → 2.3.0

package/dist/score-engine.d.ts

@@ -44,6 +44,11 @@ export declare const MODEL: {
     readonly MAX_DEMERIT_PER_FILE_MODULE: 1;
 };
 declare const PENALTY_DIMENSIONS: DimensionName[];
+/** Lowest score of each grade, best first. Shared with the report's score explanation. */
+export declare const GRADE_BANDS: ReadonlyArray<{
+    grade: Grade;
+    min: number;
+}>;
 export declare function gradeFromScore(score: number): Grade;
 export declare function locatorsScore(native: number, raw: number): number;
 /** Tests per file, keyed by the same relative file path findings carry. */

package/dist/score-engine.js

@@ -44,16 +44,16 @@ export const MODEL = {
     MAX_DEMERIT_PER_FILE_MODULE: 1.0,
 };
 const PENALTY_DIMENSIONS = ['playwrightHygiene', 'assertions', 'structure'];
+/** Lowest score of each grade, best first. Shared with the report's score explanation. */
+export const GRADE_BANDS = [
+    { grade: 'A', min: 90 },
+    { grade: 'B', min: 80 },
+    { grade: 'C', min: 70 },
+    { grade: 'D', min: 60 },
+    { grade: 'F', min: 0 },
+];
 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';
+    return (GRADE_BANDS.find((b) => score >= b.min) ?? GRADE_BANDS[GRADE_BANDS.length - 1]).grade;
 }
 export function locatorsScore(native, raw) {
     const total = native + raw;
@@ -188,6 +188,7 @@ export function computeScore(input) {
             nativeLocators: input.nativeLocators,
             rawLocators: input.rawLocators,
             unassertedTests: input.findings.filter((f) => f.rule === 'playwright/expect-expect' && !f.reportOnly).length,
+            unverifiedTests: input.findings.filter((f) => f.rule === 'playwright-score/assertion-unverified').length,
             cleanTests,
         },
         dimensions: dims,

package/dist/suite-name.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Label for one scored path, used when --name is absent. A file keeps its
+ * basename. A folder gets its own name plus parents: three segments when the
+ * name is generic ("mattermost/e2e-tests/playwright"), two otherwise. Never
+ * reaches the user-name segment of a home directory or anything above it:
+ * the walk stops under any `home`/`Users` segment (wherever it sits, so
+ * `/tmp/home/alice/e2e` is safe even if $HOME says otherwise) and under the
+ * current home directory. A folder that is itself a home directory gets a
+ * neutral label.
+ */
+export declare function suiteLabel(p: string, isDir: boolean, home?: string): string;

package/dist/suite-name.js

@@ -0,0 +1,36 @@
+import os from 'node:os';
+import path from 'node:path';
+/** Folder names that say nothing about whose suite this is. */
+const GENERIC_NAMES = new Set(['playwright', 'e2e', 'e2e-tests', 'tests', 'test', 'specs', 'spec', 'src']);
+const NEUTRAL = 'Playwright suite';
+const HOME_PARENTS = new Set(['home', 'users']);
+/**
+ * Label for one scored path, used when --name is absent. A file keeps its
+ * basename. A folder gets its own name plus parents: three segments when the
+ * name is generic ("mattermost/e2e-tests/playwright"), two otherwise. Never
+ * reaches the user-name segment of a home directory or anything above it:
+ * the walk stops under any `home`/`Users` segment (wherever it sits, so
+ * `/tmp/home/alice/e2e` is safe even if $HOME says otherwise) and under the
+ * current home directory. A folder that is itself a home directory gets a
+ * neutral label.
+ */
+export function suiteLabel(p, isDir, home = os.homedir()) {
+    const abs = path.resolve(p);
+    const base = path.basename(abs) || p;
+    if (!isDir)
+        return base;
+    const segs = abs.split(path.sep).filter(Boolean);
+    // First segment index the label may use.
+    let min = 0;
+    segs.forEach((seg, k) => {
+        if (HOME_PARENTS.has(seg.toLowerCase()))
+            min = Math.max(min, k + 2);
+    });
+    const homeSegs = path.resolve(home || path.sep).split(path.sep).filter(Boolean);
+    if (homeSegs.length > 0 && homeSegs.every((seg, k) => segs[k] === seg))
+        min = Math.max(min, homeSegs.length);
+    if (segs.length <= min)
+        return NEUTRAL;
+    const want = GENERIC_NAMES.has(base.toLowerCase()) ? 3 : 2;
+    return segs.slice(Math.max(min, segs.length - want)).join('/');
+}

package/dist/test-aliases.js

@@ -1,5 +1,69 @@
 import { parseForESLint } from '@typescript-eslint/parser';
 import { resolveRelativeImport } from './import-graph.js';
+function classifyReturn(expr) {
+    if (!expr)
+        return undefined;
+    if (expr.type === 'Identifier' && typeof expr.name === 'string') {
+        return { kind: 'ident', name: expr.name };
+    }
+    if (expr.type !== 'CallExpression')
+        return undefined;
+    const callee = expr.callee;
+    if (callee?.type === 'Identifier' && typeof callee.name === 'string') {
+        return { kind: 'call', calleeName: callee.name };
+    }
+    if (callee?.type === 'MemberExpression' && !callee.computed) {
+        const prop = callee.property;
+        const obj = callee.object;
+        if (prop?.type === 'Identifier' && prop.name === 'extend' && obj?.type === 'Identifier' && obj.name) {
+            return { kind: 'extend', baseName: obj.name };
+        }
+    }
+    return undefined;
+}
+/** `return <expr>` statements of one function body, not descending into nested functions. */
+function collectFunctionReturns(fn) {
+    const out = [];
+    const body = fn.body;
+    if (!body)
+        return out;
+    if (body.type !== 'BlockStatement') {
+        const r = classifyReturn(body);
+        if (r)
+            out.push(r);
+        return out;
+    }
+    const visit = (node) => {
+        if (!node || typeof node !== 'object')
+            return;
+        if (Array.isArray(node)) {
+            for (const n of node)
+                visit(n);
+            return;
+        }
+        const obj = node;
+        if (obj.type === 'FunctionDeclaration' ||
+            obj.type === 'FunctionExpression' ||
+            obj.type === 'ArrowFunctionExpression') {
+            return;
+        }
+        if (obj.type === 'ReturnStatement') {
+            const r = classifyReturn(obj.argument);
+            if (r)
+                out.push(r);
+            return;
+        }
+        for (const key in obj) {
+            if (key === 'parent')
+                continue;
+            const v = obj[key];
+            if (v && typeof v === 'object')
+                visit(v);
+        }
+    };
+    visit(body.body);
+    return out;
+}
 function isRelativeSpecifier(value) {
     return typeof value === 'string' && value.startsWith('.');
 }
@@ -20,12 +84,38 @@ function parseFileInfo(source, file) {
     const directExportNames = new Set();
     const imports = [];
     const reExports = [];
+    const functions = [];
+    const callDeclarations = [];
+    function collectFunction(node, exported) {
+        if (node.type === 'FunctionDeclaration') {
+            const name = node.id?.name;
+            if (name)
+                functions.push({ name, returns: collectFunctionReturns(node), exported });
+        }
+        else if (node.type === 'VariableDeclaration') {
+            for (const d of (node.declarations ?? [])) {
+                const init = d.init;
+                if (d.id?.type === 'Identifier' &&
+                    d.id.name &&
+                    init &&
+                    (init.type === 'ArrowFunctionExpression' || init.type === 'FunctionExpression')) {
+                    functions.push({ name: d.id.name, returns: collectFunctionReturns(init), exported });
+                }
+            }
+        }
+    }
     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 === 'Identifier') {
+                const calleeName = (init.callee).name;
+                if (calleeName)
+                    callDeclarations.push({ declaredName: d.id.name, calleeName });
+            }
             if (init.type === 'CallExpression' &&
                 init.callee?.type === 'MemberExpression') {
                 const callee = init.callee;
@@ -63,6 +153,9 @@ function parseFileInfo(source, file) {
         }
     }
     for (const node of ast.body ?? []) {
+        if (node.type === 'FunctionDeclaration' || node.type === 'VariableDeclaration') {
+            collectFunction(node, false);
+        }
         if (node.type === 'ImportDeclaration') {
             const src = node.source?.value;
             if (!isRelativeSpecifier(src)) {
@@ -90,6 +183,8 @@ function parseFileInfo(source, file) {
         else if (node.type === 'ExportNamedDeclaration') {
             const declaration = node.declaration;
             const src = node.source?.value;
+            if (declaration)
+                collectFunction(declaration, true);
             if (declaration?.type === 'VariableDeclaration') {
                 collectExtendFromVariableDeclaration(declaration);
                 for (const d of (declaration.declarations ?? [])) {
@@ -124,6 +219,8 @@ function parseFileInfo(source, file) {
         directExportNames,
         imports,
         reExports,
+        functions,
+        callDeclarations,
     };
 }
 /**
@@ -153,9 +250,15 @@ export function detectExtendedTestAliases(sources, importedFiles, boundaryDir) {
     }
     const localAlias = new Map();
     const exportedAlias = new Map();
+    // Test-factory functions (QAG-287): `function make(cfg) { return test.extend(...) }`.
+    // `const t = make(cfg)` then makes `t` a test alias.
+    const localFactory = new Map();
+    const exportedFactory = new Map();
     for (const file of parsed.keys()) {
         localAlias.set(file, new Set());
         exportedAlias.set(file, new Set());
+        localFactory.set(file, new Set());
+        exportedFactory.set(file, new Set());
     }
     const resolve = (fromFile, specifier) => resolveRelativeImport(fromFile, specifier, boundaryDir);
     // Bounded fixed point: each round can only add names (monotonic), and
@@ -177,16 +280,54 @@ export function detectExtendedTestAliases(sources, importedFiles, boundaryDir) {
                     changed = true;
                 }
             }
+            const factories = localFactory.get(file);
+            const exportedFactories = exportedFactory.get(file);
             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)) {
+                if (!known.has(localName) && exportedAlias.get(resolved)?.has(importedName)) {
                     known.add(localName);
                     changed = true;
                 }
+                if (!factories.has(localName) && exportedFactory.get(resolved)?.has(importedName)) {
+                    factories.add(localName);
+                    changed = true;
+                }
+            }
+            for (const fn of info.functions) {
+                if (!factories.has(fn.name)) {
+                    const returnsAlias = fn.returns.some((r) => r.kind === 'extend'
+                        ? info.playwrightTestLocalNames.has(r.baseName) || known.has(r.baseName)
+                        : r.kind === 'ident'
+                            ? known.has(r.name)
+                            : factories.has(r.calleeName));
+                    if (returnsAlias) {
+                        factories.add(fn.name);
+                        changed = true;
+                    }
+                }
+                if (fn.exported && factories.has(fn.name) && !exportedFactories.has(fn.name)) {
+                    exportedFactories.add(fn.name);
+                    changed = true;
+                }
+            }
+            for (const { declaredName, calleeName } of info.callDeclarations) {
+                if (known.has(declaredName) || !factories.has(calleeName))
+                    continue;
+                known.add(declaredName);
+                changed = true;
+            }
+            for (const { exportedName, localName, source } of info.reExports) {
+                if (exportedFactories.has(exportedName))
+                    continue;
+                const isFactory = source
+                    ? !!resolve(file, source) && exportedFactory.get(resolve(file, source))?.has(localName)
+                    : factories.has(localName);
+                if (isFactory) {
+                    exportedFactories.add(exportedName);
+                    changed = true;
+                }
             }
             for (const name of known) {
                 if (info.directExportNames.has(name) && !exported.has(name)) {

package/dist/types.d.ts

@@ -51,6 +51,10 @@ export interface ScoreSummary {
     /** Tests with no recognized assertion (uncapped playwright/expect-expect
      * census, after delegation resolution). */
     unassertedTests: number;
+    /** Tests with no expect(...) that call something this scan cannot read
+     * (`playwright-score/assertion-unverified`, report-only). They are NOT in
+     * `unassertedTests` and not penalised, but they are not known to assert. */
+    unverifiedTests: number;
     /** Tests with no demerit in any dimension — the headline the score is
      * built from: the weighted share of tests that are clean. */
     cleanTests: number;
@@ -65,6 +69,12 @@ export interface ScoreResult {
     summary: ScoreSummary;
     dimensions: ScoreDimensions;
     findings: Finding[];
+    /**
+     * Absolute directory that every `Finding.file` is relative to (the scored
+     * files' common ancestor). Lets a consumer locate source for excerpts. Local
+     * to the machine that ran the scan: never put it in a shareable artifact.
+     */
+    baseDir?: string;
     /**
      * Files matched by a directory/glob input but skipped because they show
      * positive evidence of being a non-Playwright test (an import from
@@ -82,6 +92,14 @@ export interface ScoreResult {
      * on a partial or guessed reading. See playwright-config.ts.
      */
     configWarnings?: string[];
+    /**
+     * Rules that threw while scoring this run (contained, so the run finished
+     * but their findings may be missing). Present only when non-empty.
+     */
+    ruleCrashes?: Array<{
+        rule: string;
+        count: number;
+    }>;
 }
 export interface ScoreOptions {
     paths: string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qaguardian/playwright-score",
-  "version": "2.1.1",
+  "version": "2.3.0",
   "description": "Deterministic, AI-free Playwright spec quality score — the weighted share of your tests that are clean.",
   "type": "module",
   "main": "./dist/index.js",