@hkdigital/lib-core 0.5.67 → 0.5.68

package/README.md

@@ -289,11 +289,32 @@ 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
+
+**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
+// 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';
+```
+
+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.
 
 **Routes are exempt from strict rules:**
 
@@ -305,9 +326,13 @@ 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/routes/explorer/[...path]/+page.svelte:4
   from '../components/index.js'

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.68",
 	"author": {
 		"name": "HKdigital",
 		"url": "https://hkdigital.nl"

package/scripts/validate-imports.mjs

@@ -31,6 +31,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
  *
@@ -129,11 +189,29 @@ async function validateFile(filePath) {
     // 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 +401,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;