@qwik-custom-elements/core 1.0.0

package/dist/generator.js

@@ -0,0 +1,720 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+export class GenerationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'GenerationError';
+        this.code = code;
+    }
+}
+const SSR_UNSUPPORTED_FALLBACK_CODE = 'QCE_SSR_UNSUPPORTED_FALLBACK';
+const PACKAGE_NAME_CEM_DISCOVERY_CANDIDATES = [
+    'custom-elements.json',
+    path.join('dist', 'custom-elements.json'),
+];
+const require = createRequire(import.meta.url);
+export async function generateFromConfig(config, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const requestedProjectIds = options.targetProjectIds ?? [];
+    const requestedProjectIdSet = new Set(requestedProjectIds);
+    const sortedProjects = [...config.projects].sort((a, b) => a.id.localeCompare(b.id));
+    for (const requestedProjectId of requestedProjectIds) {
+        if (!config.projects.some((project) => project.id === requestedProjectId)) {
+            throw new GenerationError('QCE_PROJECT_TARGET_UNKNOWN', `Unknown project id "${requestedProjectId}" requested via CLI targeting.`);
+        }
+    }
+    const filteredProjects = requestedProjectIdSet.size === 0
+        ? sortedProjects
+        : sortedProjects.filter((project) => requestedProjectIdSet.has(project.id));
+    validateProjectOutputSafety(filteredProjects, cwd);
+    const projectResults = config.parallel === true
+        ? await generateProjectsInParallel(filteredProjects, cwd, config.dryRun === true)
+        : await generateProjectsSequentially(filteredProjects, cwd, config.dryRun === true);
+    const skippedProjectResults = requestedProjectIdSet.size === 0
+        ? []
+        : sortedProjects
+            .filter((project) => !requestedProjectIdSet.has(project.id))
+            .map((project) => createSkippedProjectResult(project, cwd));
+    return {
+        dryRun: config.dryRun === true,
+        projects: [...projectResults, ...skippedProjectResults].sort((a, b) => a.projectId.localeCompare(b.projectId)),
+    };
+}
+async function generateProjectsSequentially(projects, cwd, dryRun) {
+    const projectResults = [];
+    for (const project of projects) {
+        const result = await generateProject(project, cwd, dryRun);
+        projectResults.push(result);
+    }
+    return projectResults;
+}
+async function generateProjectsInParallel(projects, cwd, dryRun) {
+    const settledResults = await Promise.allSettled(projects.map((project) => generateProject(project, cwd, dryRun)));
+    const projectResults = [];
+    const failures = [];
+    for (let index = 0; index < settledResults.length; index += 1) {
+        const settledResult = settledResults[index];
+        const project = projects[index];
+        if (settledResult.status === 'fulfilled') {
+            projectResults.push(settledResult.value);
+            continue;
+        }
+        failures.push({
+            projectId: project.id,
+            error: settledResult.reason,
+        });
+    }
+    if (failures.length > 0) {
+        const details = failures
+            .map(({ projectId, error }) => {
+            const errorCode = error instanceof GenerationError ? error.code : 'QCE_UNEXPECTED';
+            const errorMessage = toErrorMessage(error);
+            return `${projectId} (${errorCode}): ${errorMessage}`;
+        })
+            .join(' | ');
+        throw new GenerationError('QCE_PARALLEL_PROJECT_FAILURES', `Parallel generation failed for ${failures.length} project(s): ${details}`);
+    }
+    return projectResults;
+}
+async function generateProject(project, cwd, dryRun) {
+    const startedAtMs = Date.now();
+    const adapterModule = await loadAdapterModule(project.adapterPackage, cwd);
+    validateAdapterSourceCompatibility(project, adapterModule);
+    await validateAdapterProject(project, adapterModule);
+    const runtimeImportResult = await resolveAdapterRuntimeImports(project, adapterModule, cwd);
+    const { runtimeImports } = runtimeImportResult;
+    const sourcePath = resolveProjectSourcePath(project.id, project.source, cwd);
+    const outDirPath = path.resolve(cwd, project.outDir);
+    const componentDefinitions = await readComponentDefinitionsFromCem(sourcePath);
+    const augmentedComponentDefinitions = await augmentAdapterComponentDefinitions(componentDefinitions, adapterModule, runtimeImports, outDirPath, cwd);
+    const componentTags = augmentedComponentDefinitions.map((componentDefinition) => componentDefinition.tagName);
+    const adapterSsrCapabilities = resolveAdapterSsrCapabilities(adapterModule);
+    const ssrProbe = await probeProjectSsrAvailability(project, adapterModule, runtimeImports);
+    const adapterPlannedWrites = await createAdapterPlannedWrites(project, outDirPath, augmentedComponentDefinitions, adapterModule, runtimeImports, ssrProbe.available);
+    const plannedWrites = createPlannedWrites(project.id, outDirPath, augmentedComponentDefinitions, adapterModule, ssrProbe.available, adapterPlannedWrites);
+    const observedErrorCodes = [...runtimeImportResult.observedErrorCodes];
+    if (!ssrProbe.available) {
+        observedErrorCodes.push(SSR_UNSUPPORTED_FALLBACK_CODE);
+    }
+    observedErrorCodes.sort((a, b) => a.localeCompare(b));
+    if (!dryRun) {
+        await mkdir(outDirPath, { recursive: true });
+        for (const plannedWrite of plannedWrites) {
+            await writeFile(plannedWrite.path, plannedWrite.content, 'utf8');
+        }
+    }
+    const hasClientOnlySuccessSignal = runtimeImportResult.clientOnlyMode === true &&
+        !ssrProbe.available &&
+        plannedWrites.length > 0;
+    const generatedIndexPath = path.join(outDirPath, 'index.ts');
+    const durationMs = Date.now() - startedAtMs;
+    return {
+        projectId: project.id,
+        status: 'success',
+        durationMs,
+        adapterPackage: project.adapterPackage,
+        sourcePath,
+        outDirPath,
+        generatedIndexPath,
+        componentTags,
+        plannedWrites,
+        wroteFiles: !dryRun,
+        ssrCapabilities: {
+            available: ssrProbe.available,
+            supportsSsrProbe: adapterSsrCapabilities.supportsSsrProbe,
+            ssrRuntimeSubpath: adapterSsrCapabilities.ssrRuntimeSubpath,
+            ...(hasClientOnlySuccessSignal ? { clientOnlyMode: true } : {}),
+        },
+        observedErrorCodes,
+    };
+}
+function resolveAdapterSsrCapabilities(adapterModule) {
+    const metadata = adapterModule != null && typeof adapterModule.metadata === 'object'
+        ? adapterModule.metadata
+        : undefined;
+    const supportsSsrProbe = metadata?.supportsSsrProbe === true;
+    const ssrRuntimeSubpath = typeof metadata?.ssrRuntimeSubpath === 'string'
+        ? metadata.ssrRuntimeSubpath
+        : null;
+    return {
+        supportsSsrProbe,
+        ssrRuntimeSubpath,
+    };
+}
+async function augmentAdapterComponentDefinitions(componentDefinitions, adapterModule, runtimeImports, outDirPath, cwd) {
+    const augmentFn = adapterModule != null &&
+        typeof adapterModule.augmentComponentDefinitions === 'function'
+        ? adapterModule.augmentComponentDefinitions
+        : undefined;
+    if (augmentFn == null) {
+        return componentDefinitions;
+    }
+    const resolvedRuntimeImports = resolveProbeRuntimeImports(runtimeImports, outDirPath, cwd);
+    const result = (await augmentFn({
+        componentDefinitions,
+        runtimeImports: resolvedRuntimeImports,
+    }));
+    if (!Array.isArray(result)) {
+        return componentDefinitions;
+    }
+    return result;
+}
+function resolveProbeRuntimeImports(runtimeImports, outDirPath, cwd) {
+    if (runtimeImports == null)
+        return undefined;
+    const hydrateImport = runtimeImports.hydrateImport;
+    if (typeof hydrateImport !== 'string' || hydrateImport.trim() === '') {
+        return runtimeImports;
+    }
+    const resolved = tryResolveSpecifier(hydrateImport, outDirPath, cwd);
+    if (resolved === hydrateImport)
+        return runtimeImports;
+    return { ...runtimeImports, hydrateImport: resolved };
+}
+function tryResolveSpecifier(specifier, outDirPath, cwd) {
+    if (specifier.startsWith('file://') ||
+        specifier.startsWith('.') ||
+        path.isAbsolute(specifier)) {
+        return specifier;
+    }
+    for (const dir of [outDirPath, cwd]) {
+        try {
+            const resolved = createRequire(path.join(dir, '__qce_probe__.cjs')).resolve(specifier);
+            return pathToFileURL(resolved).href;
+        }
+        catch {
+            // try next candidate
+        }
+    }
+    return specifier;
+}
+async function probeProjectSsrAvailability(project, adapterModule, runtimeImports) {
+    const probeSSR = adapterModule != null && typeof adapterModule.probeSSR === 'function'
+        ? adapterModule.probeSSR
+        : undefined;
+    if (probeSSR == null) {
+        return { available: false };
+    }
+    const probeResult = (await probeSSR({
+        projectId: project.id,
+        source: project.source,
+        adapterOptions: project.adapterOptions ?? {},
+        runtimeImports,
+    }));
+    if (probeResult != null && probeResult.available === true) {
+        return { available: true };
+    }
+    return { available: false };
+}
+async function resolveAdapterRuntimeImports(project, adapterModule, cwd) {
+    const resolveRuntimeImports = adapterModule != null &&
+        typeof adapterModule.resolveRuntimeImports === 'function'
+        ? adapterModule.resolveRuntimeImports
+        : undefined;
+    if (resolveRuntimeImports == null) {
+        return {
+            runtimeImports: undefined,
+            observedErrorCodes: [],
+            clientOnlyMode: false,
+        };
+    }
+    try {
+        const resolvedRuntimeImports = await resolveRuntimeImports({
+            projectId: project.id,
+            cwd,
+            runtimeResolution: {
+                resolveSourcePackageRoot: (packageName) => resolvePackageRootForProject(project.id, { type: 'PACKAGE_NAME', packageName }, cwd),
+                resolveImportSpecifier: (specifier, packageRoot) => resolveRuntimeImportSpecifier(specifier, cwd, packageRoot),
+            },
+            source: project.source,
+            adapterOptions: project.adapterOptions ?? {},
+        });
+        const observedErrorCodes = extractObservedRuntimeImportErrorCodes(resolvedRuntimeImports);
+        const runtimeImports = extractResolvedRuntimeImports(resolvedRuntimeImports);
+        const clientOnlyMode = extractClientOnlyModeSignal(resolvedRuntimeImports);
+        return {
+            runtimeImports,
+            observedErrorCodes,
+            clientOnlyMode,
+        };
+    }
+    catch (error) {
+        if (error instanceof GenerationError) {
+            throw error;
+        }
+        const errorCode = typeof error === 'object' &&
+            error !== null &&
+            'code' in error &&
+            typeof error.code === 'string'
+            ? error.code
+            : 'QCE_ADAPTER_RUNTIME_IMPORTS_INVALID';
+        throw new GenerationError(errorCode, toErrorMessage(error));
+    }
+}
+function extractObservedRuntimeImportErrorCodes(resolvedRuntimeImports) {
+    if (resolvedRuntimeImports == null ||
+        typeof resolvedRuntimeImports !== 'object' ||
+        !('observedErrorCodes' in resolvedRuntimeImports) ||
+        !Array.isArray(resolvedRuntimeImports.observedErrorCodes)) {
+        return [];
+    }
+    return resolvedRuntimeImports.observedErrorCodes.filter((errorCode) => typeof errorCode === 'string');
+}
+function extractResolvedRuntimeImports(resolvedRuntimeImports) {
+    if (resolvedRuntimeImports == null ||
+        typeof resolvedRuntimeImports !== 'object') {
+        return undefined;
+    }
+    if ('runtimeImports' in resolvedRuntimeImports &&
+        resolvedRuntimeImports.runtimeImports != null &&
+        typeof resolvedRuntimeImports.runtimeImports === 'object') {
+        return resolvedRuntimeImports.runtimeImports;
+    }
+    return resolvedRuntimeImports;
+}
+function extractClientOnlyModeSignal(resolvedRuntimeImports) {
+    if (resolvedRuntimeImports == null ||
+        typeof resolvedRuntimeImports !== 'object' ||
+        !('clientOnlyMode' in resolvedRuntimeImports)) {
+        return false;
+    }
+    return resolvedRuntimeImports.clientOnlyMode === true;
+}
+function validateAdapterSourceCompatibility(project, adapterModule) {
+    const metadata = adapterModule != null && typeof adapterModule.metadata === 'object'
+        ? adapterModule.metadata
+        : undefined;
+    const supportedSourceTypes = metadata != null && Array.isArray(metadata.supportedSourceTypes)
+        ? metadata.supportedSourceTypes
+        : ['CEM'];
+    const isSourceSupported = supportedSourceTypes.some((supportedSourceType) => supportedSourceType === project.source.type);
+    if (!isSourceSupported) {
+        throw new GenerationError('QCE_ADAPTER_SOURCE_INCOMPATIBLE', `Project "${project.id}" source type "${project.source.type}" is not supported by adapter "${project.adapterPackage}".`);
+    }
+}
+async function validateAdapterProject(project, adapterModule) {
+    const validateProject = adapterModule != null && typeof adapterModule.validateProject === 'function'
+        ? adapterModule.validateProject
+        : undefined;
+    if (validateProject == null) {
+        return;
+    }
+    try {
+        await validateProject({
+            projectId: project.id,
+            source: project.source,
+            adapterOptions: project.adapterOptions ?? {},
+        });
+    }
+    catch (error) {
+        if (error instanceof GenerationError) {
+            throw error;
+        }
+        const errorCode = typeof error === 'object' &&
+            error !== null &&
+            'code' in error &&
+            typeof error.code === 'string'
+            ? error.code
+            : 'QCE_ADAPTER_PROJECT_INVALID';
+        throw new GenerationError(errorCode, toErrorMessage(error));
+    }
+}
+async function loadAdapterModule(adapterPackage, cwd) {
+    if (isRelativeOrAbsoluteSpecifier(adapterPackage)) {
+        const resolvedPath = path.isAbsolute(adapterPackage)
+            ? adapterPackage
+            : path.resolve(cwd, adapterPackage);
+        return (await import(pathToFileURL(resolvedPath).href));
+    }
+    try {
+        return (await import(adapterPackage));
+    }
+    catch (error) {
+        const workspaceLocalPath = resolveWorkspaceLocalAdapterPath(adapterPackage);
+        if (workspaceLocalPath == null) {
+            throw new GenerationError('QCE_ADAPTER_LOAD_FAILED', `Could not load adapter package "${adapterPackage}": ${toErrorMessage(error)}`);
+        }
+        try {
+            return (await import(pathToFileURL(workspaceLocalPath).href));
+        }
+        catch (workspaceError) {
+            throw new GenerationError('QCE_ADAPTER_LOAD_FAILED', `Could not load adapter package "${adapterPackage}": ${toErrorMessage(workspaceError)}`);
+        }
+    }
+}
+function isRelativeOrAbsoluteSpecifier(specifier) {
+    return (specifier.startsWith('.') ||
+        specifier.startsWith('/') ||
+        path.isAbsolute(specifier));
+}
+function resolveWorkspaceLocalAdapterPath(adapterPackage) {
+    if (!adapterPackage.startsWith('@qwik-custom-elements/')) {
+        return undefined;
+    }
+    const [scope, packageDirectoryName, ...subpathSegments] = adapterPackage.split('/');
+    if (scope !== '@qwik-custom-elements' || !packageDirectoryName) {
+        return undefined;
+    }
+    const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', packageDirectoryName);
+    const packageJsonPath = path.join(packageRoot, 'package.json');
+    const exportKey = subpathSegments.length === 0 ? '.' : `./${subpathSegments.join('/')}`;
+    try {
+        const packageJson = JSON.parse(require('node:fs').readFileSync(packageJsonPath, 'utf8'));
+        const exportTarget = resolvePackageExportImportTarget(packageJson.exports?.[exportKey]);
+        if (typeof exportTarget === 'string') {
+            return path.resolve(packageRoot, exportTarget);
+        }
+    }
+    catch {
+        // Fall through to legacy dist-path heuristics.
+    }
+    const subpath = subpathSegments.length === 0
+        ? path.join('dist', 'index.js')
+        : path.join('dist', subpathSegments.join('/'));
+    const subpathWithExtension = path.extname(subpath) === '' ? `${subpath}.js` : subpath;
+    return path.resolve(packageRoot, subpathWithExtension);
+}
+function resolvePackageExportImportTarget(exportValue) {
+    if (typeof exportValue === 'string') {
+        return exportValue;
+    }
+    if (exportValue == null || typeof exportValue !== 'object') {
+        return undefined;
+    }
+    const exportRecord = exportValue;
+    if (typeof exportRecord.import === 'string') {
+        return exportRecord.import;
+    }
+    if (typeof exportRecord.default === 'string') {
+        return exportRecord.default;
+    }
+    return undefined;
+}
+function createSkippedProjectResult(project, cwd) {
+    const outDirPath = path.resolve(cwd, project.outDir);
+    return {
+        projectId: project.id,
+        status: 'skipped',
+        durationMs: 0,
+        adapterPackage: project.adapterPackage,
+        sourcePath: resolveSkippedProjectSourcePath(project.source, cwd),
+        outDirPath,
+        generatedIndexPath: path.join(outDirPath, 'index.ts'),
+        componentTags: [],
+        plannedWrites: [],
+        wroteFiles: false,
+        ssrCapabilities: {
+            available: false,
+            supportsSsrProbe: false,
+            ssrRuntimeSubpath: null,
+        },
+        observedErrorCodes: [],
+    };
+}
+function resolveSkippedProjectSourcePath(source, cwd) {
+    if (source.type === 'CEM') {
+        return path.resolve(cwd, source.path);
+    }
+    return source.cemPath == null
+        ? `package:${source.packageName}`
+        : `package:${source.packageName}#${source.cemPath}`;
+}
+function resolveProjectSourcePath(projectId, source, cwd) {
+    if (source.type === 'CEM') {
+        return path.resolve(cwd, source.path);
+    }
+    const packageRoot = resolvePackageRootForProject(projectId, source, cwd);
+    if (source.cemPath != null) {
+        return resolvePackageNameOverrideCemPath(projectId, source, packageRoot);
+    }
+    return discoverPackageNameCemPath(projectId, source, packageRoot);
+}
+function resolvePackageRootForProject(projectId, source, cwd) {
+    const packageSpecifier = `${source.packageName}/package.json`;
+    try {
+        const packageJsonPath = require.resolve(packageSpecifier, { paths: [cwd] });
+        return path.dirname(packageJsonPath);
+    }
+    catch (error) {
+        throw new GenerationError('QCE_PACKAGE_NAME_RESOLVE_FAILED', `Project "${projectId}" could not resolve source package "${source.packageName}" from ${cwd}: ${toErrorMessage(error)}`);
+    }
+}
+function resolvePackageNameOverrideCemPath(projectId, source, packageRoot) {
+    const cemPath = source.cemPath;
+    if (path.isAbsolute(cemPath)) {
+        throw new GenerationError('QCE_PACKAGE_NAME_CEM_PATH_ABSOLUTE', `Project "${projectId}" PACKAGE_NAME source.cemPath must be relative to package root; received absolute path "${cemPath}".`);
+    }
+    const resolvedCemPath = path.resolve(packageRoot, cemPath);
+    const relativeToPackageRoot = path.relative(packageRoot, resolvedCemPath);
+    const resolvesOutsidePackageRoot = relativeToPackageRoot === '..' ||
+        relativeToPackageRoot.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relativeToPackageRoot);
+    if (resolvesOutsidePackageRoot) {
+        throw new GenerationError('QCE_PACKAGE_NAME_CEM_PATH_OUTSIDE_PACKAGE', `Project "${projectId}" PACKAGE_NAME source.cemPath resolves outside package root: "${cemPath}".`);
+    }
+    return resolvedCemPath;
+}
+function discoverPackageNameCemPath(projectId, source, packageRoot) {
+    const candidatePaths = PACKAGE_NAME_CEM_DISCOVERY_CANDIDATES.map((candidate) => path.resolve(packageRoot, candidate));
+    const existingCandidates = [];
+    for (const candidatePath of candidatePaths) {
+        if (existsSync(candidatePath)) {
+            existingCandidates.push(candidatePath);
+        }
+    }
+    if (existingCandidates.length === 1) {
+        return existingCandidates[0];
+    }
+    if (existingCandidates.length === 0) {
+        throw new GenerationError('QCE_PACKAGE_NAME_CEM_NOT_FOUND', `Project "${projectId}" could not discover a CEM file for source package "${source.packageName}". Checked: ${PACKAGE_NAME_CEM_DISCOVERY_CANDIDATES.join(', ')}. Set source.cemPath to the manifest path relative to the package root.`);
+    }
+    throw new GenerationError('QCE_PACKAGE_NAME_CEM_AMBIGUOUS', `Project "${projectId}" discovered multiple CEM candidates for source package "${source.packageName}": ${existingCandidates.join(', ')}. Set source.cemPath to disambiguate.`);
+}
+function resolveRuntimeImportSpecifier(specifier, cwd, packageRoot) {
+    const resolver = specifier.startsWith('.') && packageRoot != null
+        ? createRequire(path.join(packageRoot, 'package.json'))
+        : createRequire(path.resolve(cwd, '__qce_runtime_resolution__.cjs'));
+    return resolver.resolve(specifier);
+}
+function validateProjectOutputSafety(projects, workspaceRoot) {
+    const outputDirOwners = new Map();
+    for (const project of projects) {
+        const resolvedOutDir = path.resolve(workspaceRoot, project.outDir);
+        validateResolvedOutDirWithinWorkspace(project, workspaceRoot, resolvedOutDir);
+        const existingOwner = outputDirOwners.get(resolvedOutDir);
+        if (existingOwner != null) {
+            throw new GenerationError('QCE_OUTPUT_PATH_COLLISION', `Projects "${existingOwner}" and "${project.id}" resolve to the same output directory: ${resolvedOutDir}`);
+        }
+        outputDirOwners.set(resolvedOutDir, project.id);
+    }
+}
+function validateResolvedOutDirWithinWorkspace(project, workspaceRoot, resolvedOutDir) {
+    const relativeToWorkspace = path.relative(workspaceRoot, resolvedOutDir);
+    const resolvesOutsideWorkspace = relativeToWorkspace === '..' ||
+        relativeToWorkspace.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relativeToWorkspace);
+    if (resolvesOutsideWorkspace) {
+        throw new GenerationError('QCE_OUTPUT_OUTSIDE_WORKSPACE', `Project "${project.id}" output path resolves outside workspace root: ${project.outDir}`);
+    }
+}
+function createPlannedWrites(_projectId, _outDirPath, _componentDefinitions, _adapterModule, _ssrAvailable, adapterPlannedWrites = []) {
+    return adapterPlannedWrites;
+}
+async function createAdapterPlannedWrites(project, outDirPath, componentDefinitions, adapterModule, runtimeImports, ssrAvailable) {
+    const createGeneratedOutput = adapterModule != null &&
+        typeof adapterModule.createGeneratedOutput === 'function'
+        ? adapterModule.createGeneratedOutput
+        : undefined;
+    if (createGeneratedOutput == null) {
+        throw new GenerationError('QCE_ADAPTER_GENERATION_CONTRACT_REQUIRED', `Project "${project.id}" adapter "${project.adapterPackage}" must export createGeneratedOutput() as its primary generated-output contract.`);
+    }
+    try {
+        const plannedWrites = (await createGeneratedOutput({
+            projectId: project.id,
+            libraryName: project.libraryName,
+            source: project.source,
+            adapterOptions: project.adapterOptions ?? {},
+            runtimeImports,
+            componentDefinitions,
+            ssrAvailable,
+        }));
+        if (!Array.isArray(plannedWrites)) {
+            return [];
+        }
+        return plannedWrites
+            .filter((plannedWrite) => plannedWrite != null &&
+            typeof plannedWrite === 'object' &&
+            'relativePath' in plannedWrite &&
+            typeof plannedWrite.relativePath === 'string' &&
+            'content' in plannedWrite &&
+            typeof plannedWrite.content === 'string')
+            .map((plannedWrite) => ({
+            path: path.join(outDirPath, plannedWrite.relativePath),
+            content: plannedWrite.content,
+        }));
+    }
+    catch (error) {
+        const errorCode = typeof error === 'object' &&
+            error !== null &&
+            'code' in error &&
+            typeof error.code === 'string'
+            ? error.code
+            : 'QCE_ADAPTER_PLANNED_WRITES_INVALID';
+        throw new GenerationError(errorCode, toErrorMessage(error));
+    }
+}
+async function readComponentDefinitionsFromCem(sourcePath) {
+    let parsed;
+    try {
+        const rawText = await readFile(sourcePath, 'utf8');
+        parsed = JSON.parse(rawText);
+    }
+    catch (error) {
+        throw new GenerationError('QCE_CEM_READ_FAILED', `Could not read CEM source at ${sourcePath}: ${toErrorMessage(error)}`);
+    }
+    const manifest = parsed;
+    if (!Array.isArray(manifest.modules)) {
+        throw new GenerationError('QCE_CEM_INVALID_SHAPE', `CEM at ${sourcePath} must include a "modules" array.`);
+    }
+    const definitions = new Map();
+    for (let moduleIndex = 0; moduleIndex < manifest.modules.length; moduleIndex += 1) {
+        const module = manifest.modules[moduleIndex];
+        if (module.declarations != null && !Array.isArray(module.declarations)) {
+            throw new GenerationError('QCE_CEM_INVALID_SHAPE', `CEM at ${sourcePath} has invalid shape: modules[${moduleIndex}].declarations must be an array when provided.`);
+        }
+        const declarations = module.declarations ?? [];
+        for (let declarationIndex = 0; declarationIndex < declarations.length; declarationIndex += 1) {
+            const declaration = declarations[declarationIndex];
+            if (!Object.prototype.hasOwnProperty.call(declaration, 'tagName')) {
+                continue;
+            }
+            if (typeof declaration.tagName !== 'string' ||
+                declaration.tagName.trim() === '') {
+                throw new GenerationError('QCE_CEM_INVALID_SHAPE', `CEM at ${sourcePath} has invalid shape: modules[${moduleIndex}].declarations[${declarationIndex}].tagName must be a non-empty string when provided.`);
+            }
+            const tagName = declaration.tagName.trim();
+            const existingDefinition = definitions.get(tagName);
+            const definition = existingDefinition ?? {
+                tagName,
+                props: [],
+                events: [],
+                slots: [],
+            };
+            const propsByName = new Map(definition.props.map((prop) => [prop.name, prop]));
+            const eventsByName = new Map(definition.events.map((event) => [event.name, event]));
+            const slotsByName = new Map(definition.slots.map((slot) => [slot.name, slot]));
+            const declarationRecord = declaration;
+            for (const prop of readComponentPropsFromAttributes(declarationRecord.attributes)) {
+                propsByName.set(prop.name, prop);
+            }
+            for (const prop of readComponentPropsFromMembers(declarationRecord.members)) {
+                const existingProp = propsByName.get(prop.name);
+                if (existingProp == null ||
+                    existingProp.type === 'unknown' ||
+                    existingProp.type.trim() === '') {
+                    propsByName.set(prop.name, prop);
+                }
+            }
+            for (const event of readComponentEventsFromDeclaration(declarationRecord.events)) {
+                if (!eventsByName.has(event.name)) {
+                    eventsByName.set(event.name, event);
+                }
+            }
+            for (const slot of readComponentSlotsFromDeclaration(declarationRecord.slots)) {
+                if (!slotsByName.has(slot.name)) {
+                    slotsByName.set(slot.name, slot);
+                }
+            }
+            definition.props = Array.from(propsByName.values()).sort((a, b) => a.name.localeCompare(b.name));
+            definition.events = Array.from(eventsByName.values()).sort((a, b) => a.name.localeCompare(b.name));
+            definition.slots = Array.from(slotsByName.values()).sort((a, b) => a.name.localeCompare(b.name));
+            definitions.set(tagName, definition);
+        }
+    }
+    return Array.from(definitions.values()).sort((a, b) => a.tagName.localeCompare(b.tagName));
+}
+function readComponentPropsFromAttributes(attributes) {
+    if (!Array.isArray(attributes)) {
+        return [];
+    }
+    const props = [];
+    for (const attribute of attributes) {
+        if (typeof attribute !== 'object' || attribute === null) {
+            continue;
+        }
+        const attributeRecord = attribute;
+        const rawName = typeof attributeRecord.fieldName === 'string' &&
+            attributeRecord.fieldName.trim() !== ''
+            ? attributeRecord.fieldName
+            : attributeRecord.name;
+        if (typeof rawName !== 'string' || rawName.trim() === '') {
+            continue;
+        }
+        props.push({
+            name: rawName.trim(),
+            type: normalizeCemTypeText(attributeRecord.type?.text),
+            required: false,
+        });
+    }
+    return props;
+}
+function readComponentPropsFromMembers(members) {
+    if (!Array.isArray(members)) {
+        return [];
+    }
+    const props = [];
+    for (const member of members) {
+        if (typeof member !== 'object' || member === null) {
+            continue;
+        }
+        const memberRecord = member;
+        if (memberRecord.kind !== 'field') {
+            continue;
+        }
+        if (memberRecord.privacy === 'private') {
+            continue;
+        }
+        if (typeof memberRecord.name !== 'string' ||
+            memberRecord.name.trim() === '') {
+            continue;
+        }
+        props.push({
+            name: memberRecord.name.trim(),
+            type: normalizeCemTypeText(memberRecord.type?.text),
+            required: false,
+        });
+    }
+    return props;
+}
+function readComponentEventsFromDeclaration(events) {
+    if (!Array.isArray(events)) {
+        return [];
+    }
+    const componentEvents = [];
+    for (const event of events) {
+        if (typeof event !== 'object' || event === null) {
+            continue;
+        }
+        const eventRecord = event;
+        if (typeof eventRecord.name !== 'string' ||
+            eventRecord.name.trim() === '') {
+            continue;
+        }
+        componentEvents.push({
+            name: eventRecord.name.trim(),
+            type: normalizeCemTypeText(eventRecord.type?.text),
+        });
+    }
+    return componentEvents;
+}
+function readComponentSlotsFromDeclaration(slots) {
+    if (!Array.isArray(slots)) {
+        return [];
+    }
+    const componentSlots = [];
+    for (const slot of slots) {
+        if (typeof slot !== 'object' || slot === null) {
+            continue;
+        }
+        const slotRecord = slot;
+        if (typeof slotRecord.name !== 'string' || slotRecord.name.trim() === '') {
+            continue;
+        }
+        componentSlots.push({
+            name: slotRecord.name.trim(),
+        });
+    }
+    return componentSlots;
+}
+function normalizeCemTypeText(typeText) {
+    return typeof typeText === 'string' && typeText.trim() !== ''
+        ? typeText.trim()
+        : 'unknown';
+}
+function toErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}