@qwik-custom-elements/core 1.0.0

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+import type { CliArgs } from './types.js';
+export declare function parseCliArgs(argv: string[]): CliArgs;
+export declare function runCli(argv: string[]): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,271 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { ConfigValidationError, loadGeneratorConfig } from './config.js';
+import { GenerationError, generateFromConfig } from './generator.js';
+const RUN_SUMMARY_SCHEMA_VERSION = '1.0.0';
+const DEFAULT_RUN_SUMMARY_PATH = './generated-run-summary.json';
+const SSR_UNSUPPORTED_FALLBACK_CODE = 'QCE_SSR_UNSUPPORTED_FALLBACK';
+const CORE_PACKAGE_JSON_PATH = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+export function parseCliArgs(argv) {
+    let configPath;
+    const projectIds = [];
+    let parallel = false;
+    let help = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === '--help' || arg === '-h') {
+            help = true;
+            continue;
+        }
+        if (arg === '--config') {
+            const nextValue = argv[index + 1];
+            if (!nextValue || nextValue.startsWith('-')) {
+                throw new ConfigValidationError('QCE_CLI_INVALID_ARG', 'Flag "--config" requires a file path value.');
+            }
+            configPath = nextValue;
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--config=')) {
+            const candidate = arg.slice('--config='.length);
+            if (!candidate) {
+                throw new ConfigValidationError('QCE_CLI_INVALID_ARG', 'Flag "--config" requires a file path value.');
+            }
+            configPath = candidate;
+            continue;
+        }
+        if (arg === '--project') {
+            const nextValue = argv[index + 1];
+            if (!nextValue || nextValue.startsWith('-')) {
+                throw new ConfigValidationError('QCE_CLI_INVALID_ARG', 'Flag "--project" requires a project id value.');
+            }
+            projectIds.push(nextValue);
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--project=')) {
+            const candidate = arg.slice('--project='.length);
+            if (!candidate) {
+                throw new ConfigValidationError('QCE_CLI_INVALID_ARG', 'Flag "--project" requires a project id value.');
+            }
+            projectIds.push(candidate);
+            continue;
+        }
+        if (arg === '--parallel') {
+            parallel = true;
+            continue;
+        }
+        throw new ConfigValidationError('QCE_CLI_INVALID_ARG', `Unknown CLI argument "${arg}".`);
+    }
+    return { configPath, projectIds, parallel, help };
+}
+export async function runCli(argv) {
+    const runStartedAtMs = Date.now();
+    let resolvedConfigPath;
+    let resolvedSummaryPath;
+    let resolvedDryRun = false;
+    let selectedProjectsForSummary = [];
+    try {
+        const args = parseCliArgs(argv);
+        if (args.help) {
+            process.stdout.write('Usage: qwik-custom-elements [--config <path>] [--project <id>] [--parallel] [--help]\n' +
+                'Default config path: ./qwik-custom-elements.config.json\n' +
+                'Optional JS config path: ./qwik-custom-elements.config.js\n' +
+                'Parallel mode: add --parallel to run selected projects concurrently.\n' +
+                'Project targeting: repeat --project to run a subset by id.\n');
+            return 0;
+        }
+        const { configPath, config } = await loadGeneratorConfig({
+            configPath: args.configPath,
+        });
+        resolvedConfigPath = configPath;
+        resolvedSummaryPath = config.summaryPath;
+        resolvedDryRun = config.dryRun === true;
+        const requestedProjectIdSet = new Set(args.projectIds);
+        selectedProjectsForSummary = [...config.projects]
+            .sort((a, b) => a.id.localeCompare(b.id))
+            .map((project) => ({
+            projectId: project.id,
+            adapterPackage: project.adapterPackage,
+            sourcePath: resolveProjectSourceSummaryPath(project.source),
+            outDirPath: path.resolve(process.cwd(), project.outDir),
+            isTargeted: requestedProjectIdSet.size === 0 ||
+                requestedProjectIdSet.has(project.id),
+        }));
+        if (args.parallel) {
+            config.parallel = true;
+        }
+        const generationResult = await generateFromConfig(config, {
+            targetProjectIds: args.projectIds,
+        });
+        const mode = generationResult.dryRun ? 'dry-run' : 'write';
+        const totalWrites = generationResult.projects.reduce((sum, project) => sum + project.plannedWrites.length, 0);
+        if (config.parallel === true) {
+            for (const project of generationResult.projects) {
+                process.stdout.write(`[project:${project.projectId}] mode=${mode} plannedWrites=${project.plannedWrites.length}\n`);
+            }
+        }
+        for (const project of generationResult.projects) {
+            const observedCodeSet = new Set(project.observedErrorCodes);
+            const hasClientOnlySuccessSignal = project.ssrCapabilities.clientOnlyMode === true &&
+                observedCodeSet.has(SSR_UNSUPPORTED_FALLBACK_CODE) &&
+                project.plannedWrites.length > 0;
+            if (hasClientOnlySuccessSignal) {
+                process.stderr.write(`${SSR_UNSUPPORTED_FALLBACK_CODE}: Project "${project.projectId}" SSR is unavailable, but client-capable wrapper generation succeeded via the client-only CSR surface.
+`);
+                continue;
+            }
+            if (project.observedErrorCodes.includes(SSR_UNSUPPORTED_FALLBACK_CODE)) {
+                process.stderr.write(`${SSR_UNSUPPORTED_FALLBACK_CODE}: Project "${project.projectId}" adapter SSR is unavailable; falling back to CEM-only generation.\n`);
+            }
+        }
+        const runFinishedAtMs = Date.now();
+        await writeRunSummaryArtifact({
+            configPath,
+            summaryPath: config.summaryPath,
+            generationResult,
+            runStartedAtMs,
+            runFinishedAtMs,
+        });
+        process.stdout.write(`Generation completed (${mode}) from ${configPath}. Projects: ${generationResult.projects.length}. Planned writes: ${totalWrites}.\n`);
+        return 0;
+    }
+    catch (error) {
+        if (resolvedConfigPath != null && error instanceof GenerationError) {
+            const runFinishedAtMs = Date.now();
+            const failedDurationMs = runFinishedAtMs - runStartedAtMs;
+            await writeRunSummaryArtifact({
+                configPath: resolvedConfigPath,
+                summaryPath: resolvedSummaryPath,
+                generationResult: {
+                    dryRun: resolvedDryRun,
+                    projects: selectedProjectsForSummary.map((project) => ({
+                        projectId: project.projectId,
+                        status: project.isTargeted ? 'failed' : 'skipped',
+                        durationMs: project.isTargeted ? failedDurationMs : 0,
+                        adapterPackage: project.adapterPackage,
+                        sourcePath: project.sourcePath,
+                        outDirPath: project.outDirPath,
+                        generatedIndexPath: project.isTargeted
+                            ? ''
+                            : path.join(project.outDirPath, 'index.ts'),
+                        componentTags: [],
+                        plannedWrites: [],
+                        wroteFiles: false,
+                        ssrCapabilities: {
+                            available: false,
+                            supportsSsrProbe: false,
+                            ssrRuntimeSubpath: null,
+                        },
+                        observedErrorCodes: project.isTargeted ? [error.code] : [],
+                    })),
+                },
+                runStartedAtMs,
+                runFinishedAtMs,
+                observedErrorCodes: [error.code],
+            });
+        }
+        if (error instanceof ConfigValidationError ||
+            error instanceof GenerationError) {
+            process.stderr.write(`${error.code}: ${error.message}\n`);
+            return 1;
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`QCE_UNEXPECTED: ${message}\n`);
+        return 1;
+    }
+}
+function resolveProjectSourceSummaryPath(source) {
+    if (source.type === 'CEM') {
+        return path.resolve(process.cwd(), source.path);
+    }
+    if (source.cemPath != null) {
+        return path.resolve(process.cwd(), source.cemPath);
+    }
+    return source.packageName;
+}
+async function writeRunSummaryArtifact(params) {
+    const { configPath, summaryPath, generationResult, runStartedAtMs, runFinishedAtMs, observedErrorCodes = [], } = params;
+    const configDir = path.dirname(configPath);
+    const resolvedSummaryPath = path.resolve(configDir, summaryPath ?? DEFAULT_RUN_SUMMARY_PATH);
+    const resolvedCoreVersion = await readVersionFromPackageJson(CORE_PACKAGE_JSON_PATH);
+    const adapterVersionCache = new Map();
+    const summary = {
+        schemaVersion: RUN_SUMMARY_SCHEMA_VERSION,
+        startedAt: new Date(runStartedAtMs).toISOString(),
+        finishedAt: new Date(runFinishedAtMs).toISOString(),
+        dryRun: generationResult.dryRun,
+        projects: await Promise.all(generationResult.projects.map(async (project) => ({
+            projectId: project.projectId,
+            status: project.status,
+            durationMs: project.durationMs,
+            generatedIndexPath: project.generatedIndexPath,
+            resolvedCoreVersion,
+            resolvedAdapterVersion: await resolveAdapterVersion(project.adapterPackage, adapterVersionCache),
+            ssrCapabilities: project.ssrCapabilities,
+            observedErrorCodes: Array.from(new Set(project.observedErrorCodes)).sort((a, b) => a.localeCompare(b)),
+        }))),
+        observedErrorCodes: Array.from(new Set(observedErrorCodes)).sort((a, b) => a.localeCompare(b)),
+    };
+    await mkdir(path.dirname(resolvedSummaryPath), { recursive: true });
+    await writeFile(resolvedSummaryPath, `${JSON.stringify(summary, null, 2)}\n`, 'utf8');
+}
+async function resolveAdapterVersion(adapterPackage, cache) {
+    const cached = cache.get(adapterPackage);
+    if (cached != null) {
+        return cached;
+    }
+    const packageName = resolveAdapterVersionPackageName(adapterPackage);
+    if (packageName == null) {
+        cache.set(adapterPackage, 'unknown');
+        return 'unknown';
+    }
+    const adapterPackageJsonPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', packageName, 'package.json');
+    const resolvedVersion = await readVersionFromPackageJson(adapterPackageJsonPath);
+    cache.set(adapterPackage, resolvedVersion);
+    return resolvedVersion;
+}
+function resolveAdapterVersionPackageName(adapterPackage) {
+    if (!adapterPackage.startsWith('@qwik-custom-elements/')) {
+        return undefined;
+    }
+    const [scope, packageDirectoryName] = adapterPackage.split('/');
+    if (scope !== '@qwik-custom-elements' || !packageDirectoryName) {
+        return undefined;
+    }
+    return packageDirectoryName;
+}
+async function readVersionFromPackageJson(packageJsonPath) {
+    try {
+        const packageJsonText = await readFile(packageJsonPath, 'utf8');
+        const packageJson = JSON.parse(packageJsonText);
+        if (packageJson != null &&
+            typeof packageJson.version === 'string' &&
+            packageJson.version.length > 0) {
+            return packageJson.version;
+        }
+        return 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+function isMainModule() {
+    const executedPath = process.argv[1];
+    if (!executedPath) {
+        return false;
+    }
+    return import.meta.url === pathToFileURL(executedPath).href;
+}
+if (isMainModule()) {
+    runCli(process.argv.slice(2))
+        .then((exitCode) => {
+        process.exitCode = exitCode;
+    })
+        .catch((error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`QCE_UNEXPECTED: ${message}\n`);
+        process.exitCode = 1;
+    });
+}

package/dist/config.d.ts

@@ -0,0 +1,7 @@
+import type { GeneratorConfig, LoadConfigOptions, LoadedConfig } from './types.js';
+export declare class ConfigValidationError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function loadGeneratorConfig(options?: LoadConfigOptions): Promise<LoadedConfig>;
+export declare function validateGeneratorConfig(rawConfig: unknown): GeneratorConfig;

package/dist/config.js

@@ -0,0 +1,183 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+const DEFAULT_JSON_CONFIG = 'qwik-custom-elements.config.json';
+const DEFAULT_JS_CONFIG = 'qwik-custom-elements.config.js';
+const ROOT_ALLOWED_KEYS = new Set([
+    'projects',
+    'dryRun',
+    'parallel',
+    'format',
+    'summaryPath',
+]);
+const PROJECT_ALLOWED_KEYS = new Set([
+    'id',
+    'libraryName',
+    'adapter',
+    'adapterPackage',
+    'source',
+    'outDir',
+    'cleanOutput',
+    'adapterOptions',
+]);
+export class ConfigValidationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'ConfigValidationError';
+        this.code = code;
+    }
+}
+export async function loadGeneratorConfig(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const configPath = resolveConfigPath(cwd, options.configPath);
+    const rawConfig = await readUnknownConfigValue(configPath);
+    const config = validateGeneratorConfig(rawConfig);
+    return { configPath, config };
+}
+export function validateGeneratorConfig(rawConfig) {
+    if (!isPlainObject(rawConfig)) {
+        throw new ConfigValidationError('QCE_CONFIG_INVALID_SHAPE', 'Config must be a plain object.');
+    }
+    ensureNoUnknownKeys(rawConfig, ROOT_ALLOWED_KEYS, 'root');
+    const projects = rawConfig.projects;
+    if (!Array.isArray(projects) || projects.length === 0) {
+        throw new ConfigValidationError('QCE_CONFIG_MISSING_REQUIRED', 'Config field "projects" must be a non-empty array.');
+    }
+    const normalizedProjects = projects.map((project, index) => validateProject(project, `projects[${index}]`));
+    const config = {
+        projects: normalizedProjects,
+    };
+    config.dryRun = readOptionalBoolean(rawConfig.dryRun, 'dryRun');
+    config.parallel = readOptionalBoolean(rawConfig.parallel, 'parallel');
+    config.format = readOptionalBoolean(rawConfig.format, 'format');
+    config.summaryPath = readOptionalString(rawConfig.summaryPath, 'summaryPath');
+    return config;
+}
+function validateProject(rawProject, pathPrefix) {
+    if (!isPlainObject(rawProject)) {
+        throw new ConfigValidationError('QCE_CONFIG_INVALID_SHAPE', `Config field "${pathPrefix}" must be a plain object.`);
+    }
+    ensureNoUnknownKeys(rawProject, PROJECT_ALLOWED_KEYS, pathPrefix);
+    return {
+        id: readRequiredString(rawProject.id, `${pathPrefix}.id`),
+        libraryName: readOptionalString(rawProject.libraryName, `${pathPrefix}.libraryName`),
+        adapter: readRequiredString(rawProject.adapter, `${pathPrefix}.adapter`),
+        adapterPackage: readRequiredString(rawProject.adapterPackage, `${pathPrefix}.adapterPackage`),
+        source: readProjectSource(rawProject.source, `${pathPrefix}.source`),
+        outDir: readRequiredString(rawProject.outDir, `${pathPrefix}.outDir`),
+        cleanOutput: readOptionalBoolean(rawProject.cleanOutput, `${pathPrefix}.cleanOutput`),
+        adapterOptions: readOptionalObject(rawProject.adapterOptions, `${pathPrefix}.adapterOptions`),
+    };
+}
+function readProjectSource(value, field) {
+    if (!isPlainObject(value)) {
+        throw new ConfigValidationError('QCE_CONFIG_INVALID_TYPE', `Config field "${field}" must be a source object with a valid "type" discriminator.`);
+    }
+    const sourceType = readRequiredString(value.type, `${field}.type`);
+    if (sourceType === 'CEM') {
+        ensureNoUnknownKeys(value, new Set(['type', 'path']), field);
+        return {
+            type: 'CEM',
+            path: readRequiredString(value.path, `${field}.path`),
+        };
+    }
+    if (sourceType === 'PACKAGE_NAME') {
+        ensureNoUnknownKeys(value, new Set(['type', 'packageName', 'cemPath']), field);
+        return {
+            type: 'PACKAGE_NAME',
+            packageName: readRequiredString(value.packageName, `${field}.packageName`),
+            cemPath: readOptionalString(value.cemPath, `${field}.cemPath`),
+        };
+    }
+    throw new ConfigValidationError('QCE_CONFIG_INVALID_TYPE', `Config field "${field}.type" must be "CEM" or "PACKAGE_NAME".`);
+}
+function readRequiredString(value, field) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new ConfigValidationError('QCE_CONFIG_MISSING_REQUIRED', `Config field "${field}" must be a non-empty string.`);
+    }
+    return value;
+}
+function readOptionalString(value, field) {
+    if (value == null) {
+        return undefined;
+    }
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new ConfigValidationError('QCE_CONFIG_INVALID_TYPE', `Config field "${field}" must be a non-empty string when provided.`);
+    }
+    return value;
+}
+function readOptionalBoolean(value, field) {
+    if (value == null) {
+        return undefined;
+    }
+    if (typeof value !== 'boolean') {
+        throw new ConfigValidationError('QCE_CONFIG_INVALID_TYPE', `Config field "${field}" must be a boolean when provided.`);
+    }
+    return value;
+}
+function readOptionalObject(value, field) {
+    if (value == null) {
+        return undefined;
+    }
+    if (!isPlainObject(value)) {
+        throw new ConfigValidationError('QCE_CONFIG_INVALID_TYPE', `Config field "${field}" must be an object when provided.`);
+    }
+    return value;
+}
+function ensureNoUnknownKeys(value, allowedKeys, field) {
+    for (const key of Object.keys(value)) {
+        if (!allowedKeys.has(key)) {
+            throw new ConfigValidationError('QCE_CONFIG_UNKNOWN_FIELD', `Unknown config field "${field}.${key}".`);
+        }
+    }
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function resolveConfigPath(cwd, cliConfigPath) {
+    if (cliConfigPath) {
+        return path.resolve(cwd, cliConfigPath);
+    }
+    const defaultJsonPath = path.resolve(cwd, DEFAULT_JSON_CONFIG);
+    if (existsSync(defaultJsonPath)) {
+        return defaultJsonPath;
+    }
+    const defaultJsPath = path.resolve(cwd, DEFAULT_JS_CONFIG);
+    if (existsSync(defaultJsPath)) {
+        return defaultJsPath;
+    }
+    throw new ConfigValidationError('QCE_CONFIG_NOT_FOUND', `Could not find config file. Checked ${DEFAULT_JSON_CONFIG} and ${DEFAULT_JS_CONFIG} in ${cwd}.`);
+}
+async function readUnknownConfigValue(configPath) {
+    const extension = path.extname(configPath).toLowerCase();
+    if (extension === '.json') {
+        return readJsonConfig(configPath);
+    }
+    if (extension === '.js' || extension === '.mjs' || extension === '.cjs') {
+        return readModuleConfig(configPath);
+    }
+    throw new ConfigValidationError('QCE_CONFIG_UNSUPPORTED_EXTENSION', `Unsupported config extension "${extension}". Use .json, .js, .mjs, or .cjs.`);
+}
+async function readJsonConfig(configPath) {
+    try {
+        const rawText = await readFile(configPath, 'utf8');
+        return JSON.parse(rawText);
+    }
+    catch (error) {
+        throw new ConfigValidationError('QCE_CONFIG_INVALID_JSON', `Invalid JSON config at ${configPath}: ${toErrorMessage(error)}`);
+    }
+}
+async function readModuleConfig(configPath) {
+    try {
+        const moduleNamespace = await import(pathToFileURL(configPath).href);
+        return moduleNamespace.default ?? moduleNamespace;
+    }
+    catch (error) {
+        throw new ConfigValidationError('QCE_CONFIG_INVALID_MODULE', `Invalid JS config at ${configPath}: ${toErrorMessage(error)}`);
+    }
+}
+function toErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/generator.d.ts

@@ -0,0 +1,6 @@
+import type { GenerateOptions, GenerationResult, GeneratorConfig } from './types.js';
+export declare class GenerationError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function generateFromConfig(config: GeneratorConfig, options?: GenerateOptions): Promise<GenerationResult>;