ISA-Frontend/.claude/commands/docs-refresh-reference.md

/docs:refresh-reference - Regenerate Library Reference

Regenerate the library reference documentation (docs/library-reference.md) by scanning all libraries in the monorepo.

Tasks

1. Scan Monorepo Structure

# List all libraries
find libs/ -name "project.json" -type f | sort

# Count total libraries
find libs/ -name "project.json" -type f | wc -l

2. Extract Library Information

For each library, extract from project.json:

• Project name: name field
• Path: Directory path
• Tags: For categorization (type, domain)
• Targets: Available commands (build, test, lint)

3. Determine Path Aliases

Read tsconfig.base.json to get path mappings:

# Extract paths section
cat tsconfig.base.json | grep -A 200 '"paths"'

Map each library to its @isa/* alias.

4. Categorize Libraries by Domain

Group libraries into categories:

• Availability (1 library)
• Catalogue (1 library)
• Checkout (6 libraries)
• Common (3 libraries)
• Core (5 libraries)
• CRM (1 library)
• Icons (1 library)
• OMS (9 libraries)
• Remission (8 libraries)
• Shared Components (7 libraries)
• UI Components (17 libraries)
• Utilities (3 libraries)

5. Read Library READMEs

For each library, use docs-researcher agent to:

• Read library README.md (if exists)
• Extract description/purpose
• Extract key features
• Extract usage examples

6. Generate Library Entries

For each library, create entry with:

#### `@isa/domain/layer/name`
**Path:** `libs/domain/layer/name`
**Type:** [Feature/Data Access/UI/Util]

Brief description from README or inferred from structure.

**Key Features:**
- Feature 1
- Feature 2

**Usage:**
```typescript
import { Component } from '@isa/domain/layer/name';

### 7. Create Domain Statistics

Calculate per domain:
- Total libraries count
- Breakdown by type (feature/data-access/ui/util)
- Key capabilities overview

### 8. Generate Table of Contents

Create hierarchical TOC:
```markdown
## Table of Contents
1. [Overview](#overview)
2. [Quick Stats](#quick-stats)
3. [Library Categories](#library-categories)
   - [Availability](#availability)
   - [Catalogue](#catalogue)
   - [Checkout](#checkout)
   ...

9. Add Metadata Header

Include document metadata:

# Library Reference Guide

> **Last Updated:** [Current Date]
> **Total Libraries:** XX
> **Domains:** 12

## Quick Stats
- Availability: 1 | Catalogue: 1 | Checkout: 6 | Common: 3
- Core: 5 | CRM: 1 | Icons: 1 | OMS: 9 | Remission: 8
- Shared Components: 7 | UI Components: 17 | Utilities: 3

10. Add Usage Guidelines

Include quick reference section:

## How to Use This Guide

### Finding a Library
1. Check the domain category (e.g., OMS, Checkout, UI Components)
2. Look for the specific feature or component you need
3. Note the import path alias (e.g., `@isa/oms/feature-return-search`)

### Import Syntax
All libraries use path aliases defined in `tsconfig.base.json`:

```typescript
// Feature libraries
import { Component } from '@isa/domain/feature/name';

// Data access services
import { Service } from '@isa/domain/data-access';

// UI components
import { ButtonComponent } from '@isa/ui/buttons';

// Utilities
import { helper } from '@isa/utils/validation';

### 11. Add Cross-References

Link related libraries:
```markdown
**Related Libraries:**
- [`@isa/oms/data-access`](#isaomsdataaccess) - OMS data services
- [`@isa/ui/buttons`](#isauibuttons) - Button components

12. Include Testing Information

For each library, note test framework:

**Testing:** Vitest | Jest
**Test Command:** `npx nx test [library-name] --skip-nx-cache`

13. Validate Generated Documentation

Checks:

• All libraries included (compare count)
• All path aliases correct
• No broken internal links
• Consistent formatting
• Alphabetical ordering within categories

14. Update CLAUDE.md Reference

Update CLAUDE.md to reference new library-reference.md:

#### Library Reference Guide

The monorepo contains **62 libraries** organized across 12 domains.
For quick lookup, see **[`docs/library-reference.md`](docs/library-reference.md)**.

15. Create Backup

Before overwriting:

# Backup existing file
cp docs/library-reference.md docs/library-reference.md.backup.$(date +%s)

16. Write New Documentation

Write to docs/library-reference.md with generated content.

Output Format

Generated File Structure:

# Library Reference Guide

> Last Updated: [Date]
> Total Libraries: XX
> Domains: 12

## Table of Contents
[Auto-generated TOC]

## Overview
[Introduction and usage guide]

## Quick Stats
[Statistics by domain]

## Library Categories

### Availability
#### @isa/availability/data-access
[Details...]

### Catalogue
[Details...]

[... all domains ...]

## Appendix

### Path Aliases
[Quick reference table]

### Testing Frameworks
[Framework by library]

### Nx Commands
[Common commands]

Output Summary

Library Reference Documentation Generated
==========================================

📊 Statistics
-------------
Total libraries scanned: XX
Libraries documented: XX
Domains covered: 12

📝 Documentation Structure
--------------------------
- Table of Contents: ✅
- Quick Stats: ✅
- Library categories: XX
- Total entries: XX

🔍 Quality Checks
-----------------
- All libraries included: ✅/❌
- Path aliases validated: ✅/❌
- Internal links verified: ✅/❌
- Consistent formatting: ✅/❌

💾 Files Updated
----------------
- docs/library-reference.md: ✅
- Backup created: docs/library-reference.md.backup.[timestamp]

📈 Changes from Previous Version
---------------------------------
- Libraries added: XX
- Libraries removed: XX
- Descriptions updated: XX

🎯 Next Steps
-------------
1. Review generated documentation
2. Verify library descriptions are accurate
3. Add missing usage examples if needed
4. Commit changes: git add docs/library-reference.md

Error Handling

• Missing project.json: Skip and report
• No README found: Use generic description
• Path alias mismatch: Flag for manual review
• Broken links: List for correction

Automation Tips

Can be run:

• After adding new libraries
• During documentation updates
• As pre-release validation
• In CI/CD pipeline

References

• CLAUDE.md Library Organization section
• tsconfig.base.json (path aliases)
• Individual library README.md files
• docs/library-reference.md (existing documentation)