@gate-forge/pack-playwright 0.7.1 → 0.8.0

package/dist/discovery/static-discovery.js

@@ -33,6 +33,8 @@ import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
 import { join, posix } from 'node:path';
 import ts from 'typescript';
 import { pathInScope } from '@gate-forge/core';
+import { CLAIM_ANNOTATION_TYPE } from '../constants.js';
+import { gitIgnoredPaths } from './git-ignore.js';
 /** Default cap on files pulled in through import traversal. */
 export const DEFAULT_MAX_TRAVERSED_FILES = 200;
 /** Default bound on import-traversal depth (chain length). */
@@ -125,12 +127,127 @@ function locationOf(file, source, node) {
     const { line, character } = source.getLineAndCharacterOfPosition(node.getStart(source));
     return { file, line: line + 1, col: character };
 }
+/**
+ * Tests whether a syntax node is nested inside another node's subtree.
+ *
+ * Args:
+ *   container: candidate ancestor node.
+ *   target: node whose ancestry is checked.
+ *
+ * Returns:
+ *   boolean: true when target is inside container.
+ */
+function isWithinNode(container, target) {
+    let current = target;
+    while (current !== undefined && current !== container)
+        current = current.parent;
+    return current === container;
+}
+/**
+ * Finds Gateforge environment reads in conditional ancestors of a test
+ * registration so environment-dependent registrations can be reviewed.
+ *
+ * Args:
+ *   file: repo-relative file containing the registration.
+ *   source: parsed TypeScript source file.
+ *   node: registration call node.
+ *   titlePath: static title path for the registration.
+ *
+ * Returns:
+ *   StaticRegistrationWarning[]: one warning per relevant environment variable.
+ */
+function registrationWarningsForCall(file, source, node, titlePath) {
+    const guards = [];
+    for (let parent = node.parent; parent !== undefined; parent = parent.parent) {
+        if (ts.isIfStatement(parent) &&
+            (isWithinNode(parent.thenStatement, node) ||
+                (parent.elseStatement !== undefined && isWithinNode(parent.elseStatement, node)))) {
+            guards.push(parent.expression);
+        }
+        else if (ts.isConditionalExpression(parent) &&
+            (isWithinNode(parent.whenTrue, node) || isWithinNode(parent.whenFalse, node))) {
+            guards.push(parent.condition);
+        }
+        else if (ts.isBinaryExpression(parent) &&
+            isWithinNode(parent.right, node) &&
+            (parent.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken ||
+                parent.operatorToken.kind === ts.SyntaxKind.BarBarToken ||
+                parent.operatorToken.kind === ts.SyntaxKind.QuestionQuestionToken)) {
+            guards.push(parent.left);
+        }
+    }
+    if (guards.length === 0)
+        return [];
+    const variables = new Map();
+    /**
+     * Recognizes property or literal-index access to process.env.
+     *
+     * Args:
+     *   expression: expression to inspect.
+     *
+     * Returns:
+     *   boolean: true when expression is process.env.
+     */
+    const isProcessEnv = (expression) => (ts.isPropertyAccessExpression(expression) &&
+        ts.isIdentifier(expression.expression) &&
+        expression.expression.text === 'process' &&
+        expression.name.text === 'env') ||
+        (ts.isElementAccessExpression(expression) &&
+            ts.isIdentifier(expression.expression) &&
+            expression.expression.text === 'process' &&
+            expression.argumentExpression !== undefined &&
+            ts.isStringLiteral(expression.argumentExpression) &&
+            expression.argumentExpression.text === 'env');
+    /**
+     * Records Gateforge environment reads from one registration guard.
+     *
+     * Args:
+     *   guard: conditional expression to scan.
+     *
+     * Returns:
+     *   void.
+     */
+    const visitGuard = (guard) => {
+        if (ts.isPropertyAccessExpression(guard) && isProcessEnv(guard.expression)) {
+            const name = guard.name.text;
+            if (name.startsWith('GATEFORGE_') && !variables.has(name)) {
+                variables.set(name, locationOf(file, source, guard));
+            }
+        }
+        else if (ts.isElementAccessExpression(guard) &&
+            isProcessEnv(guard.expression) &&
+            guard.argumentExpression !== undefined &&
+            ts.isStringLiteral(guard.argumentExpression)) {
+            const name = guard.argumentExpression.text;
+            if (name.startsWith('GATEFORGE_') && !variables.has(name)) {
+                variables.set(name, locationOf(file, source, guard));
+            }
+        }
+        ts.forEachChild(guard, visitGuard);
+    };
+    for (const guard of guards)
+        visitGuard(guard);
+    return [...variables.entries()].map(([environmentVariable, location]) => ({
+        file,
+        titlePath: [...titlePath],
+        environmentVariable,
+        location,
+    }));
+}
 /**
  * Walks the repo (pruning VCS/deps/build dirs) and returns the sorted
- * repo-relative posix files matching the include globs and no exclude
- * glob. Pure filesystem listing — no content is read here.
+ * repo-relative posix files matching the include globs, no exclude glob,
+ * and no git ignore rule. Pure filesystem listing — no content is read
+ * here.
+ *
+ * A path the repository ignores (e.g. the built, git-ignored bundle a
+ * frontend build writes into the tree) can never be enumerated by the
+ * runner, so a row from it would be a permanent `unenumeratedReason`
+ * gap. Where git cannot answer — outside a work tree, or git
+ * unavailable — every candidate is kept exactly as before
+ * (see {@link gitIgnoredPaths}).
  */
-function collectCandidateFiles(cwd, include, exclude) {
+function collectCandidateFiles(cwd, include, exclude, excludeFile) {
     const found = [];
     const walk = (dir, rel) => {
         let names;
@@ -157,13 +274,17 @@ function collectCandidateFiles(cwd, include, exclude) {
             }
             else if (PARSEABLE_EXTENSIONS.some((ext) => name.endsWith(ext)) &&
                 pathInScope(relPath, include) &&
-                !pathInScope(relPath, exclude)) {
+                !pathInScope(relPath, exclude) &&
+                excludeFile?.(relPath) !== true) {
                 found.push(relPath);
             }
         }
     };
     walk(cwd, '');
-    return found.sort();
+    const ignored = gitIgnoredPaths(cwd, found);
+    if (ignored === null)
+        return found.sort();
+    return found.filter((file) => !ignored.has(file)).sort();
 }
 /** The callee shape `{base, names}` of `a.b.c(...)`, else null. */
 function calleeChain(expression) {
@@ -206,10 +327,19 @@ function bodyReferencesTest(body) {
     visit(body);
     return found;
 }
-/** Reads a file's text; unreadable content is a parse error row. */
+/**
+ * Reads a file's text; unreadable content is a parse error row. A path
+ * that is not a regular file (a directory that reached the read through
+ * a seeded or traversed row) is skipped silently — a directory is not
+ * a parse failure of the consumer's source, and reporting one used to
+ * flip `inventoryComplete` on a repo that parses fine.
+ */
 function readText(state, file) {
+    const absolute = join(state.cwd, file);
+    if (!isFile(absolute))
+        return null;
     try {
-        return readFileSync(join(state.cwd, file), 'utf8');
+        return readFileSync(absolute, 'utf8');
     }
     catch (error) {
         state.result.parseErrors.push({
@@ -539,7 +669,25 @@ function isPlaywrightSpecifier(specifier) {
 function isTestModuleSpecifier(specifier) {
     return isPlaywrightSpecifier(specifier) || isPackSpecifier(specifier);
 }
-/** Resolves a relative specifier against the repo (candidate extensions). */
+/**
+ * Resolves a relative specifier the way node/TS resolve it: a FILE
+ * first (the bare path when it names one, then each parseable
+ * extension), then a directory's `index.*`. A directory is never a
+ * resolution result — `existsSync` is true for one, and returning it
+ * made `readText` fail with EISDIR and report a false parse error
+ * against the consumer's own source whenever a file and a directory
+ * shared a name (install rehearsal F16).
+ *
+ * Args:
+ *   state: the running scan (seeded/traversed files win outright).
+ *   cwd: absolute repo root.
+ *   fromFile: repo-relative file holding the import.
+ *   specifier: the import specifier, as written.
+ *
+ * Returns:
+ *   string | null: repo-relative FILE path, or null when nothing
+ *   resolves.
+ */
 function resolveSpecifier(state, cwd, fromFile, specifier) {
     const base = posix.dirname(fromFile);
     const joined = posix.normalize(posix.join(base, specifier));
@@ -549,12 +697,33 @@ function resolveSpecifier(state, cwd, fromFile, specifier) {
         ...PARSEABLE_EXTENSIONS.map((ext) => `${joined}/index${ext}`),
     ];
     for (const candidate of candidates) {
-        if (state.seeded.has(candidate) || state.traversed.has(candidate) || existsSync(join(cwd, candidate))) {
+        if (state.seeded.has(candidate) || state.traversed.has(candidate))
+            return candidate;
+    }
+    for (const candidate of candidates) {
+        if (isFile(join(cwd, candidate)))
             return candidate;
-        }
     }
     return null;
 }
+/**
+ * Whether an absolute path is an existing regular file (never a
+ * directory, a socket, or a device node).
+ *
+ * Args:
+ *   absolute: absolute filesystem path.
+ *
+ * Returns:
+ *   boolean: true only for an existing regular file.
+ */
+function isFile(absolute) {
+    try {
+        return statSync(absolute).isFile();
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Resolves whether `name` in `file` binds to a playwright test function,
  * through aliases and relative imports, bounded by depth + file budget.
@@ -696,6 +865,34 @@ function findPageRoute(node, source, file) {
     visit(node);
     return found;
 }
+/**
+ * Collects literal URL patterns intercepted by `page.route` in one test.
+ *
+ * Args:
+ *   node: the test callback subtree.
+ *
+ * Returns:
+ *   string[]: unique, sorted static route patterns.
+ */
+function pageRouteTargets(node) {
+    const targets = new Set();
+    const visit = (current) => {
+        if (ts.isCallExpression(current) &&
+            ts.isPropertyAccessExpression(current.expression) &&
+            current.expression.name.text === 'route' &&
+            ts.isIdentifier(current.expression.expression)) {
+            const target = current.arguments[0];
+            if (target !== undefined &&
+                ts.isStringLiteralLike(target) &&
+                target.text.length > 0) {
+                targets.add(target.text);
+            }
+        }
+        ts.forEachChild(current, visit);
+    };
+    visit(node);
+    return [...targets].sort();
+}
 /** Whether the subtree calls fetch/axios (the app's HTTP boundary). */
 function findHttpClientCall(node, source, file) {
     let found = null;
@@ -769,14 +966,21 @@ function findModuleMock(source, file) {
  *   options: cwd, include/exclude globs, and optional budgets.
  *
  * Returns:
- *   StaticScanResult: entries, unresolved rows, parse errors, scanned
- *   files, and the budget flag. Never throws for scanner-detectable
- *   problems — those are rows (fail closed as data, not silence).
+ *   StaticScanResult: entries, unresolved rows, parse errors, registration
+ *   warnings, scanned files, and the budget flag. Never throws for
+ *   scanner-detectable problems — those are rows (fail closed as data, not silence).
  */
 export function scanTestFiles(options) {
     const state = {
         cwd: options.cwd,
-        result: { entries: [], unresolved: [], parseErrors: [], scannedFiles: [], budgetExceeded: false },
+        result: {
+            entries: [],
+            unresolved: [],
+            parseErrors: [],
+            registrationWarnings: [],
+            scannedFiles: [],
+            budgetExceeded: false,
+        },
         models: new Map(),
         seeded: new Set(),
         traversed: new Set(),
@@ -784,7 +988,7 @@ export function scanTestFiles(options) {
         maxTraversedFiles: options.budget?.maxTraversedFiles ?? DEFAULT_MAX_TRAVERSED_FILES,
         maxImportDepth: options.budget?.maxImportDepth ?? DEFAULT_MAX_IMPORT_DEPTH,
     };
-    const seededFiles = collectCandidateFiles(options.cwd, options.include, options.exclude);
+    const seededFiles = collectCandidateFiles(options.cwd, options.include, options.exclude, options.excludeFile);
     for (const file of seededFiles)
         state.seeded.add(file);
     for (const file of seededFiles) {
@@ -796,6 +1000,10 @@ export function scanTestFiles(options) {
         const gateforgeImport = findGateforgeFixtureImport(model.source, file);
         scanFileForTests(state, options.cwd, model, fileHttpClient, fileMock, gateforgeImport);
     }
+    state.result.registrationWarnings.sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0) ||
+        a.location.line - b.location.line ||
+        (a.environmentVariable < b.environmentVariable ? -1 : a.environmentVariable > b.environmentVariable ? 1 : 0) ||
+        (a.titlePath.join('>') < b.titlePath.join('>') ? -1 : a.titlePath.join('>') > b.titlePath.join('>') ? 1 : 0));
     state.result.entries.sort((a, b) => compareEntry(a, b));
     state.result.unresolved.sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0) ||
         a.location.line - b.location.line ||
@@ -951,6 +1159,7 @@ function scanFileForTests(state, cwd, model, fileHttpClient, fileMock, gateforge
                 gateforgeImport,
             });
             state.result.entries.push(entry);
+            state.result.registrationWarnings.push(...registrationWarningsForCall(file, source, node, entry.titlePath));
             // Walk the body so inner zero-arg `test.skip()` / `test.fixme()`
             // calls attach to THIS entry's signals.
             if (callback !== undefined) {
@@ -991,6 +1200,7 @@ function scanFileForTests(state, cwd, model, fileHttpClient, fileMock, gateforge
                     gateforgeImport,
                 });
                 state.result.entries.push(entry);
+                state.result.registrationWarnings.push(...registrationWarningsForCall(file, source, outer, entry.titlePath));
                 if (outerCallback !== undefined) {
                     const enclosing = { facts: entry.facts, signals: entry.signals };
                     ts.forEachChild(outerCallback, (child) => visit(child, describeStack, enclosing));
@@ -1034,9 +1244,234 @@ function scanFileForTests(state, cwd, model, fileHttpClient, fileMock, gateforge
     };
     visit(source, [], null);
 }
+/**
+ * Finds one top-level local constant initializer by name.
+ *
+ * Args:
+ *   source: parsed test source file.
+ *   name: local identifier to resolve.
+ *
+ * Returns:
+ *   ts.Expression | null: a unique const initializer, or null when it
+ *   is absent, ambiguous, mutable, or destructured.
+ */
+function localConstantInitializer(source, name) {
+    const matches = [];
+    for (const statement of source.statements) {
+        if (!ts.isVariableStatement(statement) || (statement.declarationList.flags & ts.NodeFlags.Const) === 0)
+            continue;
+        for (const declaration of statement.declarationList.declarations) {
+            if (ts.isIdentifier(declaration.name) && declaration.name.text === name && declaration.initializer !== undefined) {
+                matches.push(declaration.initializer);
+            }
+        }
+    }
+    return matches.length === 1 ? (matches[0] ?? null) : null;
+}
+/**
+ * Finds a pure local helper declared as a function or const arrow.
+ *
+ * Args:
+ *   source: parsed test source file.
+ *   name: helper identifier to resolve.
+ *
+ * Returns:
+ *   ts.FunctionDeclaration | ts.ArrowFunction | ts.FunctionExpression | null:
+ *   one unambiguous top-level function helper.
+ */
+function localStaticFunction(source, name) {
+    const matches = [];
+    for (const statement of source.statements) {
+        if (ts.isFunctionDeclaration(statement) && statement.name?.text === name) {
+            matches.push(statement);
+            continue;
+        }
+        if (!ts.isVariableStatement(statement) || (statement.declarationList.flags & ts.NodeFlags.Const) === 0)
+            continue;
+        for (const declaration of statement.declarationList.declarations) {
+            if (!ts.isIdentifier(declaration.name) || declaration.name.text !== name || declaration.initializer === undefined)
+                continue;
+            if (ts.isArrowFunction(declaration.initializer) || ts.isFunctionExpression(declaration.initializer)) {
+                matches.push(declaration.initializer);
+            }
+        }
+    }
+    return matches.length === 1 ? (matches[0] ?? null) : null;
+}
+/**
+ * Resolves a bounded JSON-like expression without executing consumer code.
+ *
+ * Args:
+ *   expression: source expression to resolve.
+ *   source: parsed file that may contain local consts and pure helpers.
+ *   bindings: literal arguments bound to a local helper's parameters.
+ *   depth: recursion depth used to reject cycles.
+ *
+ * Returns:
+ *   StaticJsonResult: a literal value when fully resolvable, else failure.
+ */
+function staticJsonValue(expression, source, bindings = new Map(), depth = 0) {
+    if (depth > 8)
+        return { ok: false };
+    if (ts.isAsExpression(expression) ||
+        ts.isTypeAssertionExpression(expression) ||
+        ts.isSatisfiesExpression(expression) ||
+        ts.isNonNullExpression(expression)) {
+        return staticJsonValue(expression.expression, source, bindings, depth + 1);
+    }
+    if (ts.isStringLiteralLike(expression))
+        return { ok: true, value: expression.text };
+    if (ts.isNumericLiteral(expression)) {
+        const value = Number(expression.text);
+        return Number.isFinite(value) ? { ok: true, value } : { ok: false };
+    }
+    if (expression.kind === ts.SyntaxKind.TrueKeyword)
+        return { ok: true, value: true };
+    if (expression.kind === ts.SyntaxKind.FalseKeyword)
+        return { ok: true, value: false };
+    if (expression.kind === ts.SyntaxKind.NullKeyword)
+        return { ok: true, value: null };
+    if (ts.isIdentifier(expression)) {
+        const bound = bindings.get(expression.text);
+        if (bound !== undefined)
+            return { ok: true, value: bound };
+        const initializer = localConstantInitializer(source, expression.text);
+        return initializer === null ? { ok: false } : staticJsonValue(initializer, source, bindings, depth + 1);
+    }
+    if (ts.isArrayLiteralExpression(expression)) {
+        const values = [];
+        for (const element of expression.elements) {
+            if (!ts.isExpression(element))
+                return { ok: false };
+            const resolved = staticJsonValue(element, source, bindings, depth + 1);
+            if (!resolved.ok)
+                return { ok: false };
+            values.push(resolved.value);
+        }
+        return { ok: true, value: values };
+    }
+    if (ts.isObjectLiteralExpression(expression)) {
+        const value = {};
+        for (const property of expression.properties) {
+            if (!ts.isPropertyAssignment(property))
+                return { ok: false };
+            const key = property.name;
+            if (!(ts.isIdentifier(key) || ts.isStringLiteralLike(key) || ts.isNumericLiteral(key)))
+                return { ok: false };
+            const resolved = staticJsonValue(property.initializer, source, bindings, depth + 1);
+            if (!resolved.ok)
+                return { ok: false };
+            value[key.text] = resolved.value;
+        }
+        return { ok: true, value };
+    }
+    if (ts.isCallExpression(expression) && ts.isIdentifier(expression.expression)) {
+        const helper = localStaticFunction(source, expression.expression.text);
+        if (helper === null || helper.parameters.length !== expression.arguments.length)
+            return { ok: false };
+        const values = [];
+        for (const argument of expression.arguments) {
+            if (ts.isSpreadElement(argument))
+                return { ok: false };
+            const resolved = staticJsonValue(argument, source, bindings, depth + 1);
+            if (!resolved.ok)
+                return { ok: false };
+            values.push(resolved.value);
+        }
+        const helperBindings = new Map();
+        for (const [index, parameter] of helper.parameters.entries()) {
+            if (!ts.isIdentifier(parameter.name))
+                return { ok: false };
+            const value = values[index];
+            if (value === undefined)
+                return { ok: false };
+            helperBindings.set(parameter.name.text, value);
+        }
+        const helperBody = helper.body;
+        let returned;
+        if (helperBody === undefined)
+            return { ok: false };
+        if (!ts.isBlock(helperBody)) {
+            returned = helperBody;
+        }
+        else {
+            const statement = helperBody.statements[0];
+            if (helperBody.statements.length === 1 &&
+                statement !== undefined &&
+                ts.isReturnStatement(statement) &&
+                statement.expression !== undefined) {
+                returned = statement.expression;
+            }
+        }
+        return returned === undefined
+            ? { ok: false }
+            : staticJsonValue(returned, source, helperBindings, depth + 1);
+    }
+    return { ok: false };
+}
+/**
+ * Extracts Gateforge claim annotations from one test call using literals only.
+ *
+ * Args:
+ *   node: parsed test-call node.
+ *   source: parsed test source file for local const/helper resolution.
+ *
+ * Returns:
+ *   { claims, issue }: deduplicated claim ids, or a visible reason when a
+ *   possible annotation cannot be resolved statically.
+ */
+function gateforgeAnnotationClaims(node, source) {
+    if (!ts.isCallExpression(node))
+        return { claims: [], issue: null };
+    const options = node.arguments[1];
+    if (options === undefined || ts.isArrowFunction(options) || ts.isFunctionExpression(options)) {
+        return { claims: [], issue: null };
+    }
+    if (ts.isObjectLiteralExpression(options)) {
+        const hasAnnotation = options.properties.some((property) => ts.isPropertyAssignment(property) && ts.isIdentifier(property.name) && property.name.text === 'annotation');
+        if (!hasAnnotation) {
+            return {
+                claims: [],
+                issue: options.properties.some(ts.isSpreadAssignment)
+                    ? 'test options contain a spread that may hide a Gateforge annotation'
+                    : null,
+            };
+        }
+    }
+    const resolved = staticJsonValue(options, source);
+    if (!resolved.ok) {
+        return { claims: [], issue: 'test options may contain a Gateforge annotation but are not a local literal or pure helper result' };
+    }
+    if (resolved.value === null || Array.isArray(resolved.value) || typeof resolved.value !== 'object') {
+        return { claims: [], issue: null };
+    }
+    const annotation = resolved.value['annotation'];
+    if (annotation === undefined)
+        return { claims: [], issue: null };
+    const items = Array.isArray(annotation) ? annotation : [annotation];
+    const claims = [];
+    for (const item of items) {
+        if (item === null || Array.isArray(item) || typeof item !== 'object') {
+            return { claims: [], issue: 'annotation value is not a statically resolved object' };
+        }
+        const type = item['type'];
+        if (typeof type !== 'string') {
+            return { claims: [], issue: 'annotation type is not a statically resolved string' };
+        }
+        if (type !== CLAIM_ANNOTATION_TYPE)
+            continue;
+        const description = item['description'];
+        if (typeof description !== 'string' || description.length === 0) {
+            return { claims: [], issue: 'Gateforge annotation description is not a non-empty static string' };
+        }
+        claims.push(description);
+    }
+    return { claims: [...new Set(claims)].sort(), issue: null };
+}
 /** Builds one static entry: facts from the callback body + signals. */
 function buildEntry(input) {
     const { file, source, node, callback, titlePath, location } = input;
+    const annotations = gateforgeAnnotationClaims(node, source);
     const params = callback === undefined ? [] : signatureParamsOf(callback);
     const signals = [...input.inheritedSignals];
     for (const kind of input.suppression) {
@@ -1044,6 +1479,7 @@ function buildEntry(input) {
     }
     let pageRoute = null;
     let httpClientCall = null;
+    const interceptedTargets = callback === undefined ? [] : pageRouteTargets(callback);
     if (callback !== undefined) {
         pageRoute = findPageRoute(callback, source, file);
         httpClientCall = findHttpClientCall(callback, source, file);
@@ -1058,11 +1494,14 @@ function buildEntry(input) {
         facts: {
             signatureParams: params,
             pageRoute,
+            ...(interceptedTargets.length > 0 ? { pageRouteTargets: interceptedTargets } : {}),
             httpClientCall,
             fileHttpClientCall: input.fileHttpClient,
             fileMockImport: input.fileMock,
             gateforgeFixtureImport: input.gateforgeImport,
         },
+        ...(annotations.claims.length > 0 ? { annotationClaims: annotations.claims } : {}),
+        ...(annotations.issue !== null ? { annotationIssue: annotations.issue } : {}),
     };
 }
 //# sourceMappingURL=static-discovery.js.map