@hkdigital/lib-core 0.5.77 → 0.5.79

package/README.md

@@ -309,7 +309,6 @@ The validator automatically reads path aliases from your
 `svelte.config.js` and applies the same barrel export validation rules
 to alias imports. This ensures consistent import patterns across:
 - Internal `$lib/` imports
-- Project aliases like `$hklib-core`, `$hklib-pro`, etc.
 - External `@hkdigital/*` package imports
 
 **Validation rules (enforced for `src/lib/` files only):**
@@ -344,14 +343,6 @@ import Button from '$lib/ui/primitives/buttons/Button.svelte';
 import { ProfileBlocks } from '$lib/ui/components.js';
 import { Button } from '$lib/ui/primitives.js';
 
-// Project aliases - instead of deep imports:
-import { Logger } from '$hklib-core/logging/logger/Logger.js';
-import { HttpClient } from '$hklib-core/network/http/HttpClient.js';
-
-// Use barrel exports:
-import { Logger } from '$hklib-core/logging.js';
-import { HttpClient } from '$hklib-core/network/http.js';
-
 // External imports - instead of deep imports:
 import { TextButton } from '@hkdigital/lib-core/ui/primitives/buttons/index.js';
 import { TextInput } from '@hkdigital/lib-core/ui/primitives/inputs/index.js';
@@ -380,7 +371,6 @@ Validating import paths...
 Found project aliases:
   $src → src
   $examples → src/routes/examples
-  $hklib-core → src/lib
 
 src/lib/ui/panels/Panel.svelte:3
   from '$src/lib/ui/components.js'
@@ -394,10 +384,6 @@ src/lib/ui/pages/Profile.svelte:8
   from '$lib/ui/components/profile-blocks/ProfileBlocks.svelte'
   => from '$lib/ui/components.js' (use barrel export for shorter imports)
 
-src/lib/forms/LoginForm.svelte:4
-  from '$hklib-core/logging/logger/Logger.js'
-  => from '$hklib-core/logging.js' (use barrel export)
-
 src/lib/forms/LoginForm.svelte:6
   from '@hkdigital/lib-core/ui/primitives/buttons/index.js'
   => from '@hkdigital/lib-core/ui/primitives.js' (use barrel export)
@@ -409,8 +395,8 @@ src/routes/explorer/[...path]/+page.svelte:4
 
 **What gets checked for barrel export suggestions:**
 
-The validator only suggests barrel exports (for `$lib/`, project aliases,
-and external `@hkdigital/*` packages) for:
+The validator only suggests barrel exports (for `$lib/` and external
+`@hkdigital/*` packages) for:
 - Explicit `index.js` imports
 - Component files (`.svelte`)
 - Class files (capitalized `.js` files)
@@ -418,20 +404,6 @@ and external `@hkdigital/*` packages) for:
 Intentional imports like `helpers.js`, `config.js`, or other lowercase
 utility files are assumed to be the public API and won't be flagged.
 
-**Alias configuration:**
-
-The validator automatically detects aliases in your `svelte.config.js`.
-For example, if your config has:
-```js
-alias: {
-  $src: 'src',
-  $hklib-core: 'node_modules/@hkdigital/lib-core/dist'
-}
-```
-
-The validator will apply the same barrel export rules to these aliases
-as it does to `$lib/` and `@hkdigital/*` imports.
-
 ### Import Patterns and Export Structure
 
 **Public exports use domain-specific files matching folder names:**

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/dist/design/config/design-tokens.js

@@ -87,8 +87,8 @@ const STROKE_WIDTH_SIZES = {
  * 
  * @example Usage with generateTailwindThemeExtensions
  * ```javascript
- * import { generateTailwindThemeExtensions } from '@hkdigital/lib-core/design/index.js';
- * import { designTokens } from '@hkdigital/lib-core/design/config/design-tokens.js';
+ * import { generateTailwindThemeExtensions } from '../index.js';
+ * import { designTokens } from './design-tokens.js';
  * 
  * const themeExtensions = generateTailwindThemeExtensions(designTokens);
  * ```

package/dist/design/generators/index.d.ts

@@ -27,8 +27,8 @@
  * // ... other exports
  *
  * // your-project/tailwind.config.js
- * import { generateTailwindThemeExtensions } from '@hkdigital/lib-core/design/index.js';
- * import { customUtilitiesPlugin } from '@hkdigital/lib-core/design/index.js';
+ * import { generateTailwindThemeExtensions } from '../index.js';
+ * import { customUtilitiesPlugin } from '../index.js';
  * import * as designConfig from './src/lib/design/design-config.js';
  *
  * export default {

package/dist/design/generators/index.js

@@ -27,8 +27,8 @@
  * // ... other exports
  *
  * // your-project/tailwind.config.js
- * import { generateTailwindThemeExtensions } from '@hkdigital/lib-core/design/index.js';
- * import { customUtilitiesPlugin } from '@hkdigital/lib-core/design/index.js';
+ * import { generateTailwindThemeExtensions } from '../index.js';
+ * import { customUtilitiesPlugin } from '../index.js';
  * import * as designConfig from './src/lib/design/design-config.js';
  *
  * export default {

package/dist/design/index.js

@@ -7,7 +7,7 @@
  * 
  * @example Basic usage with default tokens
  * ```javascript
- * import { generateTailwindThemeExtensions, designTokens, customUtilitiesPlugin } from '@hkdigital/lib-core/design/index.js';
+ * import { generateTailwindThemeExtensions, designTokens, customUtilitiesPlugin } from './index.js';
  *
  * const themeExtensions = generateTailwindThemeExtensions(designTokens);
  * 
@@ -21,7 +21,7 @@
  * 
  * @example Custom design tokens
  * ```javascript
- * import { generateTailwindThemeExtensions } from '@hkdigital/lib-core/design/index.js';
+ * import { generateTailwindThemeExtensions } from './index.js';
  *
  * const myTokens = {
  *   TEXT_POINT_SIZES: [4, 8, 12, 16, 24],

package/dist/design/utils/root-vars.d.ts

@@ -25,7 +25,7 @@
  * @example
  * // +layout.svelte
  * <script>
- * import { designTokens, designTokensToRootCssVars } from '@hkdigital/lib-core/design/index.js';
+ * import { designTokens, designTokensToRootCssVars } from '../index.js';
  * </script>
  *
  * <svelte:head>

package/dist/design/utils/root-vars.js

@@ -114,7 +114,7 @@ function setRootCssVar(varName, value) {
  * @example
  * // +layout.svelte
  * <script>
- * import { designTokens, designTokensToRootCssVars } from '@hkdigital/lib-core/design/index.js';
+ * import { designTokens, designTokensToRootCssVars } from '../index.js';
  * </script>
  *
  * <svelte:head>

package/dist/logging/README.md

@@ -188,7 +188,7 @@ When integrating with a service management system, you can set up global
 error handling and forward service logs to the main logger:
 
 ```javascript
-import { ServiceManager } from '$hklib-core/services/index.js';
+import { ServiceManager } from '@hkdigital/lib-core/services/index.js';
 import { initClientLogger } from '$lib/logging/client.js';
 
 /** @type {ServiceManager} */

package/dist/logging/internal/logger/Logger.js

@@ -8,7 +8,7 @@
  *
  * @example
  * // Basic usage
- * import { Logger, LOG, INFO, DEBUG } from '@hkdigital/lib-core/logger/index.js';
+ * import { Logger, LOG, INFO, DEBUG } from '../../../logger/index.js';
  *
  * const logger = new Logger('myService', INFO);
  *

package/dist/services/README.md

@@ -163,7 +163,7 @@ Manages multiple services with dependency resolution and coordinated lifecycle o
 ### Usage
 
 ```javascript
-import { ServiceManager } from '$hklib-core/services/index.js';
+import { ServiceManager } from '@hkdigital/lib-core/services/index.js';
 
 import DatabaseService from './services/DatabaseService.js';
 import AuthService from './services/AuthService.js';
@@ -211,7 +211,7 @@ class AuthService extends ServiceBase {
   /** @type {(<T>(serviceName: string) => T)} */
   #getService;
 
-  /** @type {() => import('$hklib-core/services/index.js').ServiceManager} */
+  /** @type {() => import('@hkdigital/lib-core/services/index.js').ServiceManager} */
   #getManager;
 
   constructor(serviceName, options) {
@@ -257,7 +257,7 @@ export default class PlayerService extends ServiceBase {
 
   /**
    * @param {string} serviceName
-   * @param {import('$hklib-core/services/typedef.js').ServiceOptions} [options]
+   * @param {import('@hkdigital/lib-core/services/typedef.js').ServiceOptions} [options]
    */
   constructor(serviceName, options) {
     super(serviceName, options);

package/dist/ui/components/game-box/_previous/GameBox.svelte

@@ -7,7 +7,7 @@
   } from './gamebox.util.js';
 
   import { enableContainerScaling } from '../../../../design/index.js';
-  // import { enableContainerScaling } from '@hkdigital/lib-core/design/index.js';
+  // import { enableContainerScaling } from '../../../../design/index.js';
 
   /**
    * @typedef {{

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@hkdigital/lib-core",
-	"version": "0.5.77",
+	"version": "0.5.79",
 	"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,10 +56,66 @@ 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
  *
- * @param {string} aliasPath - Import path using alias (e.g., $hklib-core/...)
+ * @param {string} aliasPath - Import path using alias (e.g., $examples/...)
  *
  * @returns {string|null} Resolved filesystem path or null
  */
@@ -379,9 +444,9 @@ async function findExternalBarrelExport(importPath, targetName) {
 /**
  * Find highest-level barrel export in alias path
  *
- * For $hklib-core/ui/primitives/buttons/index.js:
- * - Check $hklib-core/ui/primitives.js
- * - Check $hklib-core/ui.js
+ * For $components/ui/primitives/buttons/index.js:
+ * - Check $components/ui/primitives.js
+ * - Check $components/ui.js
  *
  * @param {string} importPath - Alias import path
  * @param {string} targetName - Name of export to find
@@ -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 = [];