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

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.2",
   "description": "Components for the open data catalog frontend using CMS Design System",
   "main": "dist/main.js",
   "source": "src/index.ts",

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} | ${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);
+  
+  // Detailed usage table
+  addUsageTable(lines, usageMap);
+  
+  // Footer
+  addReportFooter(lines);
   
-  // Get project info
+  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,80 +397,168 @@ function generateReport(usageMap, availableComponents) {
   lines.push('');
   lines.push('---');
   lines.push('');
-  
-  // Detailed usage table
+}
+
+/**
+ * Add detailed usage table section grouped by category
+ */
+function addUsageTable(lines, usageMap) {
   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]) => {
+  // Categorize all components
+  const categorized = new Map();
+  usageMap.forEach((usages, name) => {
     const category = categorizeComponent(name);
-    lines.push(generateUsageRow(name, usages, category));
+    if (!categorized.has(category)) {
+      categorized.set(category, []);
+    }
+    categorized.get(category).push({ name, usages });
   });
   
-  lines.push('');
-  lines.push('---');
-  lines.push('');
+  // Generate a table for each category
+  const categories = ['Component', 'Template', 'Hook', 'Context', 'Service', 'Utility'];
+  categories.forEach(category => {
+    const items = categorized.get(category);
+    if (!items || items.length === 0) return;
+    
+    // Sort by usage count within category
+    items.sort((a, b) => b.usages.length - a.usages.length);
+    
+    // Category header
+    lines.push(`### ${category}s`);
+    lines.push('');
+    
+    // Table header
+    lines.push('| Component | Count | Used In |');
+    lines.push('|-----------|-------|---------|');
+    
+    // Table rows
+    items.forEach(({ name, usages }) => {
+      lines.push(generateUsageRow(name, usages, category));
+    });
+    
+    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 +568,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)) {

package/scripts/README.md

@@ -1,119 +0,0 @@
-# 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