@hkdigital/lib-core 0.5.67 → 0.5.69

package/README.md

@@ -280,20 +280,68 @@ pnpm run publish:npm # Version bump and publish to npm
 ### Import Validation
 
 The library includes a validation script to enforce consistent import
-patterns. Run it in your project:
+patterns across both your project files and external `@hkdigital/*`
+package imports.
+
+**Add to your project's package.json:**
+
+```json
+{
+  "scripts": {
+    "lint:imports": "node node_modules/@hkdigital/lib-core/scripts/validate-imports.mjs"
+  }
+}
+```
+
+**Run validation:**
 
 ```bash
+# Using npm script (recommended)
+pnpm run lint:imports
+
+# Or directly
 node node_modules/@hkdigital/lib-core/scripts/validate-imports.mjs
 ```
 
 **Validation rules (enforced for `src/lib/` files only):**
 
 1. **Cross-domain imports** - Use `$lib/` instead of `../../../`
-2. **Parent index.js imports** - Use `$lib/` or import specific files
-3. **Non-standard extensions** - Include full extension (e.g.,
+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.,
    `.svelte.js`)
-4. **Directory imports** - Write explicitly (e.g., `./path/index.js`)
-5. **File existence** - All import paths must resolve to existing files
+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
+
+**Barrel export preference:**
+
+The validator suggests using the highest-level barrel export file that
+exports your target. This encourages shorter imports that can be
+combined:
+
+```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';
+
+// Use barrel exports:
+import { ProfileBlocks } from '$lib/ui/components.js';
+import { Button } from '$lib/ui/primitives.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';
+
+// Use barrel exports:
+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.
 
 **Routes are exempt from strict rules:**
 
@@ -305,15 +353,33 @@ files.
 **Example output:**
 
 ```
-src/lib/ui/components/Button.svelte:7
-  from '$lib/ui/primitives/buttons'
-  => from '$lib/ui/primitives/buttons/index.js'
+src/lib/ui/panels/Panel.svelte:6
+  from '../../../components/profile-blocks/ProfileBlocks.svelte'
+  => from '$lib/ui/components.js' (use barrel export)
+
+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 '@hkdigital/lib-core/ui/primitives/buttons/index.js'
+  => from '@hkdigital/lib-core/ui/primitives.js' (use barrel export)
 
 src/routes/explorer/[...path]/+page.svelte:4
   from '../components/index.js'
   ✅ Allowed in routes
 ```
 
+**What gets checked for external packages:**
+
+The validator only suggests barrel exports for:
+- Explicit `index.js` imports
+- Component files (`.svelte`)
+- Class files (capitalized `.js` files)
+
+Intentional imports like `helpers.js`, `config.js`, or other lowercase
+utility files are assumed to be the public API and won't be flagged.
+
 ### Import Patterns and Export Structure
 
 **Public exports use domain-specific files matching folder names:**

package/claude.md

@@ -112,18 +112,24 @@ This is a modern SvelteKit library built with Svelte 5 and Skeleton.dev v3 compo
 - Use `$lib/domain/...` imports for cross-domain references (e.g., `$lib/media/image.js`, `$lib/network/http.js`)
 - Use relative imports (`./` or `../`) when staying within the same main folder under `$lib`
 - **Always include file extensions** (`.js`, `.svelte`) in import statements
+- **Prefer barrel exports** - Use higher-level export files when available (e.g., `$lib/ui/components.js` instead of `$lib/ui/components/profile/ProfileBlocks.svelte`)
 - **For cross-domain imports, use specific export files** (e.g., `parsers.js`, `valibot.js`) rather than directory-only paths - this ensures compatibility outside the library
 - **For local imports within the same domain**, import specific files directly (e.g., `./ClassName.js`) rather than using local index files
 - Examples:
+  - ✅ `import { ProfileBlocks } from '$lib/ui/components.js'` (barrel export - preferred)
+  - ✅ `import { Button } from '$lib/ui/primitives.js'` (barrel export - preferred)
   - ✅ `import { ImageLoader } from '$lib/media/image.js'` (cross-domain import)
   - ✅ `import ImageLoader from './ImageLoader.svelte.js'` (local import within same domain)
   - ✅ `import IterableTree from './IterableTree.js'` (local import within same domain)
   - ✅ `import { v } from '$lib/valibot/valibot.js'` (cross-domain with specific export file)
   - ✅ `import { HumanUrl, Email } from '$lib/valibot/parsers.js'` (cross-domain with specific export file)
+  - ❌ `import ProfileBlocks from '$lib/ui/components/profile/ProfileBlocks.svelte'` (deep import when barrel exists)
   - ❌ `import { v, HumanUrl } from '$lib/valibot'` (missing specific export file)
   - ❌ `import { IterableTree } from './index.js'` (local index when specific file should be used)
   - ❌ `import something from '../../media/image.js'` (cross-domain relative import)
 
+**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.
+
 ## Class Export Conventions
 - **All classes should be default exports**: `export default class ClassName`
 - **Import classes without destructuring**: `import ClassName from './ClassName.js'`

package/dist/network/http/caching.js

@@ -1,5 +1,4 @@
-import MemoryResponseCache from '../cache/MemoryResponseCache.js';
-import IndexedDbCache from '../cache/IndexedDbCache.js';
+import { MemoryResponseCache, IndexedDbCache } from '../cache.js';
 
 import { browser } from '$app/environment';
 

package/dist/state/machines/finite-state-machine/FiniteStateMachine.svelte.d.ts

@@ -53,4 +53,4 @@ export default class FiniteStateMachine extends EventEmitter {
 export type TransitionData = import("./typedef.js").TransitionData;
 export type OnEnterCallback = import("./typedef.js").OnEnterCallback;
 export type OnExitCallback = import("./typedef.js").OnExitCallback;
-import EventEmitter from '../../../generic/events/classes/EventEmitter.js';
+import { EventEmitter } from '../../../generic/events.js';

package/dist/state/machines/finite-state-machine/FiniteStateMachine.svelte.js

@@ -5,7 +5,7 @@
  */
 
 import { isTestEnv } from '../../../util/env.js';
-import EventEmitter from '../../../generic/events/classes/EventEmitter.js';
+import { EventEmitter } from '../../../generic/events.js';
 import { ENTER, EXIT } from './constants.js';
 
 /** @typedef {import('./typedef.js').TransitionData} TransitionData */

package/dist/ui/components/button-group/ButtonGroup.svelte

@@ -6,7 +6,7 @@
    */
 
   import { onMount } from 'svelte';
-  import { findFirst } from '../../../util/array/index.js';
+  import { findFirst } from '../../../util/array.js';
 
   /**
    * @type {{

package/dist/ui/components/hk-app-layout/HkAppLayout.svelte

@@ -20,7 +20,7 @@
 	 * </AppLayout>
 	 */
 
-	import { useResizeObserver } from '../../../util/svelte/observe/index.js';
+	import { useResizeObserver } from '../../../util/svelte.js';
 
 	/**
 	 * @typedef AppLayoutProps

package/dist/ui/components/image-box/ImageBox.svelte

@@ -1,7 +1,6 @@
 <script>
-	import { ImageLoader } from '../../../network/loaders.js';
-	import { ImageVariantsLoader } from '../../../network/loaders.js';
-	import { toSingleImageMeta } from '../../../network/loaders/image/utils/index.js';
+	import { ImageLoader, ImageVariantsLoader } from '../../../network/loaders.js';
+	import { toSingleImageMeta } from '../../../network/loaders/image.js';
 
 	/**
 	 * @type {{

package/dist/ui/components/presenter/Presenter.state.svelte.js

@@ -1,8 +1,6 @@
-import { tick } from 'svelte';
+import { tick, untrack } from 'svelte';
 
-import { findFirst } from '../../../util/array/index.js';
-
-import { untrack } from 'svelte';
+import { findFirst } from '../../../util/array.js';
 
 import { HkPromise } from '../../../generic/promises.js';
 

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

@@ -2,7 +2,7 @@ import { tick } from 'svelte';
 
 import * as expect from '../../../util/expect.js';
 
-import { pushNotEmpty } from '../../../util/array/index.js';
+import { pushNotEmpty } from '../../../util/array.js';
 
 import { TRANSITION_CSS, FADE_IN, FADE_OUT } from './constants.js';
 

package/dist/ui/components/tab-bar/HkTabBarSelector.state.svelte.js

@@ -1,6 +1,6 @@
 import { defineStateContext } from '../../../state/context.js';
 
-import { useResizeObserver } from '../../../util/svelte/observe/index.js';
+import { useResizeObserver } from '../../../util/svelte.js';
 
 /* ------------------------------------------------------- Define state class */
 

package/dist/ui/primitives/buttons/button-icon-steeze/SteezeIconButton.svelte

@@ -1,7 +1,7 @@
 <script>
   import Button from '../button/Button.svelte';
 
-  import { SteezeIcon } from '../../icons/index.js';
+  import { SteezeIcon } from '../../../primitives.js';
 
   /**
    * @type {{

package/dist/ui/primitives/inputs/text-input/TextInput.svelte

@@ -4,7 +4,7 @@
 
   import { Star, ExclamationTriangle, CheckCircle } from '@steeze-ui/heroicons';
 
-  import { HkIcon } from '../../icons/index.js';
+  import { HkIcon } from '../../../primitives.js';
 
   import {
     PRISTINE,

package/dist/util/string/array-path.js

@@ -1,4 +1,4 @@
-import { PATH_SEPARATOR } from '../object/index.js';
+import { PATH_SEPARATOR } from '../object.js';
 
 /**
  * Convert a path string to an array path

package/dist/util/string/interpolate.js

@@ -1,6 +1,6 @@
 import * as expect from '../expect.js';
 
-import { toArrayPath } from '../array/index.js';
+import { toArrayPath } from '../array.js';
 
 import { objectGet, PATH_SEPARATOR } from '../object.js';
 

package/package.json

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

package/scripts/validate-imports.mjs

@@ -6,6 +6,12 @@ import { join, relative, resolve, dirname } from 'node:path';
 const PROJECT_ROOT = process.cwd();
 const SRC_DIR = join(PROJECT_ROOT, 'src');
 
+/**
+ * Scopes to validate for barrel exports
+ * Any package under these scopes will be checked
+ */
+const EXTERNAL_SCOPES_TO_VALIDATE = ['@hkdigital'];
+
 /**
  * Find all JS and Svelte files recursively
  *
@@ -31,6 +37,66 @@ async function findFiles(dir) {
   return files;
 }
 
+/**
+ * Find highest-level barrel export file that exports the target
+ *
+ * For a path like $lib/ui/components/profile-blocks/ProfileBlocks.svelte:
+ * - Check $lib/ui.js
+ * - Check $lib/ui/components.js
+ * - Check $lib/ui/components/profile-blocks.js
+ *
+ * @param {string} importPath - Import path (e.g., $lib/ui/components/...)
+ * @param {string} filePath - Source file making the import
+ *
+ * @returns {Promise<string|null>} Barrel file path or null
+ */
+async function findBarrelExportFile(importPath, filePath) {
+  if (!importPath.startsWith('$lib/')) return null;
+
+  // Remove $lib/ prefix and extract path segments
+  const pathWithoutLib = importPath.replace('$lib/', '');
+  const parts = pathWithoutLib.split('/');
+
+  // Extract the target filename (last part, possibly with extension)
+  const targetFile = parts[parts.length - 1];
+  const targetBase = targetFile.replace(/\.(js|svelte)$/, '');
+
+  // Check from highest level down (but skip the filename itself)
+  for (let i = 1; i < parts.length; i++) {
+    const barrelPath = '$lib/' + parts.slice(0, i).join('/') + '.js';
+    const fsBarrelPath = join(
+      PROJECT_ROOT,
+      barrelPath.replace('$lib/', 'src/lib/')
+    );
+
+    try {
+      const stats = await stat(fsBarrelPath);
+      if (stats.isFile()) {
+        // Check if this barrel file exports our target
+        const content = await readFile(fsBarrelPath, 'utf-8');
+
+        // Look for exports that match the target file
+        // Patterns:
+        // export { ProfileBlocks } from './path/ProfileBlocks.svelte';
+        // export * from './path/ProfileBlocks.svelte';
+        // More flexible pattern to catch various export styles
+        const exportPattern = new RegExp(
+          `export\\s+(?:\\*|\\{[^}]*\\})\\s+from\\s+['"](?:.*/)?(${targetBase}(?:\\.(?:js|svelte))?)['"]`,
+          'gm'
+        );
+
+        if (exportPattern.test(content)) {
+          return barrelPath;
+        }
+      }
+    } catch {
+      // File doesn't exist or can't be read, continue
+    }
+  }
+
+  return null;
+}
+
 /**
  * Check if import path resolves to directory with index.js
  *
@@ -81,6 +147,137 @@ async function isDirectoryWithIndex(fsPath) {
   return false;
 }
 
+/**
+ * Extract imported names from import statement
+ *
+ * @param {string} line - Import statement line
+ *
+ * @returns {string[]} Array of imported names
+ */
+function extractImportNames(line) {
+  const names = [];
+
+  // Default import: import Foo from '...'
+  const defaultMatch = line.match(/import\s+(\w+)\s+from/);
+  if (defaultMatch) {
+    names.push(defaultMatch[1]);
+  }
+
+  // Named imports: import { Foo, Bar } from '...'
+  const namedMatch = line.match(/import\s+\{([^}]+)\}\s+from/);
+  if (namedMatch) {
+    const namedImports = namedMatch[1]
+      .split(',')
+      .map(name => {
+        // Handle 'as' aliases: { Foo as Bar } → extract 'Foo'
+        const parts = name.trim().split(/\s+as\s+/);
+        return parts[0].trim();
+      })
+      .filter(name => name && name !== '*');
+    names.push(...namedImports);
+  }
+
+  return names;
+}
+
+/**
+ * Find highest-level barrel export in external package
+ *
+ * For @hkdigital/lib-core/ui/primitives/buttons/index.js:
+ * - Check @hkdigital/lib-core/ui/primitives.js
+ * - Check @hkdigital/lib-core/ui.js
+ *
+ * @param {string} importPath - External import path
+ * @param {string} targetName - Name of export to find
+ *
+ * @returns {Promise<string|null>} Suggested barrel path or null
+ */
+async function findExternalBarrelExport(importPath, targetName) {
+  // Extract package name (handle scoped packages)
+  const parts = importPath.split('/');
+  let pkgName;
+  let pathInPackage;
+
+  if (importPath.startsWith('@')) {
+    // Scoped package: @scope/package/path/to/file
+    pkgName = `${parts[0]}/${parts[1]}`;
+    pathInPackage = parts.slice(2);
+  } else {
+    // Regular package: package/path/to/file
+    pkgName = parts[0];
+    pathInPackage = parts.slice(1);
+  }
+
+  // Check if this scope should be validated
+  const scope = pkgName.startsWith('@') ?
+    pkgName.split('/')[0] : null;
+  if (scope && !EXTERNAL_SCOPES_TO_VALIDATE.includes(scope)) {
+    return null;
+  }
+
+  // If no path in package, nothing to suggest
+  if (pathInPackage.length === 0) return null;
+
+  const nodeModulesPath = join(PROJECT_ROOT, 'node_modules', pkgName);
+
+  // Extract target to find (last part without extension)
+  const lastPart = pathInPackage[pathInPackage.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 < pathInPackage.length; i++) {
+    const barrelPath = pathInPackage.slice(0, i).join('/') + '.js';
+    const fsBarrelPath = join(nodeModulesPath, 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 `${pkgName}/${barrelPath}`;
+        }
+      }
+    } catch {
+      // File doesn't exist, continue
+    }
+  }
+
+  return null;
+}
+
 /**
  * Validate import paths in a file
  *
@@ -119,21 +316,69 @@ async function validateFile(filePath) {
     // Strip query parameters (Vite asset imports like ?preset=render)
     const importPath = importPathRaw.split('?')[0];
 
-    // Skip external packages (no ./ or $lib prefix)
-    if (!importPath.startsWith('./') &&
-        !importPath.startsWith('../') &&
-        !importPath.startsWith('$lib/')) {
+    // Check external packages from configured scopes
+    const isExternalPackage = !importPath.startsWith('./') &&
+      !importPath.startsWith('../') &&
+      !importPath.startsWith('$lib/');
+
+    if (isExternalPackage) {
+      // Extract package name/scope
+      const parts = importPath.split('/');
+      const scope = importPath.startsWith('@') ? parts[0] : null;
+
+      // Check if this scope should be validated
+      if (scope && EXTERNAL_SCOPES_TO_VALIDATE.includes(scope)) {
+        // 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 findExternalBarrelExport(
+            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 external packages
       continue;
     }
 
     // Check 1: Cross-domain relative imports (3+ levels up)
     // Only enforce for lib files
     if (isInLib && importPath.match(/^\.\.\/\.\.\/\.\.\//)) {
-      errors.push(
-        `${relativePath}:${lineNum}\n` +
-        `  from '${importPath}'\n` +
-        `  => Use $lib/ for cross-domain imports`
+      // Convert relative path to $lib/ path
+      const fsPath = resolve(dirname(filePath), importPath);
+      const libPath = fsPath.replace(
+        join(PROJECT_ROOT, 'src/lib/'),
+        '$lib/'
       );
+
+      // Check for barrel export files
+      const barrelFile = await findBarrelExportFile(libPath, filePath);
+
+      if (barrelFile) {
+        errors.push(
+          `${relativePath}:${lineNum}\n` +
+          `  from '${importPath}'\n` +
+          `  => from '${barrelFile}' (use barrel export)`
+        );
+      } else {
+        errors.push(
+          `${relativePath}:${lineNum}\n` +
+          `  from '${importPath}'\n` +
+          `  => from '${libPath}'`
+        );
+      }
       continue;
     }
 
@@ -323,7 +568,52 @@ async function validateFile(filePath) {
       }
     }
 
-    // Check 5: File existence (after all other checks)
+    // Check 5: Suggest barrel exports for deep $lib/ imports
+    // Only for specific cases, not for named export files
+    if (isInLib && importPath.startsWith('$lib/')) {
+      const pathWithoutLib = importPath.replace('$lib/', '');
+      const segments = pathWithoutLib.split('/');
+
+      // Only suggest barrel exports for:
+      // 1. Directory imports (no extension, resolves to index.js)
+      // 2. Explicit index.js imports
+      // 3. Deep component/class files (.svelte or capitalized .js files)
+      let shouldCheckBarrel = false;
+
+      if (segments.length >= 3) {
+        const lastSegment = segments[segments.length - 1];
+
+        // Case 1: Explicit index.js import
+        if (lastSegment === 'index.js') {
+          shouldCheckBarrel = true;
+        }
+        // Case 2: Directory import (will be caught by Check 4)
+        // Case 3: Component or class file (.svelte or capitalized)
+        else if (lastSegment.endsWith('.svelte')) {
+          shouldCheckBarrel = true;
+        } else if (lastSegment.match(/^[A-Z][^/]*\.js$/)) {
+          // Capitalized .js file (likely a class)
+          shouldCheckBarrel = true;
+        }
+        // Skip named export files like methods.js, http.js, etc.
+        // These are lowercase and ARE the public API
+      }
+
+      if (shouldCheckBarrel) {
+        const barrelFile = await findBarrelExportFile(importPath, filePath);
+
+        if (barrelFile) {
+          errors.push(
+            `${relativePath}:${lineNum}\n` +
+            `  from '${importPath}'\n` +
+            `  => from '${barrelFile}' (use barrel export for shorter imports)`
+          );
+          continue;
+        }
+      }
+    }
+
+    // Check 6: File existence (after all other checks)
     // Verify that the import path resolves to an existing file
     // Follow Node.js/Vite resolution order
     let fileExists = false;