@lightspeed-js/core 0.1.1 → 0.2.0

package/dist/types/src/vite/component-ids.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Which file answers to each component name (ADR-058).
+ *
+ * Names are a flat namespace: a component is its filename, lowercased, from
+ * whichever root it was found in. The first root to claim a name keeps it, and
+ * `src` comes first, so an app can replace a package's component.
+ *
+ * Two files answering to one name is either that deliberate override or a
+ * collision nobody meant, and the two look identical from the files alone. So
+ * the app says which it means: an override across roots has to be declared,
+ * and two files under the same root are always a mistake.
+ */
+export interface FoundComponent {
+    /** Absolute path to the `.lsp` file. */
+    file: string;
+    /** The component root it was found under. */
+    root: string;
+}
+export type Conflict = {
+    kind: "same-root";
+    id: string;
+    kept: string;
+    other: string;
+} | {
+    kind: "undeclared-override";
+    id: string;
+    kept: string;
+    other: string;
+};
+export interface ComponentIds {
+    /** Component id to the file that answers to it. */
+    files: Map<string, string>;
+    /** Declared overrides that replaced something. */
+    overrides: Array<{
+        id: string;
+        kept: string;
+        replaced: string;
+    }>;
+    conflicts: Conflict[];
+    /** Names in `overrides` that replace nothing - left over after a rename or removal. */
+    unusedOverrides: string[];
+}
+export declare function componentIdOf(file: string): string;
+/** `found` must be in precedence order: every file of the first root, then the next. */
+export declare function resolveComponentIds(found: FoundComponent[], declaredOverrides?: readonly string[]): ComponentIds;
+/** One message per conflict, each ending in the change that fixes it (ADR-055). */
+export declare function describeConflict(conflict: Conflict, rel: (file: string) => string): string;

package/dist/types/src/vite/plugin.d.ts

@@ -61,9 +61,18 @@ interface LightspeedPluginOptions {
      * Names are a flat namespace: a component is its filename, lowercased, from
      * wherever it was found. The project's own `src` is searched first and wins,
      * so an app can replace a package's component by giving a file the same
-     * name - deliberate, and announced in the build log rather than silent.
+     * name - once it says so in `overrides` (ADR-058).
      */
     componentDirs?: string[];
+    /**
+     * Component names the app replaces on purpose: a file in `src` (or an
+     * earlier root) with the same name as one in a later `componentDirs` root.
+     *
+     * Any other clash fails the build and warns in dev, because a deliberate
+     * override and an accidental collision look identical from the files alone.
+     * Two files under the same root are never an override.
+     */
+    overrides?: string[];
 }
 export declare function lightspeedPlugin(options?: LightspeedPluginOptions): Plugin[];
 export {};

package/dist/types/test/component-ids.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/vite.js

@@ -17,6 +17,46 @@ var __toESM = (mod, isNodeMode, target) => {
 };
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
+// src/vite/component-ids.ts
+function componentIdOf(file) {
+  const name = file.split(/[\\/]/).pop() ?? file;
+  return name.replace(/\.lsp$/, "").toLowerCase();
+}
+function resolveComponentIds(found, declaredOverrides = []) {
+  const declared = new Set(declaredOverrides.map((id) => id.toLowerCase()));
+  const files = new Map;
+  const rootOf = new Map;
+  const result = { files, overrides: [], conflicts: [], unusedOverrides: [] };
+  const used = new Set;
+  for (const { file, root } of found) {
+    const id = componentIdOf(file);
+    const kept = files.get(id);
+    if (kept === undefined) {
+      files.set(id, file);
+      rootOf.set(id, root);
+      continue;
+    }
+    if (rootOf.get(id) === root) {
+      result.conflicts.push({ kind: "same-root", id, kept, other: file });
+    } else if (declared.has(id)) {
+      used.add(id);
+      result.overrides.push({ id, kept, replaced: file });
+    } else {
+      result.conflicts.push({ kind: "undeclared-override", id, kept, other: file });
+    }
+  }
+  result.unusedOverrides = [...declared].filter((id) => !used.has(id)).sort();
+  return result;
+}
+function describeConflict(conflict, rel) {
+  const kept = rel(conflict.kept);
+  const other = rel(conflict.other);
+  if (conflict.kind === "same-root") {
+    return `${conflict.id}: ${kept} and ${other} both answer to <${conflict.id}>. ` + `A component's name is its filename, lowercased, across every component directory. Rename one of them.`;
+  }
+  return `${conflict.id}: ${kept} replaces ${other}. ` + `If that is deliberate, add "${conflict.id}" to lightspeedPlugin({ overrides }); otherwise rename one of them.`;
+}
+
 // src/vite/csp.ts
 import { createHash } from "node:crypto";
 function styleHashes(html) {
@@ -4783,7 +4823,9 @@ function lightspeedPlugin(options = {}) {
   const cssMode = options.css ?? "inline";
   const cleanUrls = options.routes === true;
   const extraComponentDirs = options.componentDirs ?? [];
+  const declaredOverrides = options.overrides ?? [];
   const announcedShadowing = new Set;
+  let componentConflicts = [];
   const rewriteFormat = options.rewrites ?? "_redirects";
   const routeDeclarations = new Map;
   let relativeBase = false;
@@ -4921,6 +4963,10 @@ function lightspeedPlugin(options = {}) {
     },
     async buildStart() {
       await rebuildComponentRegistry();
+      if (!isDevMode && componentConflicts.length) {
+        this.error(componentConflicts.map((conflict) => describeConflict(conflict, (file) => relative3(root, file))).join(`
+`));
+      }
     },
     resolveId(id) {
       return id === VIRTUAL_COMPONENTS ? RESOLVED_COMPONENTS : null;
@@ -5517,20 +5563,13 @@ ${entries.join(`,
       const registry = new Map;
       const files = new Map;
       try {
-        for (const filePath of await findComponentFiles()) {
+        const ids = resolveComponentIds(await findComponentFiles(), declaredOverrides);
+        componentConflicts = ids.conflicts;
+        announceComponentIds(ids);
+        for (const [componentId, filePath] of ids.files) {
           try {
             const content = await readFile2(filePath, "utf-8");
             const parsed = withSharedStyles(parseLSP(content, filePath));
-            const componentId = basename(filePath, ".lsp").toLowerCase();
-            const claimed = files.get(componentId);
-            if (claimed !== undefined) {
-              const pair = `${claimed}\x00${filePath}`;
-              if (!announcedShadowing.has(pair)) {
-                announcedShadowing.add(pair);
-                console.log(`⚡ ${componentId}: using ${relative3(root, claimed)}, shadowing ${relative3(root, filePath)}`);
-              }
-              continue;
-            }
             files.set(componentId, filePath);
             registry.set(componentId, {
               template: parsed.view,
@@ -5575,14 +5614,32 @@ ${entries.join(`,
   async function findComponentFiles() {
     const found = [];
     for (const dir of componentRoots()) {
-      found.push(...await findLspFiles(dir));
+      for (const file of await findLspFiles(dir))
+        found.push({ file, root: dir });
     }
     return found;
   }
+  function announceComponentIds(ids) {
+    const rel = (file) => relative3(root, file);
+    for (const conflict of ids.conflicts) {
+      const key = `${conflict.kind}\x00${conflict.kept}\x00${conflict.other}`;
+      if (announcedShadowing.has(key))
+        continue;
+      announcedShadowing.add(key);
+      console.warn(`⚠️  ${describeConflict(conflict, rel)}`);
+    }
+    for (const id of ids.unusedOverrides) {
+      const key = `unused\x00${id}`;
+      if (announcedShadowing.has(key))
+        continue;
+      announcedShadowing.add(key);
+      console.warn(`⚠️  overrides lists "${id}", but nothing replaces a component of that name. Remove it from lightspeedPlugin({ overrides }).`);
+    }
+  }
   async function findLspFiles(dir) {
     const files = [];
     try {
-      const entries = await readdir(dir, { withFileTypes: true });
+      const entries = (await readdir(dir, { withFileTypes: true })).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
       for (const entry of entries) {
         const fullPath = join3(dir, entry.name);
         if (entry.isDirectory()) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightspeed-js/core",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Lightspeed: a compile-first framework for islands of reactivity in static HTML.",
   "keywords": [
     "lightspeed",