@hkdigital/lib-core 0.5.77 → 0.5.78

package/claude.md

@@ -130,6 +130,51 @@ This is a modern SvelteKit library built with Svelte 5 and Skeleton.dev v3 compo
 
 **Import validation:** Run `node scripts/validate-imports.mjs` to validate import patterns. The validator checks for barrel export files at each level and suggests the highest-level file that exports your target. These rules are enforced for `src/lib/` files only. Files in `src/routes/` can use relative imports freely. See README.md "Import Validation" section for usage in other projects.
 
+### Critical: Aliases in Libraries vs Apps
+
+**IMPORTANT**: Due to Vite/SvelteKit limitations, aliases in library
+code (`src/lib/**`) must resolve to paths **inside the project folder**.
+Aliases to external packages or paths outside the project break when
+building libraries.
+
+**The problem:**
+```javascript
+// ❌ These aliases don't work in src/lib/** files:
+// svelte.config.js
+alias: {
+  '$ext': 'node_modules/@hkdigital/lib-core/dist',  // Outside project
+  '$pkg': '@hkdigital/lib-core'  // Package name (doesn't resolve)
+}
+
+// In src/lib/** - BREAKS during build!
+import { Button } from '$ext/ui/primitives.js';
+```
+
+**The solution:**
+- **In library code (`src/lib/**`)**: Use direct package imports
+- **In app code (`src/routes/**`)**: Aliases work fine
+
+```javascript
+// ✅ Library code - use direct imports
+import { Button } from '@hkdigital/lib-core/ui/primitives.js';
+
+// ✅ App code - aliases OK (not built/published)
+import { Button } from '$ext/ui/primitives.js';
+```
+
+**Local aliases work everywhere:**
+```javascript
+// svelte.config.js
+alias: {
+  '$lib': 'src/lib',  // ✅ Inside project - works everywhere
+  '$examples': 'src/routes/examples'  // ✅ Inside project
+}
+```
+
+**Why**: Vite/SvelteKit aliases are designed for internal project
+structure. Build tools cannot properly handle aliases pointing outside
+the project or to package names.
+
 ## Class Export Conventions
 - **All classes should be default exports**: `export default class ClassName`
 - **Import classes without destructuring**: `import ClassName from './ClassName.js'`

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@hkdigital/lib-core",
-	"version": "0.5.77",
+	"version": "0.5.78",
 	"author": {
 		"name": "HKdigital",
 		"url": "https://hkdigital.nl"

package/scripts/README.md

@@ -35,6 +35,8 @@ node scripts/validate-imports.mjs
    etc. must be explicit
 5. **Import paths must exist** - All imports must resolve to actual
    files
+6. **Aliases must resolve inside project** - Library code (`src/lib/`)
+   can only use aliases that resolve to paths inside the project folder
 
 ## Import Rules
 
@@ -180,6 +182,69 @@ import { current } from './existing-file.js';
 them at build time or runtime. Helps prevent errors when refactoring
 or moving files.
 
+### Rule 6: Aliases must resolve inside the project
+
+**Library code must only use aliases that resolve to paths inside the
+project folder**
+
+Aliases are designed for internal project structure, not external
+packages. Due to Vite/SvelteKit limitations, aliases that point
+outside the project folder or to package names cannot work correctly in
+library code.
+
+❌ Bad (aliases that don't work in `src/lib/`):
+```javascript
+// svelte.config.js
+alias: {
+  // Points to node_modules (outside project)
+  '$ext-lib': 'node_modules/@some/library/dist',
+
+  // Package name (Vite treats as relative path, doesn't resolve)
+  '$pkg': '@some/library',
+
+  // Absolute path outside project
+  '$external': '/usr/local/lib/something'
+}
+
+// In src/lib/ui/MyComponent.svelte
+import { Button } from '$ext-lib/ui/primitives.js';
+// ^ Breaks when building library!
+```
+
+✅ Good (use direct package imports):
+```javascript
+// In src/lib/ui/MyComponent.svelte
+import { Button } from '@some/library/ui/primitives.js';
+```
+
+✅ Good (local aliases work everywhere):
+```javascript
+// svelte.config.js
+alias: {
+  '$lib': 'src/lib',              // ✅ Inside project
+  '$examples': 'src/routes/examples'  // ✅ Inside project
+}
+
+// In src/lib/ui/MyComponent.svelte
+import { helper } from '$lib/util/helpers.js';  // ✅ Works!
+```
+
+✅ Also good (aliases work fine in app code):
+```javascript
+// In src/routes/+page.svelte (not built/published)
+import { Button } from '$ext-lib/ui/primitives.js';
+// ✅ OK - app code isn't published
+```
+
+**Scope:**
+- **Enforced in**: `src/lib/**` (library code that gets built)
+- **Allowed in**: `src/routes/**` (app code, not published)
+
+**Why:** Vite/SvelteKit aliases are designed for internal project
+structure. Build tools (`@sveltejs/package`, Vite) cannot properly
+handle aliases pointing outside the project folder or to package names.
+For external dependencies, use direct imports.
+
 ## How Module Resolution Works
 
 Understanding how Node.js and Vite resolve imports helps explain

package/scripts/validate-imports.mjs

@@ -23,6 +23,15 @@ const EXTERNAL_SCOPES_TO_VALIDATE = ['@hkdigital'];
  */
 let PROJECT_ALIASES = {};
 
+/**
+ * Unsafe aliases that don't resolve inside the project folder
+ * These break when building libraries with @sveltejs/package
+ *
+ * Maps alias name to suggested fix (package name or explanation)
+ * @type {Map<string, string>}
+ */
+const UNSAFE_ALIASES = new Map();
+
 /**
  * Load aliases from svelte.config.js
  *
@@ -47,6 +56,62 @@ async function loadAliases() {
   return {};
 }
 
+/**
+ * Extract package name from node_modules path
+ *
+ * @param {string} path - Path containing node_modules
+ *
+ * @returns {string|null} Package name or null
+ */
+function extractPackageNameFromPath(path) {
+  // Find node_modules in the path
+  const match = path.match(/node_modules\/(@[^/]+\/[^/]+|[^/]+)/);
+  if (match) {
+    return match[1]; // Returns @scope/package or package
+  }
+  return null;
+}
+
+/**
+ * Detect unsafe aliases that don't resolve inside the project
+ * Populates the UNSAFE_ALIASES map
+ */
+function detectUnsafeAliases() {
+  UNSAFE_ALIASES.clear();
+
+  for (const [alias, target] of Object.entries(PROJECT_ALIASES)) {
+    let suggestion = null;
+
+    // Resolve to absolute path
+    const resolvedPath = isAbsolute(target) ?
+      target : join(PROJECT_ROOT, target);
+
+    // Normalize both paths for comparison (resolve symlinks, etc.)
+    const normalizedResolved = resolve(resolvedPath);
+    const normalizedRoot = resolve(PROJECT_ROOT);
+
+    // Check if resolved path is inside the project folder
+    const isInsideProject = normalizedResolved.startsWith(normalizedRoot);
+
+    if (!isInsideProject) {
+      // Path is outside project - check if it's in node_modules
+      if (resolvedPath.includes('/node_modules/')) {
+        const packageName = extractPackageNameFromPath(resolvedPath);
+        if (packageName) {
+          suggestion = packageName;
+        }
+      } else {
+        // Outside project but not node_modules
+        suggestion = '(path outside project - use direct imports)';
+      }
+
+      if (suggestion) {
+        UNSAFE_ALIASES.set(alias, suggestion);
+      }
+    }
+  }
+}
+
 /**
  * Resolve an alias path to its filesystem location
  *
@@ -538,6 +603,42 @@ async function validateFile(filePath) {
     );
 
     if (isAliasImport) {
+      // Find which alias is being used
+      let matchedAlias = null;
+      for (const alias of Object.keys(PROJECT_ALIASES)) {
+        if (importPath === alias || importPath.startsWith(alias + '/')) {
+          matchedAlias = alias;
+          break;
+        }
+      }
+
+      // Check for unsafe alias usage in library code
+      if (isInLib && matchedAlias && UNSAFE_ALIASES.has(matchedAlias)) {
+        const suggestion = UNSAFE_ALIASES.get(matchedAlias);
+        const pathAfterAlias = importPath.slice(matchedAlias.length);
+
+        // Construct suggested import if it's a package name
+        let errorMsg;
+        if (suggestion.startsWith('(')) {
+          // Generic message (not a package name)
+          errorMsg = `${relativePath}:${lineNum}\n` +
+            `  from '${importPath}'\n` +
+            `  => ${suggestion}`;
+        } else {
+          // Package name - construct full import path
+          const suggestedImport = suggestion + pathAfterAlias;
+          errorMsg = `${relativePath}:${lineNum}\n` +
+            `  from '${importPath}'\n` +
+            `  => from '${suggestedImport}' ` +
+            `(alias resolves outside project)`;
+        }
+
+        errors.push(errorMsg);
+
+        // Skip further validation for this import
+        continue;
+      }
+
       // Extract imported names from the import statement
       const importedNames = extractImportNames(line);
 
@@ -981,6 +1082,22 @@ async function main() {
     console.log();
   }
 
+  // Detect unsafe aliases (outside project folder)
+  detectUnsafeAliases();
+
+  if (UNSAFE_ALIASES.size > 0) {
+    console.log(
+      '⚠️  Unsafe aliases detected (resolve outside project folder):'
+    );
+    for (const [alias, suggestion] of UNSAFE_ALIASES.entries()) {
+      console.log(
+        `  ${alias} → ${suggestion} ` +
+        `(breaks in src/lib/, OK in src/routes/)`
+      );
+    }
+    console.log();
+  }
+
   const files = await findFiles(SRC_DIR);
   const allErrors = [];