@civicactions/cmsds-open-data-components 4.0.7 → 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,11 +1,14 @@
 {
   "name": "@civicactions/cmsds-open-data-components",
-  "version": "4.0.7",
+  "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",
   "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,264 @@
+# 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.
+
+## 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       # 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
+
+### 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
+- 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,607 @@
+#!/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 = [];
+    
+    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'
+    );
+    
+    for (const match of content.matchAll(namedImportRegex)) {
+      const names = match[1]
+        .split(',')
+        .map(n => n.trim())
+        .filter(n => n.length > 0);
+      
+      names.forEach(name => {
+        imports.push({
+          name,
+          type: 'named',
+          line: getLineNumber(match.index)
+        });
+      });
+    }
+    
+    // Match default imports: import Component from 'package'
+    const defaultImportRegex = new RegExp(
+      `import\\s+(\\w+)\\s+from\\s+['"]${PACKAGE_NAME}['"]`,
+      'g'
+    );
+    
+    for (const match of content.matchAll(defaultImportRegex)) {
+      imports.push({
+        name: match[1],
+        type: 'default',
+        line: getLineNumber(match.index)
+      });
+    }
+    
+    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 with GitHub link
+ */
+function generateUsageRow(name, usages, category) {
+  const count = usages.length;
+  const files = [...new Set(usages.map(u => u.file))];
+  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 `| ${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}`;
+}
+
+/**
+ * Generate the usage report
+ */
+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);
+  
+  return lines.join('\n');
+}
+
+/**
+ * Get project information
+ */
+function getProjectInfo(availableComponents) {
+  const projectPkgPath = path.join(projectRoot, 'package.json');
+  
+  if (!fs.existsSync(projectPkgPath)) {
+    return {
+      name: 'Unknown Project',
+      version: availableComponents.version
+    };
+  }
+  
+  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}: ${projectInfo.version}\`  `);
+  lines.push('');
+  lines.push('---');
+  lines.push('');
+}
+
+/**
+ * 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();
+  
+  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 by type
+ */
+function categorizeUsages(usageMap) {
+  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 });
+  });
+  
+  return categorized;
+}
+
+/**
+ * Add category breakdown section
+ */
+function addCategoryBreakdown(lines, categorized) {
+  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('');
+}
+
+/**
+ * Add detailed usage table section
+ */
+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]) => {
+    const category = categorizeComponent(name);
+    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' });
+  
+  lines.push(`*Last updated: ${dateStr}*  `);
+  lines.push(`*Generated by ${PACKAGE_NAME} usage report tool*`);
+  lines.push('');
+}
+
+/**
+ * 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');
+  
+  const usageMap = scanStoryFiles();
+  
+  console.log(`   Found ${usageMap.size} unique components used in stories`);
+  
+  const pkgJson = JSON.parse(fs.readFileSync(path.join(projectRoot, 'package.json'), 'utf8'));
+  const availableComponents = {
+    version: pkgJson.version,
+    exports: new Set()
+  };
+  
+  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);
+  });
+  
+  return usageMap;
+}
+
+/**
+ * Extract local imports from file content
+ */
+function extractLocalImports(content, relativePath, usageMap) {
+  const getLineNumber = (index) => content.substring(0, index).split('\n').length;
+  
+  // 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');
+}
+
+/**
+ * Main execution
+ */
+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)) {
+      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 };