@qwik-custom-elements/core 1.0.0 → 1.0.2

package/README.md

@@ -1,6 +1,20 @@
 # @qwik-custom-elements/core
 
-Deterministic generation orchestration for Qwik custom-element wrappers.
+Qwik does not natively provide server-side rendering support for custom elements. Without additional tooling, Web Components render as empty tags on the server, lose SSR benefits, and require manual boilerplate to integrate typed props and events. `@qwik-custom-elements/core` is the CLI and orchestration layer that generates typed, SSR-capable Qwik wrapper components from a Custom Elements Manifest — giving you correct server output, full type safety, and automatic event wiring, with no per-component boilerplate.
+
+`core` does not contain framework-specific logic. Instead, it delegates generated output to an adapter that understands your component library (Stencil, Lit, etc.). You configure a project once; the CLI does the rest.
+
+## Ecosystem
+
+This package is part of the `qwik-custom-elements` toolchain:
+
+| Package                                                                     | Role                                                                                                         |
+| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| **`@qwik-custom-elements/core`** _(this package)_                           | CLI entry point and adapter-agnostic orchestration: config loading, CEM parsing, write planning, diagnostics |
+| [**`@qwik-custom-elements/adapter-stencil`**](../adapter-stencil/README.md) | Stencil-specific generation: SSR/CSR bridge components, typed Qwik wrappers, hydrate runtime integration     |
+| [**`@qwik-custom-elements/adapter-lit`**](../adapter-lit/README.md)         | Lit-specific generation: SSR/CSR bridge components, typed Qwik wrappers, Declarative Shadow DOM hydration    |
+
+Install `core` alongside whichever adapter matches your component library. You will interact with `core` only through the config file and the CLI — all framework-specific behavior lives in the adapter.
 
 ## Install
 
@@ -77,6 +91,6 @@ Adapters are responsible for returning the generated file set for their framewor
 
 Changes that alter core or adapter ownership boundaries should be reflected in:
 
-- `docs/SYSTEM/decisions.md`
-- `docs/SYSTEM/findings-log.md`
+- an ADR in `docs/adr/` (system-wide) or the affected package's `docs/adr/` (context-specific)
+- the affected `CONTEXT.md` if new domain terms are introduced
 - the package README files for any affected packages

package/dist/__tests__/config.test.js

@@ -1,9 +1,25 @@
 import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import { parseCliArgs, runCli } from '../cli.js';
 import { ConfigValidationError, loadGeneratorConfig } from '../config.js';
+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';
+    }
+}
 async function withTempDir(run) {
     const tempDir = await mkdtemp(path.join(os.tmpdir(), 'qce-core-'));
     try {
@@ -519,10 +535,15 @@ describe('runCli', () => {
                     supportsSsrProbe: true,
                     ssrRuntimeSubpath: './ssr',
                 });
-                expect(summary.projects[0].resolvedCoreVersion).toBe('1.0.0');
-                expect(summary.projects[1].resolvedCoreVersion).toBe('1.0.0');
-                expect(summary.projects[0].resolvedAdapterVersion).toBe('1.0.0');
-                expect(summary.projects[1].resolvedAdapterVersion).toBe('1.0.0');
+                // Read actual versions from package.json to make test resilient to version bumps
+                const corePackageJsonPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
+                const adapterPackageJsonPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..', 'adapter-stencil', 'package.json');
+                const expectedCoreVersion = await readVersionFromPackageJson(corePackageJsonPath);
+                const expectedAdapterVersion = await readVersionFromPackageJson(adapterPackageJsonPath);
+                expect(summary.projects[0].resolvedCoreVersion).toBe(expectedCoreVersion);
+                expect(summary.projects[1].resolvedCoreVersion).toBe(expectedCoreVersion);
+                expect(summary.projects[0].resolvedAdapterVersion).toBe(expectedAdapterVersion);
+                expect(summary.projects[1].resolvedAdapterVersion).toBe(expectedAdapterVersion);
             }
             finally {
                 process.chdir(previousCwd);

package/dist/__tests__/generator.test.js

@@ -945,6 +945,37 @@ describe('generateFromConfig', () => {
             });
         });
     });
+    it('includes adapter-provided guidance in QCE_PACKAGE_NAME_CEM_NOT_FOUND when hook returns a hint', async () => {
+        await withTempDir(async (tempDir) => {
+            const packageName = '@demo/stencil-no-cem';
+            const _packageRoot = await createFixturePackage(tempDir, packageName);
+            // Mock adapter with the hint hook
+            await writeFile(path.join(tempDir, 'adapter-with-hint-hook.mjs'), [
+                'export const metadata = {',
+                "  supportedSourceTypes: ['PACKAGE_NAME'],",
+                '};',
+                'export function buildMissingCemHint({ packageRoot }) {',
+                '  return " Hint from adapter! ";',
+                '}',
+            ].join('\n'), 'utf8');
+            const config = {
+                dryRun: true,
+                projects: [
+                    {
+                        id: 'stencil-demo',
+                        adapter: 'stencil',
+                        adapterPackage: './adapter-with-hint-hook.mjs',
+                        source: { type: 'PACKAGE_NAME', packageName },
+                        outDir: './src/generated',
+                    },
+                ],
+            };
+            await expect(generateFromConfig(config, { cwd: tempDir })).rejects.toMatchObject({
+                code: 'QCE_PACKAGE_NAME_CEM_NOT_FOUND',
+                message: expect.stringContaining('Hint from adapter!'),
+            });
+        });
+    });
     it('fails deterministically when PACKAGE_NAME CEM discovery is ambiguous', async () => {
         await withTempDir(async (tempDir) => {
             const packageName = '@demo/components';
@@ -1329,3 +1360,46 @@ describe('generateFromConfig', () => {
         });
     });
 });
+it('resolves package root for PACKAGE_NAME source with strict exports map (no ./package.json)', async () => {
+    await withTempDir(async (tempDir) => {
+        const packageName = '@demo/strict-exports-lib';
+        const packageRoot = path.join(tempDir, 'node_modules', '@demo', 'strict-exports-lib');
+        await mkdir(path.join(packageRoot, 'dist'), { recursive: true });
+        // package.json has strict exports — no ./package.json export
+        await writeFile(path.join(packageRoot, 'package.json'), JSON.stringify({
+            name: packageName,
+            version: '1.0.0',
+            exports: {
+                '.': './dist/index.js',
+            },
+        }), 'utf8');
+        // A real CJS-style file so require.resolve can find it
+        await writeFile(path.join(packageRoot, 'dist', 'index.js'), 'exports.noop = () => undefined;\n', 'utf8');
+        await writeFile(path.join(packageRoot, 'custom-elements.json'), JSON.stringify({
+            modules: [{ declarations: [{ tagName: 'strict-button' }] }],
+        }), 'utf8');
+        await writeFile(path.join(tempDir, 'adapter-minimal.mjs'), [
+            'export const metadata = {',
+            "  supportedSourceTypes: ['PACKAGE_NAME'],",
+            '};',
+            'export function createGeneratedOutput() { return []; }',
+            '',
+        ].join('\n'), 'utf8');
+        const config = {
+            dryRun: true,
+            projects: [
+                {
+                    id: 'demo',
+                    adapter: 'stencil',
+                    adapterPackage: './adapter-minimal.mjs',
+                    source: { type: 'PACKAGE_NAME', packageName },
+                    outDir: './src/generated',
+                },
+            ],
+        };
+        const result = await generateFromConfig(config, { cwd: tempDir });
+        expect(result.projects[0].status).toBe('success');
+        expect(result.projects[0].componentTags).toEqual(['strict-button']);
+        expect(result.projects[0].sourcePath).toBe(path.join(packageRoot, 'custom-elements.json'));
+    });
+});

package/dist/generator.js

@@ -1,4 +1,4 @@
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import path from 'node:path';
@@ -87,7 +87,7 @@ async function generateProject(project, cwd, dryRun) {
     await validateAdapterProject(project, adapterModule);
     const runtimeImportResult = await resolveAdapterRuntimeImports(project, adapterModule, cwd);
     const { runtimeImports } = runtimeImportResult;
-    const sourcePath = resolveProjectSourcePath(project.id, project.source, cwd);
+    const sourcePath = resolveProjectSourcePath(project.id, project.source, cwd, adapterModule);
     const outDirPath = path.resolve(cwd, project.outDir);
     const componentDefinitions = await readComponentDefinitionsFromCem(sourcePath);
     const augmentedComponentDefinitions = await augmentAdapterComponentDefinitions(componentDefinitions, adapterModule, runtimeImports, outDirPath, cwd);
@@ -423,7 +423,7 @@ function resolveSkippedProjectSourcePath(source, cwd) {
         ? `package:${source.packageName}`
         : `package:${source.packageName}#${source.cemPath}`;
 }
-function resolveProjectSourcePath(projectId, source, cwd) {
+function resolveProjectSourcePath(projectId, source, cwd, adapterModule) {
     if (source.type === 'CEM') {
         return path.resolve(cwd, source.path);
     }
@@ -431,7 +431,7 @@ function resolveProjectSourcePath(projectId, source, cwd) {
     if (source.cemPath != null) {
         return resolvePackageNameOverrideCemPath(projectId, source, packageRoot);
     }
-    return discoverPackageNameCemPath(projectId, source, packageRoot);
+    return discoverPackageNameCemPath(projectId, source, packageRoot, adapterModule);
 }
 function resolvePackageRootForProject(projectId, source, cwd) {
     const packageSpecifier = `${source.packageName}/package.json`;
@@ -439,8 +439,37 @@ function resolvePackageRootForProject(projectId, source, cwd) {
         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)}`);
+    catch (primaryError) {
+        // Fallback for packages with strict exports maps that don't expose ./package.json.
+        // Resolve via the main entry point, then walk up the directory tree to find
+        // the ancestor directory whose package.json `name` matches the package name.
+        // This approach is robust across npm, pnpm (virtual store), and Yarn PnP because
+        // it matches on the canonical `name` field rather than path segments.
+        try {
+            const mainEntry = require.resolve(source.packageName, { paths: [cwd] });
+            let dir = path.dirname(mainEntry);
+            while (true) {
+                const pkgJsonPath = path.join(dir, 'package.json');
+                if (existsSync(pkgJsonPath)) {
+                    try {
+                        const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf8'));
+                        if (pkg.name === source.packageName)
+                            return dir;
+                    }
+                    catch {
+                        // Not a valid JSON package.json — keep walking up
+                    }
+                }
+                const parent = path.dirname(dir);
+                if (parent === dir)
+                    break; // Reached filesystem root with no match
+                dir = parent;
+            }
+        }
+        catch {
+            // Main entry also not resolvable — fall through to the original error
+        }
+        throw new GenerationError('QCE_PACKAGE_NAME_RESOLVE_FAILED', `Project "${projectId}" could not resolve source package "${source.packageName}" from ${cwd}: ${toErrorMessage(primaryError)}`);
     }
 }
 function resolvePackageNameOverrideCemPath(projectId, source, packageRoot) {
@@ -458,7 +487,7 @@ function resolvePackageNameOverrideCemPath(projectId, source, packageRoot) {
     }
     return resolvedCemPath;
 }
-function discoverPackageNameCemPath(projectId, source, packageRoot) {
+function discoverPackageNameCemPath(projectId, source, packageRoot, adapterModule) {
     const candidatePaths = PACKAGE_NAME_CEM_DISCOVERY_CANDIDATES.map((candidate) => path.resolve(packageRoot, candidate));
     const existingCandidates = [];
     for (const candidatePath of candidatePaths) {
@@ -470,10 +499,25 @@ function discoverPackageNameCemPath(projectId, source, packageRoot) {
         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.`);
+        const hint = tryAdapterMissingCemHintHook(adapterModule, packageRoot);
+        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.${hint}`);
     }
     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 tryAdapterMissingCemHintHook(adapterModule, packageRoot) {
+    const hook = adapterModule.buildMissingCemHint;
+    if (typeof hook !== 'function') {
+        return '';
+    }
+    try {
+        const result = hook({ packageRoot });
+        return typeof result === 'string' ? result : '';
+    }
+    catch {
+        // Hook errors are non-fatal
+        return '';
+    }
+}
 function resolveRuntimeImportSpecifier(specifier, cwd, packageRoot) {
     const resolver = specifier.startsWith('.') && packageRoot != null
         ? createRequire(path.join(packageRoot, 'package.json'))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qwik-custom-elements/core",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "type": "module",
   "exports": {
     ".": {
@@ -26,6 +26,35 @@
   "publishConfig": {
     "access": "public"
   },
+  "description": "Generate typed, SSR-capable Qwik components from Web Component libraries (CLI + orchestration)",
+  "keywords": [
+    "qwik",
+    "web-components",
+    "custom-elements",
+    "ssr",
+    "server-side-rendering",
+    "wrapper",
+    "manifest",
+    "cli",
+    "generator",
+    "code-generation"
+  ],
+  "author": "Dmitry A. Efimenko (https://github.com/DmitryEfimenko)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DmitryEfimenko/qwik-custom-elements.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/DmitryEfimenko/qwik-custom-elements#readme",
+  "bugs": {
+    "url": "https://github.com/DmitryEfimenko/qwik-custom-elements/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "funding": "https://github.com/sponsors/DmitryEfimenko",
+  "sideEffects": false,
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "check-types": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",