@hkdigital/lib-core 0.5.65 → 0.5.67

package/README.md

@@ -277,6 +277,43 @@ pnpm run upgrade:all # Update all packages
 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:
+
+```bash
+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.,
+   `.svelte.js`)
+4. **Directory imports** - Write explicitly (e.g., `./path/index.js`)
+5. **File existence** - All import paths must resolve to existing files
+
+**Routes are exempt from strict rules:**
+
+Files in `src/routes/` can use relative imports freely, including parent
+navigation and index.js imports. Since SvelteKit doesn't provide a
+`$routes` alias, relative imports are the standard pattern for route
+files.
+
+**Example output:**
+
+```
+src/lib/ui/components/Button.svelte:7
+  from '$lib/ui/primitives/buttons'
+  => from '$lib/ui/primitives/buttons/index.js'
+
+src/routes/explorer/[...path]/+page.svelte:4
+  from '../components/index.js'
+  ✅ Allowed in routes
+```
+
 ### Import Patterns and Export Structure
 
 **Public exports use domain-specific files matching folder names:**

package/package.json

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

package/scripts/validate-imports.mjs

@@ -94,6 +94,8 @@ async function validateFile(filePath) {
   const relativePath = relative(PROJECT_ROOT, filePath);
   const isTestFile = filePath.endsWith('.test.js') ||
     filePath.endsWith('.spec.js');
+  const isInLib = filePath.includes('/src/lib/');
+  const isInRoutes = filePath.includes('/src/routes/');
 
   // Check each line for import statements
   const lines = content.split('\n');
@@ -125,17 +127,20 @@ async function validateFile(filePath) {
     }
 
     // Check 1: Cross-domain relative imports (3+ levels up)
-    if (importPath.match(/^\.\.\/\.\.\/\.\.\//)) {
+    // Only enforce for lib files
+    if (isInLib && importPath.match(/^\.\.\/\.\.\/\.\.\//)) {
       errors.push(
-        `${relativePath}:${lineNum} - Cross-domain relative import ` +
-        `(use $lib/ instead)`
+        `${relativePath}:${lineNum}\n` +
+        `  from '${importPath}'\n` +
+        `  => Use $lib/ for cross-domain imports`
       );
       continue;
     }
 
-    // Check 2: Local index.js imports (skip for test files)
+    // Check 2: Local index.js imports (skip for test files and routes)
     // Allow ./index.js and ./subfolder/index.js but flag parent navigation
-    if (!isTestFile && importPath.match(/\/index\.js$/)) {
+    // Only enforce for lib files
+    if (isInLib && !isTestFile && importPath.match(/\/index\.js$/)) {
       // Allow same-directory and child directory imports
       // Examples: ./index.js, ./subfolder/index.js, ./(meta)/index.js
       // Flag parent navigation: ../index.js, ../../index.js
@@ -143,8 +148,9 @@ async function validateFile(filePath) {
 
       if (isParentNavigation) {
         errors.push(
-          `${relativePath}:${lineNum} - Parent index.js import ` +
-          `(use $lib/ or import specific file)`
+          `${relativePath}:${lineNum}\n` +
+          `  from '${importPath}'\n` +
+          `  => Use $lib/ or import specific file instead`
         );
         continue;
       }
@@ -254,8 +260,9 @@ async function validateFile(filePath) {
             if (stats.isFile()) {
               const correctImport = baseImportPath + ext;
               errors.push(
-                `${relativePath}:${lineNum} - Missing non-standard ` +
-                `extension (use '${correctImport}')`
+                `${relativePath}:${lineNum}\n` +
+                `  from '${importPath}'\n` +
+                `  => from '${correctImport}'`
               );
               foundNonStandard = true;
               break;
@@ -280,24 +287,37 @@ async function validateFile(filePath) {
     if (!hasAnyExtension) {
       // Check if it's a directory with index.js
       if (await isDirectoryWithIndex(fsPath)) {
-        // Don't suggest ../path/index.js (parent navigation)
-        // Suggest creating export file instead
-        const wouldBeParentNavigation = importPath.match(/^\.\.\//);
+        // For $lib/ imports, suggest creating a barrel export file
+        // following the library pattern: folder → matching .js file
+        if (importPath.startsWith('$lib/')) {
+          errors.push(
+            `${relativePath}:${lineNum}\n` +
+            `  from '${importPath}'\n` +
+            `  => Create export file: ${importPath}.js (remove index.js)`
+          );
+          continue;
+        }
 
+        // For relative imports with parent navigation,
+        // suggest creating export file
+        const wouldBeParentNavigation = importPath.match(/^\.\.\//);
         if (wouldBeParentNavigation) {
           errors.push(
-            `${relativePath}:${lineNum} - Directory import requires ` +
-            `parent navigation (create export file like '${importPath}.js' ` +
-            `or import specific file)`
+            `${relativePath}:${lineNum}\n` +
+            `  from '${importPath}'\n` +
+            `  => Create export file: ${importPath}.js or ` +
+            `import specific file`
           );
           continue;
         }
 
+        // For local relative imports (./path), suggest index.js
         const suggestion = importPath.endsWith('/') ?
           `${importPath}index.js` : `${importPath}/index.js`;
         errors.push(
-          `${relativePath}:${lineNum} - Directory import ` +
-          `(write explicitly: '${suggestion}')`
+          `${relativePath}:${lineNum}\n` +
+          `  from '${importPath}'\n` +
+          `  => from '${suggestion}'`
         );
         continue;
       }
@@ -336,8 +356,9 @@ async function validateFile(filePath) {
 
     if (!fileExists) {
       errors.push(
-        `${relativePath}:${lineNum} - Import path does not exist: ` +
-        `'${importPath}'`
+        `${relativePath}:${lineNum}\n` +
+        `  from '${importPath}'\n` +
+        `  => Import path does not exist`
       );
     }
   }
@@ -361,8 +382,8 @@ async function main() {
 
   if (allErrors.length > 0) {
     console.error('❌ Found import path violations:\n');
-    allErrors.forEach(error => console.error(`  ${error}`));
-    console.error(`\n${allErrors.length} error(s) found.`);
+    allErrors.forEach(error => console.error(`${error}\n`));
+    console.error(`${allErrors.length} error(s) found.`);
     process.exit(1);
   }