@qaguardian/playwright-score 0.5.0 → 1.0.0

package/METHODOLOGY.md

@@ -65,7 +65,7 @@ The **locators** dimension is independent of demerits — it is the usage
 ratio it always was:
 
 ```
-native = getByRole|getByLabel|getByTestId|getByText|getByPlaceholder calls
+native = getByRole|getByLabel|getByTestId|getByText|getByPlaceholder|getByAltText|getByTitle calls
 raw    = .locator(...) calls + legacy string-selector actions (page.click('#x'), …)
 
 locatorsScore = total === 0 ? 100 : round(100 × native / total)

package/README.md

@@ -25,7 +25,7 @@ heavily-engineered platforms and smaller, less mature projects. Not curated
 to look good: 5 of 17 fail the default threshold, for real, verifiable
 reasons (see [VALIDATION.md](./VALIDATION.md)).
 
-**17 suites · 1,228 files · 5,664 tests · 12/17 passed (80% threshold)**
+**17 suites · 1,230 files · 5,654 tests · 12/17 passed (80% threshold)**
 
 | Repo (source scanned) | Score | Grade | Result |
 |---|---:|:-:|:-:|

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import type { ScoreOptions, ScoreResult } from './types.js';
 export type { ScoreResult, ScoreOptions, Finding, ProfileName } from './types.js';
 export { computeScore, MODEL, locatorsScore, gradeFromScore, ratioDimensionScore, } from './score-engine.js';
 export { countSloc } from './sloc.js';
-export { countLocators, analyzeSource } from './metrics.js';
+export { countLocators, analyzeSource, attributeFindingScopes, getTestSpans, } from './metrics.js';
 export { formatJson } from './formatters/json.js';
 export { formatText } from './formatters/text.js';
 export { formatMarkdown } from './formatters/markdown.js';

package/dist/index.js

@@ -4,12 +4,12 @@ import { globSync } from 'glob';
 import { runEslint } from './eslint-runner.js';
 import { commonAncestorDir } from './fs-util.js';
 import { collectLocallyImportedFiles } from './import-graph.js';
-import { analyzeSource, countLocators, findLocalAssertionHelperNames, getTestSpans, looksLikeNonPlaywrightTest, } from './metrics.js';
+import { analyzeSource, attributeFindingScopes, countLocators, findLocalAssertionHelperNames, getTestSpans, looksLikeNonPlaywrightTest, } from './metrics.js';
 import { DEFAULT_THRESHOLDS } from './profiles.js';
 import { computeScore } from './score-engine.js';
 export { computeScore, MODEL, locatorsScore, gradeFromScore, ratioDimensionScore, } from './score-engine.js';
 export { countSloc } from './sloc.js';
-export { countLocators, analyzeSource } from './metrics.js';
+export { countLocators, analyzeSource, attributeFindingScopes, getTestSpans, } from './metrics.js';
 export { formatJson } from './formatters/json.js';
 export { formatText } from './formatters/text.js';
 export { formatMarkdown } from './formatters/markdown.js';
@@ -260,29 +260,9 @@ export async function scorePaths(options) {
         raw += counts.raw;
     }
     const findings = [...eslintFindings, ...metricFindings];
-    // Attribute each finding to the test it sits in (model v3): a finding
-    // inside a test span belongs to that test; inside a hook span it affects
-    // every test in the file; anything else — imports, describe bodies,
-    // file-level metrics like oversized-file — is module scope, counted once
-    // per file.
-    for (const f of findings) {
-        const spans = fileSpans.get(f.file);
-        if (!spans || f.line === undefined) {
-            f.scope = 'module';
-            continue;
-        }
-        const idx = spans.tests.findIndex((t) => f.line !== undefined && f.line >= t.startLine && f.line <= t.endLine);
-        if (idx >= 0) {
-            f.scope = 'test';
-            f.testKey = `${f.file}#${idx}`;
-        }
-        else if (spans.hooks.some((h) => f.line !== undefined && f.line >= h.startLine && f.line <= h.endLine)) {
-            f.scope = 'hook';
-        }
-        else {
-            f.scope = 'module';
-        }
-    }
+    // Attribute each finding to the test it sits in (model v3) — see
+    // attributeFindingScopes in metrics.ts.
+    attributeFindingScopes(findings, fileSpans);
     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

package/dist/metrics.d.ts

@@ -63,6 +63,18 @@ export interface TestSpans {
  * malformed anyway) are dropped so each line maps to at most one test.
  */
 export declare function getTestSpans(source: string, file?: string): TestSpans;
+/**
+ * Model-v3 finding attribution (see score-engine.ts): a finding inside a
+ * test span belongs to that test (`scope: 'test'` + a stable
+ * `file#index` testKey); inside a hook span it affects every test in the
+ * file (`scope: 'hook'`); anything else — imports, describe bodies,
+ * file-level metrics — is `scope: 'module'`, counted once per file.
+ * Exported so layers composing extra rules on top (e.g. a private
+ * house-rules dimension) attribute their own findings with the same
+ * logic the package itself uses, rather than reimplementing it.
+ * Mutates the findings in place and returns them.
+ */
+export declare function attributeFindingScopes(findings: Finding[], spansByFile: Map<string, TestSpans>): Finding[];
 /** Count test( / test.only( / test.skip( / test.fixme( style declarations (approx). */
 export declare function countTests(source: string): number;
 export declare function findOversizedFile(source: string, file: string, maxSloc?: number): Finding[];

package/dist/metrics.js

@@ -35,12 +35,18 @@ const CYPRESS_API_RE = /\bcy\.(?:visit|get|contains|click|type|should|intercept|
 export function looksLikeNonPlaywrightTest(source) {
     return NON_PLAYWRIGHT_IMPORT_RE.test(source) || RTL_API_RE.test(source) || CYPRESS_API_RE.test(source);
 }
+// The full getBy* family Playwright ships. getByAltText/getByTitle are
+// just as native as the rest — leaving them out meant an image-heavy suite
+// (alt/title locators plus one .locator() fallback) scored 0 on the
+// locators dimension for perfectly idiomatic code.
 const NATIVE_METHODS = new Set([
     'getByRole',
     'getByLabel',
     'getByTestId',
     'getByText',
     'getByPlaceholder',
+    'getByAltText',
+    'getByTitle',
 ]);
 /**
  * Generic ESTree walk (no visitor-keys dependency). `parent` is excluded so
@@ -382,6 +388,39 @@ export function getTestSpans(source, file) {
     }
     return { tests: outer, hooks };
 }
+/**
+ * Model-v3 finding attribution (see score-engine.ts): a finding inside a
+ * test span belongs to that test (`scope: 'test'` + a stable
+ * `file#index` testKey); inside a hook span it affects every test in the
+ * file (`scope: 'hook'`); anything else — imports, describe bodies,
+ * file-level metrics — is `scope: 'module'`, counted once per file.
+ * Exported so layers composing extra rules on top (e.g. a private
+ * house-rules dimension) attribute their own findings with the same
+ * logic the package itself uses, rather than reimplementing it.
+ * Mutates the findings in place and returns them.
+ */
+export function attributeFindingScopes(findings, spansByFile) {
+    for (const f of findings) {
+        const spans = spansByFile.get(f.file);
+        if (!spans || f.line === undefined) {
+            f.scope = 'module';
+            continue;
+        }
+        const line = f.line;
+        const idx = spans.tests.findIndex((t) => line >= t.startLine && line <= t.endLine);
+        if (idx >= 0) {
+            f.scope = 'test';
+            f.testKey = `${f.file}#${idx}`;
+        }
+        else if (spans.hooks.some((h) => line >= h.startLine && line <= h.endLine)) {
+            f.scope = 'hook';
+        }
+        else {
+            f.scope = 'module';
+        }
+    }
+    return findings;
+}
 const TEST_NON_DECL_RE = /\btest\.(describe|step|beforeEach|afterEach|beforeAll|afterAll|use|setTimeout|info|expect)\b/;
 /** Count test( / test.only( / test.skip( / test.fixme( style declarations (approx). */
 export function countTests(source) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@qaguardian/playwright-score",
-  "version": "0.5.0",
-  "description": "Deterministic, AI-free Playwright spec quality score (sqs-v2).",
+  "version": "1.0.0",
+  "description": "Deterministic, AI-free Playwright spec quality score — the weighted share of your tests that are clean.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",