ISA-Frontend/.claude/commands/docs-library.md

/docs:library - Generate/Update Library README

Generate or update README.md for a specific library with comprehensive documentation.

Parameters

• library-name: Name of library (e.g., oms-feature-return-search)

Tasks

1. Locate Library

# Find library directory
find libs/ -name "project.json" -path "*[library-name]*"

# Verify library exists
if [ ! -d "libs/[path-to-library]" ]; then
  echo "Library not found"
  exit 1
fi

2. Extract Library Information

Read project.json:

• Library name
• Source root
• Available targets (build, test, lint)
• Tags (domain, type)

Read tsconfig.base.json:

• Path alias (@isa/domain/layer/name)
• Entry point (src/index.ts)

3. Analyze Library Structure

Scan library contents:

# List main source files
ls -la libs/[path]/src/lib/

# Identify components
find libs/[path]/src -name "*.component.ts"

# Identify services
find libs/[path]/src -name "*.service.ts"

# Identify models/types
find libs/[path]/src -name "*.model.ts" -o -name "*.interface.ts"

# Check for exports
cat libs/[path]/src/index.ts

4. Use docs-researcher for Similar READMEs

Use docs-researcher agent to find similar library READMEs in the same domain for reference structure and style.

5. Determine Library Type and Template

Feature Library Template:

# [Library Name]

> **Type:** Feature Library
> **Domain:** [OMS/Remission/Checkout/etc]
> **Path:** `libs/[domain]/feature/[name]`

## Overview

[Brief description of what this feature does]

## Features

- Feature 1: [Description]
- Feature 2: [Description]
- Feature 3: [Description]

## Installation

This library is part of the ISA-Frontend monorepo. Import it using:

```typescript
import { ComponentName } from '@isa/[domain]/feature/[name]';

Usage

Basic Example

import { Component } from '@angular/core';
import { FeatureComponent } from '@isa/[domain]/feature/[name]';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [FeatureComponent],
  template: `
    <feature-component [input]="value" (output)="handleEvent($event)">
    </feature-component>
  `
})
export class ExampleComponent {
  value = 'example';

  handleEvent(event: any) {
    console.log(event);
  }
}

Advanced Usage

[More complex examples if applicable]

API Reference

Components

FeatureComponent

Selector: feature-component

Inputs:

• input (string): Description of input

Outputs:

• output (EventEmitter): Description of output

Example:

<feature-component [input]="value" (output)="handleEvent($event)">
</feature-component>

Services

[If applicable]

Models

[If applicable]

Testing

This library uses [Vitest/Jest] for testing.

Run tests:

npx nx test [library-name] --skip-nx-cache

Run with coverage:

npx nx test [library-name] --skip-nx-cache --coverage

Dependencies

External Dependencies:

• [List of external packages if any]

Internal Dependencies:

• @isa/[dependency] - Description

Development

Project Structure

libs/[domain]/feature/[name]/
├── src/
│   ├── lib/
│   │   ├── components/
│   │   ├── services/
│   │   └── models/
│   ├── index.ts
│   └── test-setup.ts
├── project.json
└── README.md

Build

npx nx build [library-name]

Lint

npx nx lint [library-name]

Related Documentation

• CLAUDE.md - Project guidelines
• Testing Guidelines
• Library Reference

Related Libraries

• @isa/[related-lib-1] - Description
• @isa/[related-lib-2] - Description

**Data Access Library Template:**
```markdown
# [Library Name]

> **Type:** Data Access Library
> **Domain:** [Domain]
> **Path:** `libs/[domain]/data-access`

## Overview

Data access layer for [Domain] domain. Provides services and state management for [domain-specific functionality].

## Features

- API client integration with [API names]
- NgRx Signals store for state management
- Type-safe data models with Zod validation
- Error handling and retry logic

## Installation

```typescript
import { ServiceName } from '@isa/[domain]/data-access';

Services

ServiceName

[Service description]

Methods:

getById(id: string): Observable<Model>

[Method description]

Parameters:

• id (string): Description

Returns: Observable<Model>

Example:

this.service.getById('123').subscribe({
  next: (data) => console.log(data),
  error: (err) => console.error(err)
});

State Management

This library uses NgRx Signals for state management.

Store

import { injectStore } from '@isa/[domain]/data-access';

export class Component {
  store = injectStore();

  // Access state
  items = this.store.items;
  loading = this.store.loading;

  // Call methods
  ngOnInit() {
    this.store.loadItems();
  }
}

Models

Model Name

interface ModelName {
  id: string;
  property: type;
}

Validated with Zod schema for runtime type safety.

Testing

[Testing section similar to feature library]

API Integration

This library integrates with the following Swagger-generated API clients:

• @generated/swagger/[api-name]

[Additional API documentation]

**UI Component Library Template:**
```markdown
# [Library Name]

> **Type:** UI Component Library
> **Path:** `libs/ui/[name]`

## Overview

Reusable UI components for [purpose]. Part of the ISA design system.

## Components

### ComponentName

[Component description]

**Selector:** `ui-component-name`

**Styling:** Uses Tailwind CSS with ISA design tokens

**Example:**
```html
<ui-component-name variant="primary" size="md">
  Content
</ui-component-name>

Variants

• primary: Default primary styling
• secondary: Secondary styling
• accent: Accent color

Sizes

• sm: Small (24px height)
• md: Medium (32px height)
• lg: Large (40px height)

Accessibility

• ARIA labels included
• Keyboard navigation supported
• Screen reader friendly

Storybook

View component documentation and examples:

npm run storybook

Navigate to: UI Components → [Component Name]

Testing

Includes E2E test attributes:

• data-what="component-name"
• data-which="variant"

[Rest of testing section]

### 6. Extract Code Examples

Scan library code for:
- Public component selectors
- Public API methods
- Input/Output properties
- Common usage patterns

Use `Read` tool to extract from source files.

### 7. Document Exports

Parse `src/index.ts` to document public API:
```typescript
// Read barrel export
export * from './lib/component';
export * from './lib/service';
export { PublicInterface } from './lib/models';

Document each export with:

• Type (Component/Service/Interface/Function)
• Purpose
• Basic usage

8. Add Testing Information

Based on test framework (from project.json):

• Test command
• Framework (Vitest/Jest)
• Coverage command
• Link to testing guidelines

9. Create Dependency Graph

List internal and external dependencies:

# Use Nx to show dependencies
npx nx graph --focus=[library-name]

# Extract from package.json and imports

10. Add E2E Attributes Documentation

For UI/Feature libraries, document E2E attributes:

## E2E Testing

This library includes E2E test attributes for automated testing:

| Element | data-what | data-which | Purpose |
|---------|-----------|------------|---------|
| Submit button | submit-button | form-primary | Main form submission |
| Cancel button | cancel-button | form-primary | Cancel action |

Use these attributes in your E2E tests:
```typescript
const submitBtn = page.locator('[data-what="submit-button"][data-which="form-primary"]');

### 11. Generate/Update README

Write or update `libs/[path]/README.md` with generated content.

### 12. Validate README

Checks:
- All links work (relative paths correct)
- Code examples are valid TypeScript
- Import paths use correct aliases
- No TODO or placeholder text
- Consistent formatting
- Proper markdown syntax

### 13. Add to Git (if new)

```bash
git add libs/[path]/README.md

Output Format

Library README Generated
========================

Library: [library-name]
Type: [Feature/Data Access/UI/Util]
Path: libs/[domain]/[layer]/[name]

📝 README Sections
------------------
✅ Overview
✅ Features
✅ Installation
✅ Usage Examples
✅ API Reference
✅ Testing
✅ Dependencies
✅ Development Guide

📊 Documentation Stats
----------------------
Total sections: XX
Code examples: XX
API methods documented: XX
Components documented: XX

🔗 Links Validated
-------------------
Internal links: XX/XX valid
Relative paths: ✅ Correct

💡 Highlights
-------------
- Documented XX public exports
- XX code examples included
- E2E attributes documented
- Related libraries linked

📁 File Updated
---------------
Path: libs/[domain]/[layer]/[name]/README.md
Size: XX KB
Lines: XX

🎯 Next Steps
-------------
1. Review generated README
2. Add any domain-specific details
3. Add usage examples if needed
4. Commit: git add libs/[path]/README.md

Auto-Enhancement

If existing README found:

• Preserve custom sections
• Update outdated examples
• Add missing sections
• Fix broken links
• Update import paths

Prompt:

Existing README found. What would you like to do?
1. Generate new (overwrite)
2. Enhance existing (preserve custom content)
3. Cancel

Quality Checks

• Import examples use correct path aliases
• Code examples are syntactically correct
• Links to related docs work
• API documentation complete
• Testing section accurate

References

• CLAUDE.md Library Organization section
• Use docs-researcher to find reference READMEs
• Storybook for UI component examples
• project.json for library configuration