@hkdigital/lib-core 0.5.63 → 0.5.66

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

package/scripts/validate-imports.mjs

@@ -2,10 +2,8 @@
 
 import { readdir, readFile, stat } from 'node:fs/promises';
 import { join, relative, resolve, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
 
-const __dirname = fileURLToPath(new URL('.', import.meta.url));
-const PROJECT_ROOT = join(__dirname, '..');
+const PROJECT_ROOT = process.cwd();
 const SRC_DIR = join(PROJECT_ROOT, 'src');
 
 /**
@@ -96,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');
@@ -127,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
@@ -145,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;
       }
@@ -256,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;
@@ -288,9 +293,10 @@ async function validateFile(filePath) {
 
         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 like '${importPath}.js' or ` +
+            `import specific file`
           );
           continue;
         }
@@ -298,8 +304,9 @@ async function validateFile(filePath) {
         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;
       }
@@ -338,8 +345,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`
       );
     }
   }
@@ -363,8 +371,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);
   }