@jmruthers/pace-core 0.6.6 → 0.6.8

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

@@ -0,0 +1,380 @@
+/**
+ * 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;
+}
+
+/**
+ * Format dependency audit section for markdown report
+ * @param {Object} dependencyResult - Dependency audit result
+ * @returns {string} - Formatted markdown section
+ */
+function formatDependencyAuditSection(dependencyResult) {
+  if (dependencyResult.error) {
+    return `\n### ❌ Dependency Audit\n\n**Error:** ${dependencyResult.error}\n\n`;
+  }
+  
+  const issues = dependencyResult.issues || {};
+  const includedDeps = issues.includedDeps || [];
+  const missingRequired = issues.missingRequired || [];
+  const missingOptional = issues.missingOptional || [];
+  const versionIssues = issues.versionIssues || [];
+  const wrongLocation = issues.wrongLocation || [];
+  const missingDevDeps = issues.missingDevDeps || [];
+  const devVersionIssues = issues.devVersionIssues || [];
+  
+  const totalIssues = includedDeps.length + missingRequired.length + versionIssues.length + wrongLocation.length + missingDevDeps.length + devVersionIssues.length;
+  
+  if (totalIssues === 0 && missingOptional.length === 0) {
+    return `\n### ✅ Dependency Audit\n\nNo issues found.\n`;
+  }
+  
+  let section = `\n### ${totalIssues > 0 ? '❌' : '⚠️'} Dependency Audit\n\n`;
+  section += `**Reference:** [Dependencies Guide](https://github.com/jmruthers/pace-core/blob/main/packages/core/docs/getting-started/dependencies.md)\n\n`;
+  
+  if (totalIssues > 0) {
+    section += `**Issues Found:** ${totalIssues}\n\n`;
+  }
+  
+  // Included dependencies (errors)
+  if (includedDeps.length > 0) {
+    section += `#### ❌ Included Dependencies (MUST REMOVE) - ${includedDeps.length} issue${includedDeps.length > 1 ? 's' : ''}\n\n`;
+    section += `These packages are already included in pace-core and should NOT be installed in your app:\n\n`;
+    includedDeps.forEach(issue => {
+      section += `- **${issue.package}**@${issue.installed} (in ${issue.location})\n`;
+      section += `  - Should NOT be installed (already included in pace-core)\n`;
+      section += `  - Fix: \`npm uninstall ${issue.package}\`\n\n`;
+    });
+  }
+  
+  // Missing required dependencies (errors)
+  if (missingRequired.length > 0) {
+    section += `#### ❌ Missing Required Dependencies - ${missingRequired.length} issue${missingRequired.length > 1 ? 's' : ''}\n\n`;
+    section += `These packages are required for pace-core to function:\n\n`;
+    missingRequired.forEach(issue => {
+      section += `- **${issue.package}** (required: ${issue.required})\n`;
+      section += `  - Fix: \`npm install ${issue.package}@${issue.required}\`\n\n`;
+    });
+  }
+  
+  // Version issues (errors)
+  if (versionIssues.length > 0) {
+    section += `#### ⚠️ Version Issues - ${versionIssues.length} issue${versionIssues.length > 1 ? 's' : ''}\n\n`;
+    section += `These packages have incorrect version ranges:\n\n`;
+    versionIssues.forEach(issue => {
+      section += `- **${issue.package}**\n`;
+      section += `  - Installed: ${issue.installed}\n`;
+      section += `  - Required: ${issue.required}\n`;
+      section += `  - Fix: \`npm install ${issue.package}@${issue.required}\`\n\n`;
+    });
+  }
+  
+  // Wrong location (warnings)
+  if (wrongLocation.length > 0) {
+    section += `#### ⚠️ Wrong Location - ${wrongLocation.length} issue${wrongLocation.length > 1 ? 's' : ''}\n\n`;
+    section += `These packages are in the wrong location in package.json:\n\n`;
+    wrongLocation.forEach(issue => {
+      section += `- **${issue.package}**\n`;
+      section += `  - Currently in: ${issue.current}\n`;
+      section += `  - Should be in: ${issue.shouldBe}\n`;
+      section += `  - Fix: \`npm uninstall ${issue.package} && npm install -D ${issue.package}\`\n\n`;
+    });
+  }
+  
+  // Missing optional dependencies (info)
+  if (missingOptional.length > 0) {
+    section += `#### ℹ️ Missing Optional Dependencies - ${missingOptional.length} package${missingOptional.length > 1 ? 's' : ''}\n\n`;
+    section += `These packages are optional and only needed if you use specific features:\n\n`;
+    missingOptional.forEach(issue => {
+      section += `- **${issue.package}** (required: ${issue.required})\n`;
+      section += `  - Install only if you use this feature\n`;
+      section += `  - Fix: \`npm install ${issue.package}@${issue.required}\`\n\n`;
+    });
+  }
+  
+  // Missing dev dependencies (errors)
+  if (missingDevDeps.length > 0) {
+    section += `#### ❌ Missing Required Dev Dependencies - ${missingDevDeps.length} issue${missingDevDeps.length > 1 ? 's' : ''}\n\n`;
+    section += `These dev dependencies are required for a compatible development environment:\n\n`;
+    missingDevDeps.forEach(issue => {
+      section += `- **${issue.package}** (required: ${issue.required})\n`;
+      section += `  - Fix: \`npm install -D ${issue.package}@${issue.required}\`\n\n`;
+    });
+  }
+  
+  // Dev version issues (errors)
+  if (devVersionIssues.length > 0) {
+    section += `#### ⚠️ Dev Dependency Version Issues - ${devVersionIssues.length} issue${devVersionIssues.length > 1 ? 's' : ''}\n\n`;
+    section += `These dev dependencies have incorrect version ranges:\n\n`;
+    devVersionIssues.forEach(issue => {
+      section += `- **${issue.package}** (in ${issue.location})\n`;
+      section += `  - Installed: ${issue.installed}\n`;
+      section += `  - Required: ${issue.required}\n`;
+      section += `  - Fix: \`npm install -D ${issue.package}@${issue.required}\`\n\n`;
+    });
+  }
+  
+  return section;
+}
+
+/**
+ * Generate markdown report from audit results
+ * @param {Object} results - Audit results object (standard audits)
+ * @param {string} consumingAppPath - Path to consuming app
+ * @param {Object} dependencyResult - Dependency audit result (optional)
+ * @returns {string} - Complete markdown report
+ */
+function generateMarkdownReport(results, consumingAppPath, dependencyResult = null) {
+  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;
+    }
+  });
+  
+  // Count dependency audit issues
+  let dependencyIssues = 0;
+  if (dependencyResult && !dependencyResult.error) {
+    const depIssues = dependencyResult.issues || {};
+    dependencyIssues = (depIssues.includedDeps?.length || 0) +
+                      (depIssues.missingRequired?.length || 0) +
+                      (depIssues.versionIssues?.length || 0) +
+                      (depIssues.wrongLocation?.length || 0) +
+                      (depIssues.missingDevDeps?.length || 0) +
+                      (depIssues.devVersionIssues?.length || 0);
+    totalIssues += dependencyIssues;
+  }
+  
+  report += `**Total Issues:** ${totalIssues}\n\n`;
+  report += `| Standard | Issues |\n`;
+  report += `|----------|--------|\n`;
+  
+  // Add dependency audit to summary table first
+  if (dependencyResult) {
+    const depIcon = dependencyIssues === 0 ? '✅' : '❌';
+    report += `| ${depIcon} Dependency Audit | ${dependencyIssues} |\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`;
+  
+  // Add dependency audit section first
+  if (dependencyResult) {
+    report += formatDependencyAuditSection(dependencyResult);
+  }
+  
+  // 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,
+  formatDependencyAuditSection,
+  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