@hkdigital/lib-core 0.5.70 → 0.5.72

package/README.md

@@ -303,17 +303,27 @@ pnpm run lint:imports
 node node_modules/@hkdigital/lib-core/scripts/validate-imports.mjs
 ```
 
+**Alias support:**
+
+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):**
 
-1. **Cross-domain imports** - Use `$lib/` instead of `../../../`
-2. **Prefer barrel exports** - Use higher-level export files when available
-3. **Parent index.js imports** - Use `$lib/` or import specific files
-4. **Non-standard extensions** - Include full extension (e.g.,
+1. **Alias optimization** - Use `$lib` instead of `$src/lib` (built-in
+   SvelteKit alias)
+2. **Cross-domain imports** - Use `$lib/` instead of `../../../`
+3. **Prefer barrel exports** - Use higher-level export files when
+   available (applies to `$lib/`, aliases, and `@hkdigital/*` packages)
+4. **Parent index.js imports** - Use `$lib/` or import specific files
+5. **Non-standard extensions** - Include full extension (e.g.,
    `.svelte.js`)
-5. **Directory imports** - Write explicitly or create barrel export file
-6. **File existence** - All import paths must resolve to existing files
-7. **External package optimization** - Suggests barrel exports for
-   `@hkdigital/*` packages
+6. **Directory imports** - Write explicitly or create barrel export file
+7. **File existence** - All import paths must resolve to existing files
 
 **Barrel export preference:**
 
@@ -322,6 +332,10 @@ exports your target. This encourages shorter imports that can be
 combined:
 
 ```js
+// Optimize built-in aliases:
+import { MyComponent } from '$src/lib/ui/components.js';
+// → Use: import { MyComponent } from '$lib/ui/components.js';
+
 // Internal imports - instead of deep imports:
 import ProfileBlocks from '$lib/ui/components/profile-blocks/ProfileBlocks.svelte';
 import Button from '$lib/ui/primitives/buttons/Button.svelte';
@@ -330,6 +344,14 @@ 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';
@@ -341,7 +363,7 @@ import { TextButton, TextInput } from '@hkdigital/lib-core/ui/primitives.js';
 The validator checks from highest to lowest level (`$lib/ui.js` →
 `$lib/ui/components.js` → `$lib/ui/components/profile-blocks.js`) and
 suggests the highest-level file that exports your target. The same
-logic applies to external `@hkdigital/*` packages.
+logic applies to project aliases and external `@hkdigital/*` packages.
 
 **Routes are exempt from strict rules:**
 
@@ -353,6 +375,17 @@ files.
 **Example output:**
 
 ```
+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'
+  => from '$lib/ui/components.js' (use built-in $lib alias)
+
 src/lib/ui/panels/Panel.svelte:6
   from '../../../components/profile-blocks/ProfileBlocks.svelte'
   => from '$lib/ui/components.js' (use barrel export)
@@ -362,6 +395,10 @@ src/lib/ui/pages/Profile.svelte:8
   => 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)
 
@@ -370,9 +407,10 @@ src/routes/explorer/[...path]/+page.svelte:4
   ✅ Allowed in routes
 ```
 
-**What gets checked for external packages:**
+**What gets checked for barrel export suggestions:**
 
-The validator only suggests barrel exports for:
+The validator only suggests barrel exports (for `$lib/`, project aliases,
+and external `@hkdigital/*` packages) for:
 - Explicit `index.js` imports
 - Component files (`.svelte`)
 - Class files (capitalized `.js` files)
@@ -380,6 +418,20 @@ The validator only suggests barrel exports 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/dist/ui/components/presenter/Presenter.svelte.d.ts

@@ -13,6 +13,6 @@ declare const Presenter: import("svelte").Component<{
     classes?: string;
     slides?: import("./typedef.js").Slide[];
     presenterRef?: import("./Presenter.state.svelte.js").PresenterRef;
-    layoutSnippet: import("svelte").Snippet<[import("../../components.js").Slide | null, import("../../components.js").Layer]>;
+    layoutSnippet: import("svelte").Snippet<[import("./typedef.js").Slide | null, import("./typedef.js").Layer]>;
     loadingSnippet?: import("svelte").Snippet;
 }, {}, "presenterRef">;

package/dist/ui/components/presenter/index.d.ts

@@ -1,6 +1,5 @@
 export { default as Presenter } from "./Presenter.svelte";
 export { default as ImageSlide } from "./ImageSlide.svelte";
 export { PresenterState } from "./Presenter.state.svelte.js";
-export * from "./typedef.js";
 export * from "./constants.js";
 export * from "./util.js";

package/dist/ui/components/presenter/index.js

@@ -3,7 +3,6 @@ export { default as ImageSlide } from './ImageSlide.svelte';
 
 export { PresenterState } from './Presenter.state.svelte.js';
 
-export * from './typedef.js';
 export * from './constants.js';
 
 // @ts-ignore

package/package.json

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

package/scripts/validate-imports.mjs

@@ -12,6 +12,55 @@ const SRC_DIR = join(PROJECT_ROOT, 'src');
  */
 const EXTERNAL_SCOPES_TO_VALIDATE = ['@hkdigital'];
 
+/**
+ * Project aliases from svelte.config.js
+ * Loaded dynamically at startup
+ *
+ * @type {Record<string, string>}
+ */
+let PROJECT_ALIASES = {};
+
+/**
+ * Load aliases from svelte.config.js
+ *
+ * @returns {Promise<Record<string, string>>} Alias mappings
+ */
+async function loadAliases() {
+  try {
+    const configPath = join(PROJECT_ROOT, 'svelte.config.js');
+
+    // Use dynamic import to load ES module
+    const config = await import(`file://${configPath}`);
+    const svelteConfig = config.default;
+
+    if (svelteConfig?.kit?.alias) {
+      return svelteConfig.kit.alias;
+    }
+  } catch (error) {
+    // Config file doesn't exist or can't be loaded
+    // This is OK - not all projects will have aliases
+  }
+
+  return {};
+}
+
+/**
+ * Resolve an alias path to its filesystem location
+ *
+ * @param {string} aliasPath - Import path using alias (e.g., $hklib-core/...)
+ *
+ * @returns {string|null} Resolved filesystem path or null
+ */
+function resolveAliasPath(aliasPath) {
+  for (const [alias, target] of Object.entries(PROJECT_ALIASES)) {
+    if (aliasPath === alias || aliasPath.startsWith(alias + '/')) {
+      const pathAfterAlias = aliasPath.slice(alias.length);
+      return join(PROJECT_ROOT, target, pathAfterAlias);
+    }
+  }
+  return null;
+}
+
 /**
  * Find all JS and Svelte files recursively
  *
@@ -314,6 +363,105 @@ async function findExternalBarrelExport(importPath, targetName) {
   return null;
 }
 
+/**
+ * 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
+ *
+ * @param {string} importPath - Alias import path
+ * @param {string} targetName - Name of export to find
+ *
+ * @returns {Promise<string|null>} Suggested barrel path or null
+ */
+async function findAliasBarrelExport(importPath, targetName) {
+  // Find the matching alias
+  let matchedAlias = null;
+  let pathAfterAlias = null;
+
+  for (const alias of Object.keys(PROJECT_ALIASES)) {
+    if (importPath === alias || importPath.startsWith(alias + '/')) {
+      matchedAlias = alias;
+      pathAfterAlias = importPath.slice(alias.length);
+      if (pathAfterAlias.startsWith('/')) {
+        pathAfterAlias = pathAfterAlias.slice(1);
+      }
+      break;
+    }
+  }
+
+  if (!matchedAlias || !pathAfterAlias) {
+    return null;
+  }
+
+  const pathInAlias = pathAfterAlias.split('/');
+
+  // If no path in alias, nothing to suggest
+  if (pathInAlias.length === 0 || pathInAlias[0] === '') {
+    return null;
+  }
+
+  const aliasRootPath = resolveAliasPath(matchedAlias);
+
+  // Extract target to find (last part without extension)
+  const lastPart = pathInAlias[pathInAlias.length - 1];
+  const targetBase = lastPart.replace(/\.(js|svelte)$/, '');
+
+  // Only check for specific import types (matches internal logic)
+  // 1. Explicit index.js imports
+  // 2. Component files (.svelte)
+  // 3. Class files (capitalized .js)
+  let shouldCheck = false;
+
+  if (lastPart === 'index.js') {
+    shouldCheck = true;
+  } else if (lastPart.endsWith('.svelte')) {
+    shouldCheck = true;
+  } else if (lastPart.match(/^[A-Z][^/]*\.js$/)) {
+    shouldCheck = true;
+  }
+
+  if (!shouldCheck) return null;
+
+  // Try progressively higher-level barrel files
+  for (let i = 1; i < pathInAlias.length; i++) {
+    const barrelPath = pathInAlias.slice(0, i).join('/') + '.js';
+    const fsBarrelPath = join(aliasRootPath, barrelPath);
+
+    try {
+      const stats = await stat(fsBarrelPath);
+      if (stats.isFile()) {
+        const content = await readFile(fsBarrelPath, 'utf-8');
+
+        // Check if this barrel exports our target
+        // Patterns to match:
+        // export { TextButton } from './path';
+        // export * from './path';
+        const exportPatterns = [
+          // Named export with exact name
+          new RegExp(
+            `export\\s+\\{[^}]*\\b${targetName}\\b[^}]*\\}`,
+            'm'
+          ),
+          // Re-export all
+          /export\s+\*\s+from/,
+          // Default export
+          new RegExp(`export\\s+default\\s+${targetName}\\b`, 'm')
+        ];
+
+        if (exportPatterns.some(pattern => pattern.test(content))) {
+          return `${matchedAlias}/${barrelPath}`;
+        }
+      }
+    } catch {
+      // File doesn't exist, continue
+    }
+  }
+
+  return null;
+}
+
 /**
  * Validate import paths in a file
  *
@@ -350,7 +498,52 @@ async function validateFile(filePath) {
     const importPathRaw = importMatch[1];
 
     // Strip query parameters (Vite asset imports like ?preset=render)
-    const importPath = importPathRaw.split('?')[0];
+    let importPath = importPathRaw.split('?')[0];
+
+    // Check if using $src/lib when $lib is available (built-in SvelteKit)
+    // Report the issue and normalize the path for further validation
+    let hasSrcLibIssue = false;
+    if (importPath.startsWith('$src/lib/') || importPath === '$src/lib') {
+      hasSrcLibIssue = true;
+      const optimizedPath = importPath.replace('$src/lib', '$lib');
+      errors.push(
+        `${relativePath}:${lineNum}\n` +
+        `  from '${importPath}'\n` +
+        `  => from '${optimizedPath}' (use built-in $lib alias)`
+      );
+      // Normalize for further validation
+      importPath = optimizedPath;
+    }
+
+    // Check if import uses a project alias
+    const isAliasImport = Object.keys(PROJECT_ALIASES).some(
+      alias => importPath === alias || importPath.startsWith(alias + '/')
+    );
+
+    if (isAliasImport) {
+      // Extract imported names from the import statement
+      const importedNames = extractImportNames(line);
+
+      // Check each imported name for barrel exports
+      for (const importedName of importedNames) {
+        const barrelPath = await findAliasBarrelExport(
+          importPath,
+          importedName
+        );
+
+        if (barrelPath) {
+          errors.push(
+            `${relativePath}:${lineNum}\n` +
+            `  from '${importPath}'\n` +
+            `  => from '${barrelPath}' (use barrel export)`
+          );
+          break; // Only report once per line
+        }
+      }
+
+      // Skip further validation for alias imports
+      continue;
+    }
 
     // Check external packages from configured scopes
     const isExternalPackage = !importPath.startsWith('./') &&
@@ -698,6 +891,17 @@ async function validateFile(filePath) {
 async function main() {
   console.log('Validating import paths...\n');
 
+  // Load project aliases from svelte.config.js
+  PROJECT_ALIASES = await loadAliases();
+
+  if (Object.keys(PROJECT_ALIASES).length > 0) {
+    console.log('Found project aliases:');
+    for (const [alias, target] of Object.entries(PROJECT_ALIASES)) {
+      console.log(`  ${alias} → ${target}`);
+    }
+    console.log();
+  }
+
   const files = await findFiles(SRC_DIR);
   const allErrors = [];