@jmruthers/pace-core 0.6.10 → 0.6.12

package/CHANGELOG.md

@@ -11,6 +11,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **DataTable: Automatic label display for select fields** - Select fields with `fieldType: 'select'` and `fieldOptions` now automatically display labels (e.g., "Mobile") instead of raw values (e.g., `1`) in read mode. This eliminates the need for custom cell renderers for common select field patterns. The feature supports simple options, grouped options, type coercion, and gracefully falls back to raw values when labels aren't found. Custom cell renderers are preserved if already defined.
 
 ### Breaking Changes
+- **Async API-style functions now return `ApiResult<T>` (error handling)**: All async API-style functions in pace-core now return `Promise<ApiResult<T>>` instead of throwing or returning raw values. Affected surfaces: RBAC (`isPermitted`, `getAccessLevel`, etc.), auth (auth-utils, `IAuthService`/`AuthService`), file-reference service and storage helpers (`extractFileMetadata`, `getSignedUrl`, `listFiles`, `downloadFile`, `generateFileUrlsBatch`), context/app utilities (`organisationContext`, `appIdResolver`), Google Places and CSRF, and security (`validateUserSession`, etc.).
+  - **Action Required**: Check `result.ok` and use `result.data` or `result.error` at every call site.
+  - **Migration**:
+    ```ts
+    // ❌ OLD: Direct value or throw
+    const data = await someApi();
+    if (!data) throw new Error('Failed');
+    use(data);
+
+    // ✅ NEW: ApiResult shape
+    const result = await someApi();
+    if (!result.ok) {
+      console.error(result.error.code, result.error.message);
+      return;
+    }
+    use(result.data);
+    ```
+  - **Types**: Import `ApiResult`, `ApiError`, and helpers `ok`, `err`, `isOk`, `isErr` from `@jmruthers/pace-core`.
+  - See [API & Tech Stack Standard](./docs/standards/7-api-tech-stack-standards.md) and [Architecture Standard](./docs/standards/3-architecture-standards.md).
+  - See [ApiResult migration guide](./docs/migration/ApiResult-migration.md) for affected surfaces and migration steps.
+
 - **@supabase/supabase-js is now an included dependency (security enforcement)**: Moved from peer dependency to included dependency to enforce security rules. Consuming apps can no longer import `createClient` directly.
   - **Action Required**: 
     - Remove `@supabase/supabase-js` from your `package.json` if installed

package/audit-tool/00-dependencies.cjs

@@ -154,22 +154,37 @@ function checkVersion(installed, required) {
 }
 
 // Main audit function - returns data structure for programmatic use
-function runDependencyAudit(consumingAppPath = process.cwd()) {
+// auditContext: { isPaceCorePackage?: boolean } - when true, skip audit (package does not install itself)
+function runDependencyAudit(consumingAppPath = process.cwd(), auditContext = {}) {
   const packageJsonPath = path.join(consumingAppPath, 'package.json');
-  
+  const emptyIssues = { includedDeps: [], missingRequired: [], missingOptional: [], versionIssues: [], wrongLocation: [], missingDevDeps: [], devVersionIssues: [] };
+
   if (!fs.existsSync(packageJsonPath)) {
     return {
       error: `package.json not found at ${packageJsonPath}`,
-      issues: { includedDeps: [], missingRequired: [], missingOptional: [], versionIssues: [], wrongLocation: [], missingDevDeps: [], devVersionIssues: [] }
+      issues: emptyIssues
     };
   }
+
+  if (auditContext.isPaceCorePackage === true) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+      return {
+        projectName: pkg.name || '@jmruthers/pace-core',
+        paceCoreVersion: 'self',
+        issues: emptyIssues
+      };
+    } catch (e) {
+      return { projectName: 'unknown', paceCoreVersion: 'self', issues: emptyIssues };
+    }
+  }
   
   // Load pace-core package.json
   const paceCorePath = findPaceCorePackageJson(consumingAppPath);
   if (!paceCorePath) {
     return {
       error: 'Could not find pace-core package.json. Make sure @jmruthers/pace-core is installed in your project.',
-      issues: { includedDeps: [], missingRequired: [], missingOptional: [], versionIssues: [], wrongLocation: [], missingDevDeps: [], devVersionIssues: [] }
+      issues: emptyIssues
     };
   }
   
@@ -223,16 +238,34 @@ function runDependencyAudit(consumingAppPath = process.cwd()) {
     devVersionIssues: [],
   };
   
-  // Check for included dependencies
-  INCLUDED_DEPS.forEach(dep => {
-    if (allDeps[dep]) {
-      issues.includedDeps.push({
-        package: dep,
-        installed: allDeps[dep],
-        location: consumingPkg.dependencies?.[dep] ? 'dependencies' : 'devDependencies',
-      });
+  // When auditing the pace-core repo root (monorepo), skip "included deps" check:
+  // the root package.json is the workspace root and shares the dependency tree with packages/core.
+  const packagesCorePath = path.join(consumingAppPath, 'packages', 'core', 'package.json');
+  const isPaceCoreRepoRoot = fs.existsSync(packagesCorePath);
+  let skipIncludedDepsCheck = false;
+  if (isPaceCoreRepoRoot) {
+    try {
+      const corePkg = JSON.parse(fs.readFileSync(packagesCorePath, 'utf8'));
+      if (corePkg.name === '@jmruthers/pace-core') {
+        skipIncludedDepsCheck = true;
+      }
+    } catch (e) {
+      // ignore
     }
-  });
+  }
+  
+  // Check for included dependencies (skip when auditing pace-core repo root)
+  if (!skipIncludedDepsCheck) {
+    INCLUDED_DEPS.forEach(dep => {
+      if (allDeps[dep]) {
+        issues.includedDeps.push({
+          package: dep,
+          installed: allDeps[dep],
+          location: consumingPkg.dependencies?.[dep] ? 'dependencies' : 'devDependencies',
+        });
+      }
+    });
+  }
   
   // Check for required peer dependencies
   REQUIRED_PEERS.forEach(dep => {

package/audit-tool/audits/01-pace-core-compliance.cjs

@@ -47,7 +47,8 @@ function checkProviderNesting(consumingAppPath) {
       line: 0,
       message: 'main.tsx file not found. Cannot validate provider nesting order.',
       severity: 'error',
-      fix: 'Create src/main.tsx with proper provider nesting: QueryClientProvider → BrowserRouter → UnifiedAuthProvider → OrganisationProvider',
+      fix: 'Create src/main.tsx with proper provider nesting: QueryClientProvider → BrowserRouter → UnifiedAuthProvider',
+      standardSection: 'MUST: Provider Nesting Order',
     });
     return issues;
   }
@@ -59,18 +60,22 @@ function checkProviderNesting(consumingAppPath) {
   
   const relativePath = getRelativePath(mainFile, consumingAppPath);
   
-  // Required provider order: QueryClientProvider → BrowserRouter → UnifiedAuthProvider → OrganisationProvider
+  // Required provider order: QueryClientProvider → BrowserRouter → UnifiedAuthProvider
+  // OrganisationServiceProvider is inside UnifiedAuthProvider; consuming apps must not wrap with it.
   const requiredProviders = [
     { name: 'QueryClientProvider', import: '@tanstack/react-query' },
     { name: 'BrowserRouter', import: 'react-router-dom' },
     { name: 'UnifiedAuthProvider', import: '@jmruthers/pace-core' },
-    { name: 'OrganisationProvider', import: '@jmruthers/pace-core' },
   ];
   
-  // Check if all providers are imported
+  // Check if all required providers are imported
   const missingProviders = requiredProviders.filter(provider => {
-    const importPattern = new RegExp(`import.*${provider.name}.*from\\s+['"]${provider.import.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}['"]`);
-    return !importPattern.test(content);
+    const names = [provider.name].concat(provider.altName || []);
+    const hasImport = names.some(name => {
+      const importPattern = new RegExp(`import.*${name}.*from\\s+['"]${provider.import.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}['"]`);
+      return importPattern.test(content);
+    });
+    return !hasImport;
   });
   
   if (missingProviders.length > 0) {
@@ -81,6 +86,7 @@ function checkProviderNesting(consumingAppPath) {
       message: `Missing required providers: ${missingProviders.map(p => p.name).join(', ')}`,
       severity: 'error',
       fix: `Import and use all required providers in the correct order: ${requiredProviders.map(p => p.name).join(' → ')}`,
+      standardSection: 'MUST: Provider Nesting Order',
     });
     return issues;
   }
@@ -97,7 +103,8 @@ function checkProviderNesting(consumingAppPath) {
     }
     
     const providerName = match[1];
-    if (requiredProviders.some(p => p.name === providerName)) {
+    const isRequired = requiredProviders.some(p => p.name === providerName || (p.altName && p.altName === providerName));
+    if (isRequired) {
       providers.push({
         name: providerName,
         index: match.index,
@@ -106,10 +113,13 @@ function checkProviderNesting(consumingAppPath) {
     }
   }
   
-  // Check order
+  // Check order (normalize altName to canonical name for comparison)
   if (providers.length > 0) {
     const expectedOrder = requiredProviders.map(p => p.name);
-    const actualOrder = providers.map(p => p.name);
+    const actualOrder = providers.map(p => {
+      const def = requiredProviders.find(r => r.name === p.name || r.altName === p.name);
+      return def ? def.name : p.name;
+    });
     
     // Check if order matches
     let orderCorrect = true;
@@ -129,6 +139,7 @@ function checkProviderNesting(consumingAppPath) {
         code: getCodeSnippet(content, providers[0].index, 0, 200),
         severity: 'error',
         fix: `Reorder providers to: ${expectedOrder.join(' → ')}`,
+        standardSection: 'MUST: Provider Nesting Order',
       });
     }
   }
@@ -164,6 +175,7 @@ function checkCoreStylesImport(consumingAppPath) {
       message: 'app.css file not found. Required for pace-core styling.',
       severity: 'error',
       fix: 'Create src/app.css with @import "@jmruthers/pace-core/styles/core.css";',
+      standardSection: 'Core styles import (see Styling standard)',
     });
     return issues;
   }
@@ -190,6 +202,7 @@ function checkCoreStylesImport(consumingAppPath) {
         message: `Missing required import: ${name}`,
         severity: 'error',
         fix: `Add ${name}; to app.css`,
+        standardSection: 'Core styles import (see Styling standard)',
       });
     }
   });
@@ -204,6 +217,7 @@ function checkCoreStylesImport(consumingAppPath) {
       message: 'Missing @source directives for Tailwind v4 content scanning',
       severity: 'warning',
       fix: 'Add @source directives: @source "./**/*.{js,ts,jsx,tsx}"; @source "../node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}";',
+      standardSection: 'Core styles import (see Styling standard)',
     });
   }
   
@@ -244,6 +258,7 @@ function checkRBACSetup(consumingAppPath) {
       message: 'main.tsx file not found. setupRBAC() must be called in main.tsx before app rendering.',
       severity: 'error',
       fix: 'Create src/main.tsx and call setupRBAC(supabase) before rendering the app.',
+      standardSection: 'MUST: Setup RBAC Before Use',
     });
     return issues;
   }
@@ -265,6 +280,7 @@ function checkRBACSetup(consumingAppPath) {
       message: 'setupRBAC() call not found. Must be called in main.tsx before app rendering.',
       severity: 'error',
       fix: 'Add: import { setupRBAC } from \'@jmruthers/pace-core/rbac\'; setupRBAC(supabase);',
+      standardSection: 'MUST: Setup RBAC Before Use',
     });
   } else {
     // Check if it's called before React rendering
@@ -280,6 +296,7 @@ function checkRBACSetup(consumingAppPath) {
         code: getCodeSnippet(content, setupRBACIndex),
         severity: 'error',
         fix: 'Move setupRBAC() call before createRoot() or render() call.',
+        standardSection: 'MUST: Setup RBAC Before Use',
       });
     }
   }
@@ -337,6 +354,7 @@ function checkViteAliases(consumingAppPath) {
         code: getCodeSnippet(content, match.index),
         severity: 'error',
         fix: `Remove this alias and use @jmruthers/pace-core/${paceCoreExport} directly`,
+        standardSection: 'MUST: Vite Configuration',
       });
     }
   }
@@ -413,6 +431,7 @@ function checkSecureSupabaseClient(consumingAppPath) {
           code: getCodeSnippet(content, match.index),
           severity: 'error',
           fix: 'Move createClient() call to main.tsx or lib/supabase.ts. Use useSecureSupabase() hook for queries.',
+          standardSection: 'MUST: Use Secure Supabase Client',
         });
       }
     }
@@ -436,7 +455,8 @@ function checkCursorRules(consumingAppPath) {
       line: 0,
       message: 'Cursor rules directory not found. Cursor rules provide AI-assisted enforcement.',
       severity: 'warning',
-      fix: 'Run: npm run setup:cursor-rules',
+      fix: 'Run: npm run setup',
+      standardSection: 'Step 3: Setup Cursor Rules',
     });
     return issues;
   }
@@ -459,13 +479,62 @@ function checkCursorRules(consumingAppPath) {
       line: 0,
       message: `Missing pace-core cursor rules: ${missingRules.join(', ')}`,
       severity: 'warning',
-      fix: 'Run: npm run setup:cursor-rules',
+      fix: 'Run: npm run setup',
+      standardSection: 'Step 3: Setup Cursor Rules',
     });
   }
   
   return issues;
 }
 
+/**
+ * Check for global auth gate anti-pattern (redirect to /login when !isAuthenticated in a wrapper).
+ * MUST use public /login route and ProtectedRoute per route; MUST NOT wrap Routes in a component
+ * that redirects unauthenticated users to /login (races with post-login context updates).
+ */
+function checkAuthRoutingPattern(consumingAppPath) {
+  const issues = [];
+  const srcDir = path.join(consumingAppPath, 'src');
+  if (!fs.existsSync(srcDir)) {
+    return issues;
+  }
+
+  const sourceFiles = findSourceFiles(srcDir, ['.tsx', '.jsx']);
+  const hasNavigateToLogin = /<Navigate\s+[^>]*to\s*=\s*\{?['"`]\/login['"`]?\}?/;
+  const hasAuthCheck = /(isAuthenticated|useUnifiedAuth\s*\(|useAuth\s*\()/;
+  const hasRedirectWhenUnauthenticated = /(!\s*isAuthenticated|isAuthenticated\s*===\s*false|!\s*user\b)/;
+
+  sourceFiles.forEach(filePath => {
+    const content = readFileSafe(filePath);
+    if (!content) return;
+
+    if (!hasNavigateToLogin.test(content)) return;
+    if (!hasAuthCheck.test(content)) return;
+    if (!hasRedirectWhenUnauthenticated.test(content)) return;
+
+    const normalizedPath = path.normalize(filePath);
+    if (normalizedPath.includes('ProtectedRoute') || normalizedPath.includes('packages' + path.sep + 'core')) return;
+
+    const relativePath = getRelativePath(filePath, consumingAppPath);
+    const navigateMatch = content.match(hasNavigateToLogin);
+    const line = navigateMatch ? getLineNumber(content, content.indexOf(navigateMatch[0])) : 1;
+
+    issues.push({
+      type: 'authRouting',
+      file: relativePath,
+      line,
+      message: 'Possible global auth gate: redirect to /login when not authenticated. This pattern can cause "login succeeds but redirect doesn\'t happen" or form reset.',
+      code: navigateMatch ? getCodeSnippet(content, content.indexOf(navigateMatch[0]), 0, 80) : undefined,
+      severity: 'error',
+      fix: 'Use a public /login route and wrap other routes in <Route element={<ProtectedRoute />}> (from @jmruthers/pace-core). Do not wrap <Routes> in a component that redirects when !isAuthenticated.',
+      standardSection: 'MUST: Auth routing',
+      details: 'See Authentication implementation guide: Critical: Auth routing pattern and troubleshooting "Login succeeds but redirect doesn\'t happen".',
+    });
+  });
+
+  return issues;
+}
+
 /**
  * Check ESLint config setup
  */
@@ -490,7 +559,8 @@ function checkESLintConfig(consumingAppPath) {
       line: 0,
       message: 'ESLint config file not found. ESLint provides real-time compliance checking.',
       severity: 'warning',
-      fix: 'Run: npm run setup:eslint',
+      fix: 'Run: npm run setup',
+      standardSection: 'Step 2: Setup ESLint',
     });
     return issues;
   }
@@ -514,7 +584,8 @@ function checkESLintConfig(consumingAppPath) {
       line: 1,
       message: 'ESLint config does not include pace-core config. pace-core ESLint rules provide real-time compliance checking.',
       severity: 'warning',
-      fix: 'Run: npm run setup:eslint or manually add: import paceCoreConfig from \'@jmruthers/pace-core/eslint-config\';',
+      fix: 'Run: npm run setup or manually add: import paceCoreConfig from \'@jmruthers/pace-core/eslint-config\';',
+      standardSection: 'Step 2: Setup ESLint',
     });
   }
   
@@ -524,20 +595,24 @@ function checkESLintConfig(consumingAppPath) {
 /**
  * Run audit for Standard 1: pace-core Compliance
  * @param {string} consumingAppPath - Path to consuming app
+ * @param {{ isPaceCorePackage?: boolean }} [auditContext] - When isPaceCorePackage, skip app-only checks (main.tsx, app.css, rbacSetup, cursorRules, eslintConfig)
  * @returns {object} - Audit results with issues array
  */
-function runStandard1Audit(consumingAppPath) {
+function runStandard1Audit(consumingAppPath, auditContext = {}) {
   const issues = [];
-  
+  const isPaceCorePackage = auditContext.isPaceCorePackage === true;
+
   try {
-    // System-level checks only (ESLint handles file-level checks)
-    issues.push(...checkProviderNesting(consumingAppPath));
-    issues.push(...checkCoreStylesImport(consumingAppPath));
-    issues.push(...checkRBACSetup(consumingAppPath));
+    if (!isPaceCorePackage) {
+      issues.push(...checkProviderNesting(consumingAppPath));
+      issues.push(...checkCoreStylesImport(consumingAppPath));
+      issues.push(...checkRBACSetup(consumingAppPath));
+      issues.push(...checkCursorRules(consumingAppPath));
+      issues.push(...checkESLintConfig(consumingAppPath));
+    }
     issues.push(...checkViteAliases(consumingAppPath));
     issues.push(...checkSecureSupabaseClient(consumingAppPath));
-    issues.push(...checkCursorRules(consumingAppPath));
-    issues.push(...checkESLintConfig(consumingAppPath));
+    issues.push(...checkAuthRoutingPattern(consumingAppPath));
   } catch (error) {
     return {
       standard: '01-pace-core-compliance',

package/audit-tool/audits/02-project-structure.cjs

@@ -41,6 +41,7 @@ function checkDirectoryStructure(consumingAppPath) {
         message: `Required directory missing: ${dirPath} (${description})`,
         severity: 'error',
         fix: `Create ${dirPath}/ directory`,
+        standardSection: 'Standard Directory Structure',
       });
     }
   });
@@ -72,6 +73,7 @@ function checkConfigFiles(consumingAppPath) {
         message: `Required configuration file missing: ${name} (${description})`,
         severity: 'error',
         fix: `Create ${name} file`,
+        standardSection: 'Configuration Files',
       });
     }
   });
@@ -119,6 +121,7 @@ function checkImportPaths(consumingAppPath) {
       message: 'tsconfig.json missing paths configuration. Consider adding path aliases for cleaner imports.',
       severity: 'info',
       fix: 'Add paths configuration: { "compilerOptions": { "paths": { "@/*": ["./src/*"] } } }',
+      standardSection: 'Import Path Configuration',
     });
   }
   
@@ -190,6 +193,7 @@ function checkTestColocation(consumingAppPath) {
           message: `Test file is in a test directory but should be colocated with source file. Move to ${parentDir}`,
           severity: 'warning',
           fix: `Move test file to ${parentDir} to colocate with source file`,
+          standardSection: 'Testing Structure (Test Colocation)',
         });
       }
     }
@@ -220,6 +224,7 @@ function checkFeatureBasedOrganization(consumingAppPath) {
       message: 'Domain-based organization (src/domains/) is not allowed. Use feature-based organization instead (src/components/[feature]/, src/hooks/[feature]/, etc.)',
       severity: 'error',
       fix: 'Reorganize to feature-based structure: move components from src/domains/[domain]/components/ to src/components/[domain]/, hooks to src/hooks/[domain]/, etc.',
+      standardSection: 'Component Organization / File Organization Standard',
     });
   }
   
@@ -252,6 +257,7 @@ function checkFeatureBasedOrganization(consumingAppPath) {
         message: `Components organized by type (${foundTypeBased.join(', ')}) instead of feature. Use pace-core components for UI primitives and organize app components by feature.`,
         severity: 'error',
         fix: `Reorganize components by feature. Use pace-core for ${foundTypeBased.join(', ')} components. Move feature-specific components to src/components/[feature]/`,
+        standardSection: 'Component Organization / File Organization Standard',
       });
     }
   }
@@ -275,17 +281,21 @@ function checkSupabaseStructure(consumingAppPath) {
 /**
  * Run audit for Standard 2: Project Structure
  * @param {string} consumingAppPath - Path to consuming app
+ * @param {{ isPaceCorePackage?: boolean }} [auditContext] - When isPaceCorePackage, skip organizationPattern (library organizes by type by design)
  * @returns {object} - Audit results with issues array
  */
-function runStandard2Audit(consumingAppPath) {
+function runStandard2Audit(consumingAppPath, auditContext = {}) {
   const issues = [];
-  
+  const isPaceCorePackage = auditContext.isPaceCorePackage === true;
+
   try {
     issues.push(...checkDirectoryStructure(consumingAppPath));
     issues.push(...checkConfigFiles(consumingAppPath));
     issues.push(...checkImportPaths(consumingAppPath));
     issues.push(...checkTestColocation(consumingAppPath));
-    issues.push(...checkFeatureBasedOrganization(consumingAppPath));
+    if (!isPaceCorePackage) {
+      issues.push(...checkFeatureBasedOrganization(consumingAppPath));
+    }
     issues.push(...checkSupabaseStructure(consumingAppPath));
   } catch (error) {
     return {

package/audit-tool/audits/03-architecture.cjs

@@ -23,8 +23,8 @@ function isTestFile(filePath) {
   const fileNameLower = fileName.toLowerCase();
   const filePathLower = filePath.toLowerCase();
   
-  // Standard test file patterns
-  if (filePath.includes('.test.') || filePath.includes('.spec.')) {
+  // Standard test file patterns and test-utils
+  if (filePath.includes('.test.') || filePath.includes('.spec.') || filePath.includes('test-utils')) {
     return true;
   }
   
@@ -99,7 +99,7 @@ function checkComponentBoundaries(consumingAppPath) {
     return isComponentDir && isComponentFile;
   });
   
-  // For data fetching checks, also include .ts files (to catch data fetching in hooks)
+  // For data fetching checks, include .tsx and .ts under pages/components but exclude hook files
   const filesForDataFetchingCheck = findSourceFiles(srcDir).filter(file => {
     // Skip all test files
     if (isTestFile(file)) {
@@ -110,6 +110,13 @@ function checkComponentBoundaries(consumingAppPath) {
     const isComponentDir = dir.includes('/components/') || dir.includes('/pages/');
     const isComponentFile = file.endsWith('.tsx') || file.endsWith('.ts');
     
+    // Exclude hooks: files under hooks/ or whose basename starts with 'use'
+    const basename = path.basename(file, path.extname(file));
+    const isHookFile = dir.includes('/hooks/') || basename.startsWith('use');
+    if (isHookFile) {
+      return false;
+    }
+    
     return isComponentDir && isComponentFile;
   });
   
@@ -149,6 +156,7 @@ function checkComponentBoundaries(consumingAppPath) {
               code: getCodeSnippet(content, index),
               severity: 'warning',
               fix: 'Extract data fetching logic to a custom hook (e.g., useEventData)',
+              standardSection: 'Component Design Principles / SOLID (Single Responsibility)',
             });
           }
         }
@@ -239,6 +247,7 @@ function checkComponentBoundaries(consumingAppPath) {
           message: 'Complex business logic detected in component. Consider extracting to a hook or utility function.',
           severity: 'info',
           fix: 'Extract business logic to a custom hook or utility function',
+          standardSection: 'Component Design Principles (UI Primitives Only, Stateless When Possible)',
         });
       }
     }
@@ -247,6 +256,68 @@ function checkComponentBoundaries(consumingAppPath) {
   return issues;
 }
 
+/** Thresholds for ISP heuristic (see Standard 3).
+ *  Line limits and named-export limit are enforced by ESLint only; this audit does not check them. */
+const INTERFACE_MEMBER_LIMIT = 30;
+
+/**
+ * ISP heuristic: flag interfaces/types with many members.
+ * Best-effort only; uses simple brace matching. See standard "Limitations".
+ */
+function checkLargeInterfaceHeuristic(consumingAppPath) {
+  const issues = [];
+  const srcDir = path.join(consumingAppPath, 'src');
+  if (!require('fs').existsSync(srcDir)) {
+    return issues;
+  }
+
+  const sourceFiles = findSourceFiles(srcDir).filter(file =>
+    !isTestFile(file) &&
+    (file.endsWith('.ts') || file.endsWith('.tsx')) &&
+    !file.includes('.generated.')
+  );
+
+  sourceFiles.forEach(filePath => {
+    const content = readFileSafe(filePath);
+    if (!content) {
+      return;
+    }
+
+    const re = /\b(?:interface|type)\s+\w+\s*(?:=\s*)?\{/g;
+    let m;
+    while ((m = re.exec(content)) !== null) {
+      const start = m.index + m[0].length - 1;
+      let depth = 1;
+      let i = start + 1;
+      for (; i < content.length; i++) {
+        if (content[i] === '{') {
+          depth++;
+        } else if (content[i] === '}') {
+          depth--;
+          if (depth === 0) {
+            break;
+          }
+        }
+      }
+      const block = content.substring(start, i + 1);
+      const memberCount = (block.match(/\w+\s*[?:]?\s*:/g) || []).length + (block.match(/\w+\s*\(/g) || []).length;
+      if (memberCount > INTERFACE_MEMBER_LIMIT) {
+        issues.push({
+          type: 'componentBoundary',
+          file: getRelativePath(filePath, consumingAppPath),
+          line: getLineNumber(content, m.index),
+          message: `Interface/type has ${memberCount} members (threshold ${INTERFACE_MEMBER_LIMIT}). Consider interface segregation; focused interfaces.`,
+          severity: 'info',
+          fix: 'Split into smaller, focused interfaces; see Standard 3 SOLID (ISP heuristic).',
+          standardSection: 'How we check SOLID (ISP heuristic)',
+        });
+      }
+    }
+  });
+
+  return issues;
+}
+
 /**
  * Check ApiResult shape usage (cross-file validation)
  */
@@ -313,6 +384,7 @@ function checkApiResultUsage(consumingAppPath) {
           code: getCodeSnippet(content, functionIndex),
           severity: 'info',
           fix: 'Use ApiResult<T> type: type ApiResult<T> = { ok: true; data: T } | { ok: false; error: ApiError }',
+          standardSection: 'API Design Principles (Type-Safe Results)',
         });
       }
     });
@@ -324,13 +396,15 @@ function checkApiResultUsage(consumingAppPath) {
 /**
  * Run audit for Standard 3: Architecture
  * @param {string} consumingAppPath - Path to consuming app
+ * @param {{ isPaceCorePackage?: boolean }} [auditContext] - Optional context (interface member limit already relaxed for all)
  * @returns {object} - Audit results with issues array
  */
-function runStandard3Audit(consumingAppPath) {
+function runStandard3Audit(consumingAppPath, auditContext = {}) {
   const issues = [];
   
   try {
     issues.push(...checkComponentBoundaries(consumingAppPath));
+    issues.push(...checkLargeInterfaceHeuristic(consumingAppPath));
     issues.push(...checkApiResultUsage(consumingAppPath));
   } catch (error) {
     return {

package/audit-tool/audits/04-code-quality.cjs

@@ -31,6 +31,7 @@ function checkTypeScriptConfig(consumingAppPath) {
       message: 'tsconfig.json not found. TypeScript strict mode must be enabled.',
       severity: 'error',
       fix: 'Create tsconfig.json with "strict": true in compilerOptions.',
+      standardSection: 'TypeScript Rules (Avoid Implicit any / tsconfig)',
     });
     return issues;
   }
@@ -63,9 +64,10 @@ function checkTypeScriptConfig(consumingAppPath) {
       message: 'TypeScript strict mode not enabled. Must set "strict": true in compilerOptions.',
       severity: 'error',
       fix: 'Set "strict": true in tsconfig.json compilerOptions.',
+      standardSection: 'TypeScript Rules (tsconfig strict mode)',
     });
   }
-  
+
   // Check for noImplicitAny
   if (compilerOptions.noImplicitAny !== true && compilerOptions.strict !== true) {
     issues.push({
@@ -75,6 +77,7 @@ function checkTypeScriptConfig(consumingAppPath) {
       message: 'noImplicitAny not enabled. Should set "noImplicitAny": true in compilerOptions (or enable strict mode).',
       severity: 'error',
       fix: 'Set "noImplicitAny": true in tsconfig.json compilerOptions (or enable strict mode).',
+      standardSection: 'TypeScript Rules (Avoid Implicit any)',
     });
   }
   
@@ -113,6 +116,7 @@ function checkTestCoverageConfig(consumingAppPath) {
           message: 'vitest.config.ts missing coverage configuration. Consider adding coverage thresholds.',
           severity: 'info',
           fix: 'Add coverage configuration: coverage: { provider: "v8", reporter: ["text", "json", "html"] }',
+          standardSection: 'Test coverage config (see Testing standard)',
         });
       }
     }
@@ -176,6 +180,7 @@ function checkConsoleLogging(consumingAppPath) {
           message: `Excessive ${name} usage detected (${validMatches.length} instances). Consider removing debug logs or using a proper logging library.`,
           severity: 'warning',
           fix: `Remove or replace ${name} statements. Use a logging library or remove debug logs before production.`,
+          standardSection: 'Forbidden Patterns / code hygiene',
         });
       }
     });
@@ -197,6 +202,7 @@ function checkConsoleLogging(consumingAppPath) {
         message: `Debug console logging detected (${validDebugMatches.length} instances). Debug logs should be removed or disabled in production.`,
         severity: 'warning',
         fix: 'Remove debug console.log statements or use environment-based logging that can be disabled in production.',
+        standardSection: 'Forbidden Patterns / code hygiene',
       });
     }
   });
@@ -207,9 +213,10 @@ function checkConsoleLogging(consumingAppPath) {
 /**
  * Run audit for Standard 4: Code Quality
  * @param {string} consumingAppPath - Path to consuming app
+ * @param {{ isPaceCorePackage?: boolean }} [auditContext] - Optional context (unused)
  * @returns {object} - Audit results with issues array
  */
-function runStandard4Audit(consumingAppPath) {
+function runStandard4Audit(consumingAppPath, auditContext = {}) {
   const issues = [];
   
   try {