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

package/README.md

@@ -62,7 +62,36 @@ This creates `COMPONENTS_INVENTORY.md` in the root directory with:
 
 The inventory is automatically updated on every commit via a pre-commit hook.
 
-For more details, see the [Inventory Generator Documentation](scripts/README.md).
+For more details, see the [Scripts Documentation](scripts/README.md).
+
+## Component Usage Report
+
+This project includes a script that can be run in projects that use cmsds-open-data-components as a dependency to analyze component usage.
+
+### Running in Dependent Projects
+
+From a project that has `@civicactions/cmsds-open-data-components` as a dependency:
+
+```bash
+npx generate-usage-report
+```
+
+This generates `COMPONENT_USAGE_REPORT.md` showing:
+- Which components from the library are being used
+- Where each component is imported in the project
+- Summary statistics and category breakdown
+- GitHub links to component source code
+
+### Generating Sample Report (Library Development)
+
+To generate a sample report using Storybook files in this repository:
+```bash
+npm run generate:usage-report
+```
+
+This creates `SAMPLE_COMPONENT_USAGE_REPORT.md` demonstrating the report format.
+
+For more details, see the [Scripts Documentation](scripts/README.md).
 
 ## Publishing new versions
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@civicactions/cmsds-open-data-components",
-  "version": "4.0.8-alpha.0",
+  "version": "4.0.8-alpha.1",
   "description": "Components for the open data catalog frontend using CMS Design System",
   "main": "dist/main.js",
   "source": "src/index.ts",

package/scripts/README.md

@@ -1,4 +1,8 @@
-# Component Inventory Generator
+# Scripts Documentation
+
+This directory contains utility scripts for managing and analyzing the cmsds-open-data-components library.
+
+## Component Inventory Generator
 
 This script automatically generates a comprehensive markdown inventory report for the cmsds-open-data-components library.
 
@@ -92,12 +96,153 @@ To add new special cases, update the scanning functions in `generate-inventory.c
 
 ```
 scripts/
-  generate-inventory.cjs    # Main script file
-  README.md                 # This file
+  generate-inventory.cjs       # Component inventory script
+  generate-inventory.test.js   # Tests for inventory script
+  generate-usage-report.cjs    # Component usage report script
+  generate-usage-report.test.js # Tests for usage report script
+  README.md                    # This file
+
+COMPONENTS_INVENTORY.md        # Generated inventory (root directory)
+COMPONENT_USAGE_REPORT.md      # Generated usage report (root directory, when run in dependent projects)
+SAMPLE_COMPONENT_USAGE_REPORT.md # Sample usage report (root directory, when run locally)
+```
+
+---
+
+# Component Usage Report Generator
+
+This script analyzes projects that use cmsds-open-data-components as a dependency and generates a comprehensive report showing which components are being used and where.
+
+## Usage
 
-COMPONENTS_INVENTORY.md     # Generated output file (root directory)
+### In Projects Using cmsds-open-data-components
+
+From a project that has `@civicactions/cmsds-open-data-components` as a dependency:
+
+```bash
+npx generate-usage-report
+```
+
+Or add to your project's scripts in `package.json`:
+```json
+{
+  "scripts": {
+    "usage-report": "generate-usage-report"
+  }
+}
+```
+
+Then run:
+```bash
+npm run usage-report
 ```
 
+### In the Library Repository
+
+Run the script directly in this repository to generate a sample report:
+
+```bash
+npm run generate:usage-report
+```
+
+Or run it directly:
+
+```bash
+node scripts/generate-usage-report.cjs
+```
+
+When run in the library repository, it generates a sample report (`SAMPLE_COMPONENT_USAGE_REPORT.md`) by analyzing Storybook files.
+
+## Output
+
+The script generates a markdown report containing:
+
+- **Library Version**: Version of cmsds-open-data-components being analyzed
+- **Summary Statistics**: Total unique components, import statements, and files analyzed
+- **Category Breakdown**: Components grouped by type (Component, Template, Hook, Context, Service, Utility)
+- **Component Usage Details**: Table showing each component with:
+  - Component name (linked to GitHub repository)
+  - Category/type
+  - Number of times imported
+  - List of files where it's used
+
+## What It Scans
+
+The script scans the following directories in your project:
+
+- `src/` - Main source directory
+- `app/` - Next.js app directory
+- `pages/` - Next.js pages directory
+- `components/` - Components directory
+- `templates/` - Templates directory
+
+It searches for these file types:
+- `.js`, `.jsx` - JavaScript/React files
+- `.ts`, `.tsx` - TypeScript/React files
+
+The script automatically excludes:
+- `node_modules/` - Dependencies
+- `dist/`, `build/` - Build output directories
+- `.next/`, `.cache/` - Framework cache directories
+
+## How It Works
+
+1. **Detects execution context**: Determines if running in the library repo or a dependent project
+2. **Scans project files**: Recursively searches for JavaScript/TypeScript files
+3. **Parses imports**: Uses regex to find imports from `@civicactions/cmsds-open-data-components`
+4. **Tracks usage**: Records each component, where it's imported, and at what line number
+5. **Categorizes components**: Automatically categorizes by naming patterns:
+   - Hooks: Names starting with `use`
+   - Contexts: Names ending with `Context`
+   - Templates: From `templates/` directory
+   - Services: From `services/` directory
+   - Utilities: From `utilities/` directory
+   - Components: Everything else
+6. **Generates report**: Creates formatted markdown with statistics and detailed usage tables
+7. **Adds GitHub links**: Links each component name to its source in the GitHub repository
+
+## Component Categories
+
+Components are automatically categorized based on naming conventions and source location:
+
+- **Hook**: Components starting with `use` (e.g., `useScrollToTop`, `useDatastore`)
+- **Context**: Components ending with `Context` (e.g., `ACAContext`)
+- **Template**: Components from the `templates/` directory
+- **Service**: Components from the `services/` directory
+- **Utility**: Components from the `utilities/` directory
+- **Component**: All other React components
+
+## Sample vs Real Reports
+
+**In the library repository**: Generates `SAMPLE_COMPONENT_USAGE_REPORT.md` by analyzing how components are used in Storybook files. This serves as an example of the report format.
+
+**In dependent projects**: Generates `COMPONENT_USAGE_REPORT.md` by analyzing actual component usage throughout the project's codebase.
+
+## 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-usage-report.cjs` (not `.js`)
+
+**No components found in scan**
+- Verify that `@civicactions/cmsds-open-data-components` is installed as a dependency
+- Check that your import statements use the full package name
+- Ensure source files are in scanned directories (`src/`, `app/`, `pages/`, `components/`, `templates/`)
+
+**Missing some component usages**
+- The script only detects standard ES6 import syntax
+- Dynamic imports (e.g., `import()`) are not currently detected
+- Ensure imports use the package name: `from '@civicactions/cmsds-open-data-components'`
+
+---
+
+## File Structure
+
 ## Requirements
 
 - Node.js v14 or higher

package/scripts/generate-usage-report.cjs

@@ -125,14 +125,15 @@ function parseFileForImports(filePath) {
     const content = fs.readFileSync(filePath, 'utf8');
     const imports = [];
     
-    // Match ES6 imports: import { Component1, Component2 } from '@civicactions/cmsds-open-data-components'
+    const getLineNumber = (index) => content.substring(0, index).split('\n').length;
+    
+    // Match named imports: import { Component1, Component2 } from 'package'
     const namedImportRegex = new RegExp(
       `import\\s+\\{([^}]+)\\}\\s+from\\s+['"]${PACKAGE_NAME}['"]`,
       'g'
     );
     
-    let match;
-    while ((match = namedImportRegex.exec(content)) !== null) {
+    for (const match of content.matchAll(namedImportRegex)) {
       const names = match[1]
         .split(',')
         .map(n => n.trim())
@@ -142,22 +143,22 @@ function parseFileForImports(filePath) {
         imports.push({
           name,
           type: 'named',
-          line: content.substring(0, match.index).split('\n').length
+          line: getLineNumber(match.index)
         });
       });
     }
     
-    // Match default imports: import Component from '@civicactions/cmsds-open-data-components'
+    // Match default imports: import Component from 'package'
     const defaultImportRegex = new RegExp(
       `import\\s+(\\w+)\\s+from\\s+['"]${PACKAGE_NAME}['"]`,
       'g'
     );
     
-    while ((match = defaultImportRegex.exec(content)) !== null) {
+    for (const match of content.matchAll(defaultImportRegex)) {
       imports.push({
         name: match[1],
         type: 'default',
-        line: content.substring(0, match.index).split('\n').length
+        line: getLineNumber(match.index)
       });
     }
     
@@ -229,16 +230,52 @@ function categorizeComponent(name) {
 }
 
 /**
- * Generate markdown table row
+ * Generate markdown table row with GitHub link
  */
 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`;
+  const fileList = files.map(f => `\`${f}\``).join('<br>');
+  
+  const githubPath = getGitHubPath(name, category);
+  const githubUrl = `https://github.com/GetDKAN/cmsds-open-data-components/tree/main/${githubPath}`;
+  const nameLink = `[${name}](${githubUrl})`;
   
-  return `| ${name} | ${category} | ${count} | ${fileList} |`;
+  return `| ${nameLink} | ${category} | ${count} | ${fileList} |`;
+}
+
+/**
+ * Determine GitHub path based on component category and name
+ */
+function getGitHubPath(name, category) {
+  // Standard categories map directly to directories
+  const categoryPaths = {
+    'Component': `src/components/${name}`,
+    'Hook': `src/components/${name}`,
+    'Template': `src/templates/${name}`,
+    'Service': `src/services/${name}`,
+    'Utility': `src/utilities/${name}`
+  };
+  
+  if (categoryPaths[category]) {
+    return categoryPaths[category];
+  }
+  
+  // Context locations vary, check by name
+  if (category === 'Context') {
+    if (name.includes('DataTable')) {
+      return `src/components/DatasetTableTab/${name}.tsx`;
+    }
+    if (name === 'HeaderContext') {
+      return `src/templates/Header/${name}.tsx`;
+    }
+    if (name === 'ACAContext') {
+      return `src/utilities/${name}.ts`;
+    }
+    return `src/templates/Dataset/${name}.tsx`;
+  }
+  
+  return `src/components/${name}`;
 }
 
 /**
@@ -246,33 +283,67 @@ function generateUsageRow(name, usages, category) {
  */
 function generateReport(usageMap, availableComponents) {
   const lines = [];
+  const projectInfo = getProjectInfo(availableComponents);
+  
+  // Header
+  addReportHeader(lines, projectInfo);
+  
+  // Summary statistics
+  addSummaryStatistics(lines, usageMap);
+  
+  // Categorize and add category breakdown
+  const categorized = categorizeUsages(usageMap);
+  addCategoryBreakdown(lines, categorized);
   
-  // Get project info
+  // Detailed usage table
+  addUsageTable(lines, usageMap);
+  
+  // Footer
+  addReportFooter(lines);
+  
+  return lines.join('\n');
+}
+
+/**
+ * Get project information
+ */
+function getProjectInfo(availableComponents) {
   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;
+  if (!fs.existsSync(projectPkgPath)) {
+    return {
+      name: 'Unknown Project',
+      version: availableComponents.version
+    };
   }
   
-  // Header
-  lines.push(`# ${projectName} Component Usage Report`);
+  const projectPkg = JSON.parse(fs.readFileSync(projectPkgPath, 'utf8'));
+  const deps = { ...projectPkg.dependencies, ...projectPkg.devDependencies };
+  
+  return {
+    name: projectPkg.name || path.basename(projectRoot),
+    version: deps[PACKAGE_NAME] || availableComponents.version
+  };
+}
+
+/**
+ * Add report header section
+ */
+function addReportHeader(lines, projectInfo) {
+  lines.push(`# ${projectInfo.name} 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(`**Library Version**: \`${PACKAGE_NAME}: ${projectInfo.version}\`  `);
   lines.push('');
   lines.push('---');
   lines.push('');
-  
-  // Summary statistics
+}
+
+/**
+ * Add summary statistics section
+ */
+function addSummaryStatistics(lines, usageMap) {
   const totalUsages = Array.from(usageMap.values()).reduce((sum, usages) => sum + usages.length, 0);
   const uniqueComponents = usageMap.size;
   const filesUsingComponents = new Set();
@@ -287,9 +358,14 @@ function generateReport(usageMap, availableComponents) {
   lines.push(`- **Total Import Statements**: ${totalUsages}`);
   lines.push(`- **Files Using Components**: ${filesUsingComponents.size}`);
   lines.push('');
-  
-  // Categorize components
+}
+
+/**
+ * Categorize components by type
+ */
+function categorizeUsages(usageMap) {
   const categorized = new Map();
+  
   usageMap.forEach((usages, name) => {
     const category = categorizeComponent(name);
     if (!categorized.has(category)) {
@@ -298,7 +374,13 @@ function generateReport(usageMap, availableComponents) {
     categorized.get(category).push({ name, usages });
   });
   
-  // Category breakdown
+  return categorized;
+}
+
+/**
+ * Add category breakdown section
+ */
+function addCategoryBreakdown(lines, categorized) {
   lines.push('### By Category');
   lines.push('');
   lines.push('| Category | Count |');
@@ -315,8 +397,12 @@ function generateReport(usageMap, availableComponents) {
   lines.push('');
   lines.push('---');
   lines.push('');
-  
-  // Detailed usage table
+}
+
+/**
+ * Add detailed usage table section
+ */
+function addUsageTable(lines, usageMap) {
   lines.push('## Component Usage Details');
   lines.push('');
   lines.push('| Component | Type | Usage Count | Used In |');
@@ -334,61 +420,123 @@ function generateReport(usageMap, availableComponents) {
   lines.push('');
   lines.push('---');
   lines.push('');
+}
+
+/**
+ * Add report footer
+ */
+function addReportFooter(lines) {
+  const now = new Date();
+  const dateStr = now.toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' });
   
-  // Most used components
-  lines.push('## Most Used Components');
+  lines.push(`*Last updated: ${dateStr}*  `);
+  lines.push(`*Generated by ${PACKAGE_NAME} usage report tool*`);
   lines.push('');
-  const topComponents = sortedComponents.slice(0, 10);
+}
+
+/**
+ * Check if running in the library repo itself
+ */
+function isLibraryRepo() {
+  const pkgJsonPath = path.join(projectRoot, 'package.json');
+  if (fs.existsSync(pkgJsonPath)) {
+    const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'));
+    return pkgJson.name === PACKAGE_NAME;
+  }
+  return false;
+}
+
+/**
+ * Generate sample report for the library repo using Storybook files
+ */
+function generateSampleReport() {
+  console.log('📚 Detected library repository - generating sample usage report...\n');
   
-  topComponents.forEach(([name, usages], index) => {
-    lines.push(`${index + 1}. **${name}** - ${usages.length} usage${usages.length > 1 ? 's' : ''}`);
-  });
+  const usageMap = scanStoryFiles();
   
-  lines.push('');
-  lines.push('---');
-  lines.push('');
+  console.log(`   Found ${usageMap.size} unique components used in stories`);
   
-  // Detailed file listings
-  lines.push('## Detailed File Usage');
-  lines.push('');
+  const pkgJson = JSON.parse(fs.readFileSync(path.join(projectRoot, 'package.json'), 'utf8'));
+  const availableComponents = {
+    version: pkgJson.version,
+    exports: new Set()
+  };
   
-  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('');
-      });
-    }
+  const report = generateReport(usageMap, availableComponents);
+  const sampleNote = createSampleNote();
+  
+  return sampleNote + report;
+}
+
+/**
+ * Scan Storybook files for component usage
+ */
+function scanStoryFiles() {
+  const usageMap = new Map();
+  const srcPath = path.join(projectRoot, 'src');
+  const storyFiles = findFiles(srcPath, ['.stories.js', '.stories.jsx', '.stories.ts', '.stories.tsx']);
+  
+  console.log(`   Found ${storyFiles.length} Storybook files to analyze`);
+  
+  storyFiles.forEach(file => {
+    const relativePath = path.relative(projectRoot, file);
+    const content = fs.readFileSync(file, 'utf8');
+    
+    extractLocalImports(content, relativePath, usageMap);
   });
   
-  lines.push('---');
-  lines.push('');
-  lines.push(`*Generated by ${PACKAGE_NAME} usage report tool*  `);
-  lines.push(`*Report generated: ${new Date().toISOString()}*`);
-  lines.push('');
+  return usageMap;
+}
+
+/**
+ * Extract local imports from file content
+ */
+function extractLocalImports(content, relativePath, usageMap) {
+  const getLineNumber = (index) => content.substring(0, index).split('\n').length;
   
-  return lines.join('\n');
+  // Match local imports like: import { Component } from './Component'
+  const localImportRegex = /import\s+\{([^}]+)\}\s+from\s+['"]\.\//g;
+  const defaultImportRegex = /import\s+(\w+)\s+from\s+['"]\.\//g;
+  
+  for (const match of content.matchAll(localImportRegex)) {
+    const names = match[1].split(',').map(n => n.trim()).filter(n => n.length > 0);
+    names.forEach(name => {
+      if (!usageMap.has(name)) {
+        usageMap.set(name, []);
+      }
+      usageMap.get(name).push({
+        file: relativePath,
+        line: getLineNumber(match.index),
+        type: 'named'
+      });
+    });
+  }
+  
+  for (const match of content.matchAll(defaultImportRegex)) {
+    const name = match[1];
+    if (!usageMap.has(name)) {
+      usageMap.set(name, []);
+    }
+    usageMap.get(name).push({
+      file: relativePath,
+      line: getLineNumber(match.index),
+      type: 'default'
+    });
+  }
+}
+
+/**
+ * Create sample note for library repo reports
+ */
+function createSampleNote() {
+  return [
+    '> **Note**: This is a sample usage report generated from the cmsds-open-data-components library repository.',
+    '> It shows how components are used in Storybook files within this repository.',
+    '> When run in a project that depends on this library, the report will show actual component usage.',
+    '',
+    '---',
+    ''
+  ].join('\n');
 }
 
 /**
@@ -398,6 +546,20 @@ function main() {
   console.log('📊 Generating Component Usage Report...\n');
   
   try {
+    // Check if running in the library repo itself
+    if (isLibraryRepo()) {
+      const report = generateSampleReport();
+      const outputPath = path.join(projectRoot, 'SAMPLE_' + outputFile);
+      fs.writeFileSync(outputPath, report, 'utf8');
+      
+      console.log(`\n✅ Sample usage report generated successfully!`);
+      console.log(`📄 Output: ${outputPath}`);
+      console.log(`📊 File size: ${(Buffer.byteLength(report, 'utf8') / 1024).toFixed(2)} KB`);
+      console.log(`\n💡 This sample report shows component usage in Storybook files.`);
+      console.log(`   To see real usage, run this command in a project that depends on this library.`);
+      return;
+    }
+    
     // Check if package is installed
     const packagePath = path.join(projectRoot, 'node_modules', PACKAGE_NAME);
     if (!fs.existsSync(packagePath)) {