@testspectra/cli 1.0.70 → 1.1.0-rc.1

package/dist/generator/type-generator.js

@@ -0,0 +1,740 @@
+import fs from 'fs';
+import path from 'path';
+import { ConfigLoader } from '../config/loader.js';
+import { TsConfigGenerator } from './tsconfig-generator.js';
+export const PLATFORM_HIERARCHY = {
+    web: ['web', 'common'],
+    android: ['android', 'mobile', 'common'],
+    ios: ['ios', 'mobile', 'common'],
+    mobile: ['mobile', 'common'],
+    common: ['common'],
+};
+/**
+ * Discovers all feature directories and shared library directories.
+ * Standard discovery hierarchy:
+ * 1. Nx / Monorepo Project Descriptors (`project.json`):
+ *    - projectType: "library" OR tags: ["type:shared", "type:library", "scope:shared"] => Shared Library Scope (isShared: true)
+ *    - projectType: "application" OR tags: ["type:e2e", "type:app"] => Feature Scope (isShared: false)
+ * 2. Explicit User Configuration (`tsconfig.spectra.shared.json`):
+ *    - Custom include path for shared testing utilities
+ * 3. Dynamic Workspace Filesystem Discovery (Fallback for non-Nx / custom layouts):
+ *    - Directory with specs/e2e/tests subfolders => Feature Scope
+ *    - Directory with page-objects/support/fixtures and NO specs => Shared Scope
+ */
+export function discoverEntityScopes(cwd) {
+    const scopes = [];
+    const ignoredDirNames = new Set([
+        'node_modules',
+        'dist',
+        '.git',
+        '.testspectra',
+        'templates',
+        'src',
+        'build',
+        'coverage',
+        'scripts',
+        '.nx',
+        '.turbo',
+        '.vscode',
+    ]);
+    // Priority 1: Scan for Nx `project.json` files throughout the workspace
+    function scanForNxProjects(dir, depth) {
+        if (depth <= 0 || !fs.existsSync(dir))
+            return;
+        const base = path.basename(dir);
+        if (ignoredDirNames.has(base))
+            return;
+        const projectJsonPath = path.join(dir, 'project.json');
+        if (fs.existsSync(projectJsonPath)) {
+            try {
+                const pObj = JSON.parse(fs.readFileSync(projectJsonPath, 'utf-8'));
+                const projectType = pObj.projectType;
+                const tags = Array.isArray(pObj.tags) ? pObj.tags : [];
+                const isSharedLib = projectType === 'library' ||
+                    tags.includes('type:shared') ||
+                    tags.includes('type:library') ||
+                    tags.includes('scope:shared');
+                const isE2eApp = projectType === 'application' ||
+                    tags.includes('type:e2e') ||
+                    tags.includes('type:app') ||
+                    tags.some((t) => t.startsWith('scope:') && t !== 'scope:shared');
+                if (isSharedLib) {
+                    if (!scopes.some((s) => s.dir === dir)) {
+                        scopes.push({ name: 'shared', dir, isShared: true });
+                    }
+                    return; // Do not recurse into subdirectories of an identified project
+                }
+                else if (isE2eApp) {
+                    // Extract scope name from tags (e.g. "scope:matchers" => "matchers") or project name
+                    const scopeTag = tags.find((t) => t.startsWith('scope:') && t !== 'scope:shared');
+                    let featureName = scopeTag ? scopeTag.replace('scope:', '') : '';
+                    if (!featureName && pObj.name) {
+                        featureName = pObj.name.replace(/-e2e$/, '').replace(/^e2e-/, '');
+                    }
+                    if (!featureName) {
+                        featureName = path.basename(base === 'e2e' ? path.dirname(dir) : dir);
+                    }
+                    if (!scopes.some((s) => s.dir === dir || s.name === featureName)) {
+                        scopes.push({ name: featureName, dir, isShared: false });
+                    }
+                    return;
+                }
+            }
+            catch { }
+        }
+        try {
+            const entries = fs.readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.isDirectory()) {
+                    scanForNxProjects(path.join(dir, entry.name), depth - 1);
+                }
+            }
+        }
+        catch { }
+    }
+    scanForNxProjects(cwd, 5);
+    // If projects were discovered via project.json, we have explicit deterministic descriptors
+    if (scopes.length > 0) {
+        return scopes;
+    }
+    // Priority 2: Check if user-provided tsconfig.spectra.shared.json defines custom shared library paths
+    const userSharedConfig = path.join(cwd, 'tsconfig.spectra.shared.json');
+    if (fs.existsSync(userSharedConfig)) {
+        try {
+            const conf = JSON.parse(fs.readFileSync(userSharedConfig, 'utf-8'));
+            if (Array.isArray(conf.include)) {
+                for (const inc of conf.include) {
+                    if (typeof inc === 'string' && inc.includes('**')) {
+                        const baseCandidate = inc.split('/**')[0];
+                        const resolved = path.resolve(cwd, baseCandidate);
+                        if (fs.existsSync(resolved) && !scopes.some((s) => s.dir === resolved)) {
+                            scopes.push({ name: 'shared', dir: resolved, isShared: true });
+                        }
+                    }
+                }
+            }
+        }
+        catch { }
+    }
+    // Priority 3: Fallback Directory Scan (for non-Nx or custom workspaces)
+    const entityDirNames = new Set(['page-objects', 'pageobjects', 'support', 'fixtures', 'global-hooks']);
+    function hasTestingEntities(dir) {
+        if (!fs.existsSync(dir))
+            return false;
+        const entityNames = ['page-objects', 'pageobjects', 'support', 'steps', 'actions', 'fixtures'];
+        return entityNames.some((name) => fs.existsSync(path.join(dir, name)));
+    }
+    function hasTestingSpecs(dir) {
+        if (!fs.existsSync(dir))
+            return false;
+        const specNames = ['specs', 'e2e', 'tests'];
+        return specNames.some((name) => fs.existsSync(path.join(dir, name)));
+    }
+    function fallbackScan(dir, depth) {
+        if (depth <= 0 || !fs.existsSync(dir))
+            return;
+        const base = path.basename(dir);
+        if (ignoredDirNames.has(base) || entityDirNames.has(base))
+            return;
+        if (dir !== cwd) {
+            if (base === 'e2e' || base === 'specs' || base === 'tests') {
+                const parentDir = path.dirname(dir);
+                if (parentDir !== cwd) {
+                    const featureName = path.basename(parentDir);
+                    if (!scopes.some((s) => s.dir === dir)) {
+                        scopes.push({ name: featureName, dir, isShared: false });
+                    }
+                    return;
+                }
+            }
+            if (hasTestingSpecs(dir)) {
+                let targetDir = dir;
+                if (fs.existsSync(path.join(dir, 'e2e')))
+                    targetDir = path.join(dir, 'e2e');
+                else if (fs.existsSync(path.join(dir, 'specs')))
+                    targetDir = path.join(dir, 'specs');
+                else if (fs.existsSync(path.join(dir, 'tests')))
+                    targetDir = path.join(dir, 'tests');
+                const featureName = path.basename(dir);
+                if (!scopes.some((s) => s.dir === targetDir || s.name === featureName)) {
+                    scopes.push({ name: featureName, dir: targetDir, isShared: false });
+                }
+                return;
+            }
+            if (hasTestingEntities(dir) && !hasTestingSpecs(dir)) {
+                if (!scopes.some((s) => s.isShared && s.dir === dir)) {
+                    scopes.push({ name: 'shared', dir, isShared: true });
+                    return;
+                }
+            }
+        }
+        try {
+            const entries = fs.readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.isDirectory()) {
+                    fallbackScan(path.join(dir, entry.name), depth - 1);
+                }
+            }
+        }
+        catch { }
+    }
+    fallbackScan(cwd, 5);
+    return scopes;
+}
+/**
+ * Detects a component-testing project (`@testspectra/react`'s Vitest browser-mode runner), via
+ * the same signal `cli/src/commands/test.ts` uses to gate `spectra test` itself. Used to augment
+ * the generated `Spectra` ambient type with `.mount()`, which only exists in that runtime.
+ */
+export function isComponentTestingProject(cwd) {
+    try {
+        const pkgPath = path.join(cwd, 'package.json');
+        if (!fs.existsSync(pkgPath))
+            return false;
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        return Boolean(pkg.dependencies?.['@testspectra/react'] || pkg.devDependencies?.['@testspectra/react']);
+    }
+    catch {
+        return false;
+    }
+}
+export class TypeGenerator {
+    /**
+     * Main entry point to generate all ambient type declarations.
+     */
+    static generateAll(cwd) {
+        this.writeDeclarationFiles(cwd);
+        TsConfigGenerator.scaffoldConfigs(cwd);
+    }
+    /**
+     * Reloads `spectra.config.ts` and refreshes `.testspectra/types/env.d.ts` with the current
+     * `executionConfig.environmentVariables`. Separate from `writeDeclarationFiles`/`generateAll`
+     * (which must stay synchronous) because reading the config file is unavoidably async.
+     */
+    static async syncEnvDeclaration(cwd) {
+        const rootTypesDir = path.join(cwd, '.testspectra', 'types');
+        if (!fs.existsSync(rootTypesDir)) {
+            fs.mkdirSync(rootTypesDir, { recursive: true });
+        }
+        let environmentVariables = {};
+        try {
+            const config = await ConfigLoader.loadConfig(cwd);
+            environmentVariables = config.executionConfig?.environmentVariables ?? {};
+        }
+        catch { }
+        fs.writeFileSync(path.join(rootTypesDir, 'env.d.ts'), this.generateEnvDeclaration(environmentVariables), 'utf-8');
+    }
+    /**
+     * Discovers all feature directories and shared library directories.
+     * Returns a map of scope -> base directory
+     */
+    static getEntityScopes(cwd) {
+        return discoverEntityScopes(cwd);
+    }
+    static getPageObjectsDirsForScope(scopeDir, sharedDir) {
+        const dirs = [];
+        function collectPo(dir) {
+            if (!fs.existsSync(dir))
+                return;
+            const direct = [path.join(dir, 'page-objects'), path.join(dir, 'pageobjects')];
+            for (const d of direct) {
+                if (fs.existsSync(d) && !dirs.includes(d))
+                    dirs.push(d);
+            }
+            try {
+                const entries = fs.readdirSync(dir, { withFileTypes: true });
+                for (const entry of entries) {
+                    if (entry.isDirectory() &&
+                        entry.name !== 'node_modules' &&
+                        entry.name !== 'dist' &&
+                        entry.name !== '.git' &&
+                        entry.name !== '.testspectra') {
+                        const sub = [path.join(dir, entry.name, 'page-objects'), path.join(dir, entry.name, 'pageobjects')];
+                        for (const s of sub) {
+                            if (fs.existsSync(s) && !dirs.includes(s))
+                                dirs.push(s);
+                        }
+                    }
+                }
+            }
+            catch { }
+        }
+        collectPo(scopeDir);
+        if (sharedDir && sharedDir !== scopeDir) {
+            collectPo(sharedDir);
+        }
+        return dirs;
+    }
+    static getEntityDirsForScope(entityType, scopeDir, sharedDir) {
+        const dirs = [];
+        function collectEntities(dir) {
+            if (!fs.existsSync(dir))
+                return;
+            const direct = [
+                path.join(dir, entityType),
+                path.join(dir, 'support', entityType),
+                path.join(dir, 'support', 'testing', entityType),
+            ];
+            for (const d of direct) {
+                if (fs.existsSync(d) && !dirs.includes(d))
+                    dirs.push(d);
+            }
+            try {
+                const entries = fs.readdirSync(dir, { withFileTypes: true });
+                for (const entry of entries) {
+                    if (entry.isDirectory() &&
+                        entry.name !== 'node_modules' &&
+                        entry.name !== 'dist' &&
+                        entry.name !== '.git' &&
+                        entry.name !== '.testspectra') {
+                        const sub = [path.join(dir, entry.name, entityType), path.join(dir, entry.name, 'support', entityType)];
+                        for (const s of sub) {
+                            if (fs.existsSync(s) && !dirs.includes(s))
+                                dirs.push(s);
+                        }
+                    }
+                }
+            }
+            catch { }
+        }
+        collectEntities(scopeDir);
+        if (sharedDir && sharedDir !== scopeDir) {
+            collectEntities(sharedDir);
+        }
+        return dirs;
+    }
+    static generateDeclarationsForScope(cwd, outputTypesDir, scopeDir, sharedDir, rootTypesDir) {
+        const poDirs = this.getPageObjectsDirsForScope(scopeDir, sharedDir);
+        const actionsDirs = this.getEntityDirsForScope('actions', scopeDir, sharedDir);
+        const stepsDirs = this.getEntityDirsForScope('steps', scopeDir, sharedDir);
+        const isComponentTesting = isComponentTestingProject(cwd);
+        const platforms = ['web', 'android', 'ios', 'mobile', 'common'];
+        const results = {
+            web: '',
+            android: '',
+            ios: '',
+            mobile: '',
+            common: '',
+        };
+        // `env.d.ts` always lives at the workspace root types dir (env vars come from a single
+        // `spectra.config.ts`, unlike per-scope fixtures/page-objects), so a shared/feature scope's
+        // own declarations reference it via a relative path back up to the root.
+        let envRefPath = './env.d.ts';
+        if (rootTypesDir && rootTypesDir !== outputTypesDir) {
+            envRefPath = path.relative(outputTypesDir, path.join(rootTypesDir, 'env.d.ts')).replace(/\\/g, '/');
+            if (!envRefPath.startsWith('.'))
+                envRefPath = `./${envRefPath}`;
+        }
+        for (const platform of platforms) {
+            const hierarchy = PLATFORM_HIERARCHY[platform];
+            let content = `// Auto-generated ambient declarations for TestSpectra [${platform.toUpperCase()}]\n`;
+            content += `// Managed automatically by TestSpectra Language Service Plugin.\n\n`;
+            // TestSpectra's Rust-native orchestrator worker (core/orchestrator/src/worker/bdd_runner.ts)
+            // registers its own `it`/`test`/lifecycle-hook globals directly — there is no WDIO or Mocha
+            // runtime involved at all (not just for component testing; this is true across every
+            // platform). `describe` is intentionally NOT declared here even though the runtime has a
+            // transparent no-op implementation of it — spec-schema-linter's no-describe-block rule
+            // forbids authoring it, so leaving it undeclared makes that a compile error too, not just a
+            // lint error.
+            content += `declare function it(title: string, fn: () => Promise<void> | void): void;\n`;
+            if (isComponentTesting) {
+                // Vitest's own `expect` global (test.globals: true in tools/react/vitest.config.ts) — the
+                // one thing component specs legitimately need beyond the Spectra.* DSL, for asserting
+                // plain closure/callback state (e.g. "was this onClick handler invoked") that has no DOM
+                // element to target. Reuses @testspectra/react's own re-exported `ExpectStatic` type
+                // rather than hand-duplicating Vitest's expect API surface. Not declared for E2E projects
+                // — the Rust orchestrator's BDD runtime has no `expect` global at all.
+                content += `declare const expect: import('@testspectra/react').ExpectStatic;\n`;
+            }
+            content += `/// <reference types="@testspectra/matchers" />\n`;
+            content += `/// <reference path="./fixtures.d.ts" />\n`;
+            content += `/// <reference path="${envRefPath}" />\n\n`;
+            // 1. Page Objects Global Declarations
+            const declaredPOMs = new Set();
+            for (const poDir of poDirs) {
+                if (!fs.existsSync(poDir))
+                    continue;
+                const poEntries = fs.readdirSync(poDir, { withFileTypes: true });
+                for (const entry of poEntries) {
+                    if (entry.name.startsWith('.'))
+                        continue;
+                    if (entry.isDirectory()) {
+                        const className = entry.name;
+                        if (declaredPOMs.has(className))
+                            continue;
+                        const classFolder = path.join(poDir, className);
+                        let matchedFile = null;
+                        for (const stem of hierarchy) {
+                            const candidates = [
+                                path.join(classFolder, `${stem}.ts`),
+                                path.join(classFolder, `${stem}.page.ts`),
+                                path.join(classFolder, `${stem}.po.ts`),
+                            ];
+                            if (stem === 'common') {
+                                candidates.push(path.join(classFolder, 'common.ts'));
+                                candidates.push(path.join(classFolder, 'index.ts'));
+                            }
+                            for (const cand of candidates) {
+                                if (fs.existsSync(cand)) {
+                                    matchedFile = path.relative(outputTypesDir, cand).replace(/\\/g, '/').replace(/\.ts$/, '.js');
+                                    if (!matchedFile.startsWith('.'))
+                                        matchedFile = `./${matchedFile}`;
+                                    break;
+                                }
+                            }
+                            if (matchedFile)
+                                break;
+                        }
+                        if (matchedFile) {
+                            content += `declare const ${className}: (typeof import('${matchedFile}') extends { default: infer T } ? T : typeof import('${matchedFile}'));\n`;
+                            declaredPOMs.add(className);
+                        }
+                    }
+                    else if (entry.isFile() && entry.name.endsWith('.ts')) {
+                        const parts = entry.name.split('.');
+                        const className = parts[0];
+                        if (declaredPOMs.has(className))
+                            continue;
+                        let isMatch = false;
+                        if (parts.length === 2) {
+                            isMatch = true;
+                        }
+                        else if (parts.length > 2) {
+                            const stem = parts[1];
+                            isMatch = hierarchy.includes(stem);
+                        }
+                        if (isMatch) {
+                            let rel = path
+                                .relative(outputTypesDir, path.join(poDir, entry.name))
+                                .replace(/\\/g, '/')
+                                .replace(/\.ts$/, '.js');
+                            if (!rel.startsWith('.'))
+                                rel = `./${rel}`;
+                            content += `declare const ${className}: (typeof import('${rel}') extends { default: infer T } ? T : typeof import('${rel}'));\n`;
+                            declaredPOMs.add(className);
+                        }
+                    }
+                }
+            }
+            // 2. Built-in Spectra Static Methods & Custom Actions
+            content += `interface TestSpectraCustomActions {\n`;
+            const declaredActions = new Set();
+            for (const actionsDir of actionsDirs) {
+                if (!fs.existsSync(actionsDir))
+                    continue;
+                const actionEntries = fs.readdirSync(actionsDir, { withFileTypes: true });
+                for (const entry of actionEntries) {
+                    if (entry.name.startsWith('.'))
+                        continue;
+                    if (entry.isDirectory()) {
+                        const actionName = entry.name;
+                        if (declaredActions.has(actionName))
+                            continue;
+                        const actionFolder = path.join(actionsDir, actionName);
+                        let matchedFile = null;
+                        for (const stem of hierarchy) {
+                            const cand1 = path.join(actionFolder, `${stem}.action.ts`);
+                            const cand2 = path.join(actionFolder, `${stem}.ts`);
+                            if (fs.existsSync(cand1)) {
+                                matchedFile = path.relative(outputTypesDir, cand1).replace(/\\/g, '/').replace(/\.ts$/, '.js');
+                                break;
+                            }
+                            else if (fs.existsSync(cand2)) {
+                                matchedFile = path.relative(outputTypesDir, cand2).replace(/\\/g, '/').replace(/\.ts$/, '.js');
+                                break;
+                            }
+                        }
+                        if (matchedFile) {
+                            if (!matchedFile.startsWith('.'))
+                                matchedFile = `./${matchedFile}`;
+                            const camel = actionName.replace(/[-_]+([a-zA-Z0-9])/g, (_, char) => char.toUpperCase());
+                            content += `  "${actionName}": (typeof import('${matchedFile}') extends { default: infer T } ? T : typeof import('${matchedFile}'));\n`;
+                            if (camel !== actionName && /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(camel)) {
+                                content += `  ${camel}: (typeof import('${matchedFile}') extends { default: infer T } ? T : typeof import('${matchedFile}'));\n`;
+                            }
+                            declaredActions.add(actionName);
+                        }
+                    }
+                    else if (entry.isFile() && entry.name.endsWith('.ts')) {
+                        const parts = entry.name.split('.');
+                        const actionName = parts[0];
+                        let stem = 'common';
+                        if (parts.length > 2) {
+                            stem = parts[1];
+                        }
+                        else if (parts.length === 2) {
+                            stem = 'common';
+                        }
+                        if (hierarchy.includes(stem)) {
+                            if (declaredActions.has(actionName))
+                                continue;
+                            let rel = path
+                                .relative(outputTypesDir, path.join(actionsDir, entry.name))
+                                .replace(/\\/g, '/')
+                                .replace(/\.ts$/, '.js');
+                            if (!rel.startsWith('.'))
+                                rel = `./${rel}`;
+                            const camel = actionName.replace(/[-_]+([a-zA-Z0-9])/g, (_, char) => char.toUpperCase());
+                            content += `  "${actionName}": (typeof import('${rel}') extends { default: infer T } ? T : typeof import('${rel}'));\n`;
+                            if (camel !== actionName && /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(camel)) {
+                                content += `  ${camel}: (typeof import('${rel}') extends { default: infer T } ? T : typeof import('${rel}'));\n`;
+                            }
+                            declaredActions.add(actionName);
+                        }
+                    }
+                }
+            }
+            content += `}\n`;
+            // Reuses @testspectra/react's own exported `mount` type rather than hand-duplicating its
+            // signature here — stays in sync automatically if that signature ever changes.
+            const mountAugment = isComponentTesting ? ` & { mount: typeof import('@testspectra/react').mount }` : '';
+            content += `type TestSpectraActions = import('@testspectra/matchers').SpectraStatic & TestSpectraCustomActions${mountAugment};\n`;
+            content += `declare const Spectra: TestSpectraActions;\n\n`;
+            // 3. Built-in Steps Declaration
+            content += `interface TestSpectraSteps {\n`;
+            const declaredSteps = new Set();
+            for (const stepsDir of stepsDirs) {
+                if (!fs.existsSync(stepsDir))
+                    continue;
+                const stepEntries = fs.readdirSync(stepsDir, { withFileTypes: true });
+                for (const entry of stepEntries) {
+                    if (entry.name.startsWith('.'))
+                        continue;
+                    if (entry.isDirectory()) {
+                        const stepName = entry.name;
+                        if (declaredSteps.has(stepName))
+                            continue;
+                        const stepFolder = path.join(stepsDir, stepName);
+                        let matchedFile = null;
+                        for (const stem of hierarchy) {
+                            const cand1 = path.join(stepFolder, `${stem}.step.ts`);
+                            const cand2 = path.join(stepFolder, `${stem}.ts`);
+                            if (fs.existsSync(cand1)) {
+                                matchedFile = path.relative(outputTypesDir, cand1).replace(/\\/g, '/').replace(/\.ts$/, '.js');
+                                break;
+                            }
+                            else if (fs.existsSync(cand2)) {
+                                matchedFile = path.relative(outputTypesDir, cand2).replace(/\\/g, '/').replace(/\.ts$/, '.js');
+                                break;
+                            }
+                        }
+                        if (matchedFile) {
+                            if (!matchedFile.startsWith('.'))
+                                matchedFile = `./${matchedFile}`;
+                            const camel = stepName.replace(/[-_]+([a-zA-Z0-9])/g, (_, char) => char.toUpperCase());
+                            content += `  "${stepName}": (typeof import('${matchedFile}') extends { default: infer T } ? T : typeof import('${matchedFile}'));\n`;
+                            if (camel !== stepName && /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(camel)) {
+                                content += `  ${camel}: (typeof import('${matchedFile}') extends { default: infer T } ? T : typeof import('${matchedFile}'));\n`;
+                            }
+                            declaredSteps.add(stepName);
+                        }
+                    }
+                    else if (entry.isFile() && entry.name.endsWith('.ts')) {
+                        const parts = entry.name.split('.');
+                        const stepName = parts[0];
+                        let stem = 'common';
+                        if (parts.length > 2) {
+                            stem = parts[1];
+                        }
+                        else if (parts.length === 2) {
+                            stem = 'common';
+                        }
+                        if (hierarchy.includes(stem)) {
+                            if (declaredSteps.has(stepName))
+                                continue;
+                            let rel = path
+                                .relative(outputTypesDir, path.join(stepsDir, entry.name))
+                                .replace(/\\/g, '/')
+                                .replace(/\.ts$/, '.js');
+                            if (!rel.startsWith('.'))
+                                rel = `./${rel}`;
+                            const camel = stepName.replace(/[-_]+([a-zA-Z0-9])/g, (_, char) => char.toUpperCase());
+                            content += `  "${stepName}": (typeof import('${rel}') extends { default: infer T } ? T : typeof import('${rel}'));\n`;
+                            if (camel !== stepName && /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(camel)) {
+                                content += `  ${camel}: (typeof import('${rel}') extends { default: infer T } ? T : typeof import('${rel}'));\n`;
+                            }
+                            declaredSteps.add(stepName);
+                        }
+                    }
+                }
+            }
+            content += `}\n`;
+            content += `declare const Step: TestSpectraSteps;\n\n`;
+            results[platform] = content;
+        }
+        return results;
+    }
+    static generateFixturesDeclarationForScope(cwd, outputTypesDir, scopeDir, sharedDir) {
+        const fixturesDirs = this.getEntityDirsForScope('fixtures', scopeDir, sharedDir);
+        let content = `// Auto-generated ambient fixture declarations for TestSpectra\n`;
+        content += `// Managed automatically by TestSpectra Language Service Plugin.\n\n`;
+        content += `interface TestSpectraFixtures {\n`;
+        const declaredFixtures = new Set();
+        function scanFixtureDir(dir) {
+            if (!fs.existsSync(dir))
+                return;
+            try {
+                const entries = fs.readdirSync(dir, { withFileTypes: true });
+                for (const entry of entries) {
+                    if (entry.name.startsWith('.'))
+                        continue;
+                    if (entry.isDirectory()) {
+                        scanFixtureDir(path.join(dir, entry.name));
+                    }
+                    else if (entry.isFile()) {
+                        const parsed = path.parse(entry.name);
+                        const varName = parsed.name.replace(/[^a-zA-Z0-9_$]/g, '_');
+                        if (declaredFixtures.has(varName))
+                            continue;
+                        if (entry.name.endsWith('.json')) {
+                            let rel = path.relative(outputTypesDir, path.join(dir, entry.name)).replace(/\\/g, '/');
+                            if (!rel.startsWith('.'))
+                                rel = `./${rel}`;
+                            content += `  readonly ${varName}: typeof import('${rel}');\n`;
+                        }
+                        else {
+                            content += `  readonly ${varName}: string;\n`;
+                        }
+                        declaredFixtures.add(varName);
+                    }
+                }
+            }
+            catch { }
+        }
+        for (const fixturesDir of fixturesDirs) {
+            scanFixtureDir(fixturesDir);
+        }
+        content += `}\n`;
+        content += `declare const Fixture: TestSpectraFixtures;\n`;
+        return content;
+    }
+    /**
+     * Generates the typed `Spectra.env` ambient declaration from `spectra.config.ts`'s
+     * `executionConfig.environmentVariables` — mirrors `generateFixturesDeclarationForScope`, but
+     * env vars come from a single project-level config rather than a scanned directory.
+     *
+     * Emits a bare global `interface SpectraEnv { readonly KEY: string; ... }`, which TypeScript
+     * interface-merges with the empty `SpectraEnv` shipped by `@testspectra/matchers` (the same
+     * mechanism `@types/node` uses for projects to augment `NodeJS.ProcessEnv`) — so `Spectra.env.KEY`
+     * resolves to `string`, never `string | undefined` like raw `process.env.KEY`.
+     */
+    static generateEnvDeclaration(environmentVariables) {
+        let content = `// Auto-generated ambient Spectra.env declarations for TestSpectra\n`;
+        content += `// Managed automatically by TestSpectra Language Service Plugin.\n\n`;
+        content += `interface SpectraEnv {\n`;
+        for (const key of Object.keys(environmentVariables)) {
+            content += `  readonly ${JSON.stringify(key)}: string;\n`;
+        }
+        content += `}\n`;
+        return content;
+    }
+    static writeDeclarationFiles(cwd) {
+        const rootTypesDir = path.join(cwd, '.testspectra', 'types');
+        if (!fs.existsSync(rootTypesDir)) {
+            fs.mkdirSync(rootTypesDir, { recursive: true });
+        }
+        // env.d.ts always lives at the root, regardless of Nx scopes — a single spectra.config.ts's
+        // executionConfig.environmentVariables applies workspace-wide (see generateEnvDeclaration).
+        // Reading spectra.config.ts itself is unavoidably async (ESM dynamic import), which would ripple
+        // an async signature through every caller of this long-standing sync method — instead, this only
+        // guarantees env.d.ts *exists* (so the reference below never points at a missing file) and
+        // leaves it accurate as of the last real sync. `syncEnvDeclaration` (called at the actual
+        // execution entry points: run/watch/sync-types) is what keeps its content up to date.
+        const envDtsPath = path.join(rootTypesDir, 'env.d.ts');
+        if (!fs.existsSync(envDtsPath)) {
+            fs.writeFileSync(envDtsPath, this.generateEnvDeclaration({}), 'utf-8');
+        }
+        const scopes = this.getEntityScopes(cwd);
+        const sharedScope = scopes.find((s) => s.isShared);
+        const featureScopes = scopes.filter((s) => !s.isShared);
+        const hasScopes = Boolean(sharedScope || featureScopes.length > 0);
+        const hasRootEntities = fs.existsSync(path.join(cwd, 'specs')) ||
+            fs.existsSync(path.join(cwd, 'page-objects')) ||
+            fs.existsSync(path.join(cwd, 'pageobjects')) ||
+            fs.existsSync(path.join(cwd, 'support')) ||
+            fs.existsSync(path.join(cwd, 'fixtures'));
+        // 1. Generate Global / Standalone Root Types ONLY when there are root entities or no sub-scopes
+        if (!hasScopes || hasRootEntities) {
+            const rootFixtures = this.generateFixturesDeclarationForScope(cwd, rootTypesDir, cwd);
+            fs.writeFileSync(path.join(rootTypesDir, 'fixtures.d.ts'), rootFixtures, 'utf-8');
+            const rootDeclarations = this.generateDeclarationsForScope(cwd, rootTypesDir, cwd, undefined, rootTypesDir);
+            for (const [platform, content] of Object.entries(rootDeclarations)) {
+                fs.writeFileSync(path.join(rootTypesDir, `${platform}.d.ts`), content, 'utf-8');
+            }
+        }
+        else {
+            // In a pure monorepo where entities are partitioned in shared/ and packages/,
+            // purge any root platform .d.ts files so types are not emitted outside shared & package folders
+            const rootPlatformFiles = ['web.d.ts', 'mobile.d.ts', 'android.d.ts', 'ios.d.ts', 'common.d.ts', 'fixtures.d.ts'];
+            for (const f of rootPlatformFiles) {
+                const p = path.join(rootTypesDir, f);
+                if (fs.existsSync(p)) {
+                    try {
+                        fs.unlinkSync(p);
+                    }
+                    catch { }
+                }
+            }
+        }
+        // 2. Generate Scoped Types for Shared Library: .testspectra/types/shared/
+        if (sharedScope) {
+            const sharedTypesDir = path.join(rootTypesDir, 'shared');
+            if (!fs.existsSync(sharedTypesDir))
+                fs.mkdirSync(sharedTypesDir, { recursive: true });
+            const sharedFixtures = this.generateFixturesDeclarationForScope(cwd, sharedTypesDir, sharedScope.dir);
+            fs.writeFileSync(path.join(sharedTypesDir, 'fixtures.d.ts'), sharedFixtures, 'utf-8');
+            const sharedDeclarations = this.generateDeclarationsForScope(cwd, sharedTypesDir, sharedScope.dir, undefined, rootTypesDir);
+            for (const [platform, content] of Object.entries(sharedDeclarations)) {
+                fs.writeFileSync(path.join(sharedTypesDir, `${platform}.d.ts`), content, 'utf-8');
+            }
+        }
+        else {
+            const sharedTypesDir = path.join(rootTypesDir, 'shared');
+            if (fs.existsSync(sharedTypesDir)) {
+                try {
+                    fs.rmSync(sharedTypesDir, { recursive: true, force: true });
+                }
+                catch { }
+            }
+        }
+        // 3. Generate Scoped Types for Feature Modules: .testspectra/types/features/<featureName>/
+        const activeFeatureNames = new Set(featureScopes.map((f) => f.name));
+        for (const feature of featureScopes) {
+            const featureTypesDir = path.join(rootTypesDir, 'features', feature.name);
+            if (!fs.existsSync(featureTypesDir))
+                fs.mkdirSync(featureTypesDir, { recursive: true });
+            const featureFixtures = this.generateFixturesDeclarationForScope(cwd, featureTypesDir, feature.dir, sharedScope?.dir);
+            fs.writeFileSync(path.join(featureTypesDir, 'fixtures.d.ts'), featureFixtures, 'utf-8');
+            const featureDeclarations = this.generateDeclarationsForScope(cwd, featureTypesDir, feature.dir, sharedScope?.dir, rootTypesDir);
+            for (const [platform, content] of Object.entries(featureDeclarations)) {
+                fs.writeFileSync(path.join(featureTypesDir, `${platform}.d.ts`), content, 'utf-8');
+            }
+        }
+        // Clean up stale feature folders
+        const featuresBaseDir = path.join(rootTypesDir, 'features');
+        if (fs.existsSync(featuresBaseDir)) {
+            try {
+                const existingFeatureDirs = fs.readdirSync(featuresBaseDir, { withFileTypes: true });
+                for (const entry of existingFeatureDirs) {
+                    if (entry.isDirectory() && !activeFeatureNames.has(entry.name)) {
+                        fs.rmSync(path.join(featuresBaseDir, entry.name), { recursive: true, force: true });
+                    }
+                }
+                if (activeFeatureNames.size === 0) {
+                    fs.rmSync(featuresBaseDir, { recursive: true, force: true });
+                }
+            }
+            catch { }
+        }
+        // Universal ambient index
+        const universalPath = path.join(rootTypesDir, 'index.d.ts');
+        if (sharedScope) {
+            fs.writeFileSync(universalPath, `/// <reference path="./shared/common.d.ts" />\n`, 'utf-8');
+        }
+        else {
+            fs.writeFileSync(universalPath, `/// <reference path="./common.d.ts" />\n`, 'utf-8');
+        }
+        // 4. Generate Scoped tsconfig solutions in .testspectra/tsconfig/
+        TsConfigGenerator.writeConfigs(cwd, scopes);
+    }
+}