@civicactions/cmsds-open-data-components 4.0.7 → 4.0.8-alpha.0

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@civicactions/cmsds-open-data-components",
-  "version": "4.0.7",
+  "version": "4.0.8-alpha.0",
   "description": "Components for the open data catalog frontend using CMS Design System",
   "main": "dist/main.js",
   "source": "src/index.ts",
   "types": "dist/types.d.ts",
   "type": "module",
+  "bin": {
+    "generate-usage-report": "./scripts/generate-usage-report.cjs"
+  },
   "scripts": {
     "build": "parcel build",
     "build:report": "parcel build --reporter @parcel/reporter-bundle-analyzer",
@@ -16,6 +19,7 @@
     "storybook": "storybook dev -p 6006",
     "build-storybook": "storybook build",
     "generate:inventory": "node scripts/generate-inventory.cjs",
+    "generate:usage-report": "node scripts/generate-usage-report.cjs",
     "prepare": "husky"
   },
   "author": "",

package/scripts/README.md

@@ -0,0 +1,119 @@
+# Component Inventory Generator
+
+This script automatically generates a comprehensive markdown inventory report for the cmsds-open-data-components library.
+
+## Usage
+
+Run the script using npm:
+
+```bash
+npm run generate:inventory
+```
+
+Or run it directly:
+
+```bash
+node scripts/generate-inventory.cjs
+```
+
+## Output
+
+The script generates `COMPONENTS_INVENTORY.md` in the root directory containing:
+
+- **Inventory Table**: Complete list of all components, services, templates, hooks, contexts, utilities, types, and assets
+- **Public Export Status**: Indicates which items are publicly exported vs internal-only
+- **Storybook Status**: Shows which items have Storybook stories for visual documentation
+- **Unit Test Status**: Shows which items have unit test coverage
+- **Quality Metrics**: Summary statistics for documentation and testing coverage
+- **Export Summary**: Count of public vs internal items by category
+
+## What It Scans
+
+The script automatically scans the following directories:
+
+- `src/components/` - React components
+- `src/templates/` - Page-level templates
+- `src/services/` - API service hooks
+- `src/utilities/` - Utility functions
+- `src/types/` - TypeScript type definitions
+- `src/assets/` - Static assets and data files
+
+It also automatically detects:
+- **Hooks**: Directories or files starting with `use` (e.g., `useScrollToTop`)
+- **Contexts**: Files ending with `Context` that contain `createContext()` calls
+
+## How It Works
+
+1. **Reads `src/index.ts`** to determine which items are publicly exported
+2. **Scans each directory** for subdirectories and files
+3. **Dynamically discovers hooks and contexts** by naming patterns and file content
+4. **Checks for `.stories.*` files** to determine Storybook coverage
+5. **Checks for `.test.*` and `.spec.*` files** to determine unit test coverage
+6. **Calculates statistics** for overall project quality metrics
+7. **Generates markdown** with formatted tables and summaries
+
+## Maintenance
+
+The script is designed to automatically adapt to changes in the codebase:
+
+- New components/templates/services/hooks/contexts are automatically discovered
+- Public export status updates when `src/index.ts` changes
+- Story and test status updates as files are added/removed
+- Statistics recalculate automatically
+
+No manual updates needed when adding or removing hooks and contexts!
+
+### Hook and Context Detection
+
+**Hooks** are detected by:
+- Directory names starting with `use` (e.g., `src/components/useScrollToTop/`)
+- File names starting with `use` (e.g., `useAddLoginLink.ts`)
+
+**Contexts** are detected by:
+- File names ending with `Context` (e.g., `HeaderContext.tsx`)
+- File must contain a `createContext()` call
+- Export name is extracted from `export default` or `export const` statements
+
+The scanner automatically excludes test and story files to prevent false positives.
+
+### Known Special Cases
+
+The script handles several special cases:
+
+- **DatasetAdditionalInformation**: Exports `buildRows` function
+- **DatasetTableTab**: Exported as `DatasetTable`
+- **Datatable**: Exported as `DataTable` (case difference)
+- **frequencyMap**: Commented out in exports
+- **aca.ts**: Exports `acaToParams` function
+
+To add new special cases, update the scanning functions in `generate-inventory.cjs`.
+
+## File Structure
+
+```
+scripts/
+  generate-inventory.cjs    # Main script file
+  README.md                 # This file
+
+COMPONENTS_INVENTORY.md     # Generated output file (root directory)
+```
+
+## Requirements
+
+- Node.js v14 or higher
+- No additional dependencies required (uses Node.js built-in `fs` and `path` modules)
+
+## Troubleshooting
+
+**Error: "require is not defined"**
+- The script uses `.cjs` extension to work with the ES module package type
+- Make sure the file is named `generate-inventory.cjs` (not `.js`)
+
+**Missing components in output**
+- Ensure new components follow the standard directory structure
+- Component directories should be in `src/components/`
+- Each component should have an `index.tsx` or similar entry file
+
+**Incorrect public export status**
+- Check if the component is exported in `src/index.ts`
+- For special export names, add them to the scanning logic in the script

package/scripts/generate-usage-report.cjs

@@ -0,0 +1,445 @@
+#!/usr/bin/env node
+
+/**
+ * Component Usage Report Generator
+ * 
+ * Scans a project that uses cmsds-open-data-components as a dependency and generates
+ * a comprehensive markdown usage report including:
+ * - Which components, templates, services, hooks, and utilities are being used
+ * - Where they are imported/used in the codebase
+ * - Usage frequency and patterns
+ * - Unused available components
+ * 
+ * This script should be run from the root of a project that depends on
+ * @civicactions/cmsds-open-data-components
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Configuration
+const DEFAULT_SCAN_DIRS = ['src', 'app', 'pages', 'components', 'templates'];
+const FILE_EXTENSIONS = ['.js', '.jsx', '.ts', '.tsx'];
+const PACKAGE_NAME = '@civicactions/cmsds-open-data-components';
+
+// Command line arguments
+const args = process.argv.slice(2);
+const outputFile = args[0] || 'COMPONENT_USAGE_REPORT.md';
+const projectRoot = process.cwd();
+
+/**
+ * Get the list of public exports from the installed package
+ */
+function getAvailableComponents() {
+  try {
+    const packagePath = path.join(projectRoot, 'node_modules', PACKAGE_NAME);
+    const indexPath = path.join(packagePath, 'dist', 'index.d.ts');
+    
+    if (!fs.existsSync(indexPath)) {
+      // Fallback to package.json exports
+      const pkgJsonPath = path.join(packagePath, 'package.json');
+      if (fs.existsSync(pkgJsonPath)) {
+        const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'));
+        return {
+          version: pkgJson.version,
+          exports: new Set()
+        };
+      }
+      throw new Error('Could not find package index');
+    }
+    
+    const content = fs.readFileSync(indexPath, 'utf8');
+    const exports = new Set();
+    
+    // Match export declarations
+    const exportMatches = content.matchAll(/export\s+(?:declare\s+)?(?:const|function|class|interface|type)\s+(\w+)/g);
+    for (const match of exportMatches) {
+      exports.add(match[1]);
+    }
+    
+    // Match default exports
+    const defaultMatches = content.matchAll(/export\s+\{\s*default\s+as\s+(\w+)\s*\}/g);
+    for (const match of defaultMatches) {
+      exports.add(match[1]);
+    }
+    
+    // Get version
+    const pkgJsonPath = path.join(packagePath, 'package.json');
+    const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'));
+    
+    return {
+      version: pkgJson.version,
+      exports
+    };
+  } catch (error) {
+    console.warn('⚠️  Could not read package exports, will detect from usage');
+    return {
+      version: 'unknown',
+      exports: new Set()
+    };
+  }
+}
+
+/**
+ * Recursively find all files with specified extensions in a directory
+ */
+function findFiles(dir, extensions, results = []) {
+  if (!fs.existsSync(dir)) {
+    return results;
+  }
+  
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      
+      // Skip node_modules, .git, build directories
+      if (entry.name === 'node_modules' || 
+          entry.name === '.git' || 
+          entry.name === 'build' || 
+          entry.name === 'dist' ||
+          entry.name === '.next' ||
+          entry.name === 'coverage') {
+        continue;
+      }
+      
+      if (entry.isDirectory()) {
+        findFiles(fullPath, extensions, results);
+      } else if (extensions.some(ext => entry.name.endsWith(ext))) {
+        results.push(fullPath);
+      }
+    }
+  } catch (error) {
+    // Skip directories we can't read
+  }
+  
+  return results;
+}
+
+/**
+ * Parse a file for imports from cmsds-open-data-components
+ */
+function parseFileForImports(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const imports = [];
+    
+    // Match ES6 imports: import { Component1, Component2 } from '@civicactions/cmsds-open-data-components'
+    const namedImportRegex = new RegExp(
+      `import\\s+\\{([^}]+)\\}\\s+from\\s+['"]${PACKAGE_NAME}['"]`,
+      'g'
+    );
+    
+    let match;
+    while ((match = namedImportRegex.exec(content)) !== null) {
+      const names = match[1]
+        .split(',')
+        .map(n => n.trim())
+        .filter(n => n.length > 0);
+      
+      names.forEach(name => {
+        imports.push({
+          name,
+          type: 'named',
+          line: content.substring(0, match.index).split('\n').length
+        });
+      });
+    }
+    
+    // Match default imports: import Component from '@civicactions/cmsds-open-data-components'
+    const defaultImportRegex = new RegExp(
+      `import\\s+(\\w+)\\s+from\\s+['"]${PACKAGE_NAME}['"]`,
+      'g'
+    );
+    
+    while ((match = defaultImportRegex.exec(content)) !== null) {
+      imports.push({
+        name: match[1],
+        type: 'default',
+        line: content.substring(0, match.index).split('\n').length
+      });
+    }
+    
+    return imports;
+  } catch (error) {
+    return [];
+  }
+}
+
+/**
+ * Scan the project for component usage
+ */
+function scanProjectForUsage() {
+  console.log('🔍 Scanning project for component usage...');
+  
+  const usageMap = new Map();
+  const scanDirs = DEFAULT_SCAN_DIRS
+    .map(dir => path.join(projectRoot, dir))
+    .filter(dir => fs.existsSync(dir));
+  
+  if (scanDirs.length === 0) {
+    console.warn('⚠️  No standard source directories found. Scanning entire project...');
+    scanDirs.push(projectRoot);
+  }
+  
+  let filesScanned = 0;
+  
+  for (const scanDir of scanDirs) {
+    const files = findFiles(scanDir, FILE_EXTENSIONS);
+    filesScanned += files.length;
+    
+    for (const file of files) {
+      const imports = parseFileForImports(file);
+      
+      if (imports.length > 0) {
+        const relativePath = path.relative(projectRoot, file);
+        
+        for (const imp of imports) {
+          if (!usageMap.has(imp.name)) {
+            usageMap.set(imp.name, []);
+          }
+          
+          usageMap.get(imp.name).push({
+            file: relativePath,
+            line: imp.line,
+            type: imp.type
+          });
+        }
+      }
+    }
+  }
+  
+  console.log(`   Scanned ${filesScanned} files`);
+  console.log(`   Found ${usageMap.size} unique components in use`);
+  
+  return usageMap;
+}
+
+/**
+ * Categorize components by type based on naming conventions
+ */
+function categorizeComponent(name) {
+  if (name.startsWith('use')) return 'Hook';
+  if (name.endsWith('Context') || name.endsWith('Provider')) return 'Context';
+  if (name.endsWith('Page') || name.endsWith('Template')) return 'Template';
+  if (name.includes('Service') || name.startsWith('fetch') || name.startsWith('get')) return 'Service';
+  if (name.endsWith('Util') || name.endsWith('Helper')) return 'Utility';
+  return 'Component';
+}
+
+/**
+ * Generate markdown table row
+ */
+function generateUsageRow(name, usages, category) {
+  const count = usages.length;
+  const files = [...new Set(usages.map(u => u.file))];
+  const fileList = files.length <= 3 
+    ? files.map(f => `\`${f}\``).join(', ')
+    : `${files.slice(0, 3).map(f => `\`${f}\``).join(', ')} and ${files.length - 3} more`;
+  
+  return `| ${name} | ${category} | ${count} | ${fileList} |`;
+}
+
+/**
+ * Generate the usage report
+ */
+function generateReport(usageMap, availableComponents) {
+  const lines = [];
+  
+  // Get project info
+  const projectPkgPath = path.join(projectRoot, 'package.json');
+  let projectName = 'Unknown Project';
+  let projectVersion = '';
+  
+  if (fs.existsSync(projectPkgPath)) {
+    const projectPkg = JSON.parse(fs.readFileSync(projectPkgPath, 'utf8'));
+    projectName = projectPkg.name || path.basename(projectRoot);
+    
+    // Get the installed version
+    const deps = { ...projectPkg.dependencies, ...projectPkg.devDependencies };
+    projectVersion = deps[PACKAGE_NAME] || availableComponents.version;
+  }
+  
+  // Header
+  lines.push(`# ${projectName} Component Usage Report`);
+  lines.push('');
+  lines.push(`Analysis of \`${PACKAGE_NAME}\` usage in this project.`);
+  lines.push('');
+  lines.push(`**Library Version**: \`${PACKAGE_NAME}: ${projectVersion}\`  `);
+  lines.push(`**Generated**: ${new Date().toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' })}`);
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+  
+  // Summary statistics
+  const totalUsages = Array.from(usageMap.values()).reduce((sum, usages) => sum + usages.length, 0);
+  const uniqueComponents = usageMap.size;
+  const filesUsingComponents = new Set();
+  
+  usageMap.forEach(usages => {
+    usages.forEach(usage => filesUsingComponents.add(usage.file));
+  });
+  
+  lines.push('## Summary Statistics');
+  lines.push('');
+  lines.push(`- **Unique Components Used**: ${uniqueComponents}`);
+  lines.push(`- **Total Import Statements**: ${totalUsages}`);
+  lines.push(`- **Files Using Components**: ${filesUsingComponents.size}`);
+  lines.push('');
+  
+  // Categorize components
+  const categorized = new Map();
+  usageMap.forEach((usages, name) => {
+    const category = categorizeComponent(name);
+    if (!categorized.has(category)) {
+      categorized.set(category, []);
+    }
+    categorized.get(category).push({ name, usages });
+  });
+  
+  // Category breakdown
+  lines.push('### By Category');
+  lines.push('');
+  lines.push('| Category | Count |');
+  lines.push('|----------|-------|');
+  
+  const categories = ['Component', 'Template', 'Hook', 'Context', 'Service', 'Utility'];
+  categories.forEach(cat => {
+    const count = categorized.get(cat)?.length || 0;
+    if (count > 0) {
+      lines.push(`| ${cat}s | ${count} |`);
+    }
+  });
+  
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+  
+  // Detailed usage table
+  lines.push('## Component Usage Details');
+  lines.push('');
+  lines.push('| Component | Type | Usage Count | Used In |');
+  lines.push('|-----------|------|-------------|---------|');
+  
+  // Sort by usage count (descending)
+  const sortedComponents = Array.from(usageMap.entries())
+    .sort((a, b) => b[1].length - a[1].length);
+  
+  sortedComponents.forEach(([name, usages]) => {
+    const category = categorizeComponent(name);
+    lines.push(generateUsageRow(name, usages, category));
+  });
+  
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+  
+  // Most used components
+  lines.push('## Most Used Components');
+  lines.push('');
+  const topComponents = sortedComponents.slice(0, 10);
+  
+  topComponents.forEach(([name, usages], index) => {
+    lines.push(`${index + 1}. **${name}** - ${usages.length} usage${usages.length > 1 ? 's' : ''}`);
+  });
+  
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+  
+  // Detailed file listings
+  lines.push('## Detailed File Usage');
+  lines.push('');
+  
+  categorized.forEach((items, category) => {
+    if (items.length > 0) {
+      lines.push(`### ${category}s`);
+      lines.push('');
+      
+      items.sort((a, b) => a.name.localeCompare(b.name));
+      
+      items.forEach(({ name, usages }) => {
+        lines.push(`#### ${name}`);
+        lines.push('');
+        
+        // Group by file
+        const fileGroups = new Map();
+        usages.forEach(usage => {
+          if (!fileGroups.has(usage.file)) {
+            fileGroups.set(usage.file, []);
+          }
+          fileGroups.get(usage.file).push(usage);
+        });
+        
+        fileGroups.forEach((fileUsages, file) => {
+          const lineNumbers = fileUsages.map(u => u.line).join(', ');
+          lines.push(`- \`${file}\` (line${fileUsages.length > 1 ? 's' : ''} ${lineNumbers})`);
+        });
+        
+        lines.push('');
+      });
+    }
+  });
+  
+  lines.push('---');
+  lines.push('');
+  lines.push(`*Generated by ${PACKAGE_NAME} usage report tool*  `);
+  lines.push(`*Report generated: ${new Date().toISOString()}*`);
+  lines.push('');
+  
+  return lines.join('\n');
+}
+
+/**
+ * Main execution
+ */
+function main() {
+  console.log('📊 Generating Component Usage Report...\n');
+  
+  try {
+    // Check if package is installed
+    const packagePath = path.join(projectRoot, 'node_modules', PACKAGE_NAME);
+    if (!fs.existsSync(packagePath)) {
+      console.error(`❌ Error: ${PACKAGE_NAME} is not installed in this project`);
+      console.error('   Make sure to run this from a project that depends on cmsds-open-data-components');
+      process.exit(1);
+    }
+    
+    // Get available components
+    const availableComponents = getAvailableComponents();
+    console.log(`   Library version: ${availableComponents.version}`);
+    
+    // Scan for usage
+    const usageMap = scanProjectForUsage();
+    
+    if (usageMap.size === 0) {
+      console.warn('⚠️  No component usage found in this project');
+      console.warn('   Make sure you are running this from the correct directory');
+      process.exit(0);
+    }
+    
+    // Generate report
+    const report = generateReport(usageMap, availableComponents);
+    
+    // Write to file
+    const outputPath = path.join(projectRoot, outputFile);
+    fs.writeFileSync(outputPath, report, 'utf8');
+    
+    console.log(`\n✅ Usage report generated successfully!`);
+    console.log(`📄 Output: ${outputPath}`);
+    console.log(`📊 File size: ${(Buffer.byteLength(report, 'utf8') / 1024).toFixed(2)} KB`);
+    console.log(`📦 Components tracked: ${usageMap.size}`);
+  } catch (error) {
+    console.error('❌ Error generating report:', error.message);
+    console.error(error.stack);
+    process.exit(1);
+  }
+}
+
+// Run if called directly
+if (require.main === module) {
+  main();
+}
+
+module.exports = { main, scanProjectForUsage, generateReport };