@qaguardian/playwright-score 2.2.0 → 2.3.0

package/dist/rules/no-unawaited-expect-value.js

@@ -0,0 +1,46 @@
+import { isPlaywrightReceiver, memberName, parseMatcherCall, resolveConstInit } from './ast-util.js';
+export const PROMISE_METHODS = new Set([
+    'innerText', 'innerHTML', 'textContent', 'inputValue', 'getAttribute', 'isVisible', 'isHidden',
+    'isEnabled', 'isDisabled', 'isChecked', 'isEditable', 'count', 'title', 'allInnerTexts',
+    'allTextContents', 'boundingBox', 'content',
+]);
+const WEB_FIRST = /^(toHave|toBe(Visible|Hidden|Enabled|Disabled|Checked|Editable|Empty|Focused|Attached|InViewport|OK)$|toContainText$|toMatchAriaSnapshot$|toPass$|toMatchSnapshot$|toHaveScreenshot$)/;
+const VALUE_ARG_MATCHERS = new Set(['toBe', 'toEqual', 'toStrictEqual']);
+export const noUnawaitedExpectValue = {
+    meta: {
+        type: 'problem',
+        docs: { description: 'Disallow un-awaited Promise-returning Playwright calls inside expect()' },
+        messages: {
+            missingAwait: 'Missing await: {{call}}() returns a Promise, and this matcher compares the Promise itself, not the value (so it always passes or always fails). Add await, or use a web-first assertion on the locator.',
+        },
+        schema: [],
+    },
+    create(context) {
+        function bareCall(n0) {
+            // `const t = page.title(); expect(t)...`: a const initialised from an un-awaited call.
+            const n = n0?.type === 'Identifier' ? resolveConstInit(context, n0) : n0;
+            if (!n || n.type !== 'CallExpression')
+                return undefined; // AwaitExpression etc. are not bare
+            const name = memberName(n.callee);
+            if (!name || !PROMISE_METHODS.has(name))
+                return undefined;
+            return isPlaywrightReceiver(context, n.callee?.object) ? name : undefined;
+        }
+        return {
+            CallExpression(raw) {
+                const node = raw;
+                const m = parseMatcherCall(node);
+                if (!m || m.modifiers.some((x) => x === 'resolves' || x === 'rejects'))
+                    return;
+                if (WEB_FIRST.test(m.matcher))
+                    return;
+                const isPoll = m.expectCall.callee?.type === 'MemberExpression' && m.expectCall.callee.property?.name === 'poll';
+                const subject = (m.expectCall.arguments ?? [])[0];
+                const hit = (!isPoll && bareCall(subject)) ||
+                    (VALUE_ARG_MATCHERS.has(m.matcher) ? bareCall((node.arguments ?? [])[0]) : undefined);
+                if (hit)
+                    context.report({ node: raw, messageId: 'missingAwait', data: { call: hit } });
+            },
+        };
+    },
+};

package/dist/rules/no-weak-assertion.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Assertions that cannot fail, or assert almost nothing. Exact shapes:
+ *
+ *  1. `expect(<count>).toBeGreaterThanOrEqual(0)` / `.toBeGreaterThan(-1)`
+ *     (no `.not`), where <count> is `.length`, `[await] x.count()`, a const
+ *     initialised from one of those, or `expect.poll(() => x.count())`.
+ *  2. `expect(<Locator>).toBeTruthy()` / `.toBeDefined()` / `.not.toBeNull()`
+ *     / `.not.toBeUndefined()`; <Locator> is syntactic only: `page.locator()`,
+ *     `x.getBy*()`, those chained with first/last/nth/filter/locator, or a
+ *     const initialised from one. A Locator object is always truthy.
+ *  3. `expect(await x.isVisible()).toBeDefined()` (also isHidden, isEnabled,
+ *     isDisabled, isChecked, isEditable, count, innerText, innerHTML,
+ *     inputValue, title; textContent/getAttribute only for toBeDefined):
+ *     these always return a value, so "defined" proves nothing.
+ *
+ * `toBeTruthy()` on any other value is NOT flagged.
+ */
+import type { Rule } from 'eslint';
+export declare const noWeakAssertion: Rule.RuleModule;

package/dist/rules/no-weak-assertion.js

@@ -0,0 +1,82 @@
+import { FN_TYPES, isLocatorExpr, memberName, parseMatcherCall, resolveConstInit, unwrap } from './ast-util.js';
+const ALWAYS_VALUE = new Set([
+    'isVisible', 'isHidden', 'isEnabled', 'isDisabled', 'isChecked', 'isEditable',
+    'count', 'innerText', 'innerHTML', 'inputValue', 'title',
+]);
+const MAYBE_NULL = new Set(['textContent', 'getAttribute']); // null is "defined"
+function isCountish(context, node, depth = 0) {
+    const n = unwrap(node);
+    if (!n || depth > 2)
+        return false;
+    if (n.type === 'MemberExpression' && !n.computed && n.property?.name === 'length')
+        return true;
+    if (n.type === 'CallExpression' && memberName(n.callee) === 'count')
+        return true;
+    if (n.type === 'Identifier') {
+        const init = resolveConstInit(context, n);
+        return init ? isCountish(context, init, depth + 1) : false;
+    }
+    return false;
+}
+function negativeLiteral(arg, want) {
+    if (!arg)
+        return false;
+    if (arg.type === 'Literal')
+        return arg.value === want;
+    return arg.type === 'UnaryExpression' && arg.operator === '-' && arg.argument?.type === 'Literal' && -arg.argument.value === want;
+}
+export const noWeakAssertion = {
+    meta: {
+        type: 'problem',
+        docs: { description: 'Disallow assertions that cannot fail or assert almost nothing' },
+        messages: {
+            count: 'A count is never negative, so this assertion cannot fail. Assert the expected count, or use expect(locator).toHaveCount(n).',
+            locator: 'A Locator object is always truthy/defined, so this assertion cannot fail. Use a web-first assertion such as expect(locator).toBeVisible().',
+            defined: 'This call always returns a value, so asserting it is defined cannot fail. Assert the value itself, or use a web-first assertion.',
+        },
+        schema: [],
+    },
+    create(context) {
+        return {
+            CallExpression(raw) {
+                const node = raw;
+                const m = parseMatcherCall(node);
+                if (!m || m.modifiers.some((x) => x === 'resolves' || x === 'rejects'))
+                    return;
+                const not = m.modifiers.includes('not');
+                const arg0 = (m.expectCall.arguments ?? [])[0];
+                const isPoll = m.expectCall.callee?.type === 'MemberExpression' && m.expectCall.callee.property?.name === 'poll';
+                // 1. count >= 0
+                if (!not && ((m.matcher === 'toBeGreaterThanOrEqual' && negativeLiteral((node.arguments ?? [])[0], 0)) ||
+                    (m.matcher === 'toBeGreaterThan' && negativeLiteral((node.arguments ?? [])[0], -1)))) {
+                    let subject = arg0;
+                    if (isPoll && subject && FN_TYPES.has(subject.type) && subject.type === 'ArrowFunctionExpression' && subject.body.type !== 'BlockStatement') {
+                        subject = subject.body;
+                    }
+                    if (isCountish(context, subject))
+                        context.report({ node: raw, messageId: 'count' });
+                    return;
+                }
+                // 2. Locator truthy
+                const truthy = (!not && (m.matcher === 'toBeTruthy' || m.matcher === 'toBeDefined')) ||
+                    (not && (m.matcher === 'toBeNull' || m.matcher === 'toBeUndefined'));
+                if (truthy && !isPoll) {
+                    if (isLocatorExpr(context, arg0)) {
+                        context.report({ node: raw, messageId: 'locator' });
+                        return;
+                    }
+                    // 3. value-returning call asserted "defined"
+                    const subj = unwrap(arg0);
+                    const name = subj?.type === 'CallExpression' ? memberName(subj.callee) : undefined;
+                    if (name) {
+                        const definedCheck = (!not && m.matcher === 'toBeDefined') || (not && m.matcher === 'toBeUndefined');
+                        const nullCheck = not && m.matcher === 'toBeNull';
+                        if ((definedCheck && (ALWAYS_VALUE.has(name) || MAYBE_NULL.has(name))) || (nullCheck && ALWAYS_VALUE.has(name))) {
+                            context.report({ node: raw, messageId: 'defined' });
+                        }
+                    }
+                }
+            },
+        };
+    },
+};

package/dist/rules/rule-util.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Small AST helpers shared by the QAG-287 flake-risk rules (one rule per
+ * file). Nodes are typed loosely on purpose: the parser may produce
+ * TypeScript-ESTree node types that the plain ESTree typings do not model.
+ */
+export type AnyNode = any;
+/** Strips `x!`, `x as T` and optional-chain wrappers. */
+export declare function unwrap(node: AnyNode): AnyNode;
+/** Name of a non-computed member property (or string-literal computed one). */
+export declare function propName(member: AnyNode): string | undefined;
+/**
+ * True when the expression is *syntactically* a Playwright Page or Locator:
+ * the identifier `page`, a `.page` property (`this.page`, `fixtures.page`),
+ * a locator-producing call chain on one of those (`page.getByRole(..)`,
+ * `page.locator(..).first()`), or an identifier bound once by `const` to
+ * such an expression. Anything else (a parameter called `el`, a jQuery
+ * wrapper, an array) is not a receiver, so a method that happens to share a
+ * Playwright name on another object is never matched.
+ */
+export declare function isPwReceiver(context: {
+    sourceCode: AnyNode;
+}, expr: AnyNode, depth?: number): boolean;
+/** Nearest enclosing function node, or undefined at module level. */
+export declare function enclosingFunction(node: AnyNode): AnyNode;
+/** Evaluates a numeric literal / simple arithmetic expression, else undefined. */
+export declare function evalNumber(node: AnyNode): number | undefined;
+/** Static string value of a literal or an expression-free template literal. */
+export declare function staticString(node: AnyNode): string | undefined;
+/** `test(...)`, `test.only(...)`, `it(...)` — a test declaration call (not describe/hook). */
+export declare function isTestDeclaration(call: AnyNode, testNames: ReadonlySet<string>): boolean;
+export declare function hookName(call: AnyNode, testNames: ReadonlySet<string>): string | undefined;
+/** `test.describe(...)`, `describe(...)`, `test.describe.serial/parallel/only(...)`. */
+export declare function isDescribeCall(call: AnyNode, testNames: ReadonlySet<string>): boolean;
+/** `test.describe.serial(...)` call. */
+export declare function isSerialDescribeCall(call: AnyNode, testNames: ReadonlySet<string>): boolean;
+/** `test.describe.configure({ mode: 'serial' })` call. */
+export declare function isSerialConfigureCall(call: AnyNode, testNames: ReadonlySet<string>): boolean;
+/**
+ * Is `node` in a scope declared serial: the file has a top-level
+ * `test.describe.configure({ mode: 'serial' })`, or any enclosing describe is
+ * `test.describe.serial(...)` or configures serial mode in its own body.
+ */
+export declare function isInSerialScope(node: AnyNode, testNames: ReadonlySet<string>): boolean;
+export declare function testNamesFromOptions(options: unknown[]): Set<string>;
+export declare const TEST_ALIAS_SCHEMA: {
+    type: "object";
+    properties: {
+        testAliasNames: {
+            items: {
+                type: "string";
+            };
+            type: "array";
+        };
+    };
+    additionalProperties: boolean;
+}[];

package/dist/rules/rule-util.js

@@ -0,0 +1,253 @@
+/** Strips `x!`, `x as T` and optional-chain wrappers. */
+export function unwrap(node) {
+    let n = node;
+    while (n &&
+        (n.type === 'TSNonNullExpression' ||
+            n.type === 'ChainExpression' ||
+            n.type === 'TSAsExpression' ||
+            n.type === 'TSSatisfiesExpression' ||
+            n.type === 'TSTypeAssertion')) {
+        n = n.expression;
+    }
+    return n;
+}
+/** Name of a non-computed member property (or string-literal computed one). */
+export function propName(member) {
+    if (!member || member.type !== 'MemberExpression')
+        return undefined;
+    const p = member.property;
+    if (!member.computed && p?.type === 'Identifier')
+        return p.name;
+    if (member.computed && p?.type === 'Literal' && typeof p.value === 'string')
+        return p.value;
+    return undefined;
+}
+const LOCATOR_PRODUCERS = new Set([
+    'locator',
+    'getByRole',
+    'getByText',
+    'getByLabel',
+    'getByPlaceholder',
+    'getByAltText',
+    'getByTitle',
+    'getByTestId',
+    'first',
+    'last',
+    'nth',
+    'filter',
+    'and',
+    'or',
+    'frameLocator',
+    'contentFrame',
+]);
+function findConstInit(context, node, name) {
+    let scope = context.sourceCode.getScope(node);
+    while (scope) {
+        const v = scope.set?.get(name);
+        if (v) {
+            const defs = v.defs ?? [];
+            if (defs.length !== 1)
+                return undefined;
+            const def = defs[0];
+            if (def.type !== 'Variable' || def.parent?.kind !== 'const')
+                return undefined;
+            return def.node?.init;
+        }
+        scope = scope.upper;
+    }
+    return undefined;
+}
+/**
+ * True when the expression is *syntactically* a Playwright Page or Locator:
+ * the identifier `page`, a `.page` property (`this.page`, `fixtures.page`),
+ * a locator-producing call chain on one of those (`page.getByRole(..)`,
+ * `page.locator(..).first()`), or an identifier bound once by `const` to
+ * such an expression. Anything else (a parameter called `el`, a jQuery
+ * wrapper, an array) is not a receiver, so a method that happens to share a
+ * Playwright name on another object is never matched.
+ */
+export function isPwReceiver(context, expr, depth = 0) {
+    const n = unwrap(expr);
+    if (!n || depth > 4)
+        return false;
+    if (n.type === 'Identifier') {
+        if (n.name === 'page')
+            return true;
+        const init = findConstInit(context, n, n.name);
+        return init ? isPwReceiver(context, init, depth + 1) : false;
+    }
+    if (n.type === 'MemberExpression') {
+        return propName(n) === 'page';
+    }
+    if (n.type === 'CallExpression' && n.callee?.type === 'MemberExpression') {
+        const name = propName(n.callee);
+        return !!name && LOCATOR_PRODUCERS.has(name) && isPwReceiver(context, n.callee.object, depth + 1);
+    }
+    return false;
+}
+/** Nearest enclosing function node, or undefined at module level. */
+export function enclosingFunction(node) {
+    let p = node?.parent;
+    while (p) {
+        if (p.type === 'FunctionDeclaration' ||
+            p.type === 'FunctionExpression' ||
+            p.type === 'ArrowFunctionExpression') {
+            return p;
+        }
+        p = p.parent;
+    }
+    return undefined;
+}
+/** Evaluates a numeric literal / simple arithmetic expression, else undefined. */
+export function evalNumber(node) {
+    const n = unwrap(node);
+    if (!n)
+        return undefined;
+    if (n.type === 'Literal' && typeof n.value === 'number')
+        return n.value;
+    if (n.type === 'UnaryExpression' && (n.operator === '-' || n.operator === '+')) {
+        const v = evalNumber(n.argument);
+        return v === undefined ? undefined : n.operator === '-' ? -v : v;
+    }
+    if (n.type === 'BinaryExpression' && ['+', '-', '*', '/', '**'].includes(n.operator)) {
+        const a = evalNumber(n.left);
+        const b = evalNumber(n.right);
+        if (a === undefined || b === undefined)
+            return undefined;
+        switch (n.operator) {
+            case '+':
+                return a + b;
+            case '-':
+                return a - b;
+            case '*':
+                return a * b;
+            case '/':
+                return b === 0 ? undefined : a / b;
+            default:
+                return a ** b;
+        }
+    }
+    return undefined;
+}
+/** Static string value of a literal or an expression-free template literal. */
+export function staticString(node) {
+    const n = unwrap(node);
+    if (!n)
+        return undefined;
+    if (n.type === 'Literal' && typeof n.value === 'string')
+        return n.value;
+    if (n.type === 'TemplateLiteral' && n.expressions.length === 0 && n.quasis.length === 1) {
+        return n.quasis[0].value.cooked ?? undefined;
+    }
+    return undefined;
+}
+/** `test(...)`, `test.only(...)`, `it(...)` — a test declaration call (not describe/hook). */
+export function isTestDeclaration(call, testNames) {
+    if (call?.type !== 'CallExpression')
+        return false;
+    const c = call.callee;
+    if (c?.type === 'Identifier')
+        return testNames.has(c.name) || c.name === 'it';
+    if (c?.type === 'MemberExpression' && c.object?.type === 'Identifier') {
+        const m = propName(c);
+        return (testNames.has(c.object.name) || c.object.name === 'it') && (m === 'only' || m === 'fail' || m === 'fixme');
+    }
+    return false;
+}
+const HOOKS = new Set(['beforeEach', 'afterEach', 'beforeAll', 'afterAll']);
+export function hookName(call, testNames) {
+    const c = call?.type === 'CallExpression' ? call.callee : undefined;
+    if (c?.type === 'MemberExpression' && c.object?.type === 'Identifier' && testNames.has(c.object.name)) {
+        const m = propName(c);
+        if (m && HOOKS.has(m))
+            return m;
+    }
+    if (c?.type === 'Identifier' && HOOKS.has(c.name))
+        return c.name;
+    return undefined;
+}
+/** `test.describe(...)`, `describe(...)`, `test.describe.serial/parallel/only(...)`. */
+export function isDescribeCall(call, testNames) {
+    if (call?.type !== 'CallExpression')
+        return false;
+    const c = call.callee;
+    if (c?.type === 'Identifier')
+        return c.name === 'describe';
+    if (c?.type !== 'MemberExpression')
+        return false;
+    const m = propName(c);
+    const o = unwrap(c.object);
+    if (m === 'describe')
+        return o?.type === 'Identifier' && (testNames.has(o.name) || o.name === 'it');
+    if (m === 'serial' || m === 'parallel' || m === 'only' || m === 'skip' || m === 'fixme') {
+        return (o?.type === 'MemberExpression' &&
+            propName(o) === 'describe' &&
+            o.object?.type === 'Identifier' &&
+            testNames.has(o.object.name));
+    }
+    return false;
+}
+/** `test.describe.serial(...)` call. */
+export function isSerialDescribeCall(call, testNames) {
+    if (call?.type !== 'CallExpression')
+        return false;
+    const c = unwrap(call.callee);
+    if (c?.type !== 'MemberExpression' || propName(c) !== 'serial')
+        return false;
+    const o = unwrap(c.object);
+    return o?.type === 'MemberExpression' && propName(o) === 'describe' && o.object?.type === 'Identifier' && testNames.has(o.object.name);
+}
+/** `test.describe.configure({ mode: 'serial' })` call. */
+export function isSerialConfigureCall(call, testNames) {
+    if (call?.type !== 'CallExpression')
+        return false;
+    const c = unwrap(call.callee);
+    if (c?.type !== 'MemberExpression' || propName(c) !== 'configure')
+        return false;
+    const o = unwrap(c.object);
+    if (!(o?.type === 'MemberExpression' && propName(o) === 'describe' && o.object?.type === 'Identifier' && testNames.has(o.object.name)))
+        return false;
+    const arg = unwrap(call.arguments?.[0]);
+    if (arg?.type !== 'ObjectExpression')
+        return false;
+    return arg.properties.some((p) => p.type === 'Property' && (p.key?.name ?? p.key?.value) === 'mode' && p.value?.type === 'Literal' && p.value.value === 'serial');
+}
+/** Does this statement list directly contain `test.describe.configure({ mode: 'serial' })`? */
+function bodyHasSerialConfigure(body, testNames) {
+    return (body ?? []).some((st) => {
+        if (st?.type !== 'ExpressionStatement')
+            return false;
+        const e = unwrap(st.expression);
+        return isSerialConfigureCall(e?.type === 'AwaitExpression' ? unwrap(e.argument) : e, testNames);
+    });
+}
+/**
+ * Is `node` in a scope declared serial: the file has a top-level
+ * `test.describe.configure({ mode: 'serial' })`, or any enclosing describe is
+ * `test.describe.serial(...)` or configures serial mode in its own body.
+ */
+export function isInSerialScope(node, testNames) {
+    for (let p = node?.parent; p; p = p.parent) {
+        if (p.type === 'Program')
+            return bodyHasSerialConfigure(p.body, testNames);
+        if ((p.type === 'ArrowFunctionExpression' || p.type === 'FunctionExpression') && p.parent?.type === 'CallExpression' && p.parent.arguments.includes(p)) {
+            const call = p.parent;
+            if (isSerialDescribeCall(call, testNames))
+                return true;
+            if (isDescribeCall(call, testNames) && p.body?.type === 'BlockStatement' && bodyHasSerialConfigure(p.body.body, testNames))
+                return true;
+        }
+    }
+    return false;
+}
+export function testNamesFromOptions(options) {
+    const names = options[0]?.testAliasNames ?? [];
+    return new Set(['test', ...names]);
+}
+export const TEST_ALIAS_SCHEMA = [
+    {
+        type: 'object',
+        properties: { testAliasNames: { items: { type: 'string' }, type: 'array' } },
+        additionalProperties: false,
+    },
+];

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;

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('/');
+}