@jmruthers/pace-core 0.6.6 → 0.6.7

package/audit-tool/utils/file-utils.cjs

@@ -0,0 +1,230 @@
+/**
+ * File System Utilities for Audit Tool
+ * @package @jmruthers/pace-core
+ * @module Audit/utils/file-utils
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Recursively find all source files matching extensions
+ * @param {string} dir - Directory to search
+ * @param {string[]} extensions - File extensions to match (e.g., ['.ts', '.tsx', '.js', '.jsx'])
+ * @param {string[]} fileList - Accumulator for found files
+ * @returns {string[]} - Array of file paths
+ */
+function findSourceFiles(dir, extensions = ['.ts', '.tsx', '.js', '.jsx'], fileList = []) {
+  if (!fs.existsSync(dir)) {
+    return fileList;
+  }
+  
+  const files = fs.readdirSync(dir);
+  
+  files.forEach(file => {
+    const filePath = path.join(dir, file);
+    const stat = fs.statSync(filePath);
+    
+    if (stat.isDirectory()) {
+      // Skip common build/dependency directories
+      if (!['node_modules', 'dist', 'build', '.git', '.next', '.vite', 'coverage', '.turbo', '.cursor'].includes(file)) {
+        findSourceFiles(filePath, extensions, fileList);
+      }
+    } else {
+      const ext = path.extname(file);
+      if (extensions.includes(ext)) {
+        fileList.push(filePath);
+      }
+    }
+  });
+  
+  return fileList;
+}
+
+/**
+ * Recursively find all SQL files in a directory
+ * @param {string} dir - Directory to search
+ * @param {string[]} fileList - Accumulator for found files
+ * @returns {string[]} - Array of SQL file paths
+ */
+function findSQLFiles(dir, fileList = []) {
+  if (!fs.existsSync(dir)) {
+    return fileList;
+  }
+  
+  const files = fs.readdirSync(dir);
+  
+  files.forEach(file => {
+    const filePath = path.join(dir, file);
+    const stat = fs.statSync(filePath);
+    
+    if (stat.isDirectory()) {
+      // Skip common build/dependency directories
+      if (!['node_modules', 'dist', 'build', '.git', '.next', '.vite', 'coverage', '.turbo'].includes(file)) {
+        findSQLFiles(filePath, fileList);
+      }
+    } else if (/\.sql$/.test(file)) {
+      fileList.push(filePath);
+    }
+  });
+  
+  return fileList;
+}
+
+/**
+ * Find configuration files by name
+ * @param {string} dir - Directory to search
+ * @param {string[]} configNames - Array of config file names to find
+ * @returns {Object} - Object mapping config names to paths (or null if not found)
+ */
+function findConfigFiles(dir, configNames) {
+  const results = {};
+  
+  for (const configName of configNames) {
+    const possiblePaths = [
+      path.join(dir, configName),
+      path.join(dir, `.${configName}`),
+    ];
+    
+    // Also check common variations
+    if (configName.includes('.')) {
+      const [base, ext] = configName.split('.');
+      possiblePaths.push(
+        path.join(dir, `${base}.js`),
+        path.join(dir, `${base}.ts`),
+        path.join(dir, `${base}.cjs`),
+        path.join(dir, `${base}.mjs`),
+        path.join(dir, `.${base}.js`),
+        path.join(dir, `.${base}.ts`),
+        path.join(dir, `.${base}.cjs`),
+        path.join(dir, `.${base}.mjs`)
+      );
+    }
+    
+    let found = null;
+    for (const configPath of possiblePaths) {
+      if (fs.existsSync(configPath)) {
+        found = configPath;
+        break;
+      }
+    }
+    
+    results[configName] = found;
+  }
+  
+  return results;
+}
+
+/**
+ * Safely read a file with error handling
+ * @param {string} filePath - Path to file
+ * @returns {string|null} - File content or null if error
+ */
+function readFileSafe(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) {
+      return null;
+    }
+    return fs.readFileSync(filePath, 'utf8');
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Get relative path from base path
+ * @param {string} filePath - Absolute file path
+ * @param {string} basePath - Base path to make relative to
+ * @returns {string} - Relative path
+ */
+function getRelativePath(filePath, basePath) {
+  try {
+    return path.relative(basePath, filePath);
+  } catch (error) {
+    return filePath;
+  }
+}
+
+/**
+ * Find pace-core package.json
+ * @param {string} consumingAppPath - Path to consuming app
+ * @returns {string|null} - Path to pace-core package.json or null
+ */
+function findPaceCorePackageJson(consumingAppPath) {
+  const possiblePaths = [
+    path.resolve(__dirname, '../../package.json'), // From packages/core/audit-tool/utils
+    path.resolve(__dirname, '../../../package.json'), // Alternative location (from root)
+    path.join(consumingAppPath, 'node_modules', '@jmruthers', 'pace-core', 'package.json'),
+  ];
+  
+  for (const packagePath of possiblePaths) {
+    if (fs.existsSync(packagePath)) {
+      return packagePath;
+    }
+  }
+  
+  return null;
+}
+
+/**
+ * Load core-usage-manifest.json
+ * @param {string} consumingAppPath - Path to consuming app
+ * @returns {Object|null} - Manifest object or null
+ */
+function loadManifest(consumingAppPath) {
+  const possiblePaths = [
+    path.resolve(__dirname, '../../../core-usage-manifest.json'),
+    path.resolve(__dirname, '../../../../core-usage-manifest.json'),
+    path.join(consumingAppPath, 'node_modules', '@jmruthers', 'pace-core', 'core-usage-manifest.json'),
+  ];
+  
+  for (const manifestPath of possiblePaths) {
+    if (fs.existsSync(manifestPath)) {
+      try {
+        return JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+      } catch (e) {
+        // Continue to next path
+      }
+    }
+  }
+  
+  return null;
+}
+
+/**
+ * Check if a directory exists
+ * @param {string} dirPath - Directory path
+ * @returns {boolean} - True if directory exists
+ */
+function directoryExists(dirPath) {
+  try {
+    return fs.existsSync(dirPath) && fs.statSync(dirPath).isDirectory();
+  } catch (error) {
+    return false;
+  }
+}
+
+/**
+ * Check if a file exists
+ * @param {string} filePath - File path
+ * @returns {boolean} - True if file exists
+ */
+function fileExists(filePath) {
+  try {
+    return fs.existsSync(filePath) && fs.statSync(filePath).isFile();
+  } catch (error) {
+    return false;
+  }
+}
+
+module.exports = {
+  findSourceFiles,
+  findSQLFiles,
+  findConfigFiles,
+  readFileSafe,
+  getRelativePath,
+  findPaceCorePackageJson,
+  loadManifest,
+  directoryExists,
+  fileExists,
+};

package/audit-tool/utils/report-utils.cjs

@@ -0,0 +1,241 @@
+/**
+ * Report Generation Utilities for Audit Tool
+ * @package @jmruthers/pace-core
+ * @module Audit/utils/report-utils
+ */
+
+const path = require('path');
+
+/**
+ * Format a single issue for markdown report
+ * @param {Object} issue - Issue object
+ * @param {string} standard - Standard name (e.g., '01-pace-core-compliance')
+ * @returns {string} - Formatted markdown
+ */
+function formatIssue(issue, standard) {
+  const severity = issue.severity || 'error';
+  const severityIcon = severity === 'error' ? '❌' : severity === 'warning' ? '⚠️' : 'ℹ️';
+  
+  let formatted = `\n#### ${severityIcon} ${issue.type || 'Issue'}\n\n`;
+  
+  if (issue.file) {
+    formatted += `**File:** \`${issue.file}\`\n\n`;
+  }
+  
+  if (issue.line) {
+    formatted += `**Line:** ${issue.line}\n\n`;
+  }
+  
+  if (issue.message) {
+    formatted += `**Message:** ${issue.message}\n\n`;
+  }
+  
+  if (issue.code) {
+    formatted += `**Code:**\n\`\`\`\n${issue.code}\n\`\`\`\n\n`;
+  }
+  
+  if (issue.fix) {
+    formatted += `**Fix:** ${issue.fix}\n\n`;
+  }
+  
+  if (issue.details) {
+    formatted += `**Details:** ${issue.details}\n\n`;
+  }
+  
+  return formatted;
+}
+
+/**
+ * Format a standard section in the report
+ * @param {string} standard - Standard number and name (e.g., '01-pace-core-compliance')
+ * @param {string} standardName - Human-readable standard name
+ * @param {Array} issues - Array of issues
+ * @param {string} standardDocPath - Path to standards documentation
+ * @returns {string} - Formatted markdown section
+ */
+function formatStandardSection(standard, standardName, issues, standardDocPath) {
+  if (issues.length === 0) {
+    return `\n### ✅ Standard ${standard}: ${standardName}\n\nNo issues found.\n`;
+  }
+  
+  let section = `\n### ❌ Standard ${standard}: ${standardName}\n\n`;
+  section += `**Reference:** [${standardName}](https://github.com/jmruthers/pace-core/blob/main/packages/core/docs/standards/${standardDocPath})\n\n`;
+  section += `**Issues Found:** ${issues.length}\n\n`;
+  
+  // Group issues by type
+  const issuesByType = {};
+  issues.forEach(issue => {
+    const type = issue.type || 'other';
+    if (!issuesByType[type]) {
+      issuesByType[type] = [];
+    }
+    issuesByType[type].push(issue);
+  });
+  
+  // Format each type group
+  Object.entries(issuesByType).forEach(([type, typeIssues]) => {
+    section += `\n#### ${type} (${typeIssues.length} issue${typeIssues.length > 1 ? 's' : ''})\n`;
+    typeIssues.forEach(issue => {
+      section += formatIssue(issue, standard);
+    });
+  });
+  
+  return section;
+}
+
+/**
+ * Generate markdown report from audit results
+ * @param {Object} results - Audit results object
+ * @param {string} consumingAppPath - Path to consuming app
+ * @returns {string} - Complete markdown report
+ */
+function generateMarkdownReport(results, consumingAppPath) {
+  const now = new Date();
+  const timestamp = now.toISOString();
+  
+  let report = `# pace-core Audit Report\n\n`;
+  report += `**Generated:** ${timestamp}\n`;
+  report += `**App Path:** ${consumingAppPath}\n\n`;
+  report += `---\n\n`;
+  report += `## Summary\n\n`;
+  
+  // Calculate totals
+  const standardNames = {
+    '01-pace-core-compliance': 'pace-core Compliance',
+    '02-project-structure': 'Project Structure',
+    '03-architecture': 'Architecture',
+    '04-code-quality': 'Code Quality',
+    '05-styling': 'Styling',
+    '06-security-rbac': 'Security & RBAC',
+    '07-api-tech-stack': 'API & Tech Stack',
+    '08-testing-documentation': 'Testing & Documentation',
+    '09-operations': 'Operations',
+  };
+  
+  const standardDocPaths = {
+    '01-pace-core-compliance': '1-pace-core-compliance-standards.md',
+    '02-project-structure': '2-project-structure-standards.md',
+    '03-architecture': '3-architecture-standards.md',
+    '04-code-quality': '4-code-quality-standards.md',
+    '05-styling': '5-styling-standards.md',
+    '06-security-rbac': '6-security-rbac-standards.md',
+    '07-api-tech-stack': '7-api-tech-stack-standards.md',
+    '08-testing-documentation': '8-testing-documentation-standards.md',
+    '09-operations': '9-operations-standards.md',
+  };
+  
+  let totalIssues = 0;
+  const standardCounts = {};
+  
+  // Count issues per standard
+  Object.keys(standardNames).forEach(standard => {
+    const standardResult = results[standard];
+    if (standardResult && standardResult.issues) {
+      const count = Array.isArray(standardResult.issues) 
+        ? standardResult.issues.length 
+        : Object.values(standardResult.issues).flat().length;
+      standardCounts[standard] = count;
+      totalIssues += count;
+    } else {
+      standardCounts[standard] = 0;
+    }
+  });
+  
+  report += `**Total Issues:** ${totalIssues}\n\n`;
+  report += `| Standard | Issues |\n`;
+  report += `|----------|--------|\n`;
+  
+  Object.entries(standardCounts).forEach(([standard, count]) => {
+    const icon = count === 0 ? '✅' : '❌';
+    report += `| ${icon} ${standardNames[standard]} | ${count} |\n`;
+  });
+  
+  report += `\n---\n\n`;
+  report += `## Detailed Results\n\n`;
+  
+  // Generate sections for each standard
+  Object.keys(standardNames).forEach(standard => {
+    const standardResult = results[standard];
+    if (standardResult) {
+      const issues = Array.isArray(standardResult.issues) 
+        ? standardResult.issues 
+        : Object.values(standardResult.issues || {}).flat();
+      
+      report += formatStandardSection(
+        standard,
+        standardNames[standard],
+        issues,
+        standardDocPaths[standard]
+      );
+    }
+  });
+  
+  report += `\n---\n\n`;
+  report += `## Next Steps\n\n`;
+  
+  if (totalIssues === 0) {
+    report += `✅ All audits passed! Your app is compliant with pace-core standards.\n\n`;
+  } else {
+    report += `Please review the issues above and address them according to the referenced standards.\n\n`;
+    report += `For more information, see the [pace-core Standards Documentation](https://github.com/jmruthers/pace-core/blob/main/packages/core/docs/standards/README.md).\n\n`;
+  }
+  
+  return report;
+}
+
+/**
+ * Generate summary statistics
+ * @param {Object} results - Audit results object
+ * @returns {Object} - Summary object with counts
+ */
+function generateSummary(results) {
+  const standardNames = {
+    '01-pace-core-compliance': 'pace-core Compliance',
+    '02-project-structure': 'Project Structure',
+    '03-architecture': 'Architecture',
+    '04-code-quality': 'Code Quality',
+    '05-styling': 'Styling',
+    '06-security-rbac': 'Security & RBAC',
+    '07-api-tech-stack': 'API & Tech Stack',
+    '08-testing-documentation': 'Testing & Documentation',
+    '09-operations': 'Operations',
+  };
+  
+  const summary = {
+    total: 0,
+    byStandard: {},
+    bySeverity: { error: 0, warning: 0, info: 0 },
+  };
+  
+  Object.keys(standardNames).forEach(standard => {
+    const standardResult = results[standard];
+    if (standardResult && standardResult.issues) {
+      const issues = Array.isArray(standardResult.issues) 
+        ? standardResult.issues 
+        : Object.values(standardResult.issues || {}).flat();
+      
+      const count = issues.length;
+      summary.byStandard[standard] = count;
+      summary.total += count;
+      
+      // Count by severity
+      issues.forEach(issue => {
+        const severity = issue.severity || 'error';
+        if (summary.bySeverity[severity] !== undefined) {
+          summary.bySeverity[severity]++;
+        }
+      });
+    } else {
+      summary.byStandard[standard] = 0;
+    }
+  });
+  
+  return summary;
+}
+
+module.exports = {
+  formatIssue,
+  formatStandardSection,
+  generateMarkdownReport,
+  generateSummary,
+};

package/cursor-rules/00-standards-overview.mdc

@@ -0,0 +1,156 @@
+---
+description: Overview of the pace-core standards system and the four layers of quality enforcement
+globs: ["**/*.{ts,tsx,js,jsx,md,mdx}"]
+alwaysApply: true
+paceCoreVersion: "0.6.x"
+rulesVersion: "2025-01-28"
+---
+# Standards Overview
+
+**📚 Human-Readable Standard**: See [0-standards-overview.md](../../packages/core/docs/standards/0-standards-overview.md) for complete documentation.
+
+This is the entry point to the pace-core standards system. It explains how the four layers of quality enforcement work together and how cursor rules fit into the system.
+
+## AI Agent Instructions
+
+**When writing or modifying code, ALWAYS:**
+1. **Start here** - Read this overview to understand the system
+2. **Use the right rule** - Check the Quick Reference below to find the relevant rule(s)
+3. **Follow decision trees** - Each rule includes decision trees to guide your choices
+4. **Check examples** - Every rule includes ❌ WRONG / ✅ CORRECT examples
+5. **Reference standards** - When in doubt, check the linked standards document
+6. **Focus on patterns** - These rules guide patterns, not mechanical checks (ESLint handles those)
+
+## The Four Layers of Quality Enforcement
+
+The pace-suite uses **four complementary quality layers**, each with a distinct responsibility:
+
+### 1. Standards Documents (Source of Truth)
+- Human-readable `.md` documents
+- Define *what "good" looks like*
+- **If there is a conflict, the standards win.**
+
+### 2. Cursor Rules (Real-time Guidance) ← **You are here**
+- AI-optimised interpretations of the standards
+- Applied while code is being written or modified
+- Prevent mistakes *before* they land
+- **Translate standards into behaviour**, but do not redefine them
+
+### 3. ESLint (Fast, Local Static Analysis)
+- Deterministic, file-level static analysis
+- Catches obvious issues early (types, hooks, imports, patterns)
+- Enforces *how code is written*, not *whether the system is correct*
+
+### 4. Audit Tool (Deep, System-Level Analysis)
+- Operates across files, folders, and systems
+- Validates architectural compliance (RBAC, data access, boundaries)
+- Answers: *"Is this system actually compliant?"*
+
+## How the Layers Work Together
+
+| Layer        | Strength                         | Timing          |
+|--------------|----------------------------------|-----------------|
+| Standards    | Intent & clarity                 | Design time     |
+| Cursor rules | Preventive guidance              | Write time      |
+| ESLint       | Fast mechanical enforcement      | Dev / CI        |
+| Audit tool   | Deep architectural verification  | Review / CI     |
+
+**No single layer is sufficient on its own.** Together, they create a repeatable, scalable quality system.
+
+## Standards File Mapping
+
+The standards are organized into 10 files, each with a corresponding cursor rule:
+
+| File | Standard | Cursor Rule | Purpose |
+|------|----------|------------|---------|
+| `0-standards-overview.md` | Overview | `00-standards-overview.mdc` | This file - entry point and system overview |
+| `1-pace-core-compliance-standards.md` | pace-core Compliance | `01-pace-core-compliance.mdc` | Enforce pace-core usage patterns |
+| `2-project-structure-standards.md` | Project Structure | `02-project-structure.mdc` | Define standard folder structure |
+| `3-architecture-standards.md` | Architecture | `03-architecture.mdc` | Enforce SOLID architecture principles |
+| `4-code-quality-standards.md` | Code Quality | `04-code-quality.mdc` | Enforce code quality standards |
+| `5-styling-standards.md` | Styling | `05-styling.mdc` | Enforce clean markup and styling standards |
+| `6-security-rbac-standards.md` | Security & RBAC | `06-security-rbac.mdc` | Enforce RBAC contract and security |
+| `7-api-tech-stack-standards.md` | API & Tech Stack | `07-api-tech-stack.mdc` | Enforce tech stack versions and API standards |
+| `8-testing-documentation-standards.md` | Testing & Documentation | `08-testing-documentation.mdc` | Enforce testing and documentation standards |
+| `9-operations-standards.md` | Operations | `09-operations.mdc` | Enforce error handling, performance, and CI/CD |
+
+## Precedence Order
+
+When standards conflict, apply this precedence order:
+
+1. **Security** - Security and RBAC standards take highest priority
+2. **API/RPC** - API contracts and RPC standards
+3. **Components & Markup** - Component usage and markup quality
+4. **Code Quality/Style** - TypeScript, naming, code style
+5. **Testing & Documentation** - Testing and documentation requirements
+6. **Consuming App Structure** - Project structure and organization
+
+**Example:** If a component pattern conflicts with a security requirement, security wins.
+
+## Quick Reference Guide
+
+**New to pace-core?** Start here:
+1. Read [Standards Overview](../../packages/core/docs/standards/0-standards-overview.md) (this file) - Understand the system
+2. Read [Styling Standards](../../packages/core/docs/standards/5-styling-standards.md) - **CRITICAL:** Required CSS setup
+3. Read [pace-core Compliance](../../packages/core/docs/standards/1-pace-core-compliance-standards.md) - How to use pace-core
+4. Read [Project Structure](../../packages/core/docs/standards/2-project-structure-standards.md) - Organize your code
+
+**Common Tasks:**
+- **Setting up a new app?** → [Project Structure](../../packages/core/docs/standards/2-project-structure-standards.md) + [Styling Standards](../../packages/core/docs/standards/5-styling-standards.md)
+- **Writing components?** → [Architecture](../../packages/core/docs/standards/3-architecture-standards.md) + [Code Quality](../../packages/core/docs/standards/4-code-quality-standards.md)
+- **Working with RBAC?** → [Security & RBAC](../../packages/core/docs/standards/6-security-rbac-standards.md)
+- **Creating APIs/RPCs?** → [API & Tech Stack](../../packages/core/docs/standards/7-api-tech-stack-standards.md)
+- **Handling errors?** → [Operations](../../packages/core/docs/standards/9-operations-standards.md)
+- **Writing tests?** → [Testing & Documentation](../../packages/core/docs/standards/8-testing-documentation-standards.md)
+
+## Key Principles
+
+- **Do not silence tools** — fix the underlying issue
+- **Do not duplicate rules** — each layer has a purpose
+- **Do not diverge silently** — document exceptions explicitly
+- **Standards always win** — tools must align to them
+
+## What Cursor Rules Do
+
+Cursor rules provide **real-time guidance** during code writing:
+
+✅ **DO:**
+- Steer AI agents toward correct patterns
+- Enforce architectural intent during development
+- Reduce rework later in linting or audits
+- Translate standards into actionable behavior
+
+❌ **DON'T:**
+- Replace lint or audits
+- Invent new standards
+- Silence problems "to move on"
+- Enforce mechanical checks (ESLint handles this)
+- Validate system-level compliance (audit tool handles this)
+
+## Quick Reference: Which Rule to Use?
+
+**When writing code, use these rules:**
+
+- **Creating components?** → `01-pace-core-compliance.mdc` + `03-architecture.mdc` + `05-styling.mdc`
+- **Writing hooks or utilities?** → `01-pace-core-compliance.mdc` + `03-architecture.mdc` + `04-code-quality.mdc`
+- **Setting up providers or auth?** → `01-pace-core-compliance.mdc` + `06-security-rbac.mdc`
+- **Creating RPCs or APIs?** → `07-api-tech-stack.mdc` + `06-security-rbac.mdc`
+- **Writing tests?** → `08-testing-documentation.mdc`
+- **Handling errors?** → `09-operations.mdc`
+- **Optimizing performance?** → `09-operations.mdc` + `04-code-quality.mdc`
+- **Organizing files?** → `02-project-structure.mdc`
+- **Styling components?** → `05-styling.mdc` (ALWAYS APPLIED)
+- **Working with RBAC?** → `06-security-rbac.mdc`
+
+## Related Documentation
+
+- [Standards Overview](../../packages/core/docs/standards/0-standards-overview.md) - Complete standards system documentation
+- [pace-core Compliance](../../packages/core/docs/standards/1-pace-core-compliance-standards.md) - pace-core usage patterns
+- [Project Structure](../../packages/core/docs/standards/2-project-structure-standards.md) - Project structure and organization
+- [Architecture](../../packages/core/docs/standards/3-architecture-standards.md) - SOLID architecture principles
+- [Code Quality](../../packages/core/docs/standards/4-code-quality-standards.md) - Code quality and TypeScript standards
+- [Styling](../../packages/core/docs/standards/5-styling-standards.md) - Markup and styling standards
+- [Security & RBAC](../../packages/core/docs/standards/6-security-rbac-standards.md) - RBAC and RLS standards
+- [API & Tech Stack](../../packages/core/docs/standards/7-api-tech-stack-standards.md) - Tech stack and API/RPC standards
+- [Testing & Documentation](../../packages/core/docs/standards/8-testing-documentation-standards.md) - Testing and documentation standards
+- [Operations](../../packages/core/docs/standards/9-operations-standards.md) - Error handling, performance, and CI/CD