@testspectra/cli 1.0.70 → 1.1.0-rc.1

package/dist/generator/tsconfig-generator.js

@@ -0,0 +1,419 @@
+import fs from 'fs';
+import path from 'path';
+import { discoverEntityScopes } from './type-generator.js';
+export class TsConfigGenerator {
+    static getRootTsConfig() {
+        return {
+            files: [],
+            references: [{ path: './.testspectra/tsconfig.json' }],
+        };
+    }
+    static getMasterSolutionConfig(references) {
+        return {
+            compilerOptions: {
+                target: 'ES2022',
+                module: 'NodeNext',
+                moduleResolution: 'NodeNext',
+                skipLibCheck: true,
+                strict: true,
+                noEmit: true,
+            },
+            files: [],
+            references: references || [
+                { path: './tsconfig/web.json' },
+                { path: './tsconfig/mobile.json' },
+                { path: './tsconfig/android.json' },
+                { path: './tsconfig/ios.json' },
+                { path: './tsconfig/common.json' },
+            ],
+        };
+    }
+    static getStemExcludes(prefix, stems) {
+        const excludes = [];
+        for (const stem of stems) {
+            excludes.push(`${prefix}/**/page-objects/**/${stem}.ts`, `${prefix}/**/support/**/${stem}.*`, `${prefix}/**/global-hooks/**/${stem}.*`, `${prefix}/**/specs/**/hooks/**/${stem}.*`, `${prefix}/**/specs/**/${stem}.test.ts`, `${prefix}/**/${stem}.ts`, `${prefix}/**/${stem}.*`, `${prefix}/**/${stem}.*.ts`, `${prefix}/**/*.${stem}.ts`, `${prefix}/**/*.${stem}.*`, `${prefix}/**/*.${stem}.*.ts`);
+        }
+        return excludes;
+    }
+    static getWebConfig() {
+        return {
+            compilerOptions: {
+                target: 'ES2022',
+                module: 'NodeNext',
+                moduleResolution: 'NodeNext',
+                jsx: 'react-jsx',
+                composite: true,
+                noEmit: true,
+                skipLibCheck: true,
+                strict: true,
+                types: ['node'],
+            },
+            include: [
+                '../types/web.d.ts',
+                '../types/fixtures.d.ts',
+                '../../**/specs/**/*.ts',
+                '../../**/specs/**/*.tsx',
+                '../../**/page-objects/**/*.ts',
+                '../../**/page-objects/**/*.tsx',
+                '../../**/support/**/*.ts',
+                '../../**/support/**/*.tsx',
+                '../../**/global-hooks/**/*.ts',
+                '../../**/global-hooks/**/*.tsx',
+                '../../**/fixtures/**/*.ts',
+                '../../**/fixtures/**/*.json',
+                '../../**/src/**/*.ts',
+                '../../**/src/**/*.tsx',
+                '../../spectra.config.ts',
+            ],
+            exclude: [
+                '../../node_modules',
+                '../../dist',
+                '../../.testspectra/reports',
+                '../../.testspectra/runs',
+                '../../.testspectra/cache',
+                ...TsConfigGenerator.getStemExcludes('../..', ['android', 'ios', 'mobile']),
+            ],
+        };
+    }
+    static getMobileConfig() {
+        return {
+            compilerOptions: {
+                target: 'ES2022',
+                module: 'NodeNext',
+                moduleResolution: 'NodeNext',
+                jsx: 'react-jsx',
+                composite: true,
+                noEmit: true,
+                skipLibCheck: true,
+                strict: true,
+                types: ['node'],
+            },
+            include: [
+                '../types/mobile.d.ts',
+                '../types/fixtures.d.ts',
+                '../../**/specs/**/*.ts',
+                '../../**/specs/**/*.tsx',
+                '../../**/page-objects/**/*.ts',
+                '../../**/page-objects/**/*.tsx',
+                '../../**/support/**/*.ts',
+                '../../**/support/**/*.tsx',
+                '../../**/global-hooks/**/*.ts',
+                '../../**/global-hooks/**/*.tsx',
+                '../../**/fixtures/**/*.ts',
+                '../../**/fixtures/**/*.json',
+                '../../**/src/**/*.ts',
+                '../../**/src/**/*.tsx',
+                '../../spectra.config.ts',
+            ],
+            exclude: [
+                '../../node_modules',
+                '../../dist',
+                '../../.testspectra/reports',
+                '../../.testspectra/runs',
+                '../../.testspectra/cache',
+                ...TsConfigGenerator.getStemExcludes('../..', ['web', 'android', 'ios']),
+            ],
+        };
+    }
+    static getAndroidConfig() {
+        return {
+            compilerOptions: {
+                target: 'ES2022',
+                module: 'NodeNext',
+                moduleResolution: 'NodeNext',
+                jsx: 'react-jsx',
+                composite: true,
+                noEmit: true,
+                skipLibCheck: true,
+                strict: true,
+                types: ['node'],
+            },
+            include: [
+                '../types/android.d.ts',
+                '../types/fixtures.d.ts',
+                '../../**/specs/**/*.ts',
+                '../../**/specs/**/*.tsx',
+                '../../**/page-objects/**/*.ts',
+                '../../**/page-objects/**/*.tsx',
+                '../../**/support/**/*.ts',
+                '../../**/support/**/*.tsx',
+                '../../**/global-hooks/**/*.ts',
+                '../../**/global-hooks/**/*.tsx',
+                '../../**/fixtures/**/*.ts',
+                '../../**/fixtures/**/*.json',
+                '../../**/src/**/*.ts',
+                '../../**/src/**/*.tsx',
+                '../../spectra.config.ts',
+            ],
+            exclude: [
+                '../../node_modules',
+                '../../dist',
+                '../../.testspectra/reports',
+                '../../.testspectra/runs',
+                '../../.testspectra/cache',
+                ...TsConfigGenerator.getStemExcludes('../..', ['web', 'ios']),
+            ],
+        };
+    }
+    static getIosConfig() {
+        return {
+            compilerOptions: {
+                target: 'ES2022',
+                module: 'NodeNext',
+                moduleResolution: 'NodeNext',
+                jsx: 'react-jsx',
+                composite: true,
+                noEmit: true,
+                skipLibCheck: true,
+                strict: true,
+                types: ['node'],
+            },
+            include: [
+                '../types/ios.d.ts',
+                '../types/fixtures.d.ts',
+                '../../**/specs/**/*.ts',
+                '../../**/specs/**/*.tsx',
+                '../../**/page-objects/**/*.ts',
+                '../../**/page-objects/**/*.tsx',
+                '../../**/support/**/*.ts',
+                '../../**/support/**/*.tsx',
+                '../../**/global-hooks/**/*.ts',
+                '../../**/global-hooks/**/*.tsx',
+                '../../**/fixtures/**/*.ts',
+                '../../**/fixtures/**/*.json',
+                '../../**/src/**/*.ts',
+                '../../**/src/**/*.tsx',
+                '../../spectra.config.ts',
+            ],
+            exclude: [
+                '../../node_modules',
+                '../../dist',
+                '../../.testspectra/reports',
+                '../../.testspectra/runs',
+                '../../.testspectra/cache',
+                ...TsConfigGenerator.getStemExcludes('../..', ['web', 'android']),
+            ],
+        };
+    }
+    static getCommonConfig() {
+        return {
+            compilerOptions: {
+                target: 'ES2022',
+                module: 'NodeNext',
+                moduleResolution: 'NodeNext',
+                jsx: 'react-jsx',
+                composite: true,
+                noEmit: true,
+                skipLibCheck: true,
+                strict: true,
+                types: ['node'],
+            },
+            include: [
+                '../types/common.d.ts',
+                '../types/fixtures.d.ts',
+                '../../**/page-objects/**/common.ts',
+                '../../**/page-objects/**/common.tsx',
+                '../../**/support/**/common.*',
+                '../../**/global-hooks/**/common.*',
+                '../../**/specs/**/hooks/**/common.*',
+                '../../**/specs/**/common.test.ts',
+                '../../**/specs/**/common.test.tsx',
+                '../../spectra.config.ts',
+            ],
+            exclude: [
+                '../../node_modules',
+                '../../dist',
+                '../../.testspectra/reports',
+                '../../.testspectra/runs',
+                '../../.testspectra/cache',
+                ...TsConfigGenerator.getStemExcludes('../..', ['web', 'android', 'ios', 'mobile']),
+            ],
+        };
+    }
+    static getScopedConfig(options) {
+        const { subConfigDir, scopeDir, relTypesDir, platform } = options;
+        const relScope = path.relative(subConfigDir, scopeDir).replace(/\\/g, '/');
+        const relSpectraConfig = path
+            .relative(subConfigDir, path.join(options.cwd, 'spectra.config.ts'))
+            .replace(/\\/g, '/');
+        const relNodeModules = path.relative(subConfigDir, path.join(options.cwd, 'node_modules')).replace(/\\/g, '/');
+        const relDist = path.relative(subConfigDir, path.join(options.cwd, 'dist')).replace(/\\/g, '/');
+        const relReports = path
+            .relative(subConfigDir, path.join(options.cwd, '.testspectra', 'reports'))
+            .replace(/\\/g, '/');
+        const relRuns = path.relative(subConfigDir, path.join(options.cwd, '.testspectra', 'runs')).replace(/\\/g, '/');
+        const relCache = path.relative(subConfigDir, path.join(options.cwd, '.testspectra', 'cache')).replace(/\\/g, '/');
+        const platformDts = `${relTypesDir}/${platform}.d.ts`;
+        const fixturesDts = `${relTypesDir}/fixtures.d.ts`;
+        const include = [platformDts, fixturesDts, `${relScope}/**/*.ts`, `${relScope}/**/*.tsx`, relSpectraConfig];
+        const baseExcludes = [relNodeModules, relDist, relReports, relRuns, relCache];
+        const stemMap = {
+            web: ['android', 'ios', 'mobile'],
+            mobile: ['web', 'android', 'ios'],
+            android: ['web', 'ios'],
+            ios: ['web', 'android'],
+            common: ['web', 'android', 'ios', 'mobile'],
+        };
+        const platformExcludes = TsConfigGenerator.getStemExcludes(relScope, stemMap[platform]);
+        return {
+            compilerOptions: {
+                target: 'ES2022',
+                module: 'NodeNext',
+                moduleResolution: 'NodeNext',
+                composite: true,
+                noEmit: true,
+                skipLibCheck: true,
+                strict: true,
+                types: ['node'],
+            },
+            include,
+            exclude: [...baseExcludes, ...platformExcludes],
+        };
+    }
+    static getEntityScopes(cwd) {
+        return discoverEntityScopes(cwd);
+    }
+    static writeConfigs(cwd, providedScopes) {
+        const tsconfigBaseDir = path.join(cwd, '.testspectra', 'tsconfig');
+        if (!fs.existsSync(tsconfigBaseDir)) {
+            fs.mkdirSync(tsconfigBaseDir, { recursive: true });
+        }
+        const writtenFiles = {};
+        const references = [];
+        // 1. Always generate root platform configs (for standalone and IDE fallback)
+        const platformConfigs = {
+            'web.json': this.getWebConfig(),
+            'mobile.json': this.getMobileConfig(),
+            'android.json': this.getAndroidConfig(),
+            'ios.json': this.getIosConfig(),
+            'common.json': this.getCommonConfig(),
+        };
+        for (const [filename, contentObj] of Object.entries(platformConfigs)) {
+            const filePath = path.join(tsconfigBaseDir, filename);
+            const jsonContent = JSON.stringify(contentObj, null, 2) + '\n';
+            fs.writeFileSync(filePath, jsonContent, 'utf-8');
+            writtenFiles[filename] = filePath;
+        }
+        // 2. Scopes handling (Monorepo shared & feature sub-configs)
+        const scopes = providedScopes || 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'));
+        if (!hasScopes || hasRootEntities) {
+            for (const filename of Object.keys(platformConfigs)) {
+                references.push({ path: `./tsconfig/${filename}` });
+            }
+        }
+        const platforms = [
+            'web',
+            'mobile',
+            'android',
+            'ios',
+            'common',
+        ];
+        if (sharedScope) {
+            const sharedTsConfigDir = path.join(tsconfigBaseDir, 'shared');
+            if (!fs.existsSync(sharedTsConfigDir)) {
+                fs.mkdirSync(sharedTsConfigDir, { recursive: true });
+            }
+            for (const p of platforms) {
+                const conf = this.getScopedConfig({
+                    cwd,
+                    subConfigDir: sharedTsConfigDir,
+                    scopeDir: sharedScope.dir,
+                    relTypesDir: '../../types/shared',
+                    platform: p,
+                });
+                const filePath = path.join(sharedTsConfigDir, `${p}.json`);
+                fs.writeFileSync(filePath, JSON.stringify(conf, null, 2) + '\n', 'utf-8');
+                writtenFiles[`shared/${p}.json`] = filePath;
+                references.push({ path: `./tsconfig/shared/${p}.json` });
+            }
+        }
+        else {
+            const sharedTsConfigDir = path.join(tsconfigBaseDir, 'shared');
+            if (fs.existsSync(sharedTsConfigDir)) {
+                try {
+                    fs.rmSync(sharedTsConfigDir, { recursive: true, force: true });
+                }
+                catch { }
+            }
+        }
+        const activeFeatureNames = new Set(featureScopes.map((f) => f.name));
+        for (const feat of featureScopes) {
+            const featTsConfigDir = path.join(tsconfigBaseDir, 'features', feat.name);
+            if (!fs.existsSync(featTsConfigDir)) {
+                fs.mkdirSync(featTsConfigDir, { recursive: true });
+            }
+            for (const p of platforms) {
+                const conf = this.getScopedConfig({
+                    cwd,
+                    subConfigDir: featTsConfigDir,
+                    scopeDir: feat.dir,
+                    relTypesDir: `../../../types/features/${feat.name}`,
+                    platform: p,
+                });
+                const filePath = path.join(featTsConfigDir, `${p}.json`);
+                fs.writeFileSync(filePath, JSON.stringify(conf, null, 2) + '\n', 'utf-8');
+                writtenFiles[`features/${feat.name}/${p}.json`] = filePath;
+                references.push({ path: `./tsconfig/features/${feat.name}/${p}.json` });
+            }
+        }
+        // Clean up any stale feature tsconfig folders that no longer exist
+        const featuresBaseDir = path.join(tsconfigBaseDir, '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 { }
+        }
+        // 3. Write Master Orchestrator: .testspectra/tsconfig.json
+        const masterConfigPath = path.join(cwd, '.testspectra', 'tsconfig.json');
+        const masterConfigContent = JSON.stringify(this.getMasterSolutionConfig(references), null, 2) + '\n';
+        fs.writeFileSync(masterConfigPath, masterConfigContent, 'utf-8');
+        writtenFiles['.testspectra/tsconfig.json'] = masterConfigPath;
+        // Clean up any legacy root tsconfig.spectra.json
+        const legacySpectraPath = path.join(cwd, 'tsconfig.spectra.json');
+        if (fs.existsSync(legacySpectraPath)) {
+            try {
+                fs.unlinkSync(legacySpectraPath);
+            }
+            catch { }
+        }
+        return writtenFiles;
+    }
+    static scaffoldConfigs(cwd, force = false) {
+        const rootTsConfigPath = path.join(cwd, 'tsconfig.json');
+        const writtenFiles = {};
+        if (!fs.existsSync(rootTsConfigPath) || force) {
+            fs.writeFileSync(rootTsConfigPath, JSON.stringify(this.getRootTsConfig(), null, 2) + '\n', 'utf-8');
+            writtenFiles['tsconfig.json'] = rootTsConfigPath;
+        }
+        else {
+            try {
+                const existing = JSON.parse(fs.readFileSync(rootTsConfigPath, 'utf-8'));
+                if (!existing.references || !Array.isArray(existing.references)) {
+                    existing.references = [];
+                }
+                existing.references = existing.references.filter((r) => r.path !== './tsconfig.spectra.json');
+                if (!existing.references.some((r) => r.path === './.testspectra/tsconfig.json')) {
+                    existing.references.push({ path: './.testspectra/tsconfig.json' });
+                }
+                fs.writeFileSync(rootTsConfigPath, JSON.stringify(existing, null, 2) + '\n', 'utf-8');
+            }
+            catch { }
+        }
+        const subConfigs = this.writeConfigs(cwd);
+        Object.assign(writtenFiles, subConfigs);
+        return writtenFiles;
+    }
+}

package/dist/generator/type-generator.d.ts

@@ -0,0 +1,59 @@
+export type PlatformTarget = 'web' | 'android' | 'ios' | 'mobile' | 'common';
+export declare const PLATFORM_HIERARCHY: Record<PlatformTarget, string[]>;
+export interface EntityScope {
+    name: string;
+    dir: string;
+    isShared: boolean;
+}
+/**
+ * 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 declare function discoverEntityScopes(cwd: string): EntityScope[];
+/**
+ * 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 declare function isComponentTestingProject(cwd: string): boolean;
+export declare class TypeGenerator {
+    /**
+     * Main entry point to generate all ambient type declarations.
+     */
+    static generateAll(cwd: string): void;
+    /**
+     * 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 syncEnvDeclaration(cwd: string): Promise<void>;
+    /**
+     * Discovers all feature directories and shared library directories.
+     * Returns a map of scope -> base directory
+     */
+    static getEntityScopes(cwd: string): EntityScope[];
+    static getPageObjectsDirsForScope(scopeDir: string, sharedDir?: string): string[];
+    static getEntityDirsForScope(entityType: 'actions' | 'steps' | 'fixtures', scopeDir: string, sharedDir?: string): string[];
+    static generateDeclarationsForScope(cwd: string, outputTypesDir: string, scopeDir: string, sharedDir?: string, rootTypesDir?: string): Record<PlatformTarget, string>;
+    static generateFixturesDeclarationForScope(cwd: string, outputTypesDir: string, scopeDir: string, sharedDir?: string): string;
+    /**
+     * 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: Record<string, string>): string;
+    static writeDeclarationFiles(cwd: string): void;
+}