@testspectra/cli 1.0.70 → 1.1.0

package/dist/generator/__tests__/type-generator.test.js

@@ -0,0 +1,386 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import ts from 'typescript';
+import { TypeGenerator, PLATFORM_HIERARCHY } from '../type-generator.js';
+import { startWatcher } from '../../commands/watch.js';
+import { syncTypesCommand } from '../../commands/sync-types.js';
+describe('TypeGenerator Engine (docs/v2/cli/ambient-types-generator.md)', () => {
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'testspectra-gen-test-'));
+    });
+    afterEach(() => {
+        try {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+        catch { }
+    });
+    it('generates all expected .d.ts files in .testspectra/types/', () => {
+        // Setup minimal workspace
+        fs.mkdirSync(path.join(tmpDir, 'page-objects', 'LoginPage'), { recursive: true });
+        fs.writeFileSync(path.join(tmpDir, 'page-objects', 'LoginPage', 'web.ts'), 'export default class LoginPage {}');
+        fs.mkdirSync(path.join(tmpDir, 'support', 'steps', 'loginAsAdmin'), { recursive: true });
+        fs.writeFileSync(path.join(tmpDir, 'support', 'steps', 'loginAsAdmin', 'web.step.ts'), 'export default async function () {}');
+        fs.mkdirSync(path.join(tmpDir, 'support', 'actions', 'safeClick'), { recursive: true });
+        fs.writeFileSync(path.join(tmpDir, 'support', 'actions', 'safeClick', 'web.action.ts'), 'export default async function () {}');
+        fs.mkdirSync(path.join(tmpDir, 'fixtures'), { recursive: true });
+        fs.writeFileSync(path.join(tmpDir, 'fixtures', 'users.json'), JSON.stringify({ admin: { id: 1 } }));
+        TypeGenerator.generateAll(tmpDir);
+        const typesDir = path.join(tmpDir, '.testspectra', 'types');
+        expect(fs.existsSync(path.join(typesDir, 'web.d.ts'))).toBe(true);
+        expect(fs.existsSync(path.join(typesDir, 'mobile.d.ts'))).toBe(true);
+        expect(fs.existsSync(path.join(typesDir, 'android.d.ts'))).toBe(true);
+        expect(fs.existsSync(path.join(typesDir, 'ios.d.ts'))).toBe(true);
+        expect(fs.existsSync(path.join(typesDir, 'common.d.ts'))).toBe(true);
+        expect(fs.existsSync(path.join(typesDir, 'fixtures.d.ts'))).toBe(true);
+        expect(fs.existsSync(path.join(typesDir, 'index.d.ts'))).toBe(true);
+        const webDts = fs.readFileSync(path.join(typesDir, 'web.d.ts'), 'utf-8');
+        expect(webDts).toContain('declare const LoginPage:');
+        expect(webDts).toContain('"loginAsAdmin":');
+        expect(webDts).toContain('"safeClick":');
+        expect(webDts).toContain('declare const Spectra: TestSpectraActions;');
+        expect(webDts).toContain('declare const Step: TestSpectraSteps;');
+        const fixturesDts = fs.readFileSync(path.join(typesDir, 'fixtures.d.ts'), 'utf-8');
+        expect(fixturesDts).toContain('readonly users: typeof import(');
+    });
+    it('validates zero-import TypeScript test compilation with zero diagnostic errors', () => {
+        // 1. Setup workspace with real TypeScript exports
+        const poDir = path.join(tmpDir, 'page-objects', 'LoginPage');
+        fs.mkdirSync(poDir, { recursive: true });
+        fs.writeFileSync(path.join(poDir, 'web.ts'), 'export default class LoginPage {\n  static username = "#user";\n  static async login() {}\n}');
+        const stepDir = path.join(tmpDir, 'support', 'steps', 'loginAsAdmin');
+        fs.mkdirSync(stepDir, { recursive: true });
+        fs.writeFileSync(path.join(stepDir, 'web.step.ts'), 'export default async function loginAsAdmin(role?: string) {}');
+        const fixDir = path.join(tmpDir, 'fixtures');
+        fs.mkdirSync(fixDir, { recursive: true });
+        fs.writeFileSync(path.join(fixDir, 'users.json'), JSON.stringify({ admin: { id: 101, email: 'admin@test.local' } }));
+        // Generate declarations
+        TypeGenerator.generateAll(tmpDir);
+        const webDtsPath = path.join(tmpDir, '.testspectra', 'types', 'web.d.ts');
+        const fixturesDtsPath = path.join(tmpDir, '.testspectra', 'types', 'fixtures.d.ts');
+        // 2. Write a test file that uses ZERO imports
+        const testFilePath = path.join(tmpDir, 'specs', 'auth.test.ts');
+        fs.mkdirSync(path.dirname(testFilePath), { recursive: true });
+        fs.writeFileSync(testFilePath, `// Zero manual imports!
+async function verifyZeroImport() {
+  const user = Fixture.users.admin.email;
+  const selector = LoginPage.username;
+  await LoginPage.login();
+  await Step.loginAsAdmin("superadmin");
+}
+`);
+        // 3. Compile with TypeScript compiler API
+        const program = ts.createProgram([testFilePath, webDtsPath, fixturesDtsPath], {
+            noEmit: true,
+            target: ts.ScriptTarget.ES2022,
+            module: ts.ModuleKind.NodeNext,
+            moduleResolution: ts.ModuleResolutionKind.NodeNext,
+            skipLibCheck: true,
+            strict: true,
+        });
+        const diagnostics = ts.getPreEmitDiagnostics(program);
+        const relevantErrors = diagnostics.filter((d) => d.file?.fileName === testFilePath);
+        expect(relevantErrors.length).toBe(0);
+    });
+    it('enforces common.d.ts contains only universal common symbols and fixtures', () => {
+        // Create web-specific Page Object and common-specific Page Object
+        fs.mkdirSync(path.join(tmpDir, 'page-objects', 'WebOnlyPage'), { recursive: true });
+        fs.writeFileSync(path.join(tmpDir, 'page-objects', 'WebOnlyPage', 'web.ts'), 'export default class WebOnlyPage {}');
+        fs.mkdirSync(path.join(tmpDir, 'page-objects', 'CommonPage'), { recursive: true });
+        fs.writeFileSync(path.join(tmpDir, 'page-objects', 'CommonPage', 'common.ts'), 'export default class CommonPage {}');
+        // Create web-specific step and common step
+        fs.mkdirSync(path.join(tmpDir, 'support', 'steps', 'webStep'), { recursive: true });
+        fs.writeFileSync(path.join(tmpDir, 'support', 'steps', 'webStep', 'web.step.ts'), 'export default async function () {}');
+        fs.mkdirSync(path.join(tmpDir, 'support', 'steps', 'commonStep'), { recursive: true });
+        fs.writeFileSync(path.join(tmpDir, 'support', 'steps', 'commonStep', 'common.step.ts'), 'export default async function () {}');
+        TypeGenerator.generateAll(tmpDir);
+        const commonDts = fs.readFileSync(path.join(tmpDir, '.testspectra', 'types', 'common.d.ts'), 'utf-8');
+        // Must contain common
+        expect(commonDts).toContain('CommonPage');
+        expect(commonDts).toContain('commonStep');
+        // Must NOT contain web-only symbols
+        expect(commonDts).not.toContain('WebOnlyPage');
+        expect(commonDts).not.toContain('webStep');
+    });
+    it('strictly enforces platform inheritance across Android, iOS, Mobile, Web, and Common', () => {
+        expect(PLATFORM_HIERARCHY.web).toEqual(['web', 'common']);
+        expect(PLATFORM_HIERARCHY.android).toEqual(['android', 'mobile', 'common']);
+        expect(PLATFORM_HIERARCHY.ios).toEqual(['ios', 'mobile', 'common']);
+        expect(PLATFORM_HIERARCHY.mobile).toEqual(['mobile', 'common']);
+        expect(PLATFORM_HIERARCHY.common).toEqual(['common']);
+        // Setup platform specific Page Objects
+        const poDir = path.join(tmpDir, 'page-objects');
+        fs.mkdirSync(path.join(poDir, 'PlatformMatrix'), { recursive: true });
+        fs.writeFileSync(path.join(poDir, 'PlatformMatrix', 'android.ts'), 'export default class AndroidPO {}');
+        fs.writeFileSync(path.join(poDir, 'PlatformMatrix', 'ios.ts'), 'export default class IosPO {}');
+        fs.writeFileSync(path.join(poDir, 'PlatformMatrix', 'web.ts'), 'export default class WebPO {}');
+        fs.mkdirSync(path.join(poDir, 'MobileOnly'), { recursive: true });
+        fs.writeFileSync(path.join(poDir, 'MobileOnly', 'mobile.ts'), 'export default class MobileOnlyPO {}');
+        TypeGenerator.generateAll(tmpDir);
+        const typesDir = path.join(tmpDir, '.testspectra', 'types');
+        const androidDts = fs.readFileSync(path.join(typesDir, 'android.d.ts'), 'utf-8');
+        const iosDts = fs.readFileSync(path.join(typesDir, 'ios.d.ts'), 'utf-8');
+        const mobileDts = fs.readFileSync(path.join(typesDir, 'mobile.d.ts'), 'utf-8');
+        const webDts = fs.readFileSync(path.join(typesDir, 'web.d.ts'), 'utf-8');
+        // Android should resolve android.js and mobile.js, but NOT web.js or ios.js
+        expect(androidDts).toContain('PlatformMatrix/android.js');
+        expect(androidDts).toContain('MobileOnly/mobile.js');
+        expect(androidDts).not.toContain('PlatformMatrix/ios.js');
+        expect(androidDts).not.toContain('PlatformMatrix/web.js');
+        // iOS should resolve ios.js and mobile.js, but NOT web.js or android.js
+        expect(iosDts).toContain('PlatformMatrix/ios.js');
+        expect(iosDts).toContain('MobileOnly/mobile.js');
+        expect(iosDts).not.toContain('PlatformMatrix/android.js');
+        expect(iosDts).not.toContain('PlatformMatrix/web.js');
+        // Mobile should resolve mobile.js, but NOT android.js, ios.js, or web.js
+        expect(mobileDts).toContain('MobileOnly/mobile.js');
+        expect(mobileDts).not.toContain('PlatformMatrix/android.js');
+        expect(mobileDts).not.toContain('PlatformMatrix/ios.js');
+        expect(mobileDts).not.toContain('PlatformMatrix/web.js');
+        // Web should resolve web.js, but NOT mobile.js, android.js, or ios.js
+        expect(webDts).toContain('PlatformMatrix/web.js');
+        expect(webDts).not.toContain('MobileOnly/mobile.js');
+        expect(webDts).not.toContain('PlatformMatrix/android.js');
+        expect(webDts).not.toContain('PlatformMatrix/ios.js');
+    });
+    it('enforces strict ambient scope: excludes raw $ and $$ from global ambient namespace', () => {
+        TypeGenerator.generateAll(tmpDir);
+        const webDts = fs.readFileSync(path.join(tmpDir, '.testspectra', 'types', 'web.d.ts'), 'utf-8');
+        const mobileDts = fs.readFileSync(path.join(tmpDir, '.testspectra', 'types', 'mobile.d.ts'), 'utf-8');
+        // Raw $ and $$ must NOT be declared as global variables to enforce Spectra.get() / Spectra.getAll()
+        expect(webDts).not.toMatch(/declare\s+const\s+\$:/);
+        expect(webDts).not.toMatch(/declare\s+const\s+\$\$: /);
+        expect(mobileDts).not.toMatch(/declare\s+const\s+\$:/);
+        expect(mobileDts).not.toMatch(/declare\s+const\s+\$\$: /);
+    });
+    it('purges declarations when full directory is deleted', () => {
+        const stepDir = path.join(tmpDir, 'support', 'steps', 'loginAsAdmin');
+        fs.mkdirSync(stepDir, { recursive: true });
+        fs.writeFileSync(path.join(stepDir, 'web.step.ts'), 'export default async function () {}');
+        TypeGenerator.generateAll(tmpDir);
+        let webDts = fs.readFileSync(path.join(tmpDir, '.testspectra', 'types', 'web.d.ts'), 'utf-8');
+        expect(webDts).toContain('loginAsAdmin');
+        // Delete entire step folder
+        fs.rmSync(stepDir, { recursive: true, force: true });
+        TypeGenerator.generateAll(tmpDir);
+        webDts = fs.readFileSync(path.join(tmpDir, '.testspectra', 'types', 'web.d.ts'), 'utf-8');
+        expect(webDts).not.toContain('loginAsAdmin');
+    });
+    it('handles partial platform file deletion: purges from web while preserving in mobile/android/ios', () => {
+        const stepDir = path.join(tmpDir, 'support', 'steps', 'loginAsAdmin');
+        fs.mkdirSync(stepDir, { recursive: true });
+        fs.writeFileSync(path.join(stepDir, 'web.step.ts'), 'export default async function () {}');
+        fs.writeFileSync(path.join(stepDir, 'mobile.step.ts'), 'export default async function () {}');
+        TypeGenerator.generateAll(tmpDir);
+        let webDts = fs.readFileSync(path.join(tmpDir, '.testspectra', 'types', 'web.d.ts'), 'utf-8');
+        let mobileDts = fs.readFileSync(path.join(tmpDir, '.testspectra', 'types', 'mobile.d.ts'), 'utf-8');
+        let androidDts = fs.readFileSync(path.join(tmpDir, '.testspectra', 'types', 'android.d.ts'), 'utf-8');
+        let iosDts = fs.readFileSync(path.join(tmpDir, '.testspectra', 'types', 'ios.d.ts'), 'utf-8');
+        expect(webDts).toContain('loginAsAdmin');
+        expect(mobileDts).toContain('loginAsAdmin');
+        expect(androidDts).toContain('loginAsAdmin');
+        expect(iosDts).toContain('loginAsAdmin');
+        // Delete only web.step.ts
+        fs.unlinkSync(path.join(stepDir, 'web.step.ts'));
+        TypeGenerator.generateAll(tmpDir);
+        webDts = fs.readFileSync(path.join(tmpDir, '.testspectra', 'types', 'web.d.ts'), 'utf-8');
+        mobileDts = fs.readFileSync(path.join(tmpDir, '.testspectra', 'types', 'mobile.d.ts'), 'utf-8');
+        androidDts = fs.readFileSync(path.join(tmpDir, '.testspectra', 'types', 'android.d.ts'), 'utf-8');
+        iosDts = fs.readFileSync(path.join(tmpDir, '.testspectra', 'types', 'ios.d.ts'), 'utf-8');
+        // Purged from web
+        expect(webDts).not.toContain('loginAsAdmin');
+        // Preserved in mobile, android, ios
+        expect(mobileDts).toContain('loginAsAdmin');
+        expect(androidDts).toContain('loginAsAdmin');
+        expect(iosDts).toContain('loginAsAdmin');
+    });
+    it('falls back to common.ts when web.ts is deleted inside page object folder', () => {
+        const poDir = path.join(tmpDir, 'page-objects', 'LoginPage');
+        fs.mkdirSync(poDir, { recursive: true });
+        fs.writeFileSync(path.join(poDir, 'web.ts'), 'export default class LoginPageWeb {}');
+        fs.writeFileSync(path.join(poDir, 'common.ts'), 'export default class LoginPageCommon {}');
+        TypeGenerator.generateAll(tmpDir);
+        let webDts = fs.readFileSync(path.join(tmpDir, '.testspectra', 'types', 'web.d.ts'), 'utf-8');
+        expect(webDts).toContain('LoginPage/web.js');
+        // Delete web.ts, leaving common.ts
+        fs.unlinkSync(path.join(poDir, 'web.ts'));
+        TypeGenerator.generateAll(tmpDir);
+        webDts = fs.readFileSync(path.join(tmpDir, '.testspectra', 'types', 'web.d.ts'), 'utf-8');
+        // Still declared, gracefully falling back to common.js
+        expect(webDts).toContain('declare const LoginPage:');
+        expect(webDts).toContain('LoginPage/common.js');
+    });
+    it('manages fixture file lifecycle for json, yaml, and csv files', () => {
+        const fixturesDir = path.join(tmpDir, 'fixtures');
+        fs.mkdirSync(fixturesDir, { recursive: true });
+        fs.writeFileSync(path.join(fixturesDir, 'users.json'), JSON.stringify({ user1: 'test' }));
+        fs.writeFileSync(path.join(fixturesDir, 'config.yaml'), 'env: production\n');
+        fs.writeFileSync(path.join(fixturesDir, 'dataset.csv'), 'id,name\n1,Alpha\n');
+        TypeGenerator.generateAll(tmpDir);
+        let fixturesDts = fs.readFileSync(path.join(tmpDir, '.testspectra', 'types', 'fixtures.d.ts'), 'utf-8');
+        expect(fixturesDts).toContain('readonly users: typeof import(');
+        expect(fixturesDts).toContain('readonly config: string;');
+        expect(fixturesDts).toContain('readonly dataset: string;');
+        // Rename fixtures/users.json to fixtures/accounts.json
+        fs.renameSync(path.join(fixturesDir, 'users.json'), path.join(fixturesDir, 'accounts.json'));
+        TypeGenerator.generateAll(tmpDir);
+        fixturesDts = fs.readFileSync(path.join(tmpDir, '.testspectra', 'types', 'fixtures.d.ts'), 'utf-8');
+        expect(fixturesDts).not.toContain('readonly users:');
+        expect(fixturesDts).toContain('readonly accounts:');
+        // Delete accounts.json and dataset.csv
+        fs.unlinkSync(path.join(fixturesDir, 'accounts.json'));
+        fs.unlinkSync(path.join(fixturesDir, 'dataset.csv'));
+        TypeGenerator.generateAll(tmpDir);
+        fixturesDts = fs.readFileSync(path.join(tmpDir, '.testspectra', 'types', 'fixtures.d.ts'), 'utf-8');
+        expect(fixturesDts).not.toContain('readonly accounts:');
+        expect(fixturesDts).not.toContain('readonly dataset:');
+        expect(fixturesDts).toContain('readonly config: string;');
+    });
+    it('executes spectra sync-types CLI command directly', async () => {
+        fs.mkdirSync(path.join(tmpDir, 'page-objects', 'CartPage'), { recursive: true });
+        fs.writeFileSync(path.join(tmpDir, 'page-objects', 'CartPage', 'web.ts'), 'export default class CartPage {}');
+        await syncTypesCommand({ cwd: tmpDir });
+        const webDts = fs.readFileSync(path.join(tmpDir, '.testspectra', 'types', 'web.d.ts'), 'utf-8');
+        expect(webDts).toContain('declare const CartPage:');
+    });
+    it('updates declarations via watcher in debounced manner within <= 100ms', async () => {
+        const fixturesDir = path.join(tmpDir, 'fixtures');
+        fs.mkdirSync(fixturesDir, { recursive: true });
+        const handle = startWatcher(tmpDir, 30);
+        await new Promise((resolve) => setTimeout(resolve, 50));
+        try {
+            // Add a fixture
+            fs.writeFileSync(path.join(fixturesDir, 'products.json'), JSON.stringify({ item: 1 }));
+            const start = Date.now();
+            let found = false;
+            while (Date.now() - start < 2000) {
+                try {
+                    const fixturesDts = fs.readFileSync(path.join(tmpDir, '.testspectra', 'types', 'fixtures.d.ts'), 'utf-8');
+                    if (fixturesDts.includes('readonly products:')) {
+                        found = true;
+                        break;
+                    }
+                }
+                catch { }
+                await new Promise((resolve) => setTimeout(resolve, 20));
+            }
+            expect(found).toBe(true);
+            const fixturesDts = fs.readFileSync(path.join(tmpDir, '.testspectra', 'types', 'fixtures.d.ts'), 'utf-8');
+            expect(fixturesDts).toContain('readonly products:');
+        }
+        finally {
+            handle.close();
+        }
+    });
+    it('discovers custom shared library directory configured in tsconfig.spectra.shared.json', () => {
+        const customSharedDir = path.join(tmpDir, 'libs', 'shared-e2e');
+        fs.mkdirSync(path.join(customSharedDir, 'page-objects', 'SharedNav'), { recursive: true });
+        fs.writeFileSync(path.join(customSharedDir, 'page-objects', 'SharedNav', 'common.ts'), 'export default class SharedNav {}');
+        // Write tsconfig.spectra.shared.json pointing to custom libs/shared-e2e
+        fs.writeFileSync(path.join(tmpDir, 'tsconfig.spectra.shared.json'), JSON.stringify({
+            include: ['.testspectra/types/shared/common.d.ts', 'libs/shared-e2e/**/*.ts'],
+        }), 'utf-8');
+        const scopes = TypeGenerator.getEntityScopes(tmpDir);
+        const sharedScope = scopes.find((s) => s.isShared);
+        expect(sharedScope).toBeDefined();
+        expect(sharedScope?.dir).toBe(path.resolve(customSharedDir));
+        TypeGenerator.generateAll(tmpDir);
+        const sharedCommonDts = fs.readFileSync(path.join(tmpDir, '.testspectra', 'types', 'shared', 'common.d.ts'), 'utf-8');
+        expect(sharedCommonDts).toContain('declare const SharedNav:');
+    });
+    it('nx monorepo: does NOT generate types from libs/ or packages/ in root scope', () => {
+        // Simulate an Nx monorepo: nx.json at root, page-objects only inside libs/shared-e2e
+        fs.writeFileSync(path.join(tmpDir, 'nx.json'), JSON.stringify({ version: 2 }), 'utf-8');
+        const libsSharedDir = path.join(tmpDir, 'libs', 'shared-e2e');
+        fs.mkdirSync(path.join(libsSharedDir, 'page-objects', 'LibPage'), { recursive: true });
+        fs.writeFileSync(path.join(libsSharedDir, 'page-objects', 'LibPage', 'common.ts'), 'export default class LibPage {}');
+        const pkgDir = path.join(tmpDir, 'packages', 'shared');
+        fs.mkdirSync(path.join(pkgDir, 'page-objects', 'PkgPage'), { recursive: true });
+        fs.writeFileSync(path.join(pkgDir, 'page-objects', 'PkgPage', 'common.ts'), 'export default class PkgPage {}');
+        // Also add a root-level page-object (should appear in root scope)
+        fs.mkdirSync(path.join(tmpDir, 'page-objects', 'RootPage'), { recursive: true });
+        fs.writeFileSync(path.join(tmpDir, 'page-objects', 'RootPage', 'common.ts'), 'export default class RootPage {}');
+        TypeGenerator.generateAll(tmpDir);
+        const rootCommonDts = fs.readFileSync(path.join(tmpDir, '.testspectra', 'types', 'common.d.ts'), 'utf-8');
+        // Root scope must contain the root-level page object
+        expect(rootCommonDts).toContain('RootPage');
+        // Root scope must NOT bleed in types from libs/ or packages/ subdirs
+        expect(rootCommonDts).not.toContain('LibPage');
+        expect(rootCommonDts).not.toContain('PkgPage');
+    });
+    it('nx monorepo: does NOT generate steps/actions from libs/ or packages/ in root scope', () => {
+        fs.writeFileSync(path.join(tmpDir, 'nx.json'), JSON.stringify({ version: 2 }), 'utf-8');
+        // Step inside libs/ — should stay in shared scope, not root scope
+        const libsStepDir = path.join(tmpDir, 'libs', 'shared-e2e', 'support', 'steps', 'sharedLogin');
+        fs.mkdirSync(libsStepDir, { recursive: true });
+        fs.writeFileSync(path.join(libsStepDir, 'common.step.ts'), 'export default async function sharedLogin() {}');
+        // Step inside packages/ — same expectation
+        const pkgStepDir = path.join(tmpDir, 'packages', 'testing', 'support', 'steps', 'pkgStep');
+        fs.mkdirSync(pkgStepDir, { recursive: true });
+        fs.writeFileSync(path.join(pkgStepDir, 'common.step.ts'), 'export default async function pkgStep() {}');
+        // Root-level step (should appear in root scope)
+        const rootStepDir = path.join(tmpDir, 'support', 'steps', 'rootLogin');
+        fs.mkdirSync(rootStepDir, { recursive: true });
+        fs.writeFileSync(path.join(rootStepDir, 'common.step.ts'), 'export default async function rootLogin() {}');
+        TypeGenerator.generateAll(tmpDir);
+        const rootCommonDts = fs.readFileSync(path.join(tmpDir, '.testspectra', 'types', 'common.d.ts'), 'utf-8');
+        // Root step is present
+        expect(rootCommonDts).toContain('rootLogin');
+        // Shared/pkg steps must NOT bleed into root scope
+        expect(rootCommonDts).not.toContain('sharedLogin');
+        expect(rootCommonDts).not.toContain('pkgStep');
+    });
+    it('does not generate features/ scope for templates/, src/, or build/ subdirectories', () => {
+        // Simulate a parent workspace that contains a templates/default/specs/ structure
+        // (e.g., when generateAll is run from cli/ which contains templates/default/)
+        const templatesDefault = path.join(tmpDir, 'templates', 'default');
+        fs.mkdirSync(path.join(templatesDefault, 'specs', 'Suite1', 'TC-001'), { recursive: true });
+        fs.writeFileSync(path.join(templatesDefault, 'specs', 'Suite1', 'TC-001', 'web.test.ts'), 'it("t", () => {});');
+        // Same for src/ and build/
+        const srcSpecs = path.join(tmpDir, 'src', 'app', 'specs');
+        fs.mkdirSync(srcSpecs, { recursive: true });
+        fs.writeFileSync(path.join(srcSpecs, 'foo.ts'), '');
+        const buildTests = path.join(tmpDir, 'build', 'tests');
+        fs.mkdirSync(buildTests, { recursive: true });
+        TypeGenerator.generateAll(tmpDir);
+        // features/default, features/app, features/build must NOT be generated
+        expect(fs.existsSync(path.join(tmpDir, '.testspectra', 'types', 'features', 'default'))).toBe(false);
+        expect(fs.existsSync(path.join(tmpDir, '.testspectra', 'types', 'features', 'app'))).toBe(false);
+        expect(fs.existsSync(path.join(tmpDir, '.testspectra', 'types', 'features', 'build'))).toBe(false);
+    });
+    it('discovers arbitrary custom shared library directory (e.g. core/testing) dynamically without candidate list', () => {
+        // Custom user folder structure: core/testing (shared) + apps/portal/e2e (feature)
+        const customShared = path.join(tmpDir, 'core', 'testing');
+        fs.mkdirSync(path.join(customShared, 'page-objects', 'CoreNav'), { recursive: true });
+        fs.writeFileSync(path.join(customShared, 'page-objects', 'CoreNav', 'common.ts'), 'export default class CoreNav {}');
+        fs.mkdirSync(path.join(customShared, 'support', 'steps', 'coreAuth'), { recursive: true });
+        fs.writeFileSync(path.join(customShared, 'support', 'steps', 'coreAuth', 'common.step.ts'), 'export default async function coreAuth() {}');
+        fs.mkdirSync(path.join(customShared, 'fixtures'), { recursive: true });
+        fs.writeFileSync(path.join(customShared, 'fixtures', 'appConfig.json'), JSON.stringify({ env: 'staging' }));
+        const portalFeature = path.join(tmpDir, 'apps', 'portal', 'e2e');
+        fs.mkdirSync(path.join(portalFeature, 'specs', 'Auth'), { recursive: true });
+        fs.writeFileSync(path.join(portalFeature, 'specs', 'Auth', 'portal.web.test.ts'), 'it("test", () => {});');
+        const scopes = TypeGenerator.getEntityScopes(tmpDir);
+        const sharedScope = scopes.find((s) => s.isShared);
+        const featureScope = scopes.find((s) => !s.isShared && s.name === 'portal');
+        expect(sharedScope).toBeDefined();
+        expect(sharedScope?.dir).toBe(path.resolve(customShared));
+        expect(featureScope).toBeDefined();
+        TypeGenerator.generateAll(tmpDir);
+        // Shared declarations generated dynamically in .testspectra/types/shared/
+        const sharedCommonDts = fs.readFileSync(path.join(tmpDir, '.testspectra', 'types', 'shared', 'common.d.ts'), 'utf-8');
+        expect(sharedCommonDts).toContain('declare const CoreNav:');
+        expect(sharedCommonDts).toContain('coreAuth');
+        // Feature declarations generated dynamically in .testspectra/types/features/portal/
+        const featureCommonDts = fs.readFileSync(path.join(tmpDir, '.testspectra', 'types', 'features', 'portal', 'common.d.ts'), 'utf-8');
+        expect(featureCommonDts).toContain('declare const CoreNav:');
+        expect(featureCommonDts).toContain('coreAuth');
+        // Pure monorepo with zero root entities: root platform .d.ts files must NOT be generated
+        expect(fs.existsSync(path.join(tmpDir, '.testspectra', 'types', 'android.d.ts'))).toBe(false);
+        expect(fs.existsSync(path.join(tmpDir, '.testspectra', 'types', 'ios.d.ts'))).toBe(false);
+        expect(fs.existsSync(path.join(tmpDir, '.testspectra', 'types', 'web.d.ts'))).toBe(false);
+        expect(fs.existsSync(path.join(tmpDir, '.testspectra', 'types', 'common.d.ts'))).toBe(false);
+    });
+});

package/dist/generator/index.d.ts

@@ -0,0 +1,2 @@
+export * from './type-generator.js';
+export * from './tsconfig-generator.js';

package/dist/generator/index.js

@@ -0,0 +1,2 @@
+export * from './type-generator.js';
+export * from './tsconfig-generator.js';

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

@@ -0,0 +1,27 @@
+import { type EntityScope } from './type-generator.js';
+export interface PlatformTsConfigOptions {
+    cwd: string;
+    force?: boolean;
+}
+export declare class TsConfigGenerator {
+    static getRootTsConfig(): object;
+    static getMasterSolutionConfig(references?: {
+        path: string;
+    }[]): object;
+    static getStemExcludes(prefix: string, stems: string[]): string[];
+    static getWebConfig(): object;
+    static getMobileConfig(): object;
+    static getAndroidConfig(): object;
+    static getIosConfig(): object;
+    static getCommonConfig(): object;
+    static getScopedConfig(options: {
+        cwd: string;
+        subConfigDir: string;
+        scopeDir: string;
+        relTypesDir: string;
+        platform: 'web' | 'mobile' | 'android' | 'ios' | 'common';
+    }): object;
+    static getEntityScopes(cwd: string): EntityScope[];
+    static writeConfigs(cwd: string, providedScopes?: EntityScope[]): Record<string, string>;
+    static scaffoldConfigs(cwd: string, force?: boolean): Record<string, string>;
+}