@taodigital/agents 0.0.0-stage → 1.2.1

package/dist/repo-scan-agent.js

@@ -0,0 +1,2032 @@
+"use strict";
+/**
+ * GitHub repo scanning agent for Framework Modernization.
+ *
+ * Handles: GitHub API calls (raw fetch), framework detection from config file paths,
+ * test ID extraction from test file content, and style extraction from sample files.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateGitHubRepo = validateGitHubRepo;
+exports.fetchRepoTree = fetchRepoTree;
+exports.fetchFileContent = fetchFileContent;
+exports.detectFramework = detectFramework;
+exports.resolveFixtureAliasesFromImports = resolveFixtureAliasesFromImports;
+exports.extractTestIds = extractTestIds;
+exports.extractStyleProfile = extractStyleProfile;
+exports.deriveJavaBasePackage = deriveJavaBasePackage;
+exports.buildPageObjectInventory = buildPageObjectInventory;
+exports.formatPageObjectInventoryForPrompt = formatPageObjectInventoryForPrompt;
+exports.deriveRepoTargetPath = deriveRepoTargetPath;
+exports.parseFrameworkConfig = parseFrameworkConfig;
+exports.detectConfigFilesToFetch = detectConfigFilesToFetch;
+const core_1 = require("@taodigital/core");
+const llm_js_1 = require("./llm.js");
+const llm_config_js_1 = require("./llm-config.js");
+const app_brain_1 = require("@taodigital/app-brain");
+const GITHUB_API_BASE = process.env.GITHUB_API_BASE_URL ?? 'https://api.github.com';
+// ---------------------------------------------------------------------------
+// Test data / fixture / locators directory detection
+// ---------------------------------------------------------------------------
+// Ordered from most-specific to least-specific; detectDataDirs scores by index position.
+const TEST_DATA_PATTERNS = [
+    /(?:^|\/)testdata\//i,
+    /(?:^|\/)test-data\//i,
+    /(?:^|\/)test_data\//i,
+    /(?:^|\/)src\/test\/resources\//i,
+    /(?:^|\/)test[-_]?resources\//i,
+    /(?:^|\/)mocks?\//i,
+    /(?:^|\/)stubs?\//i,
+    /(?:^|\/)seeds?\//i,
+    /(?:^|\/)factor(?:y|ies)\//i,
+    // src/data/ is a common Playwright repo convention — must score above the generic data/ catch-all
+    /(?:^|\/)src\/data\//i,
+    // __snapshots__/ is Jest auto-generated assertion artifacts, NOT test data
+    // data/ is last — too broad; scored low so testdata/ wins when both present
+    /(?:^|\/)data\//i,
+];
+const FIXTURE_PATTERNS = [
+    // src/fixtures/ is a common Playwright repo convention where all test support lives under src/
+    // Must be index 0 to beat tests/fixtures/ which receives +5 bonus from the tests/ path scoring
+    /(?:^|\/)src\/fixtures?\//i,
+    /(?:^|\/)fixtures?\//i,
+    /(?:^|\/)fixture\//i,
+    /(?:^|\/)__fixtures__\//i,
+    /(?:^|\/)__mocks__\//i,
+    /(?:^|\/)spec\/fixtures?\//i,
+    /(?:^|\/)spec\/support\//i,
+    /(?:^|\/)src\/test\/resources\//i,
+];
+// Only genuine locator/selector dirs — not generic `constants/`, `objects/` (DTOs), or `step_definitions/` (test code)
+const LOCATOR_PATTERNS = [
+    /(?:^|\/)locators?\//i,
+    /(?:^|\/)selectors?\//i,
+    /(?:^|\/)elements?\//i,
+    /(?:^|\/)mapping\//i,
+    /(?:^|\/)objectmap\//i,
+    /(?:^|\/)po\//i,
+];
+const UTILS_PATTERNS = [
+    /(?:^|\/)support\/utils?\//i,
+    /(?:^|\/)lib\/utils?\//i,
+    /(?:^|\/)utils?\//i,
+    /(?:^|\/)helpers?\//i,
+    /(?:^|\/)shared\//i,
+    /(?:^|\/)common\//i,
+];
+const CONFIG_PATTERNS = [
+    /(?:^|\/)src\/config\//i,
+    /(?:^|\/)config\/(?!playwright|jest|cypress|webpack|babel|eslint|prettier|rollup|vite|tsconfig)\w/i,
+    /(?:^|\/)conf\//i,
+    /(?:^|\/)settings\//i,
+];
+/**
+ * Scan actual repo file paths to detect test data, fixture, and locators directory names.
+ * Returns first matching directory prefix for each, or null if not found.
+ * Heuristic runs BEFORE LLM so detected values can be passed as authoritative context.
+ */
+function detectDataDirs(paths) {
+    // Exclude node_modules and package manager caches — they produce false positives (e.g. lodash/data/)
+    const filtered = paths.filter((p) => !p.includes('node_modules/') && !p.startsWith('.yarn/') && !p.startsWith('.pnp'));
+    // Score-based: lower patternIndex = more specific = higher score; test-path bonus.
+    function extractDir(p, m) {
+        const seg = m[0].replace(/^\//, '');
+        const idx = p.indexOf(seg);
+        const dir = p.slice(0, idx + seg.length);
+        return dir.startsWith('/') ? dir.slice(1) : dir;
+    }
+    function bestMatch(patterns) {
+        let best = null;
+        for (const p of filtered) {
+            for (let i = 0; i < patterns.length; i++) {
+                const m = p.match(patterns[i]);
+                if (!m)
+                    continue;
+                // Higher score = more specific pattern (lower index) + bonus if inside a test dir
+                const score = (patterns.length - i) * 10 + (/(?:^|\/)tests?\//i.test(p) ? 5 : 0);
+                if (!best || score > best.score) {
+                    best = { dir: extractDir(p, m), score };
+                }
+                break; // one pattern match per path is enough
+            }
+        }
+        return best ? best.dir : null;
+    }
+    return {
+        testDataDir: bestMatch(TEST_DATA_PATTERNS),
+        fixtureDir: bestMatch(FIXTURE_PATTERNS),
+        locatorsDir: bestMatch(LOCATOR_PATTERNS),
+        utilsDir: bestMatch(UTILS_PATTERNS),
+        configDir: bestMatch(CONFIG_PATTERNS),
+    };
+}
+// ---------------------------------------------------------------------------
+// GitHub API helpers
+// ---------------------------------------------------------------------------
+function githubHeaders(token) {
+    return {
+        Authorization: `Bearer ${token}`,
+        Accept: 'application/vnd.github+json',
+        'X-GitHub-Api-Version': '2022-11-28',
+    };
+}
+async function validateGitHubRepo(token, repoFullName) {
+    try {
+        const res = await fetch(`${GITHUB_API_BASE}/repos/${repoFullName}`, {
+            headers: githubHeaders(token),
+        });
+        if (!res.ok) {
+            const body = await res.json().catch(() => ({}));
+            return {
+                ok: false,
+                defaultBranch: '',
+                private: false,
+                error: body?.message ?? `HTTP ${res.status}`,
+            };
+        }
+        const data = await res.json();
+        // For public repos, GET /repos/:name returns 200 even with an invalid/expired token.
+        // Validate the token itself by calling GET /user (auth-required endpoint).
+        if (!data.private) {
+            const userRes = await fetch(`${GITHUB_API_BASE}/user`, { headers: githubHeaders(token) });
+            if (!userRes.ok) {
+                const body = await userRes.json().catch(() => ({}));
+                return {
+                    ok: false,
+                    defaultBranch: '',
+                    private: false,
+                    error: body?.message ?? 'Token is invalid or expired',
+                };
+            }
+        }
+        return {
+            ok: true,
+            defaultBranch: data.default_branch ?? 'main',
+            private: data.private ?? false,
+        };
+    }
+    catch (e) {
+        return { ok: false, defaultBranch: '', private: false, error: e?.message ?? 'Network error' };
+    }
+}
+async function fetchRepoTree(token, repoFullName, branch = 'HEAD') {
+    let res;
+    try {
+        res = await fetch(`${GITHUB_API_BASE}/repos/${repoFullName}/git/trees/${branch}?recursive=1`, { headers: githubHeaders(token) });
+    }
+    catch (e) {
+        const cause = e?.cause?.message ?? e?.cause ?? '';
+        throw new Error(`GitHub API unreachable: ${e?.message ?? 'fetch failed'}${cause ? ` (${cause})` : ''}`);
+    }
+    if (!res.ok) {
+        const body = await res.json().catch(() => ({}));
+        const detail = body?.message ? `: ${body.message}` : '';
+        throw new Error(`GitHub API error: HTTP ${res.status}${detail}`);
+    }
+    const data = await res.json();
+    const paths = (data.tree ?? [])
+        .filter((item) => item.type === 'blob')
+        .map((item) => item.path);
+    return { paths, sha: data.sha ?? '', truncated: data.truncated ?? false };
+}
+async function fetchFileContent(token, repoFullName, filePath) {
+    const maxAttempts = 3;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            await new Promise((r) => setTimeout(r, 100 * attempt));
+            const res = await fetch(`${GITHUB_API_BASE}/repos/${repoFullName}/contents/${filePath}`, { headers: githubHeaders(token) });
+            if (res.status === 403 || res.status === 429) {
+                // Rate limited — check Retry-After or back off exponentially
+                const retryAfter = res.headers.get('Retry-After');
+                const delay = retryAfter ? parseInt(retryAfter, 10) * 1000 : 1000 * attempt;
+                if (attempt < maxAttempts) {
+                    await new Promise((r) => setTimeout(r, delay));
+                    continue;
+                }
+                return null;
+            }
+            if (!res.ok)
+                return null;
+            const data = await res.json();
+            if (data.encoding === 'base64' && typeof data.content === 'string') {
+                return Buffer.from(data.content.replace(/\n/g, ''), 'base64').toString('utf-8');
+            }
+            return null;
+        }
+        catch {
+            if (attempt === maxAttempts)
+                return null;
+        }
+    }
+    return null;
+}
+const FRAMEWORK_SIGNATURES = [
+    {
+        configPatterns: [/playwright\.config\.ts$/i],
+        framework: 'playwright-ts',
+        language: 'typescript',
+        testGlob: '**/*.spec.ts',
+        confidence: 'HIGH',
+    },
+    {
+        configPatterns: [/playwright\.config\.js$/i],
+        framework: 'playwright-js',
+        language: 'javascript',
+        testGlob: '**/*.spec.js',
+        confidence: 'HIGH',
+    },
+    {
+        configPatterns: [/cypress\.config\.ts$/i],
+        framework: 'cypress-ts',
+        language: 'typescript',
+        testGlob: 'cypress/e2e/**/*.cy.ts',
+        confidence: 'HIGH',
+    },
+    {
+        configPatterns: [/cypress\.config\.js$/i],
+        framework: 'cypress-js',
+        language: 'javascript',
+        testGlob: 'cypress/e2e/**/*.cy.js',
+        confidence: 'HIGH',
+    },
+    {
+        configPatterns: [/jest\.config\.ts$/i],
+        framework: 'jest-ts',
+        language: 'typescript',
+        testGlob: '**/*.test.ts',
+        confidence: 'HIGH',
+    },
+    {
+        configPatterns: [/jest\.config\.js$/i],
+        framework: 'jest-js',
+        language: 'javascript',
+        testGlob: '**/*.test.js',
+        confidence: 'HIGH',
+    },
+    {
+        configPatterns: [/pytest\.ini$/i, /pyproject\.toml$/i, /setup\.cfg$/i, /conftest\.py$/i],
+        framework: 'pytest',
+        language: 'python',
+        testGlob: '**/*.py',
+        confidence: 'HIGH',
+    },
+    {
+        configPatterns: [/pom\.xml$/i],
+        framework: 'junit',
+        language: 'java',
+        testGlob: 'src/test/**/*.java',
+        confidence: 'HIGH',
+    },
+    {
+        configPatterns: [/build\.gradle(\.kts)?$/i],
+        framework: 'junit',
+        language: 'java',
+        testGlob: 'src/test/**/*.java',
+        confidence: 'HIGH',
+    },
+    {
+        configPatterns: [/testng\.xml$/i],
+        framework: 'junit', // TestNG uses JUnit-compatible runner; will upgrade to selenium-java
+        language: 'java',
+        testGlob: 'src/test/**/*.java',
+        confidence: 'HIGH',
+    },
+    {
+        configPatterns: [/wdio\.conf\.(js|ts)$/i],
+        framework: 'webdriverio',
+        language: 'javascript',
+        testGlob: 'test/specs/**/*.js',
+        confidence: 'HIGH',
+    },
+    {
+        configPatterns: [/vitest\.config\.(ts|js|mts|mjs)$/i],
+        framework: 'jest-ts',
+        language: 'typescript',
+        testGlob: '**/*.test.ts',
+        confidence: 'HIGH',
+    },
+    {
+        configPatterns: [/\.mocharc\.(js|json|yml|yaml|cjs|mjs)$/i],
+        framework: 'jest-js',
+        language: 'javascript',
+        testGlob: 'test/**/*.js',
+        confidence: 'MEDIUM',
+    },
+    {
+        // Nightwatch ≠ WebdriverIO but no dedicated support; map to closest equivalent
+        configPatterns: [/nightwatch\.conf\.(js|ts)$/i],
+        framework: 'webdriverio',
+        language: 'javascript',
+        testGlob: 'test/**/*.js',
+        confidence: 'LOW',
+    },
+    {
+        configPatterns: [/playwright\.config\.(py|cfg)$/i, /conftest\.py$/i],
+        framework: 'pytest',
+        language: 'python',
+        testGlob: '**/*.py',
+        confidence: 'MEDIUM',
+    },
+    {
+        configPatterns: [/behave\.ini$/i, /features\/.*\.feature$/i],
+        framework: 'cucumber',
+        language: 'python',
+        testGlob: 'features/**/*.feature',
+        confidence: 'HIGH',
+    },
+    {
+        configPatterns: [/\.feature$/i],
+        framework: 'cucumber',
+        language: 'javascript',
+        testGlob: '**/*.feature',
+        confidence: 'MEDIUM',
+    },
+];
+function detectFramework(paths) {
+    const results = [];
+    const seen = new Set();
+    for (const sig of FRAMEWORK_SIGNATURES) {
+        for (const path of paths) {
+            for (const pattern of sig.configPatterns) {
+                if (pattern.test(path)) {
+                    if (!seen.has(sig.framework)) {
+                        seen.add(sig.framework);
+                        results.push({
+                            framework: sig.framework,
+                            language: sig.language,
+                            testGlob: sig.testGlob,
+                            configPath: path,
+                            confidence: sig.confidence,
+                        });
+                    }
+                    break;
+                }
+            }
+        }
+    }
+    if (results.length === 0) {
+        results.push({
+            framework: 'unknown',
+            language: 'javascript',
+            testGlob: '**/*.test.*',
+            configPath: '',
+            confidence: 'LOW',
+        });
+    }
+    // Upgrade pytest → playwright-py when playwright appears in any repo path
+    // (playwright-python projects use pytest-playwright as the runner)
+    const hasPlaywrightPaths = paths.some(p => /playwright/i.test(p));
+    if (hasPlaywrightPaths) {
+        for (const r of results) {
+            if (r.framework === 'pytest') {
+                r.framework = 'playwright-py';
+            }
+        }
+    }
+    // Upgrade junit → playwright-java or selenium-java based on repo paths.
+    // pom.xml alone can't distinguish Selenium from Playwright Java;
+    // use presence of playwright-specific paths to decide.
+    for (const r of results) {
+        if (r.framework === 'junit') {
+            r.framework = hasPlaywrightPaths ? 'playwright-java' : 'selenium-java';
+        }
+    }
+    // Deterministic primary-framework ordering when multiple frameworks detected.
+    // FRAMEWORK_SIGNATURES order already encodes priority (playwright > cypress > jest > ...),
+    // so results array is already in priority order — but sort explicitly to be safe.
+    const FRAMEWORK_PRIORITY = {
+        'playwright-ts': 0, 'playwright-js': 1, 'playwright-py': 2, 'playwright-java': 3,
+        'cypress-ts': 4, 'cypress-js': 5,
+        'jest-ts': 6, 'jest-js': 7,
+        'webdriverio': 8,
+        'pytest': 9, 'selenium-py': 10,
+        'selenium-java': 11,
+        'cucumber': 12, 'gherkin': 13,
+        'unknown': 99,
+    };
+    results.sort((a, b) => (FRAMEWORK_PRIORITY[a.framework] ?? 50) - (FRAMEWORK_PRIORITY[b.framework] ?? 50));
+    return results;
+}
+// ---------------------------------------------------------------------------
+// Test ID extraction
+// ---------------------------------------------------------------------------
+function normalizeName(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^\w\s]/g, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+function isDynamic(name) {
+    return (name.includes('${') || // JS template literal: ${var}
+        name.includes('\\${') || // escaped: \${var}
+        name.includes('%') || // printf-style: %s %d %i %f %p
+        /\{[^}]+\}/.test(name) || // bare braces: {name} {index} {param} (JUnit/pytest)
+        /<[^>]+>/.test(name) // Gherkin Scenario Outline: <variable>
+    );
+}
+/** Strip string literals and line comments so brace-counting isn't corrupted by `{` inside strings. */
+function stripStringLiterals(line) {
+    // Remove line comment first
+    let s = line.replace(/\/\/.*$/, '');
+    // Remove single-quoted, double-quoted, and template-literal string contents (handles simple escapes)
+    s = s.replace(/'(?:[^'\\]|\\.)*'/g, "''");
+    s = s.replace(/"(?:[^"\\]|\\.)*"/g, '""');
+    s = s.replace(/`(?:[^`\\]|\\.)*`/g, '``');
+    return s;
+}
+/** Name-based heuristic: is this specifier name likely a test object? */
+function isTestObjectName(name) {
+    const lower = name.toLowerCase();
+    return (lower === 'test' ||
+        lower === 'it' ||
+        lower.endsWith('test') || // authTest, mobalyticsTest, adminTest
+        lower.endsWith('fixture') || // testFixture, authFixture
+        lower === 'base' ||
+        lower === 'expect' // sometimes exported alongside test
+    );
+}
+/**
+ * Detect fixture-aliased test identifiers from import statements.
+ *
+ * Strategy:
+ * - Relative imports (../ ./): accept ANY specifier whose name looks like a test object
+ *   — path doesn't matter, name heuristic is enough.
+ * - Package imports (@scope/pkg, bare names): use broadened keyword list covering
+ *   common enterprise directory names (core, auth, support, helpers, utils, testing, lib).
+ * - `test as alias` renames: always captured regardless of path.
+ * - require() destructuring: same rules as named imports.
+ * - extraAliases: pre-resolved aliases from multi-file tracing (G-07), merged in directly.
+ */
+function detectTestAliases(content, extraAliases) {
+    const aliases = new Set(extraAliases);
+    const namedImportRe = /^import\s*\{([^}]+)\}\s*from\s*['"]([^'"]+)['"]/gm;
+    let m;
+    while ((m = namedImportRe.exec(content)) !== null) {
+        const importPath = m[2];
+        const isRelative = importPath.startsWith('./') || importPath.startsWith('../');
+        // For package imports, require at least one fixture-related keyword in the path
+        const isFixturePath = isRelative ||
+            /\bfixture[s]?\b/i.test(importPath) ||
+            /\/(?:setup|base|support|helpers?|utils?|core|auth|testing|lib)\b/.test(importPath) ||
+            /\btest(?:ing|s)?\b/i.test(importPath);
+        if (!isFixturePath)
+            continue;
+        const specifiers = m[1].split(',').map((s) => s.trim());
+        for (const spec of specifiers) {
+            const asMatch = /^(\w+)\s+as\s+(\w+)$/.exec(spec);
+            if (asMatch) {
+                // `test as authTest` — the rename target IS the test function regardless of name
+                aliases.add(asMatch[2]);
+            }
+            else if (/^\w+$/.test(spec) && isTestObjectName(spec)) {
+                aliases.add(spec);
+            }
+        }
+    }
+    // require() destructuring: const { authTest } = require('../auth')
+    const requireRe = /const\s*\{([^}]+)\}\s*=\s*require\s*\(\s*['"]([^'"]+)['"]/gm;
+    while ((m = requireRe.exec(content)) !== null) {
+        const importPath = m[2];
+        const isRelative = importPath.startsWith('./') || importPath.startsWith('../');
+        const isFixturePath = isRelative ||
+            /\bfixture[s]?\b/i.test(importPath) ||
+            /\/(?:setup|base|support|helpers?|utils?|core|auth|testing|lib)\b/.test(importPath);
+        if (!isFixturePath)
+            continue;
+        const specifiers = m[1].split(',').map((s) => s.trim());
+        for (const spec of specifiers) {
+            if (/^\w+$/.test(spec) && isTestObjectName(spec)) {
+                aliases.add(spec);
+            }
+        }
+    }
+    return aliases;
+}
+/**
+ * G-07: Multi-file fixture tracing.
+ * For relative imports where specifier name does NOT match the name heuristic,
+ * fetch the imported file and check if it exports a test.extend() result.
+ * Returns a set of confirmed alias names to merge into detectTestAliases.
+ * Max 3 fixture files fetched per spec file to stay within rate limits.
+ */
+/** Resolve a relative import path against a base directory string (no Node.js path module needed). */
+function resolveRelativeImport(specDir, importPath) {
+    const parts = specDir ? specDir.split('/') : [];
+    for (const seg of importPath.split('/')) {
+        if (seg === '..')
+            parts.pop();
+        else if (seg !== '.')
+            parts.push(seg);
+    }
+    return parts.join('/');
+}
+/**
+ * G-07: Multi-file fixture tracing.
+ * For relative imports where specifier name does NOT match the name heuristic,
+ * fetch the imported file and check if it exports a test.extend() result.
+ * Returns confirmed alias names to merge into detectTestAliases.
+ * Max 3 fixture files fetched per spec file to stay within rate limits.
+ */
+async function resolveFixtureAliasesFromImports(content, token, repoFullName, specFilePath) {
+    const confirmed = new Set();
+    const namedImportRe = /^import\s*\{([^}]+)\}\s*from\s*['"]([^'"]+)['"]/gm;
+    let m;
+    let fetched = 0;
+    const specDir = specFilePath.includes('/')
+        ? specFilePath.substring(0, specFilePath.lastIndexOf('/'))
+        : '';
+    while ((m = namedImportRe.exec(content)) !== null && fetched < 3) {
+        const importPath = m[2];
+        if (!importPath.startsWith('./') && !importPath.startsWith('../'))
+            continue;
+        const specifiers = m[1].split(',').map((s) => s.trim());
+        // Only trace imports where at least one specifier name looks non-obvious
+        const unknownSpecs = specifiers.filter((sp) => {
+            const name = (/^(\w+)\s+as\s+(\w+)$/.exec(sp) ?? [])[2] ?? sp;
+            return /^\w+$/.test(name) && !isTestObjectName(name);
+        });
+        if (unknownSpecs.length === 0)
+            continue;
+        const resolved = resolveRelativeImport(specDir, importPath);
+        const candidates = [`${resolved}.ts`, `${resolved}/index.ts`, `${resolved}.js`, `${resolved}/index.js`];
+        for (const candidate of candidates) {
+            const fixContent = await fetchFileContent(token, repoFullName, candidate);
+            if (!fixContent)
+                continue;
+            fetched++;
+            // Check if file exports a test.extend() result
+            const hasExtend = /(?:test|it|base)\s*(?:\.\w+)?\s*\.extend\s*\(/.test(fixContent) ||
+                /=\s*(?:test|it|base)\s*\.extend\s*\(/.test(fixContent);
+            if (!hasExtend)
+                break;
+            // Confirmed fixture module — add all unknown specifier names
+            for (const sp of unknownSpecs) {
+                const asMatch = /^(\w+)\s+as\s+(\w+)$/.exec(sp);
+                const aliasName = asMatch ? asMatch[2] : sp;
+                if (/^\w+$/.test(aliasName))
+                    confirmed.add(aliasName);
+            }
+            break;
+        }
+    }
+    return confirmed;
+}
+function buildAliasedIdentifierPattern(aliases) {
+    // Returns a regex alternation group for all known test identifiers
+    // Base identifiers always included; fixture aliases appended
+    const base = ['test', 'it'];
+    const extra = [...aliases].filter((a) => !base.includes(a));
+    return [...base, ...extra].map((a) => a.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|');
+}
+function extractJestLike(content, filePath, framework, extraAliases) {
+    const tests = [];
+    const lines = content.split('\n');
+    const describeStack = [];
+    // Detect fixture-aliased test identifiers (e.g. authTest from test.extend())
+    const aliases = detectTestAliases(content, extraAliases);
+    const idPat = buildAliasedIdentifierPattern(aliases);
+    // describe/suite/<alias>.describe — including .only/.skip/.each/.parallel/.configure variants
+    const describeRe = new RegExp(String.raw `^\s*(?:(?:${idPat})\.describe(?:\.\w+)?|describe(?:\.\w+)?|suite)\s*(?:\.each\b[^(]*)?\s*\(\s*(['"\`])(.*?)\1`);
+    // test/it/<alias> with all modifiers; also x-prefixed variants
+    const testRe = new RegExp(String.raw `^\s*(?:x(?:test|it)|(?:${idPat})(?:\.(?:skip|only|fixme|fail|slow|concurrent|todo|each\b[^(]*))?)\s*\(\s*(['"\`])(.*?)\1`);
+    // test.each tagged template: test.each`data`('title %s', fn)
+    const eachTaggedRe = new RegExp(String.raw `^\s*(?:${idPat})(?:\.(?:skip|only|fixme))?\s*\.each\s*` + '`');
+    // test.each([...])('title', fn) — function call form start detection
+    const eachFnStartRe = new RegExp(String.raw `^\s*(?:${idPat})(?:\.(?:skip|only|fixme))?\s*\.each\s*\(`);
+    // Closing of test.each data followed by title: ])('title') or ])(  or })('title')
+    const eachFnClosingRe = /^[\s\]})]*\)\s*\(\s*(['"`])(.*?)\1/;
+    let braceDepthAtDescribe = [];
+    let braceDepth = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const lineNum = i + 1;
+        // Use stripped line for brace counting to avoid corruption from string literals
+        const stripped = stripStringLiterals(line);
+        const openBraces = (stripped.match(/\{/g) ?? []).length;
+        const closeBraces = (stripped.match(/\}/g) ?? []).length;
+        const describeMatch = describeRe.exec(line);
+        if (describeMatch) {
+            describeStack.push(describeMatch[2]);
+            braceDepthAtDescribe.push(braceDepth + openBraces - closeBraces);
+        }
+        const testMatch = testRe.exec(line);
+        if (testMatch) {
+            const name = testMatch[2];
+            tests.push({
+                name,
+                normalizedName: normalizeName(name),
+                filePath,
+                lineNumber: lineNum,
+                describeBlock: describeStack.length > 0 ? describeStack.join(' > ') : undefined,
+                framework,
+                dynamic: isDynamic(name),
+            });
+        }
+        // test.each tagged template literal: test.each`...`('title %s', fn)
+        if (eachTaggedRe.test(line)) {
+            // Scan forward to find the closing backtick then the title call
+            for (let j = i + 1; j < Math.min(i + 20, lines.length); j++) {
+                const nextLine = lines[j];
+                if (/^\s*`/.test(nextLine)) {
+                    // Next line after backtick-close may have (' title', fn) or be on same line
+                    const afterClose = nextLine.split('`').pop() ?? '';
+                    const titleMatch = /\(\s*(['"`])(.*?)\1/.exec(afterClose);
+                    if (titleMatch) {
+                        tests.push({
+                            name: titleMatch[2],
+                            normalizedName: normalizeName(titleMatch[2]),
+                            filePath,
+                            lineNumber: j + 1,
+                            describeBlock: describeStack.length > 0 ? describeStack.join(' > ') : undefined,
+                            framework,
+                            dynamic: isDynamic(titleMatch[2]),
+                        });
+                    }
+                    else {
+                        // Title on the line after the backtick-close
+                        const nextNext = lines[j + 1] ?? '';
+                        const titleMatch2 = /^\s*\(\s*(['"`])(.*?)\1/.exec(nextNext);
+                        if (titleMatch2) {
+                            tests.push({
+                                name: titleMatch2[2],
+                                normalizedName: normalizeName(titleMatch2[2]),
+                                filePath,
+                                lineNumber: j + 2,
+                                describeBlock: describeStack.length > 0 ? describeStack.join(' > ') : undefined,
+                                framework,
+                                dynamic: isDynamic(titleMatch2[2]),
+                            });
+                        }
+                    }
+                    break;
+                }
+            }
+        }
+        // test.each([...])('title', fn) — function call form, data spans multiple lines
+        // Detect the opening `test.each(` and scan forward for the closing `])('title'`
+        if (eachFnStartRe.test(line)) {
+            // Check same line first: test.each([data])('title', fn)
+            const sameLineMatch = /\)\s*\(\s*(['"`])(.*?)\1/.exec(line.replace(/^[^(]*\(/, ''));
+            if (sameLineMatch) {
+                tests.push({
+                    name: sameLineMatch[2],
+                    normalizedName: normalizeName(sameLineMatch[2]),
+                    filePath,
+                    lineNumber: lineNum,
+                    describeBlock: describeStack.length > 0 ? describeStack.join(' > ') : undefined,
+                    framework,
+                    dynamic: isDynamic(sameLineMatch[2]),
+                });
+            }
+            else {
+                // Multi-line: scan forward for the closing title call
+                for (let j = i + 1; j < Math.min(i + 30, lines.length); j++) {
+                    const closingMatch = eachFnClosingRe.exec(lines[j]);
+                    if (closingMatch) {
+                        tests.push({
+                            name: closingMatch[2],
+                            normalizedName: normalizeName(closingMatch[2]),
+                            filePath,
+                            lineNumber: j + 1,
+                            describeBlock: describeStack.length > 0 ? describeStack.join(' > ') : undefined,
+                            framework,
+                            dynamic: isDynamic(closingMatch[2]),
+                        });
+                        break;
+                    }
+                    // Stop scanning if we hit another test definition
+                    if (testRe.test(lines[j]) || describeRe.test(lines[j]))
+                        break;
+                }
+            }
+        }
+        braceDepth += openBraces - closeBraces;
+        while (braceDepthAtDescribe.length > 0 &&
+            braceDepth <= braceDepthAtDescribe[braceDepthAtDescribe.length - 1]) {
+            braceDepthAtDescribe.pop();
+            describeStack.pop();
+        }
+    }
+    return tests;
+}
+function extractPytest(content, filePath) {
+    const tests = [];
+    const lines = content.split('\n');
+    // async def test_* also valid in pytest-asyncio
+    const testFnRe = /^(?:async\s+)?def\s+(test_\w+)\s*\(/;
+    const classRe = /^class\s+(\w+)\s*[:(]/;
+    const parametrizeRe = /@pytest\.mark\.parametrize\b/;
+    let currentClass;
+    let hasParametrize = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const lineNum = i + 1;
+        const classMatch = classRe.exec(line);
+        if (classMatch) {
+            currentClass = classMatch[1];
+            hasParametrize = false;
+            continue;
+        }
+        // Track @pytest.mark.parametrize decorator before function
+        if (parametrizeRe.test(line)) {
+            hasParametrize = true;
+            continue;
+        }
+        const testMatch = testFnRe.exec(line);
+        if (testMatch) {
+            const name = testMatch[1];
+            tests.push({
+                name,
+                normalizedName: normalizeName(name),
+                filePath,
+                lineNumber: lineNum,
+                describeBlock: currentClass,
+                framework: 'pytest',
+                dynamic: hasParametrize || isDynamic(name),
+            });
+            hasParametrize = false;
+        }
+        else if (!/^\s*@/.test(line) && !/^\s*$/.test(line) && !/^\s*#/.test(line)) {
+            // Non-decorator, non-blank, non-comment line resets parametrize flag
+            hasParametrize = false;
+        }
+    }
+    return tests;
+}
+function extractJUnit(content, filePath) {
+    const tests = [];
+    const lines = content.split('\n');
+    // JUnit 5: @Test, @ParameterizedTest, @RepeatedTest, @TestFactory; JUnit 4: @Test
+    const testAnnotRe = /@(?:Test|ParameterizedTest|RepeatedTest|TestFactory)\b/;
+    let nextIsTest = false;
+    // Track @Nested inner classes as describe blocks
+    const nestedStack = [];
+    let braceDepth = 0;
+    let braceDepthAtNested = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const lineNum = i + 1;
+        const stripped = stripStringLiterals(line);
+        braceDepth += (stripped.match(/\{/g) ?? []).length - (stripped.match(/\}/g) ?? []).length;
+        if (/@Nested\b/.test(line)) {
+            // The class name follows on next non-annotation line
+            for (let j = i + 1; j < Math.min(i + 4, lines.length); j++) {
+                const classMatch = /class\s+(\w+)/.exec(lines[j]);
+                if (classMatch) {
+                    nestedStack.push(classMatch[1]);
+                    braceDepthAtNested.push(braceDepth);
+                    break;
+                }
+            }
+        }
+        // Pop nested class stack when brace depth falls to pre-nested level
+        while (braceDepthAtNested.length > 0 && braceDepth < braceDepthAtNested[braceDepthAtNested.length - 1]) {
+            braceDepthAtNested.pop();
+            nestedStack.pop();
+        }
+        if (testAnnotRe.test(line)) {
+            nextIsTest = true;
+            continue;
+        }
+        if (nextIsTest) {
+            // Prefer @DisplayName("text") if it appeared on the previous 3 lines
+            let displayName;
+            for (let j = Math.max(0, i - 3); j < i; j++) {
+                const dm = /@DisplayName\s*\(\s*["']([^"']+)["']/.exec(lines[j]);
+                if (dm) {
+                    displayName = dm[1];
+                    break;
+                }
+            }
+            const methodMatch = /(?:public|protected|private|void|\s)+\s+(\w+)\s*\(/.exec(line);
+            if (methodMatch) {
+                const rawName = methodMatch[1];
+                const name = displayName ?? rawName;
+                tests.push({
+                    name,
+                    normalizedName: normalizeName(rawName),
+                    filePath,
+                    lineNumber: lineNum,
+                    describeBlock: nestedStack.length > 0 ? nestedStack.join(' > ') : undefined,
+                    framework: 'junit',
+                    dynamic: isDynamic(name),
+                });
+            }
+            nextIsTest = false;
+        }
+    }
+    return tests;
+}
+function extractGherkin(content, filePath) {
+    const tests = [];
+    const lines = content.split('\n');
+    const scenarioRe = /^\s*Scenario(?:\s+Outline)?:\s*(.+)$/;
+    const featureRe = /^\s*Feature:\s*(.+)$/;
+    // Gherkin v6+: Rule: groups scenarios within a feature
+    const ruleRe = /^\s*Rule:\s*(.+)$/;
+    const tagRe = /^\s*(@\S+(?:\s+@\S+)*)\s*$/;
+    let featureName;
+    let ruleName;
+    let pendingTags;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const lineNum = i + 1;
+        const featureMatch = featureRe.exec(line);
+        if (featureMatch) {
+            featureName = featureMatch[1].trim();
+            ruleName = undefined;
+            continue;
+        }
+        const ruleMatch = ruleRe.exec(line);
+        if (ruleMatch) {
+            ruleName = ruleMatch[1].trim();
+            continue;
+        }
+        const tagMatch = tagRe.exec(line);
+        if (tagMatch) {
+            pendingTags = tagMatch[1].trim();
+            continue;
+        }
+        const scenarioMatch = scenarioRe.exec(line);
+        if (scenarioMatch) {
+            const name = scenarioMatch[1].trim();
+            const describeBlock = ruleName
+                ? `${featureName ?? ''} > ${ruleName}`.trim()
+                : featureName;
+            tests.push({
+                name,
+                normalizedName: normalizeName(name),
+                filePath,
+                lineNumber: lineNum,
+                describeBlock,
+                framework: 'cucumber',
+                dynamic: isDynamic(name),
+            });
+            pendingTags = undefined;
+            continue;
+        }
+        // Non-tag, non-scenario line clears pending tags
+        if (!/^\s*$/.test(line) && !tagMatch) {
+            pendingTags = undefined;
+        }
+    }
+    return tests;
+}
+function extractTestIds(content, filePath, framework, extraAliases) {
+    if (framework === 'pytest') {
+        return extractPytest(content, filePath);
+    }
+    if (framework === 'junit') {
+        return extractJUnit(content, filePath);
+    }
+    if (framework === 'cucumber') {
+        return extractGherkin(content, filePath);
+    }
+    // playwright-ts, playwright-js, cypress-ts, cypress-js, jest-ts, jest-js, webdriverio
+    return extractJestLike(content, filePath, framework, extraAliases);
+}
+// ---------------------------------------------------------------------------
+// Style profile extraction
+// ---------------------------------------------------------------------------
+function extractImportLines(content, max = 10) {
+    const importRe = /^(?:import|from)\s+.+$/gm;
+    const matches = content.match(importRe) ?? [];
+    return matches.slice(0, max);
+}
+function extractPatternExample(content, re) {
+    const match = re.exec(content);
+    if (!match)
+        return '';
+    // Return the matched block trimmed to a reasonable length
+    return match[0].trim().slice(0, 200);
+}
+function detectDirFileStem(allPaths, dir) {
+    if (!dir)
+        return '';
+    const prefix = dir.replace(/\/?$/, '/');
+    const files = allPaths
+        .filter(p => p.startsWith(prefix) && !p.slice(prefix.length).includes('/'))
+        .map(p => p.split('/').pop())
+        .filter(f => /\.(ts|js|py|java|kt|json)$/.test(f) && !f.startsWith('index.') && !f.startsWith('_'))
+        .slice(0, 8);
+    if (files.length === 0)
+        return '';
+    const isPascal = /^[A-Z]/.test(files[0]);
+    const caseToken = isPascal ? '{PascalCase}' : '{camelCase}';
+    // Multi-part extension like .fixture.ts or .spec.ts
+    const fullExt = files[0].match(/(?:\.[a-z]+){1,2}$/)?.[0] ?? '';
+    const withoutExt = files.map(f => f.replace(/(?:\.[a-z]+){1,2}$/, ''));
+    const KNOWN_SUFFIXES = ['Page', 'Locators', 'Locator', 'TestData', 'Data', 'Actions', 'Assertions', 'Helper', 'Utils', 'Constants', 'Steps', 'Helpers'];
+    let suffix = '';
+    for (const s of KNOWN_SUFFIXES) {
+        if (withoutExt.filter(f => f.endsWith(s)).length > 0) {
+            suffix = s;
+            break;
+        }
+    }
+    return `${caseToken}${suffix}${fullExt}`;
+}
+function detectFolderPattern(paths) {
+    if (paths.length === 0)
+        return '';
+    // For Java repos: prefer actual test class files (*Test.java/*Tests.java),
+    // deprioritize utility/helper dirs which appear first alphabetically.
+    const helperDirRe = /\/(helper|util|utils|base|common|shared)\//;
+    const javaTestRe = /[A-Z]\w*Tests?\.java$/;
+    const javaTestFiles = paths.filter((p) => javaTestRe.test(p));
+    const preferred = javaTestFiles.filter((p) => !helperDirRe.test(p));
+    const candidate = preferred[0] ?? javaTestFiles[0] ?? paths[0];
+    const parts = candidate.split('/');
+    if (parts.length >= 2) {
+        const prefix = parts.slice(0, -1).join('/');
+        const filename = parts[parts.length - 1];
+        const ext = filename.includes('.') ? filename.slice(filename.lastIndexOf('.')) : '';
+        return `${prefix}/{feature}${ext}`;
+    }
+    return candidate;
+}
+function detectNamingPattern(paths) {
+    if (paths.length === 0)
+        return '';
+    const filenames = paths.map((p) => p.split('/').pop() ?? p);
+    const javaCount = filenames.filter((f) => f.endsWith('.java')).length;
+    const kotlinCount = filenames.filter((f) => f.endsWith('.kt')).length;
+    if (kotlinCount > javaCount && kotlinCount > 0)
+        return '{PascalCase}Test.kt';
+    if (javaCount > 0)
+        return '{PascalCase}Test.java';
+    const specCount = filenames.filter((f) => f.includes('.spec.')).length;
+    const cyCount = filenames.filter((f) => f.includes('.cy.')).length;
+    const testCount = filenames.filter((f) => f.includes('.test.')).length;
+    const e2eCount = filenames.filter((f) => f.includes('.e2e.')).length;
+    const intCount = filenames.filter((f) => f.includes('.integration.')).length;
+    const smokeCount = filenames.filter((f) => f.includes('.smoke.')).length;
+    const featureCount = filenames.filter((f) => f.endsWith('.feature')).length;
+    const pyTestSuffix = filenames.filter((f) => f.endsWith('_test.py')).length;
+    const pyTestPrefix = filenames.filter((f) => /^test_/.test(f)).length;
+    const rbSpecCount = filenames.filter((f) => f.endsWith('_spec.rb')).length;
+    const stepsCount = filenames.filter((f) => f.includes('.steps.')).length;
+    if (featureCount > 0)
+        return '{kebab-feature}.feature';
+    if (pyTestSuffix > 0)
+        return '{snake_feature}_test.py';
+    if (pyTestPrefix > 0)
+        return 'test_{snake_feature}.py';
+    if (rbSpecCount > 0)
+        return '{snake_feature}_spec.rb';
+    // Prefer most-used TS/JS suffix; spec > cy > test > e2e > integration > smoke
+    const tsxCount = filenames.filter((f) => f.includes('.test.tsx') || f.includes('.spec.tsx')).length;
+    const isTsx = tsxCount > Math.max(specCount, testCount) / 2;
+    const ext = isTsx ? 'tsx' : 'ts';
+    if (cyCount > 0 && cyCount >= specCount)
+        return `{kebab-feature}.cy.${ext}`;
+    if (stepsCount > 0)
+        return `{kebab-feature}.steps.${ext}`;
+    if (e2eCount > 0 && e2eCount >= testCount)
+        return `{kebab-feature}.e2e.${ext}`;
+    if (intCount > 0 && intCount >= testCount)
+        return `{kebab-feature}.integration.${ext}`;
+    if (smokeCount > 0 && smokeCount >= testCount)
+        return `{kebab-feature}.smoke.${ext}`;
+    if (specCount >= testCount)
+        return `{kebab-feature}.spec.${ext}`;
+    return `{kebab-feature}.test.${ext}`;
+}
+async function extractStyleProfile(sampleFiles, framework, language, tenantId, projectId, jobId, 
+/** Filtered code paths (test + source files) — used by LLM for convention/structure analysis */
+allPaths, 
+/**
+ * Full repo tree paths (unfiltered) — used ONLY by heuristic detectDataDirs() so that
+ * testdata/*.json, fixtures/*.yaml, locators/ etc. are visible even when they contain no .ts files.
+ * When omitted, falls back to allPaths (same behaviour as before).
+ */
+fullTreePaths) {
+    if (sampleFiles.length === 0) {
+        return {
+            framework,
+            language,
+            importLines: [],
+            describePattern: '',
+            beforeEachPattern: '',
+            pageObjectPattern: '',
+            conventions: '',
+            folderPattern: '',
+            namingPattern: '',
+        };
+    }
+    // Pick up to 5 samples from different directories for pattern diversity
+    function pickDiverseSamples(files, n) {
+        if (files.length <= n)
+            return files;
+        const seenDir = new Set();
+        const picked = [];
+        for (const f of files) {
+            const dir = f.path.includes('/') ? f.path.split('/').slice(0, -2).join('/') : '';
+            if (!seenDir.has(dir) && picked.length < n) {
+                seenDir.add(dir);
+                picked.push(f);
+            }
+        }
+        for (const f of files) {
+            if (picked.length >= n)
+                break;
+            if (!picked.includes(f))
+                picked.push(f);
+        }
+        return picked;
+    }
+    const primary = sampleFiles[0];
+    const diverseSamples = pickDiverseSamples(sampleFiles, 5);
+    const allContent = diverseSamples
+        .map((f) => `// File: ${f.path}\n${f.content.slice(0, 1500)}`)
+        .join('\n\n---\n\n');
+    const importLines = extractImportLines(primary.content);
+    const describePattern = extractPatternExample(primary.content, /describe\s*\([^)]*\)\s*\{[^}]{0,300}/s);
+    const beforeEachPattern = extractPatternExample(primary.content, /beforeEach\s*\([^)]*\)\s*\{[^}]{0,300}/s);
+    // Detect page object usage pattern — try constructor first, then functional factory, then static methods
+    const pageObjectPattern = extractPatternExample(primary.content, /new\s+\w+(?:Page|Component|Screen|Helper)\s*\([^\n]{0,150}/) ||
+        extractPatternExample(primary.content, /(?:const|let)\s+\w+\s*=\s*(?:await\s+)?\w+(?:Page|Component|Screen|Helper)\s*\([^\n]{0,150}/) ||
+        extractPatternExample(primary.content, /\w+(?:Page|Component|Screen|Helper)\.\w+\s*\(page[^\n]{0,120}/) ||
+        extractPatternExample(primary.content, /export\s+(?:const|function|async\s+function)\s+\w+(?:Page|Component|Screen|Helper)\s*\([^\n]{0,120}/) ||
+        '';
+    // Heuristic fallbacks (used when LLM call fails)
+    const paths = allPaths ?? sampleFiles.map((f) => f.path);
+    let folderPattern = detectFolderPattern(paths);
+    let namingPattern = detectNamingPattern(paths);
+    let conventions = '';
+    let llmBasePackage = null;
+    let llmJavaRoot = null;
+    let llmTestStructurePattern = null;
+    let llmTestLayers = null;
+    let llmPageObjectLocation = null;
+    let llmTestLocation = null;
+    let llmBasePageClass = null;
+    let llmDriverClass = null;
+    let llmTestDataDir = undefined;
+    let llmFixtureDir = undefined;
+    let llmLocatorsDir = undefined;
+    let llmComponentDir = null;
+    let llmTestSubDirs = null;
+    let llmIsTestFixtureModule = null;
+    // Heuristic detection before LLM — runs on FULL tree so testdata/*.json, fixtures/*.yaml are visible.
+    // fullTreePaths may contain all file extensions; detectDataDirs uses pattern matching on path strings only.
+    const { testDataDir: detectedTestDataDir, fixtureDir: detectedFixtureDir, locatorsDir: detectedLocatorsDir, utilsDir: detectedUtilsDir, configDir: detectedConfigDir } = detectDataDirs(fullTreePaths ?? paths);
+    try {
+        const llmCfg = await (0, llm_config_js_1.getTaskAgentLLMConfig)(tenantId, 'testGeneration');
+        // Send up to 300 code paths — test files first, then source files
+        const isTestP = (p) => /\.(spec|test|e2e|cy|steps|feature)\./i.test(p) || /(?:_test|Test)\.(py|java|kt)$/.test(p) || /^test_/.test(p.split('/').pop() ?? '');
+        const testPathsSorted = paths.filter(isTestP);
+        const nonTestPaths = paths.filter(p => !isTestP(p));
+        // Also include unique top-level directories from full tree so LLM can infer data/fixture/locator dirs
+        // even when those dirs contain only JSON/YAML/CSV (non-code) files
+        const fullTree = fullTreePaths ?? paths;
+        const extraDirs = [...new Set(fullTree
+                .filter(p => !p.includes('node_modules/') && !p.startsWith('.') && p.includes('/'))
+                .map(p => {
+                const parts = p.split('/');
+                return parts.length >= 3 ? parts.slice(0, 2).join('/') : parts[0];
+            }))].slice(0, 120).map(d => `${d}/`); // format as dir hint
+        // Include heuristic-detected dirs (config/utils/locators) so they always reach the LLM
+        // even when those dirs contain only non-code files (JSON/YAML) excluded from the paths array.
+        const detectedDirHints = [
+            detectedConfigDir, detectedUtilsDir, detectedLocatorsDir,
+            detectedTestDataDir, detectedFixtureDir,
+        ].filter((d) => d !== null && d !== undefined)
+            .map(d => (d.endsWith('/') ? d : `${d}/`));
+        const pathList = [
+            ...testPathsSorted.slice(0, 200),
+            ...nonTestPaths.slice(0, 100),
+            '', '# All top-level dirs:', ...extraDirs,
+            ...(detectedDirHints.length > 0 ? ['', '# Framework dirs detected by heuristic (config/utils/locators):', ...detectedDirHints] : []),
+        ].join('\n');
+        const systemPrompt = `You are a test repository structure analyst. Given ${framework} (${language}) test file paths and sample content, return ONLY a JSON object — no markdown, no explanation.
+
+Fields to return:
+
+"javaRoot": Java only — the source root directory for test files (e.g. "src/test/java", "src/main/java"). Leave empty string for non-Java.
+
+"basePackage": package/module root under javaRoot:
+- Java: dot-separated (e.g. "tests", "com.company.qa")
+- TypeScript/JavaScript: root test directory (e.g. "tests", "e2e")
+- Python: dot-separated module (e.g. "tests")
+- Ruby: spec root (e.g. "spec")
+- C#: namespace root (e.g. "Company.Tests")
+
+"testStructurePattern": how the repo organises tests (choose one):
+- "flat": single test class per feature, no separation of page objects
+- "two-tier": page objects in one location, test classes in another
+- "zeta-v2": already uses Zeta v2 layers (locators + pages + actions + assertions + testdata + smoke subfolders)
+- "custom": multi-layer but different names
+
+"testLayers": array of subdirectory layer names actually found in this repo (e.g. [] for flat, ["pages"] for two-tier, ["locators","pages","actions","assertions","testdata"] for zeta-v2)
+
+"pageObjectLocation": where TEST AUTOMATION page object classes ACTUALLY EXIST relative to repo root. IMPORTANT: if both a 'pages/' or 'src/pages/' directory AND a 'src/components/' or 'components/' directory exist, use 'pages/'/'src/pages/' for pageObjectLocation — 'src/components/' holds UI framework components (React/Vue/Angular), NOT test page objects. For Java test repos, page objects almost always live in src/test/java (e.g. "src/test/java/pages") NOT src/main/java. Empty if flat.
+"componentDir": if the repo has a SEPARATE UI components directory distinct from pageObjectLocation (e.g. "src/components" for React components). Empty string if none or same as pageObjectLocation. This should be the React/Vue/Angular component folder, NOT the test page objects folder.
+"testLocation": where test runner classes ACTUALLY EXIST relative to repo root (e.g. "tests", "tests/ui", "src/test/java/tests").
+"testSubDirs": if tests are split into multiple subdirectories by type, list them (e.g. ["tests/ui","tests/api"]). Empty array if single directory.
+"basePageClass": repo's base class name for page objects (e.g. "Page", "BasePage"). Empty if none.
+"driverClass": repo's driver/browser factory class name (e.g. "Browser", "DriverFactory"). Empty if none.
+
+"testDataDir": directory where test data files live (e.g. "src/data/", "testdata/", "data/", "src/test/resources/"). Set to null if no such directory.
+"fixtureDir": directory where fixture/data files live (e.g. "src/fixtures/", "fixtures/", "cypress/fixtures/"). May be same as testDataDir. Set to null if none.
+"isTestFixtureModule": true ONLY if fixtureDir contains TypeScript/JavaScript files that export an extended test object (Playwright fixtures, not static JSON/CSV data). false otherwise.
+"locatorsDir": directory where locator/selector constant files live (e.g. "locators/", "selectors/", "src/locators/"). Set to null if none.
+
+"folderPattern": full template path for a new test file using {feature} placeholder (e.g. "src/test/java/tests/{feature}/{Feature}Tests.java")
+"namingPattern": file naming template (e.g. "{PascalCase}Tests.java", "{kebab}.spec.ts")
+"conventions": exactly 5 bullet points about coding style, naming, patterns`;
+        const shownCount = Math.min(300, testPathsSorted.length + nonTestPaths.length);
+        const userPrompt = `Test file paths (${paths.length} total, showing ${shownCount} — test files first):
+${pathList}
+
+Sample file content:
+${allContent}
+
+Return JSON: {"javaRoot":"...","basePackage":"...","testStructurePattern":"...","testLayers":[...],"pageObjectLocation":"...","componentDir":"...","testLocation":"...","testSubDirs":[...],"basePageClass":"...","driverClass":"...","testDataDir":"...or null","fixtureDir":"...or null","isTestFixtureModule":false,"locatorsDir":"...or null","folderPattern":"...","namingPattern":"...","conventions":"..."}`;
+        const t0 = Date.now();
+        const seed = (0, llm_js_1.deterministicSeed)(`${tenantId}:${projectId ?? ''}:repo-scan:${framework}:${paths.slice(0, 20).join('|').slice(0, 400)}`);
+        const effectiveSystemPrompt = await (0, core_1.getAgentPrompt)('repo-scan-style', undefined, tenantId) ?? systemPrompt;
+        const result = await (0, llm_js_1.askTracked)(effectiveSystemPrompt, userPrompt, llmCfg, undefined, undefined, { temperature: 0, seed });
+        if (projectId) {
+            (0, app_brain_1.recordLLMCall)({
+                tenantId,
+                projectId,
+                agentType: 'repo_scan',
+                label: `style_profile_${framework}`,
+                jobId,
+                usage: result.usage,
+                latencyMs: Date.now() - t0,
+            }).catch(() => { });
+        }
+        // Strip markdown code fences before attempting JSON extraction
+        const cleanText = result.text.replace(/^```[\w-]*\s*/m, '').replace(/\s*```\s*$/m, '');
+        const jsonMatch = cleanText.match(/\{[\s\S]*\}/);
+        function applyLLMProfile(parsed) {
+            if (parsed.conventions)
+                conventions = parsed.conventions;
+            if (parsed.folderPattern)
+                folderPattern = parsed.folderPattern;
+            if (parsed.namingPattern)
+                namingPattern = parsed.namingPattern;
+            if (parsed.basePackage)
+                llmBasePackage = parsed.basePackage;
+            if (parsed.javaRoot)
+                llmJavaRoot = parsed.javaRoot;
+            if (parsed.testStructurePattern && ['flat', 'two-tier', 'zeta-v2', 'custom'].includes(parsed.testStructurePattern)) {
+                llmTestStructurePattern = parsed.testStructurePattern;
+            }
+            if (Array.isArray(parsed.testLayers))
+                llmTestLayers = parsed.testLayers;
+            if (parsed.componentDir)
+                llmComponentDir = parsed.componentDir;
+            // Reject pageObjectLocation if it resolves to the same path as componentDir —
+            // LLM sometimes picks src/components/ (UI framework dir) instead of src/pages/ (test PO dir)
+            if (parsed.pageObjectLocation) {
+                const poNorm = parsed.pageObjectLocation.replace(/\/$/, '');
+                const compNorm = (parsed.componentDir ?? '').replace(/\/$/, '');
+                if (!compNorm || poNorm !== compNorm) {
+                    llmPageObjectLocation = parsed.pageObjectLocation;
+                }
+            }
+            if (parsed.testLocation)
+                llmTestLocation = parsed.testLocation;
+            if (Array.isArray(parsed.testSubDirs) && parsed.testSubDirs.length > 0)
+                llmTestSubDirs = parsed.testSubDirs;
+            if (parsed.basePageClass)
+                llmBasePageClass = parsed.basePageClass;
+            if (parsed.driverClass)
+                llmDriverClass = parsed.driverClass;
+            if ('testDataDir' in parsed)
+                llmTestDataDir = parsed.testDataDir ?? null;
+            if ('fixtureDir' in parsed)
+                llmFixtureDir = parsed.fixtureDir ?? null;
+            if (typeof parsed.isTestFixtureModule === 'boolean')
+                llmIsTestFixtureModule = parsed.isTestFixtureModule;
+            if ('locatorsDir' in parsed)
+                llmLocatorsDir = parsed.locatorsDir ?? null;
+        }
+        let parsed = null;
+        if (jsonMatch) {
+            try {
+                parsed = JSON.parse(jsonMatch[0]);
+            }
+            catch { /* fall through to retry */ }
+        }
+        if (!parsed) {
+            // Retry once with a stripped prompt asking only for JSON
+            try {
+                const retryResult = await (0, llm_js_1.askTracked)('Return ONLY valid JSON. No markdown, no explanation.', `Convert this to valid JSON matching the schema from the previous request:\n${result.text.slice(0, 2000)}`, llmCfg, undefined, undefined, { temperature: 0, seed });
+                const retryClean = retryResult.text.replace(/^```[\w-]*\s*/m, '').replace(/\s*```\s*$/m, '');
+                const retryMatch = retryClean.match(/\{[\s\S]*\}/);
+                if (retryMatch) {
+                    try {
+                        parsed = JSON.parse(retryMatch[0]);
+                    }
+                    catch { /* ignore */ }
+                }
+            }
+            catch { /* ignore retry failure */ }
+        }
+        if (parsed) {
+            applyLLMProfile(parsed);
+        }
+        else if (!jsonMatch) {
+            // LLM returned plain text — treat as conventions
+            conventions = result.text;
+        }
+    }
+    catch {
+        conventions = '';
+    }
+    // basePackage from LLM takes priority; fallback to regex heuristic for Java
+    const javaBasePackage = llmBasePackage ?? deriveJavaBasePackage(folderPattern, sampleFiles.map((f) => f.path));
+    // Heuristic path detection wins over LLM when found in actual repo paths
+    const resolvedTestDataDir = detectedTestDataDir ?? (llmTestDataDir !== undefined ? llmTestDataDir : undefined);
+    const resolvedFixtureDir = detectedFixtureDir ?? (llmFixtureDir !== undefined ? llmFixtureDir : undefined);
+    // locatorsDir: heuristic wins; LLM fills gap when heuristic found nothing
+    const resolvedLocatorsDir = detectedLocatorsDir !== null
+        ? detectedLocatorsDir
+        : (llmLocatorsDir !== undefined ? (llmLocatorsDir ?? undefined) : undefined);
+    // utilsDir: heuristic only — no LLM inference needed
+    const resolvedUtilsDir = detectedUtilsDir !== null ? detectedUtilsDir : undefined;
+    const resolvedConfigDir = detectedConfigDir !== null ? detectedConfigDir : undefined;
+    // Detect isTestFixtureModule from heuristic: fixtureDir path contains a .ts or .js file
+    const heuristicIsFixtureModule = resolvedFixtureDir
+        ? paths.some(p => p.startsWith(resolvedFixtureDir) && /\.(ts|js)$/.test(p))
+        : false;
+    const resolvedIsTestFixtureModule = llmIsTestFixtureModule ?? heuristicIsFixtureModule;
+    // Per-directory file naming stems (heuristic from actual file paths in each dir)
+    const treePaths = fullTreePaths ?? paths;
+    const pageFileStem = detectDirFileStem(treePaths, llmPageObjectLocation);
+    const locatorFileStem = detectDirFileStem(treePaths, resolvedLocatorsDir);
+    const testDataFileStem = detectDirFileStem(treePaths, resolvedTestDataDir);
+    const fixtureFileStem = detectDirFileStem(treePaths, resolvedFixtureDir);
+    // Detect actual base page file location from repo tree
+    const _scanTree = fullTreePaths ?? paths;
+    const _basePageFile = _scanTree.find(p => /(?:^|\/)(?:base\.page|BasePage|base_page)\.(ts|js|py|java|kt)$/.test(p) &&
+        !p.includes('node_modules/') && !p.includes('.next/'));
+    let _detectedBasePageImport;
+    if (_basePageFile && llmPageObjectLocation && typeof llmPageObjectLocation === 'string') {
+        // Compute relative import from pageObjectDir to base page file (without extension)
+        const _from = llmPageObjectLocation.replace(/\/$/, '').split('/');
+        const _to = _basePageFile.replace(/\.(ts|js|py|java|kt)$/, '').split('/');
+        let _i = 0;
+        while (_i < _from.length && _i < _to.length && _from[_i] === _to[_i])
+            _i++;
+        const _ups = Array(_from.length - _i).fill('..');
+        const _rel = [..._ups, ..._to.slice(_i)].join('/');
+        _detectedBasePageImport = _rel.startsWith('.') ? _rel : `./${_rel}`;
+    }
+    return {
+        framework,
+        language,
+        importLines,
+        describePattern,
+        beforeEachPattern,
+        pageObjectPattern,
+        conventions,
+        folderPattern,
+        namingPattern,
+        ...(javaBasePackage ? { javaBasePackage } : {}),
+        ...(llmJavaRoot ? { javaRoot: llmJavaRoot } : {}),
+        ...(llmTestStructurePattern ? { testStructurePattern: llmTestStructurePattern } : {}),
+        ...(llmTestLayers ? { testLayers: llmTestLayers } : {}),
+        ...(llmPageObjectLocation ? { pageObjectLocation: llmPageObjectLocation } : {}),
+        ...(llmComponentDir ? { componentDir: llmComponentDir } : {}),
+        ...(llmTestLocation ? { testLocation: llmTestLocation } : {}),
+        ...(llmTestSubDirs ? { testSubDirs: llmTestSubDirs } : {}),
+        ...(llmBasePageClass ? { basePageClass: llmBasePageClass } : {}),
+        ...(_detectedBasePageImport ? { basePageImport: _detectedBasePageImport } : {}),
+        ...(llmDriverClass ? { driverClass: llmDriverClass } : {}),
+        ...(resolvedTestDataDir !== undefined ? { testDataDir: resolvedTestDataDir } : {}),
+        ...(resolvedFixtureDir !== undefined ? { fixtureDir: resolvedFixtureDir } : {}),
+        ...(resolvedIsTestFixtureModule ? { isTestFixtureModule: true } : {}),
+        ...(resolvedLocatorsDir !== undefined ? { locatorsDir: resolvedLocatorsDir } : {}),
+        ...(resolvedUtilsDir !== undefined ? { utilsDir: resolvedUtilsDir } : {}),
+        ...(resolvedConfigDir !== undefined ? { configDir: resolvedConfigDir } : {}),
+        ...(pageFileStem ? { pageFileStem } : {}),
+        ...(locatorFileStem ? { locatorFileStem } : {}),
+        ...(testDataFileStem ? { testDataFileStem } : {}),
+        ...(fixtureFileStem ? { fixtureFileStem } : {}),
+    };
+}
+/**
+ * Extract Java base package from folder pattern or file paths.
+ * e.g. "src/test/java/com/crm/qa/testc/{feature}Test.java" → "com.crm.qa"
+ */
+function deriveJavaBasePackage(folderPattern, filePaths) {
+    const paths = [folderPattern, ...(filePaths ?? [])].filter(Boolean);
+    for (const p of paths) {
+        const m = p.match(/src\/(?:test|main)\/java\/(.+?)(?:\/[^/]*\{[^}]*\}|\/[A-Z][^/]*\.java|\/?$)/);
+        if (m && m[1]) {
+            // Convert path to package, drop last segment if it looks feature-specific
+            const parts = m[1].replace(/\/$/, '').split('/').filter(Boolean);
+            // A segment is "feature-specific" if it looks like a feature folder (not a standard package segment)
+            // Heuristic: if the last part is a short word matching the test class name pattern, drop it
+            const pkg = parts.join('.');
+            if (pkg && pkg.includes('.'))
+                return pkg;
+            if (pkg)
+                return pkg;
+        }
+    }
+    return null;
+}
+/**
+ * Extract public methods from a TypeScript/JavaScript class.
+ * Simple regex-based — good enough for generating import hints.
+ */
+function extractTSClassMethods(content) {
+    const classMatch = content.match(/(?:export\s+)?(?:default\s+)?class\s+(\w+)/);
+    const className = classMatch?.[1] ?? 'UnknownPage';
+    const methods = [];
+    const seen = new Set();
+    // Regular methods (sync + async, public + no modifier)
+    const methodRe = /(?:async\s+)?(?:public\s+)?(?!private|protected|static|constructor|get\s|set\s)(\w+)\s*\(([^)]*)\)\s*(?::\s*([^{;]+?))?\s*\{/g;
+    let m;
+    while ((m = methodRe.exec(content)) !== null) {
+        const name = m[1];
+        if (['if', 'for', 'while', 'switch', 'catch'].includes(name))
+            continue;
+        if (seen.has(name))
+            continue;
+        seen.add(name);
+        methods.push({ name, params: (m[2] ?? '').trim().slice(0, 80), returnType: (m[3] ?? 'void').trim().slice(0, 40) });
+    }
+    // Arrow function class fields: `name = () =>` or `name = async () =>`
+    const arrowRe = /(?:public\s+)?(\w+)\s*=\s*(?:async\s+)?\(([^)]*)\)\s*(?::\s*([^=>{]+?))?\s*=>/g;
+    while ((m = arrowRe.exec(content)) !== null) {
+        const name = m[1];
+        if (['constructor', 'if', 'for'].includes(name) || seen.has(name))
+            continue;
+        seen.add(name);
+        methods.push({ name, params: (m[2] ?? '').trim().slice(0, 80), returnType: (m[3] ?? 'void').trim().slice(0, 40) });
+    }
+    // Getter methods: `get name()`
+    const getterRe = /(?:public\s+)?get\s+(\w+)\s*\(\s*\)\s*(?::\s*([^{]+?))?\s*\{/g;
+    while ((m = getterRe.exec(content)) !== null) {
+        const name = `get_${m[1]}`;
+        if (seen.has(name))
+            continue;
+        seen.add(name);
+        methods.push({ name, params: '', returnType: (m[2] ?? 'unknown').trim().slice(0, 40) });
+    }
+    return { className, methods };
+}
+/**
+ * Extract public methods from a Python class.
+ */
+function extractPyClassMethods(content) {
+    const methods = [];
+    const seen = new Set();
+    const lines = content.split('\n');
+    let pendingDecorator = '';
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+        // Track last decorator before def
+        if (line.startsWith('@')) {
+            pendingDecorator = line;
+            continue;
+        }
+        // Instance method: def name(self, ...)
+        const instM = line.match(/^def\s+([a-z_]\w*)\s*\(self(?:,\s*([^)]*))?\)\s*(?:->\s*([^:]+))?:/);
+        if (instM) {
+            const name = instM[1];
+            if (!name.startsWith('__') && !seen.has(name)) {
+                seen.add(name);
+                const isProp = pendingDecorator.includes('@property');
+                methods.push({ name: isProp ? `get_${name}` : name, params: (instM[2] ?? '').trim().slice(0, 80), returnType: (instM[3] ?? 'None').trim().slice(0, 40) });
+            }
+            pendingDecorator = '';
+            continue;
+        }
+        // Static/class method: def name(cls, ...) or def name(...)
+        const staticM = line.match(/^def\s+([a-z_]\w*)\s*\((?:cls|(?![a-z]))[^)]*\)\s*(?:->\s*([^:]+))?:/);
+        if (staticM && (pendingDecorator.includes('@staticmethod') || pendingDecorator.includes('@classmethod'))) {
+            const name = staticM[1];
+            if (!name.startsWith('_') && !seen.has(name)) {
+                seen.add(name);
+                methods.push({ name, params: '', returnType: (staticM[2] ?? 'None').trim().slice(0, 40) });
+            }
+        }
+        pendingDecorator = '';
+    }
+    return methods;
+}
+function extractJavaClassMethods(content) {
+    const methods = [];
+    const seen = new Set();
+    // Identify test/lifecycle annotation positions so we can skip those methods
+    const testAnnotationRe = /@(?:Test|Before(?:Each|All)?|After(?:Each|All)?|BeforeMethod|AfterMethod|Given|When|Then|And|But)\b/g;
+    const testAnnotationPositions = new Set();
+    let am;
+    while ((am = testAnnotationRe.exec(content)) !== null) {
+        testAnnotationPositions.add(am.index);
+    }
+    // Match public and protected methods (not constructors, not main)
+    const methodRe = /(?:public|protected)\s+(?!class|static\s+void\s+main)(?:[\w<>\[\]]+\s+)?(\w+)\s*\(([^)]*)\)/g;
+    let m;
+    while ((m = methodRe.exec(content)) !== null) {
+        const name = m[1];
+        if (['if', 'for', 'while', 'switch', 'catch', 'new', 'return', 'throw'].includes(name))
+            continue;
+        if (seen.has(name))
+            continue;
+        // Skip if a test annotation appears within 150 chars before this method
+        const before = m.index;
+        const hasTestAnnotation = [...testAnnotationPositions].some(pos => pos >= before - 150 && pos < before);
+        if (hasTestAnnotation)
+            continue;
+        seen.add(name);
+        methods.push({ name, params: (m[2] ?? '').trim().slice(0, 80), returnType: '' });
+    }
+    return methods;
+}
+/**
+ * Detect whether a file looks like a Page Object (not a test file).
+ */
+function isPageObjectFile(filePath, content) {
+    const lower = filePath.toLowerCase();
+    // Path-based signal — common PO/component/helper directories across all frameworks
+    const PO_PATH_PATTERNS = [
+        /(?:^|\/)pages\//i,
+        /(?:^|\/)page-objects\//i,
+        /(?:^|\/)pageobjects\//i,
+        /(?:^|\/)pom\//i,
+        /(?:^|\/)components\//i,
+        /(?:^|\/)helpers?\//i,
+        /(?:^|\/)services\//i,
+        /(?:^|\/)actions\//i,
+        /(?:^|\/)locators?\//i,
+        /(?:^|\/)screens?\//i,
+        /(?:^|\/)fragments?\//i,
+        /(?:^|\/)step[_-]?definitions?\//i,
+        /(?:^|\/)support\//i,
+        /(?:^|\/)utils?\//i,
+        /(?:^|\/)utilities\//i,
+    ];
+    if (PO_PATH_PATTERNS.some(rx => rx.test(lower)))
+        return true;
+    // Name-based signal: any file named *Page.* or *Screen.* or *Component.*
+    if (/page\.(ts|js|py|java|kt)$/.test(lower) || /Page\.(ts|js|py|java|kt)$/.test(filePath))
+        return true;
+    if (/screen\.(ts|js|py|java|kt)$/.test(lower) || /Screen\.(ts|js|py|java|kt)$/.test(filePath))
+        return true;
+    // Content-based — when content is provided (second pass after fetch)
+    if (content) {
+        if (/class\s+\w+Page/.test(content) || /class\s+\w+PO/.test(content))
+            return true;
+        if (/class\s+\w+Component/.test(content) || /class\s+\w+Helper/.test(content))
+            return true;
+        if (/class\s+\w+Screen/.test(content) || /class\s+\w+Fragment/.test(content))
+            return true;
+        if (/class\s+\w+Actions?/.test(content) || /class\s+\w+Service/.test(content))
+            return true;
+        if (content.includes('@FindBy') || content.includes('@FindBys'))
+            return true;
+        // Python: class inherits BasePage or similar
+        if (/class\s+\w+\s*\(\s*\w*[Pp]age\w*\s*\)/.test(content))
+            return true;
+        // Playwright fixture: exports extended `test` object
+        if (/export\s+(?:const\s+)?test\s*=/.test(content) && content.includes('extend'))
+            return true;
+    }
+    return false;
+}
+/**
+ * Build the page object inventory from all non-test repo files.
+ * Pass up to 60 candidate files for efficiency.
+ */
+async function buildPageObjectInventory(token, repoFullName, allPaths, framework) {
+    const isPython = framework === 'pytest' || framework === 'selenium-py';
+    const isJava = framework === 'selenium-java' || framework === 'playwright-java';
+    const ext = isPython ? /\.(py)$/ : isJava ? /\.(java|kt)$/ : /\.(ts|js)$/;
+    const baseFilter = (p) => ext.test(p) && !p.includes('node_modules') && !p.includes('dist/') && !p.includes('.config.');
+    // Pass 1: path-based known PO directories — high confidence
+    const strictCandidates = allPaths.filter(baseFilter).filter((p) => isPageObjectFile(p, ''));
+    // Pass 2: any non-test source file for content-based detection (catches POs in unexpected dirs)
+    const isTestFile = (p) => /\.(spec|test|e2e|cy|steps|integration|smoke)\.(ts|js|py)$/.test(p)
+        || p.endsWith('.feature') || /Test(s)?\.java$/.test(p) || p.endsWith('_test.py') || /\/test_/.test(p);
+    const strictSet = new Set(strictCandidates);
+    // NOTE: for Java, page objects live under src/test/java/pages — do NOT filter /test/ for Java
+    const looseCandidates = allPaths
+        .filter(baseFilter)
+        .filter((p) => !strictSet.has(p) && !isTestFile(p) && (isJava || (!p.includes('/tests/') && !p.includes('/spec/'))))
+        .slice(0, 40);
+    const candidates = [...strictCandidates.slice(0, 110), ...looseCandidates];
+    const processCandidateBatch = async (batch) => {
+        const results = await Promise.all(batch.map(async (filePath) => {
+            try {
+                const content = await fetchFileContent(token, repoFullName, filePath);
+                if (!content || content.length < 50)
+                    return null;
+                if (!isPageObjectFile(filePath, content))
+                    return null;
+                let className = 'UnknownPage';
+                let methods = [];
+                if (isPython) {
+                    const cm = content.match(/class\s+(\w+)/);
+                    className = cm?.[1] ?? 'UnknownPage';
+                    methods = extractPyClassMethods(content);
+                }
+                else if (isJava) {
+                    const cm = content.match(/(?:public\s+)?class\s+(\w+)/);
+                    className = cm?.[1] ?? 'UnknownPage';
+                    methods = extractJavaClassMethods(content);
+                }
+                else {
+                    const result = extractTSClassMethods(content);
+                    className = result.className;
+                    methods = result.methods;
+                }
+                if (methods.length === 0)
+                    return null;
+                return {
+                    filePath,
+                    className,
+                    methods: methods.slice(0, 20),
+                    importPath: filePath.replace(/\.(ts|js|java|kt|py)$/, ''),
+                };
+            }
+            catch {
+                return null;
+            }
+        }));
+        return results.filter((r) => r !== null);
+    };
+    // Fetch in batches of 10 — respects GitHub API concurrency without hammering rate limits
+    const BATCH_SIZE = 10;
+    const summaries = [];
+    for (let i = 0; i < candidates.length; i += BATCH_SIZE) {
+        const batch = candidates.slice(i, i + BATCH_SIZE);
+        summaries.push(...await processCandidateBatch(batch));
+    }
+    return summaries;
+}
+/**
+ * Format page object inventory as a prompt-friendly string for LLM injection.
+ */
+function formatPageObjectInventoryForPrompt(inventory, urlHint) {
+    if (inventory.length === 0)
+        return '';
+    // Relevance-rank: boost classes whose file path or class name matches URL segments
+    let ranked = inventory;
+    if (urlHint) {
+        const slug = urlHint.toLowerCase().replace(/[^a-z0-9]/g, '');
+        ranked = [...inventory].sort((a, b) => {
+            const aScore = (a.filePath.toLowerCase().replace(/[^a-z0-9]/g, '').includes(slug) || a.className.toLowerCase().includes(slug)) ? 1 : 0;
+            const bScore = (b.filePath.toLowerCase().replace(/[^a-z0-9]/g, '').includes(slug) || b.className.toLowerCase().includes(slug)) ? 1 : 0;
+            return bScore - aScore;
+        });
+    }
+    const lines = ['=== EXISTING PAGE OBJECTS — reuse these, do not reinvent ==='];
+    for (const po of ranked.slice(0, 25)) {
+        const methodList = po.methods.slice(0, 12).map((m) => `${m.name}(${m.params})`).join(', ');
+        lines.push(`${po.className} (${po.filePath}): ${methodList}`);
+    }
+    return lines.join('\n');
+}
+// ---------------------------------------------------------------------------
+// Repo Target Path Derivation
+// ---------------------------------------------------------------------------
+/**
+ * Given a screen URL and the repo's detected style profile, derive
+ * the canonical path where a new test script for this screen should live.
+ *
+ * Example:
+ *   url: https://app.acme.com/reports/export
+ *   folderPattern: tests/e2e/
+ *   framework: playwright-ts
+ *   → tests/e2e/reports-export.spec.ts
+ */
+function deriveRepoTargetPath(screenUrl, styleProfile, framework) {
+    // Determine base folder from style profile. folderPattern is a template like
+    // "e2e/tests/{feature}.spec.ts" (see detectFolderPattern below) — it embeds the
+    // filename shape, not just a directory. Using it verbatim as a directory prefix
+    // produced paths like "e2e/tests/{feature}.spec.ts/login-page.spec.ts": a literal
+    // "{feature}.spec.ts" folder that doesn't exist in the repo, so pushes landed in a
+    // brand-new bogus directory instead of the repo's real test folder. Strip the
+    // {placeholder}... filename segment first, same as pomPaths() does for the same field.
+    const rawPattern = styleProfile.folderPattern ?? '';
+    let base = rawPattern
+        ? rawPattern.replace(/\{[^}]+\}.*$/, '').replace(/\/[^/]*$/, '/').replace(/^\//, '')
+        : '';
+    if (!base) {
+        base = framework.startsWith('cypress') ? 'cypress/e2e/'
+            : (framework === 'pytest' || framework === 'playwright-py' || framework === 'selenium-py') ? 'tests/'
+                : framework === 'junit' || framework === 'playwright-java' || framework === 'selenium-java' ? 'src/test/java/'
+                    : 'tests/e2e/';
+    }
+    base = base.replace(/\/?$/, '/'); // ensure trailing slash
+    // Convert URL path to slug
+    let slug;
+    try {
+        const parsed = new URL(screenUrl);
+        slug = parsed.pathname
+            .replace(/^\//, '') // strip leading slash
+            .replace(/\/+$/, '') // strip trailing slash
+            .replace(/[^a-zA-Z0-9/-]/g, '-')
+            .replace(/-+/g, '-')
+            .replace(/\//g, '-')
+            .toLowerCase()
+            || 'home';
+    }
+    catch {
+        slug = 'screen';
+    }
+    // When testSubDirs is populated, pick the most appropriate subdir based on URL path.
+    // Simple heuristic: if URL contains /api/ or path starts with api, prefer tests/api subdir.
+    if (styleProfile.testSubDirs && styleProfile.testSubDirs.length > 1) {
+        let urlPath = '';
+        try {
+            urlPath = new URL(screenUrl).pathname.toLowerCase();
+        }
+        catch { /* ignore */ }
+        const isApiPath = /\/(api|graphql|rest|v\d+)\b/.test(urlPath);
+        const apiDir = styleProfile.testSubDirs.find(d => /api|graphql|rest/.test(d.toLowerCase()));
+        const uiDir = styleProfile.testSubDirs.find(d => /ui|e2e|web|browser/.test(d.toLowerCase()));
+        const preferredDir = isApiPath ? (apiDir ?? styleProfile.testSubDirs[0]) : (uiDir ?? styleProfile.testSubDirs[0]);
+        base = `${preferredDir.replace(/\/?$/, '/')}`;
+    }
+    // Determine file extension — Kotlin gets .kt suffix for Java frameworks
+    const isKotlin = (framework === 'junit' || framework === 'playwright-java' || framework === 'selenium-java')
+        && styleProfile.namingPattern?.endsWith('.kt');
+    const ext = (framework === 'pytest' || framework === 'playwright-py' || framework === 'selenium-py') ? '_test.py'
+        : isKotlin ? 'Test.kt'
+            : (framework === 'junit' || framework === 'playwright-java' || framework === 'selenium-java') ? 'Test.java'
+                : framework.includes('ts') ? '.spec.ts'
+                    : '.spec.js';
+    // Apply naming pattern from style profile if it tells us something
+    const naming = styleProfile.namingPattern ?? '';
+    if (naming.includes('.test.')) {
+        return `${base}${slug}.test.${framework.includes('ts') ? 'ts' : 'js'}`;
+    }
+    if (naming.includes('.cy.')) {
+        return `${base}${slug}.cy.${framework.includes('ts') ? 'ts' : 'js'}`;
+    }
+    if (naming.includes('.e2e.')) {
+        return `${base}${slug}.e2e.${framework.includes('ts') ? 'ts' : 'js'}`;
+    }
+    return `${base}${slug}${ext}`;
+}
+/** Strip leading ./ and trailing / from a path string. */
+function normDir(s) { return s.replace(/^\.\//, '').replace(/\/$/, ''); }
+/** Extract the glob root directory (before first ** or * wildcard). */
+function globRoot(pattern) {
+    const root = pattern.replace(/\/\*\*.*$/, '').replace(/\/\*[^*].*$/, '');
+    return (root && !root.startsWith('*') && !root.startsWith('{')) ? normDir(root) : null;
+}
+/**
+ * Extract path-relevant settings from framework config files using regex/JSON.
+ * No LLM — these files have predictable, well-documented structure.
+ */
+function parseFrameworkConfig(configType, content) {
+    const result = {};
+    // ── TypeScript / tsconfig.json ────────────────────────────────────────────
+    if (configType === 'tsconfig') {
+        try {
+            const stripped = content.replace(/\/\/[^\n]*/g, '').replace(/,(\s*[}\]])/g, '$1');
+            const parsed = JSON.parse(stripped);
+            const opts = parsed?.compilerOptions ?? {};
+            if (opts.paths && typeof opts.paths === 'object')
+                result.tsconfigPaths = opts.paths;
+            if (typeof opts.baseUrl === 'string')
+                result.tsconfigBaseUrl = opts.baseUrl;
+        }
+        catch { /* malformed */ }
+        return result;
+    }
+    // ── Playwright ────────────────────────────────────────────────────────────
+    if (configType === 'playwright') {
+        const tdM = content.match(/\btestDir\s*:\s*['"`]([^'"`]+)['"`]/);
+        if (tdM)
+            result.testDir = normDir(tdM[1]);
+        const buM = content.match(/\bbaseURL\s*:\s*['"`]([^'"`]+)['"`]/);
+        if (buM)
+            result.baseURL = buM[1];
+        return result;
+    }
+    // ── Cypress ───────────────────────────────────────────────────────────────
+    if (configType === 'cypress') {
+        // Modern: specPattern (v10+)
+        const spM = content.match(/\bspecPattern\s*:\s*['"`]([^'"`]+)['"`]/);
+        if (spM) {
+            const r = globRoot(spM[1]);
+            if (r)
+                result.testDir = r;
+        }
+        // Legacy: testFiles (v9 and below)
+        if (!result.testDir) {
+            const tfM = content.match(/\btestFiles\s*:\s*['"`]([^'"`]+)['"`]/);
+            if (tfM) {
+                const r = globRoot(tfM[1]);
+                if (r)
+                    result.testDir = r;
+            }
+        }
+        // Default: integrationFolder (v9)
+        if (!result.testDir) {
+            const ifM = content.match(/\bintegrationFolder\s*:\s*['"`]([^'"`]+)['"`]/);
+            if (ifM)
+                result.testDir = normDir(ifM[1]);
+        }
+        const ffM = content.match(/\bfixturesFolder\s*:\s*['"`]([^'"`]+)['"`]/);
+        if (ffM)
+            result.fixturesFolder = normDir(ffM[1]);
+        const buM = content.match(/\bbaseUrl\s*:\s*['"`]([^'"`]+)['"`]/);
+        if (buM)
+            result.baseURL = buM[1];
+        return result;
+    }
+    // ── Jest ──────────────────────────────────────────────────────────────────
+    if (configType === 'jest') {
+        // roots: ['<rootDir>/src'] or roots: ['src']
+        const rootsM = content.match(/\broots\s*:\s*\[([^\]]+)\]/);
+        if (rootsM) {
+            const firstRoot = rootsM[1].match(/['"`]([^'"`]+)['"`]/)?.[1];
+            if (firstRoot)
+                result.testDir = firstRoot.replace(/<rootDir>\/?/, '').replace(/\/$/, '') || 'src';
+        }
+        // testMatch globs
+        if (!result.testDir) {
+            const tmM = content.match(/\btestMatch\s*:\s*\[([^\]]+)\]/);
+            if (tmM) {
+                const firstPat = tmM[1].match(/['"`]([^'"`]+)['"`]/)?.[1];
+                if (firstPat) {
+                    const r = globRoot(firstPat.replace(/<rootDir>\/?/, ''));
+                    if (r)
+                        result.testDir = r;
+                }
+            }
+        }
+        // testRegex: some repos use regex instead of glob
+        if (!result.testDir) {
+            const trM = content.match(/\btestRegex\s*:\s*['"`]([^'"`]+)['"`]/);
+            if (trM) {
+                // Extract directory prefix from regex (e.g. "__tests__" from "/__tests__/.*\\.test\\.ts$")
+                const dirM = trM[1].match(/^[/\\]?(\w[\w-]*)[/\\]/);
+                if (dirM)
+                    result.testDir = dirM[1];
+            }
+        }
+        // moduleNameMapper: { '^@/(.*)$': '<rootDir>/src/$1' }
+        const mnmM = content.match(/\bmoduleNameMapper\s*:\s*\{([^}]+)\}/s);
+        if (mnmM) {
+            const mapper = {};
+            const pairs = mnmM[1].matchAll(/['"`]([^'"`]+)['"`]\s*:\s*['"`]([^'"`]+)['"`]/g);
+            for (const [, k, v] of pairs)
+                mapper[k] = v;
+            if (Object.keys(mapper).length > 0)
+                result.jestModuleNameMapper = mapper;
+        }
+        return result;
+    }
+    // ── package.json — jest field + test script ───────────────────────────────
+    if (configType === 'package-json') {
+        try {
+            const parsed = JSON.parse(content);
+            const jestCfg = parsed?.jest ?? {};
+            if (Array.isArray(jestCfg.roots) && jestCfg.roots[0]) {
+                result.testDir = String(jestCfg.roots[0]).replace(/<rootDir>\/?/, '').replace(/\/$/, '') || 'src';
+            }
+            if (!result.testDir && Array.isArray(jestCfg.testMatch) && jestCfg.testMatch[0]) {
+                const r = globRoot(String(jestCfg.testMatch[0]).replace(/<rootDir>\/?/, ''));
+                if (r)
+                    result.testDir = r;
+            }
+            if (jestCfg.moduleNameMapper && typeof jestCfg.moduleNameMapper === 'object') {
+                result.jestModuleNameMapper = jestCfg.moduleNameMapper;
+            }
+        }
+        catch { /* malformed JSON */ }
+        return result;
+    }
+    // ── Python pytest.ini / tox.ini ───────────────────────────────────────────
+    if (configType === 'pytest-ini') {
+        // Works for pytest.ini ([pytest] section), tox.ini ([pytest] section), setup.cfg ([tool:pytest])
+        const tpM = content.match(/^\s*testpaths\s*=\s*(.+)$/m);
+        if (tpM) {
+            const first = tpM[1].trim().split(/\s+/)[0];
+            if (first)
+                result.testDir = normDir(first);
+        }
+        // python_files hint (e.g. python_files = test_*.py *_tests.py)
+        // Not stored as testDir but logged for awareness
+        return result;
+    }
+    // ── Python pyproject.toml ─────────────────────────────────────────────────
+    if (configType === 'pyproject-toml') {
+        // [tool.pytest.ini_options]
+        // testpaths = ["tests"]
+        const tpM = content.match(/testpaths\s*=\s*\[([^\]]+)\]/);
+        if (tpM) {
+            const first = tpM[1].match(/['"]([^'"]+)['"]/)?.[1];
+            if (first)
+                result.testDir = normDir(first);
+        }
+        // Fallback: testpaths = "tests" (single string)
+        if (!result.testDir) {
+            const tpM2 = content.match(/testpaths\s*=\s*['"]([^'"]+)['"]/);
+            if (tpM2)
+                result.testDir = normDir(tpM2[1]);
+        }
+        return result;
+    }
+    // ── Python setup.cfg ──────────────────────────────────────────────────────
+    if (configType === 'setup-cfg') {
+        // [tool:pytest] or [pytest]
+        // testpaths = tests
+        const tpM = content.match(/^\s*testpaths\s*=\s*(.+)$/m);
+        if (tpM) {
+            const first = tpM[1].trim().split(/[\s,]+/)[0];
+            if (first)
+                result.testDir = normDir(first);
+        }
+        return result;
+    }
+    // ── Java Maven pom.xml ────────────────────────────────────────────────────
+    if (configType === 'pom-xml') {
+        // <testSourceDirectory>src/test/java</testSourceDirectory>
+        const tsdM = content.match(/<testSourceDirectory>\s*([^<]+)\s*<\/testSourceDirectory>/);
+        if (tsdM)
+            result.javaTestSourceDir = normDir(tsdM[1].trim());
+        // Surefire <include>**/*Test.java</include> — no testDir derivation needed (use testSourceDir)
+        return result;
+    }
+    // ── Java Gradle build.gradle / build.gradle.kts ───────────────────────────
+    if (configType === 'build-gradle') {
+        // Groovy DSL: srcDirs = ['src/test/java'] or srcDir 'src/test/java'
+        const srcM = content.match(/srcDir[s]?\s*[=([]?\s*['"`]([^'"`]+)['"`]/);
+        if (srcM)
+            result.javaTestSourceDir = normDir(srcM[1]);
+        // Kotlin DSL: srcDir("src/test/kotlin") or setSrcDirs(listOf("src/test/java"))
+        if (!result.javaTestSourceDir) {
+            const kM = content.match(/srcDir\s*\(\s*['"`]([^'"`]+)['"`]\s*\)/);
+            if (kM)
+                result.javaTestSourceDir = normDir(kM[1]);
+        }
+        if (!result.javaTestSourceDir) {
+            const listM = content.match(/(?:setSrcDirs|setOf|listOf)\s*\(\s*['"`]([^'"`]+)['"`]/);
+            if (listM)
+                result.javaTestSourceDir = normDir(listM[1]);
+        }
+        // sourceSets.test.java.srcDirs = ['...'] Groovy style
+        if (!result.javaTestSourceDir) {
+            const ssM = content.match(/sourceSets\s*\.\s*test\s*\.\s*(?:java|kotlin)\s*\.\s*srcDir[s]?\s*[=([]?\s*['"`]([^'"`]+)['"`]/);
+            if (ssM)
+                result.javaTestSourceDir = normDir(ssM[1]);
+        }
+        return result;
+    }
+    // ── Java TestNG testng.xml ────────────────────────────────────────────────
+    if (configType === 'testng-xml') {
+        // <package name="com.example.tests"/> → testDir is src/test/java (implied, but extract package)
+        // We store nothing here — testng.xml is less reliable for dir; pom.xml is better
+        return result;
+    }
+    // ── WebdriverIO wdio.conf.ts / wdio.conf.js ───────────────────────────────
+    if (configType === 'wdio') {
+        // specs: ['./test/specs/**/*.spec.ts'] or specs: ['test/specs/**/*.e2e.ts']
+        const specsM = content.match(/\bspecs\s*:\s*\[([^\]]+)\]/);
+        if (specsM) {
+            const firstSpec = specsM[1].match(/['"`]([^'"`]+)['"`]/)?.[1];
+            if (firstSpec) {
+                const r = globRoot(firstSpec);
+                if (r)
+                    result.testDir = r;
+            }
+        }
+        const buM = content.match(/\bbaseUrl\s*:\s*['"`]([^'"`]+)['"`]/);
+        if (buM)
+            result.baseURL = buM[1];
+        // cucumberOpts.require or specs for page objects
+        const ffM = content.match(/\bfixturesFolder\s*:\s*['"`]([^'"`]+)['"`]/);
+        if (ffM)
+            result.fixturesFolder = normDir(ffM[1]);
+        return result;
+    }
+    // ── Cucumber .cucumber.js / cucumber.json / .cucumber.yaml ───────────────
+    if (configType === 'cucumber') {
+        // JS: paths: ['features/**/*.feature'] or default: { paths: [...] }
+        const pathsM = content.match(/\bpaths\s*:\s*\[([^\]]+)\]/);
+        if (pathsM) {
+            const firstPat = pathsM[1].match(/['"`]([^'"`]+)['"`]/)?.[1];
+            if (firstPat) {
+                const r = globRoot(firstPat);
+                if (r)
+                    result.testDir = r;
+            }
+        }
+        // JSON: {"default": {"paths": ["features/**/*.feature"]}}
+        if (!result.testDir) {
+            try {
+                const parsed = JSON.parse(content);
+                const paths = parsed?.default?.paths ?? parsed?.paths;
+                if (Array.isArray(paths) && paths[0]) {
+                    const r = globRoot(String(paths[0]));
+                    if (r)
+                        result.testDir = r;
+                }
+            }
+            catch { /* not JSON */ }
+        }
+        // YAML: paths:\n  - features
+        if (!result.testDir) {
+            const yamlM = content.match(/^paths:\s*\n\s+-\s+(.+)$/m);
+            if (yamlM) {
+                const r = globRoot(yamlM[1].trim());
+                if (r)
+                    result.testDir = r;
+            }
+        }
+        return result;
+    }
+    return result;
+}
+/**
+ * Given a repo's file tree paths and detected framework, return which config
+ * files to fetch and what parser to use for each.
+ * Covers all supported frameworks: playwright, cypress, jest, pytest, junit,
+ * selenium-java/py, webdriverio, cucumber.
+ */
+function detectConfigFilesToFetch(paths, framework) {
+    const pathSet = new Set(paths);
+    const result = [];
+    const added = new Set();
+    // Exact-match helper — tries known root-level and shallow config paths
+    const tryAdd = (candidates, type) => {
+        for (const c of candidates) {
+            if (pathSet.has(c) && !added.has(c)) {
+                result.push({ path: c, type });
+                added.add(c);
+                break;
+            }
+        }
+    };
+    // Monorepo fallback — scan tree for config at any depth, prefer shallowest
+    const scanTree = (fileRe, type) => {
+        if (result.some(r => r.type === type))
+            return; // already found via exact match
+        const matches = paths.filter(p => fileRe.test(p) && !added.has(p) && !p.includes('node_modules/'));
+        if (matches.length === 0)
+            return;
+        // Pick shallowest (fewest path segments)
+        matches.sort((a, b) => a.split('/').length - b.split('/').length);
+        result.push({ path: matches[0], type });
+        added.add(matches[0]);
+    };
+    const lang = framework.includes('java') ? 'java'
+        : (framework.includes('py') || framework === 'pytest') ? 'python'
+            : 'js';
+    // ── JavaScript / TypeScript frameworks ───────────────────────────────────
+    if (lang === 'js') {
+        if (framework.startsWith('playwright')) {
+            tryAdd([
+                'playwright.config.ts', 'playwright.config.js', 'playwright.config.mts',
+                'e2e/playwright.config.ts', 'config/playwright.config.ts', 'config/test.config.ts',
+            ], 'playwright');
+            // Monorepo: e.g. apps/web/playwright.config.ts, packages/e2e/playwright.config.ts
+            scanTree(/(?:^|\/)playwright\.config\.(ts|js|mts|cjs)$/, 'playwright');
+        }
+        if (framework.startsWith('cypress')) {
+            tryAdd([
+                'cypress.config.ts', 'cypress.config.js',
+                'e2e/cypress.config.ts', 'cypress/cypress.config.ts',
+            ], 'cypress');
+            scanTree(/(?:^|\/)cypress\.config\.(ts|js)$/, 'cypress');
+        }
+        if (framework === 'jest-ts' || framework === 'jest-js') {
+            tryAdd(['jest.config.ts', 'jest.config.js', 'jest.config.mjs', 'jest.config.cjs', 'jest.config.json'], 'jest');
+            tryAdd(['package.json'], 'package-json');
+            scanTree(/(?:^|\/)jest\.config\.(ts|js|mjs|cjs|json)$/, 'jest');
+        }
+        if (framework === 'webdriverio') {
+            tryAdd(['wdio.conf.ts', 'wdio.conf.js', 'wdio.config.ts', 'wdio.config.js', 'wdio.config.mjs'], 'wdio');
+            scanTree(/(?:^|\/)wdio\.(?:conf|config)\.(ts|js|mjs)$/, 'wdio');
+        }
+        if (framework === 'cucumber' || framework === 'gherkin') {
+            tryAdd(['.cucumber.js', '.cucumber.cjs', 'cucumber.json', '.cucumber.yaml', '.cucumber.yml', '.cucumberrc.json'], 'cucumber');
+            tryAdd(['package.json'], 'package-json');
+        }
+        // tsconfig.json always valuable for TS repos — import aliases
+        tryAdd(['tsconfig.json', 'tsconfig.base.json'], 'tsconfig');
+        scanTree(/(?:^|\/)tsconfig(?:\.base)?\.json$/, 'tsconfig');
+    }
+    // ── Python frameworks ─────────────────────────────────────────────────────
+    if (lang === 'python') {
+        tryAdd(['pytest.ini', '.pytest.ini'], 'pytest-ini');
+        tryAdd(['pyproject.toml'], 'pyproject-toml');
+        tryAdd(['setup.cfg'], 'setup-cfg');
+        tryAdd(['tox.ini'], 'pytest-ini'); // tox.ini may contain [pytest] section
+        scanTree(/(?:^|\/)pyproject\.toml$/, 'pyproject-toml');
+    }
+    // ── Java frameworks ───────────────────────────────────────────────────────
+    if (lang === 'java') {
+        tryAdd(['pom.xml'], 'pom-xml');
+        tryAdd(['build.gradle.kts', 'build.gradle'], 'build-gradle');
+        tryAdd(['testng.xml', 'src/test/resources/testng.xml', 'testng-suite.xml', 'src/test/resources/testng-suite.xml'], 'testng-xml');
+        scanTree(/(?:^|\/)pom\.xml$/, 'pom-xml');
+        scanTree(/(?:^|\/)build\.gradle(?:\.kts)?$/, 'build-gradle');
+    }
+    return result;
+}