@hkdigital/lib-core 0.5.68 → 0.5.70

package/README.md

@@ -280,9 +280,26 @@ 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
 ```
 
@@ -295,6 +312,8 @@ node node_modules/@hkdigital/lib-core/scripts/validate-imports.mjs
    `.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
 
 **Barrel export preference:**
 
@@ -303,18 +322,26 @@ exports your target. This encourages shorter imports that can be
 combined:
 
 ```js
-// Instead of deep imports:
+// 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.
+suggests the highest-level file that exports your target. The same
+logic applies to external `@hkdigital/*` packages.
 
 **Routes are exempt from strict rules:**
 
@@ -334,11 +361,25 @@ 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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@hkdigital/lib-core",
-	"version": "0.5.68",
+	"version": "0.5.70",
 	"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
  *
@@ -141,6 +147,173 @@ 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;
+
+  // Read package.json to check for exports mapping
+  let exportsMapping = null;
+  try {
+    const pkgJsonPath = join(nodeModulesPath, 'package.json');
+    const pkgJsonContent = await readFile(pkgJsonPath, 'utf-8');
+    const pkgJson = JSON.parse(pkgJsonContent);
+
+    // Check if there's a "./*" export mapping
+    if (pkgJson.exports && pkgJson.exports['./*']) {
+      const mapping = pkgJson.exports['./*'];
+      const mappingStr = typeof mapping === 'string' ?
+        mapping : mapping.default;
+
+      // Extract prefix from mapping like "./dist/*" -> "dist/"
+      if (mappingStr && mappingStr.includes('*')) {
+        exportsMapping = mappingStr.replace(/\/?\*$/, '');
+        if (exportsMapping.startsWith('./')) {
+          exportsMapping = exportsMapping.slice(2);
+        }
+        if (exportsMapping && !exportsMapping.endsWith('/')) {
+          exportsMapping += '/';
+        }
+      }
+    }
+  } catch {
+    // Could not read package.json, continue without mapping
+  }
+
+  // Try progressively higher-level barrel files
+  for (let i = 1; i < pathInPackage.length; i++) {
+    const barrelPath = pathInPackage.slice(0, i).join('/') + '.js';
+
+    // Try both with and without exports mapping
+    const pathsToTry = [
+      join(nodeModulesPath, barrelPath),
+      exportsMapping ?
+        join(nodeModulesPath, exportsMapping + barrelPath) : null
+    ].filter(Boolean);
+
+    for (const fsBarrelPath of pathsToTry) {
+      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
  *
@@ -179,10 +352,40 @@ 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;
     }