From b845f997368ef898ad315f3dfdd43506cfdb5679 Mon Sep 17 00:00:00 2001 From: "m.osumi" Date: Thu, 1 Jan 2026 21:53:25 +0900 Subject: [PATCH 1/4] feat: add demo environment for local CODE_REF testing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add comprehensive demo directory with: - Sample TypeScript files (basic, advanced, edge-cases) - Documentation examples (valid, invalid, mixed patterns) - NPM scripts for quick testing (demo:validate, demo:fix) - Shell scripts for validation and fixing - Complete README with usage guide This allows users to test docs-coderef locally with various CODE_REF patterns and understand tool capabilities. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 --- .gitignore | 3 + demo/.docs-coderefrc.json | 6 + demo/README.md | 293 ++++++++++++++++++++++++ demo/docs/invalid/content-mismatch.md | 78 +++++++ demo/docs/invalid/missing-blocks.md | 76 ++++++ demo/docs/invalid/symbol-errors.md | 73 ++++++ demo/docs/invalid/wrong-lines.md | 43 ++++ demo/docs/mixed/combined-patterns.md | 144 ++++++++++++ demo/docs/valid/class-methods.md | 203 ++++++++++++++++ demo/docs/valid/line-based.md | 87 +++++++ demo/docs/valid/symbol-based.md | 94 ++++++++ demo/docs/valid/variables.md | 88 +++++++ demo/scripts/reset-demo.sh | 30 +++ demo/scripts/test-fix.sh | 26 +++ demo/scripts/test-validate.sh | 25 ++ demo/src/advanced/async.ts | 75 ++++++ demo/src/advanced/destructuring.ts | 61 +++++ demo/src/advanced/generics.ts | 71 ++++++ demo/src/basic/classes.ts | 92 ++++++++ demo/src/basic/functions.ts | 43 ++++ demo/src/basic/variables.ts | 41 ++++ demo/src/edge-cases/multiple-symbols.ts | 53 +++++ demo/src/edge-cases/overloads.ts | 47 ++++ package.json | 6 + 24 files changed, 1758 insertions(+) create mode 100644 demo/.docs-coderefrc.json create mode 100644 demo/README.md create mode 100644 demo/docs/invalid/content-mismatch.md create mode 100644 demo/docs/invalid/missing-blocks.md create mode 100644 demo/docs/invalid/symbol-errors.md create mode 100644 demo/docs/invalid/wrong-lines.md create mode 100644 demo/docs/mixed/combined-patterns.md create mode 100644 demo/docs/valid/class-methods.md create mode 100644 demo/docs/valid/line-based.md create mode 100644 demo/docs/valid/symbol-based.md create mode 100644 demo/docs/valid/variables.md create mode 100755 demo/scripts/reset-demo.sh create mode 100755 demo/scripts/test-fix.sh create mode 100755 demo/scripts/test-validate.sh create mode 100644 demo/src/advanced/async.ts create mode 100644 demo/src/advanced/destructuring.ts create mode 100644 demo/src/advanced/generics.ts create mode 100644 demo/src/basic/classes.ts create mode 100644 demo/src/basic/functions.ts create mode 100644 demo/src/basic/variables.ts create mode 100644 demo/src/edge-cases/multiple-symbols.ts create mode 100644 demo/src/edge-cases/overloads.ts diff --git a/.gitignore b/.gitignore index 2a52d57..49d409f 100644 --- a/.gitignore +++ b/.gitignore @@ -142,3 +142,6 @@ dist # Vite logs files vite.config.js.timestamp-* vite.config.ts.timestamp-* + +# Demo backup files +demo/**/*.backup diff --git a/demo/.docs-coderefrc.json b/demo/.docs-coderefrc.json new file mode 100644 index 0000000..a741d20 --- /dev/null +++ b/demo/.docs-coderefrc.json @@ -0,0 +1,6 @@ +{ + "projectRoot": ".", + "docsDir": "docs", + "ignoreFile": ".gitignore", + "verbose": true +} diff --git a/demo/README.md b/demo/README.md new file mode 100644 index 0000000..03fc1cc --- /dev/null +++ b/demo/README.md @@ -0,0 +1,293 @@ +# docs-coderef Demo Environment + +This directory contains a complete local testing environment for the `docs-coderef` tool. It demonstrates various CODE_REF patterns, both valid and intentionally invalid, to help you understand how the tool works. + +## Prerequisites + +- Node.js >= 22.0.0 +- The project must be built before running demos + +## Quick Start + +1. **Build the project**: + + ```bash + npm run build + ``` + +2. **Validate the demo documentation**: + + ```bash + npx docs-coderef validate demo/docs + ``` + +3. **Test the fix command**: + ```bash + npx docs-coderef fix + ``` + +Or use the convenience scripts: + +```bash +# Quick validation +npm run demo:validate + +# Validate only valid examples +npm run demo:validate:valid + +# Validate only invalid examples (will show errors) +npm run demo:validate:invalid + +# Test fix in dry-run mode +npm run demo:fix:dry + +# Test fix in auto mode +npm run demo:fix:auto +``` + +## Directory Structure + +``` +demo/ +├── README.md # This file +├── .docs-coderefrc.json # Demo-specific configuration +├── src/ # Sample source code files +│ ├── basic/ +│ │ ├── functions.ts # Various function patterns +│ │ ├── variables.ts # Constants and variables +│ │ └── classes.ts # Class and method examples +│ ├── advanced/ +│ │ ├── generics.ts # Generic functions/classes +│ │ ├── destructuring.ts # Destructuring patterns +│ │ └── async.ts # Async/await patterns +│ └── edge-cases/ +│ ├── overloads.ts # Function overloads +│ └── multiple-symbols.ts # Multiple symbols with same name +├── docs/ # Sample markdown documentation +│ ├── valid/ +│ │ ├── line-based.md # ✅ Valid line-based references +│ │ ├── symbol-based.md # ✅ Valid symbol references +│ │ ├── class-methods.md # ✅ Valid class method references +│ │ └── variables.md # ✅ Valid variable references +│ ├── invalid/ +│ │ ├── wrong-lines.md # ❌ Intentional line mismatch errors +│ │ ├── missing-blocks.md # ❌ Missing code blocks +│ │ ├── content-mismatch.md # ❌ Code content doesn't match +│ │ └── symbol-errors.md # ❌ Symbol not found errors +│ └── mixed/ +│ └── combined-patterns.md # 🔀 Mix of valid and invalid +└── scripts/ + ├── test-validate.sh # Run validation on demo + ├── test-fix.sh # Run fix on demo (with backup) + └── reset-demo.sh # Reset demo to initial state +``` + +## Demo Scenarios + +### 1. Valid References (`docs/valid/`) + +These files demonstrate correct usage of CODE_REF comments: + +- **line-based.md**: Line number references like `` +- **symbol-based.md**: Symbol references like `` +- **class-methods.md**: Class method references like `` +- **variables.md**: Variable references like `` + +Run validation: + +```bash +npx docs-coderef validate demo/docs/valid +``` + +Expected result: ✅ All validations should pass + +### 2. Invalid References (`docs/invalid/`) + +These files contain intentional errors to demonstrate error detection: + +- **wrong-lines.md**: `CODE_LOCATION_MISMATCH` - Code is correct but at different line numbers +- **missing-blocks.md**: `CODE_BLOCK_MISSING` - CODE_REF without following code block +- **content-mismatch.md**: `CODE_CONTENT_MISMATCH` - Code block doesn't match source +- **symbol-errors.md**: `SYMBOL_NOT_FOUND` - References to non-existent symbols + +Run validation: + +```bash +npx docs-coderef validate demo/docs/invalid +``` + +Expected result: ❌ Multiple validation errors (this is intentional!) + +### 3. Mixed Patterns (`docs/mixed/`) + +- **combined-patterns.md**: A realistic documentation file with both valid and invalid references + +Run validation: + +```bash +npx docs-coderef validate demo/docs/mixed/combined-patterns.md +``` + +Expected result: ⚠️ Some errors, some successes + +## Example Commands + +### Validation + +```bash +# Validate all demo documentation +npx docs-coderef validate demo/docs + +# Validate specific file +npx docs-coderef validate demo/docs/valid/symbol-based.md + +# Validate specific directory +npx docs-coderef validate demo/docs/valid + +# Validate with verbose output +npx docs-coderef validate demo/docs --verbose + +# Change working directory to demo first +cd demo +npx docs-coderef validate docs +``` + +### Fix + +```bash +# Interactive fix with preview (recommended) +npx docs-coderef fix + +# Dry-run mode (preview without making changes) +npx docs-coderef fix --dry-run + +# Auto-fix all errors without prompting +npx docs-coderef fix --auto + +# Create backups before fixing +npx docs-coderef fix --backup +``` + +### Using Shell Scripts + +```bash +# From project root: +./demo/scripts/test-validate.sh # Build and validate +./demo/scripts/test-fix.sh # Build and run fix +./demo/scripts/reset-demo.sh # Reset demo to original state +``` + +## CODE_REF Pattern Reference + +### Line-Based References + +```markdown + +``` + +References specific line numbers in a file. + +### Symbol References + +```markdown + +``` + +References a function, class, or variable by name. + +### Class Method References + +```markdown + +``` + +References a method within a class: `ClassName#methodName` + +### Symbol with Line Hint + +```markdown + +``` + +Useful when multiple symbols have the same name. + +## Expected Validation Output + +### Valid Files + +When validating `demo/docs/valid/`, you should see: + +``` +✓ demo/docs/valid/line-based.md - All 5 CODE_REF references are valid +✓ demo/docs/valid/symbol-based.md - All 5 CODE_REF references are valid +✓ demo/docs/valid/class-methods.md - All 5 CODE_REF references are valid +✓ demo/docs/valid/variables.md - All 8 CODE_REF references are valid +``` + +### Invalid Files + +When validating `demo/docs/invalid/`, you should see errors like: + +``` +✗ demo/docs/invalid/wrong-lines.md + - CODE_LOCATION_MISMATCH: Code matches but at different lines + +✗ demo/docs/invalid/missing-blocks.md + - CODE_BLOCK_MISSING: No code block found after CODE_REF + +✗ demo/docs/invalid/content-mismatch.md + - CODE_CONTENT_MISMATCH: Code block content differs from source + +✗ demo/docs/invalid/symbol-errors.md + - SYMBOL_NOT_FOUND: Symbol does not exist in file +``` + +## Resetting the Demo + +After running `fix --auto`, the demo files will be modified. To restore them to their original state: + +```bash +# Using the script (recommended) +./demo/scripts/reset-demo.sh + +# Or manually +git checkout demo/docs/ +``` + +## Exploring the Demo + +1. **Start with valid examples**: Check `docs/valid/` to see correct CODE_REF usage +2. **Examine source files**: Look at the TypeScript files in `src/` to understand what's being referenced +3. **Try validation**: Run validation on different directories to see the output +4. **Test error detection**: Validate `docs/invalid/` to see how errors are reported +5. **Experiment with fix**: Run `fix --dry-run` to see what changes would be made +6. **Try real fixes**: Run `fix` on invalid files and observe the interactive prompts +7. **Reset and repeat**: Use `reset-demo.sh` to start fresh + +## Troubleshooting + +### "Command not found: docs-coderef" + +- Make sure you've run `npm run build` first +- The tool must be built before it can be used + +### "File not found" errors + +- Check that you're running commands from the project root +- Paths in CODE_REF should be relative to demo directory + +### "Symbol not found" errors + +- Verify the symbol name matches exactly (case-sensitive) +- Check that you're referencing a TypeScript/JavaScript file +- Make sure the symbol is exported + +### Validation succeeds but should fail + +- Check that CODE_REF paths are correct +- Verify code blocks match source exactly (including whitespace) +- Ensure JSDoc comments are included if present in source + +--- + +Happy testing! 🚀 diff --git a/demo/docs/invalid/content-mismatch.md b/demo/docs/invalid/content-mismatch.md new file mode 100644 index 0000000..be42938 --- /dev/null +++ b/demo/docs/invalid/content-mismatch.md @@ -0,0 +1,78 @@ +# Content Mismatch Examples + +This document contains intentional CODE_CONTENT_MISMATCH errors. +The code blocks don't match the actual source code. + +## Outdated Function Documentation + +This shows an old version of the greet function: + + + +```typescript +/** + * Greets a person by name + * @param name - The name of the person to greet + * @returns A greeting message + */ +export function greet(name: string): string { + return `Hello, ${name}!`; +} +``` + +## Wrong Variable Value + +The API_KEY has the wrong value: + + + +```typescript +/** + * API configuration constants + */ +export const API_KEY = 'demo-api-key-12345'; +``` + +## Modified Method + +The getName method has different implementation: + + + +```typescript +/** + * Gets the user's name + * @returns The user's name + */ +getName(): string { + return this.name; +} +``` + +## Missing JSDoc + +The add function is shown without its JSDoc comment: + + + +```typescript +/** + * Adds two numbers together + * @param a - First number + * @param b - Second number + * @returns The sum of a and b + */ +export function add(a: number, b: number): number { + return a + b; +} +``` + +## Wrong Line Count + +This has extra lines that don't exist in the source: + + + +```typescript +*/ +``` diff --git a/demo/docs/invalid/missing-blocks.md b/demo/docs/invalid/missing-blocks.md new file mode 100644 index 0000000..ce43798 --- /dev/null +++ b/demo/docs/invalid/missing-blocks.md @@ -0,0 +1,76 @@ +# Missing Code Blocks Examples + +This document contains intentional CODE_BLOCK_MISSING errors. +CODE_REF comments are not followed by code blocks. + +## Missing Block After Reference + +This CODE_REF is not followed by a code block: + + + +```typescript +/** + * Greets a person by name + * @param name - The name of the person to greet + * @returns A greeting message + */ +export function greet(name: string): string { + return `Hello, ${name}!`; +} +``` + +This is just regular text, not a code block. + +## Another Missing Block + + + +```typescript +/** + * API configuration constants + */ +export const API_KEY = 'demo-api-key-12345'; +``` + +Some more text without a code block. + +## CODE_REF Followed by Different Content + + + +```typescript +/** + * Gets the user's name + * @returns The user's name + */ +getName(): string { + return this.name; +} +``` + +Here we have a paragraph instead of a code block. The validation should fail because there's no code block immediately following the CODE_REF comment. + +## Mixed Case: Valid Reference Followed by Text + + + +```typescript +/** + * Async function that fetches user data + * @param userId - The ID of the user to fetch + * @returns Promise resolving to user data + */ +export async function fetchUser( + userId: string +): Promise<{ id: string; name: string }> { + // Simulate API call + return new Promise((resolve) => { + setTimeout(() => { + resolve({ id: userId, name: 'John Doe' }); + }, 100); + }); +} +``` + +The fetchUser function is an async function that fetches user data. But this description is not in a code block! diff --git a/demo/docs/invalid/symbol-errors.md b/demo/docs/invalid/symbol-errors.md new file mode 100644 index 0000000..a38a9b0 --- /dev/null +++ b/demo/docs/invalid/symbol-errors.md @@ -0,0 +1,73 @@ +# Symbol Error Examples + +This document contains intentional symbol-related errors. + +## Non-Existent Function + +This references a function that doesn't exist: + + + +```typescript +export function nonExistentFunction(): void { + console.log('This function does not exist in the source file'); +} +``` + +## Non-Existent Variable + +This references a variable that doesn't exist: + + + +```typescript +export const NON_EXISTENT_CONSTANT = 'does not exist'; +``` + +## Non-Existent Class + +This references a class that doesn't exist: + + + +```typescript +export class NonExistentClass { + constructor() {} +} +``` + +## Non-Existent Method + +This references a method that doesn't exist in the User class: + + + +```typescript +nonExistentMethod(): void { + console.log('This method does not exist'); +} +``` + +## File Not Found + +This references a file that doesn't exist: + + + +```typescript +export function someFunction(): void { + console.log('The file itself does not exist'); +} +``` + +## Wrong File Extension + +This tries to use symbol reference on a non-TypeScript file (if it existed): + + + +```markdown +# Some Symbol + +This shouldn't work because symbol search only works on TS/JS files +``` diff --git a/demo/docs/invalid/wrong-lines.md b/demo/docs/invalid/wrong-lines.md new file mode 100644 index 0000000..b2a2051 --- /dev/null +++ b/demo/docs/invalid/wrong-lines.md @@ -0,0 +1,43 @@ +# Wrong Line Numbers Examples + +This document contains intentional CODE_LOCATION_MISMATCH errors. +The code content is correct, but the line numbers are wrong. + +## Wrong Lines for greet Function + +This references lines 1-5, but the actual function is at lines 7-13: + + + +```typescript +/** + * Greets a person by name + * @param name - The name of the person to greet + * @returns A greeting message + */ +export function greet(name: string): string { + return `Hello, ${name}!`; +} +``` + +## Wrong Lines for add Function + +This references lines 20-22, but the actual function is at lines 16-18: + + + +```typescript +export function add(a: number, b: number): number { + return a + b; +} +``` + +## Wrong Lines for API_KEY + +This references line 10, but the actual constant is at line 7: + + + +```typescript +export const API_VERSION = 'v1'; +``` diff --git a/demo/docs/mixed/combined-patterns.md b/demo/docs/mixed/combined-patterns.md new file mode 100644 index 0000000..830768c --- /dev/null +++ b/demo/docs/mixed/combined-patterns.md @@ -0,0 +1,144 @@ +# Combined Patterns - Real World Example + +This document demonstrates a realistic documentation scenario with both valid and invalid CODE_REF patterns mixed together. + +## Getting Started + +### Basic Functions + +The `greet` function is the main entry point for greeting users: + + + +```typescript +/** + * Greets a person by name + * @param name - The name of the person to greet + * @returns A greeting message + */ +export function greet(name: string): string { + return `Hello, ${name}!`; +} +``` + +You can also use the `add` function for calculations (this has wrong line numbers): + + + +```typescript +export function add(a: number, b: number): number { + return a + b; +} +``` + +### Configuration + +Configure your application using these constants: + + + +```typescript +export const API_KEY = 'demo-api-key-12345'; +``` + +The API endpoint is defined here (this has outdated content): + + + +```typescript +export const API_ENDPOINT = 'https://old-api.example.com'; +``` + +### User Management + +The User class provides user management capabilities: + + + +```typescript +/** + * Gets the user's name + * @returns The user's name + */ +getName(): string { + return this.name; +} +``` + +This is a reference without a code block: + + + +The getEmail method returns the user's email address. + +### Advanced Features + +For type-safe operations, use generic functions: + + + +```typescript +/** + * Generic function that returns the first element of an array + * @param items - Array of items + * @returns The first element or undefined + */ +export function getFirst(items: T[]): T | undefined { + return items[0]; +} +``` + +And for async operations (this references a non-existent function): + + + +```typescript +export async function nonExistentAsyncFunc(): Promise { + await Promise.resolve(); +} +``` + +### Working with Products + +The Product class helps manage products: + + + +```typescript +/** + * Applies a discount to the product + * @param percentage - Discount percentage (0-100) + * @returns The discounted price + */ +applyDiscount(percentage: number): number { + return this.price * (1 - percentage / 100); +} +``` + +### Utility Functions + +For formatting, use the multi-parameter function: + + + +```typescript +export function formatUserInfo( + firstName: string, + lastName: string, + age: number +): string { + return `${firstName} ${lastName} (${age} years old)`; +} +``` + +## Summary + +This document contains: + +- ✅ 5 valid CODE_REF references +- ❌ 1 wrong line number (add function) +- ❌ 1 content mismatch (API_ENDPOINT) +- ❌ 1 missing code block (getEmail) +- ❌ 1 symbol not found (nonExistentAsyncFunc) + +Total: 9 CODE_REF comments (5 valid, 4 invalid) diff --git a/demo/docs/valid/class-methods.md b/demo/docs/valid/class-methods.md new file mode 100644 index 0000000..86f0878 --- /dev/null +++ b/demo/docs/valid/class-methods.md @@ -0,0 +1,203 @@ +# Class and Method CODE_REF Examples + +This document demonstrates valid class and method CODE_REF patterns. + +## Class Reference + +The complete `User` class: + + + +```typescript +/** + * Represents a user in the system + */ +export class User { + private name: string; + private email: string; + private age: number; + + /** + * Creates a new User instance + * @param name - User's full name + * @param email - User's email address + * @param age - User's age + */ + constructor(name: string, email: string, age: number) { + this.name = name; + this.email = email; + this.age = age; + } + + /** + * Gets the user's name + * @returns The user's name + */ + getName(): string { + return this.name; + } + + /** + * Gets the user's email + * @returns The user's email address + */ + getEmail(): string { + return this.email; + } + + /** + * Gets the user's age + * @returns The user's age + */ + getAge(): number { + return this.age; + } + + /** + * Updates the user's email + * @param newEmail - The new email address + */ + updateEmail(newEmail: string): void { + this.email = newEmail; + } + + /** + * Checks if user is an adult + * @returns True if user is 18 or older + */ + private isAdult(): boolean { + return this.age >= 18; + } + + /** + * Creates a default guest user + * @returns A new User instance for guests + */ + static createGuest(): User { + return new User('Guest', 'guest@example.com', 0); + } +} +``` + +## Method Reference + +The `getName` method from the User class: + + + +```typescript +/** + * Gets the user's name + * @returns The user's name + */ +getName(): string { + return this.name; +} +``` + +## Another Method + +The `updateEmail` method: + + + +```typescript +/** + * Updates the user's email + * @param newEmail - The new email address + */ +updateEmail(newEmail: string): void { + this.email = newEmail; +} +``` + +## Static Method + +The static `createGuest` method: + + + +```typescript +/** + * Creates a default guest user + * @returns A new User instance for guests + */ +static createGuest(): User { + return new User('Guest', 'guest@example.com', 0); +} +``` + +## Product Class + +A simpler class with public properties: + + + +```typescript +/** + * Represents a product in an e-commerce system + */ +export class Product { + constructor( + public id: string, + public name: string, + public price: number + ) {} + + /** + * Applies a discount to the product + * @param percentage - Discount percentage (0-100) + * @returns The discounted price + */ + applyDiscount(percentage: number): number { + return this.price * (1 - percentage / 100); + } +} +``` + +## Generic Class + +The generic `Stack` class: + + + +```typescript +/** + * Generic class representing a stack data structure + */ +export class Stack { + private items: T[] = []; + + /** + * Pushes an item onto the stack + * @param item - The item to push + */ + push(item: T): void { + this.items.push(item); + } + + /** + * Pops an item from the stack + * @returns The popped item or undefined + */ + pop(): T | undefined { + return this.items.pop(); + } + + /** + * Peeks at the top item without removing it + * @returns The top item or undefined + */ + peek(): T | undefined { + return this.items[this.items.length - 1]; + } + + /** + * Gets the size of the stack + * @returns The number of items + */ + size(): number { + return this.items.length; + } +} +``` diff --git a/demo/docs/valid/line-based.md b/demo/docs/valid/line-based.md new file mode 100644 index 0000000..9e3231b --- /dev/null +++ b/demo/docs/valid/line-based.md @@ -0,0 +1,87 @@ +# Line-Based CODE_REF Examples + +This document demonstrates valid line-based CODE_REF patterns. + +## Basic Function (Lines 5-12) + +Here's the `greet` function with its JSDoc comment: + + + +```typescript +/** + * Greets a person by name + * @param name - The name of the person to greet + * @returns A greeting message + */ +export function greet(name: string): string { + return `Hello, ${name}!`; +} +``` + +## Add Function (Lines 14-22) + +The simple `add` function: + + + +```typescript +/** + * Adds two numbers together + * @param a - First number + * @param b - Second number + * @returns The sum of a and b + */ +export function add(a: number, b: number): number { + return a + b; +} +``` + +## Arrow Function (Lines 24-29) + +An arrow function example: + + + +```typescript +/** + * Arrow function example + */ +export const multiply = (a: number, b: number): number => { + return a * b; +}; +``` + +## Multi-Parameter Function (Lines 31-40) + +A function with multiple parameters: + + + +```typescript +/** + * Function with multiple parameters + */ +export function formatUserInfo( + firstName: string, + lastName: string, + age: number +): string { + return `${firstName} ${lastName} (${age} years old)`; +} +``` + +## Default Export (Lines 42-47) + +Default export function: + + + +```typescript +/** + * Default export function + */ +export default function welcome(): string { + return 'Welcome to the demo!'; +} +``` diff --git a/demo/docs/valid/symbol-based.md b/demo/docs/valid/symbol-based.md new file mode 100644 index 0000000..6915014 --- /dev/null +++ b/demo/docs/valid/symbol-based.md @@ -0,0 +1,94 @@ +# Symbol-Based CODE_REF Examples + +This document demonstrates valid symbol-based CODE_REF patterns. + +## Function Reference + +Here's the `greet` function referenced by symbol: + + + +```typescript +/** + * Greets a person by name + * @param name - The name of the person to greet + * @returns A greeting message + */ +export function greet(name: string): string { + return `Hello, ${name}!`; +} +``` + +## Another Function + +The `add` function: + + + +```typescript +/** + * Adds two numbers together + * @param a - First number + * @param b - Second number + * @returns The sum of a and b + */ +export function add(a: number, b: number): number { + return a + b; +} +``` + +## Arrow Function Reference + +Arrow function stored in a const: + + + +```typescript +/** + * Arrow function example + */ +export const multiply = (a: number, b: number): number => { + return a * b; +}; +``` + +## Generic Function + +Generic function from advanced examples: + + + +```typescript +/** + * Generic function that returns the first element of an array + * @param items - Array of items + * @returns The first element or undefined + */ +export function getFirst(items: T[]): T | undefined { + return items[0]; +} +``` + +## Async Function + +Async function example: + + + +```typescript +/** + * Async function that fetches user data + * @param userId - The ID of the user to fetch + * @returns Promise resolving to user data + */ +export async function fetchUser( + userId: string +): Promise<{ id: string; name: string }> { + // Simulate API call + return new Promise((resolve) => { + setTimeout(() => { + resolve({ id: userId, name: 'John Doe' }); + }, 100); + }); +} +``` diff --git a/demo/docs/valid/variables.md b/demo/docs/valid/variables.md new file mode 100644 index 0000000..32180ae --- /dev/null +++ b/demo/docs/valid/variables.md @@ -0,0 +1,88 @@ +# Variable CODE_REF Examples + +This document demonstrates valid variable and constant CODE_REF patterns. + +## Simple Constant + +The `API_KEY` constant: + + + +```typescript +export const API_KEY = 'demo-api-key-12345'; +``` + +## API Endpoint + +The `API_ENDPOINT` constant: + + + +```typescript +export const API_ENDPOINT = 'https://api.example.com'; +``` + +## Configuration Object + +The `config` object: + + + +```typescript +/** + * Application configuration object + */ +export const config = { + appName: 'Demo App', + version: '1.0.0', + debug: true, +}; +``` + +## Array Destructuring + +Destructured array constants: + + + +```typescript +export const [primaryColor, secondaryColor] = ['blue', 'green']; +``` + +## Object Destructuring + +Destructured object properties: + + + +```typescript +export const { appName, version } = config; +``` + +## Multiple Constants + +The `MAX_RETRIES` constant: + + + +```typescript +export const MAX_RETRIES = 3; +``` + +The `TIMEOUT_MS` constant: + + + +```typescript +export const TIMEOUT_MS = 5000; +``` + +## Computed Constant + +The `CACHE_DURATION` computed constant: + + + +```typescript +export const CACHE_DURATION = 60 * 60 * 1000; // 1 hour in milliseconds +``` diff --git a/demo/scripts/reset-demo.sh b/demo/scripts/reset-demo.sh new file mode 100755 index 0000000..c717054 --- /dev/null +++ b/demo/scripts/reset-demo.sh @@ -0,0 +1,30 @@ +#!/bin/bash + +# Script to reset demo files to original state +# Run from project root: ./demo/scripts/reset-demo.sh + +echo "================================" +echo "Resetting demo files to original state..." +echo "================================" + +git checkout demo/docs/ + +if [ $? -eq 0 ]; then + echo "✓ Demo documentation files reset successfully!" +else + echo "✗ Failed to reset demo files." + echo " Make sure you're in a git repository and have demo/docs/ committed." + exit 1 +fi + +# Remove any backup files +if ls demo/docs/**/*.backup 1> /dev/null 2>&1; then + echo "Removing backup files..." + rm demo/docs/**/*.backup + echo "✓ Backup files removed" +fi + +echo "" +echo "================================" +echo "Demo reset complete!" +echo "================================" diff --git a/demo/scripts/test-fix.sh b/demo/scripts/test-fix.sh new file mode 100755 index 0000000..dcb46d6 --- /dev/null +++ b/demo/scripts/test-fix.sh @@ -0,0 +1,26 @@ +#!/bin/bash + +# Script to test the fix command on demo documentation +# Run from project root: ./demo/scripts/test-fix.sh + +echo "================================" +echo "Building project..." +echo "================================" +npm run build + +if [ $? -ne 0 ]; then + echo "Build failed! Exiting." + exit 1 +fi + +echo "" +echo "================================" +echo "Running fix command (interactive mode with backup)..." +echo "================================" +npx docs-coderef fix --backup + +echo "" +echo "================================" +echo "Fix complete!" +echo "================================" +echo "To reset demo files, run: ./demo/scripts/reset-demo.sh" diff --git a/demo/scripts/test-validate.sh b/demo/scripts/test-validate.sh new file mode 100755 index 0000000..6f1b6ab --- /dev/null +++ b/demo/scripts/test-validate.sh @@ -0,0 +1,25 @@ +#!/bin/bash + +# Script to validate demo documentation +# Run from project root: ./demo/scripts/test-validate.sh + +echo "================================" +echo "Building project..." +echo "================================" +npm run build + +if [ $? -ne 0 ]; then + echo "Build failed! Exiting." + exit 1 +fi + +echo "" +echo "================================" +echo "Validating demo documentation..." +echo "================================" +npx docs-coderef validate demo/docs --verbose + +echo "" +echo "================================" +echo "Validation complete!" +echo "================================" diff --git a/demo/src/advanced/async.ts b/demo/src/advanced/async.ts new file mode 100644 index 0000000..d0b1eeb --- /dev/null +++ b/demo/src/advanced/async.ts @@ -0,0 +1,75 @@ +/** + * Async/await pattern examples for CODE_REF demonstration + */ + +/** + * Async function that fetches user data + * @param userId - The ID of the user to fetch + * @returns Promise resolving to user data + */ +export async function fetchUser(userId: string): Promise<{ id: string; name: string }> { + // Simulate API call + return new Promise((resolve) => { + setTimeout(() => { + resolve({ id: userId, name: 'John Doe' }); + }, 100); + }); +} + +/** + * Async arrow function + */ +export const fetchPosts = async (limit: number): Promise => { + // Simulate API call + return new Promise((resolve) => { + setTimeout(() => { + resolve(['Post 1', 'Post 2', 'Post 3'].slice(0, limit)); + }, 100); + }); +}; + +/** + * Function returning a Promise + * @param data - Data to save + * @returns Promise resolving to success status + */ +export function saveData(data: unknown): Promise { + return new Promise((resolve, reject) => { + setTimeout(() => { + if (data) { + resolve(true); + } else { + reject(new Error('No data provided')); + } + }, 100); + }); +} + +/** + * Async function with error handling + * @param url - URL to fetch + * @returns Promise resolving to response data or null on error + */ +export async function fetchWithErrorHandling(url: string): Promise { + try { + // Simulate fetch + const response = await fetch(url); + const data = await response.text(); + return data; + } catch (error) { + console.error('Fetch failed:', error); + return null; + } +} + +/** + * Async function using Promise.all + * @param userIds - Array of user IDs + * @returns Promise resolving to array of users + */ +export async function fetchMultipleUsers( + userIds: string[] +): Promise<{ id: string; name: string }[]> { + const promises = userIds.map((id) => fetchUser(id)); + return Promise.all(promises); +} diff --git a/demo/src/advanced/destructuring.ts b/demo/src/advanced/destructuring.ts new file mode 100644 index 0000000..4840059 --- /dev/null +++ b/demo/src/advanced/destructuring.ts @@ -0,0 +1,61 @@ +/** + * Destructuring pattern examples for CODE_REF demonstration + */ + +/** + * Function using parameter destructuring + * @param user - User object with name and email + * @returns A formatted string + */ +export function printUser({ name, email }: { name: string; email: string }): string { + return `User: ${name} (${email})`; +} + +/** + * Function with array destructuring in parameters + * @param coordinates - Array of [x, y] coordinates + * @returns The sum of coordinates + */ +export function sumCoordinates([x, y]: [number, number]): number { + return x + y; +} + +/** + * Object destructuring with renaming + */ +export function processConfig(config: { apiUrl: string; timeout: number }): void { + const { apiUrl: url, timeout: timeoutMs } = config; + console.log(`URL: ${url}, Timeout: ${timeoutMs}ms`); +} + +/** + * Array destructuring example + */ +export const [first, second, ...rest] = [1, 2, 3, 4, 5]; + +/** + * Object destructuring example + */ +export const userData = { + username: 'john_doe', + email: 'john@example.com', + age: 30, +}; + +export const { username, email: userEmail } = userData; + +/** + * Nested destructuring example + * @param data - Nested data structure + * @returns The extracted city name + */ +export function extractCity(data: { + user: { address: { city: string; country: string } }; +}): string { + const { + user: { + address: { city }, + }, + } = data; + return city; +} diff --git a/demo/src/advanced/generics.ts b/demo/src/advanced/generics.ts new file mode 100644 index 0000000..46f93fb --- /dev/null +++ b/demo/src/advanced/generics.ts @@ -0,0 +1,71 @@ +/** + * Generic function and class examples for CODE_REF demonstration + */ + +/** + * Generic function that returns the first element of an array + * @param items - Array of items + * @returns The first element or undefined + */ +export function getFirst(items: T[]): T | undefined { + return items[0]; +} + +/** + * Generic function with multiple type parameters + * @param key - The key + * @param value - The value + * @returns An object with the key-value pair + */ +export function createPair(key: K, value: V): { key: K; value: V } { + return { key, value }; +} + +/** + * Generic class representing a stack data structure + */ +export class Stack { + private items: T[] = []; + + /** + * Pushes an item onto the stack + * @param item - The item to push + */ + push(item: T): void { + this.items.push(item); + } + + /** + * Pops an item from the stack + * @returns The popped item or undefined + */ + pop(): T | undefined { + return this.items.pop(); + } + + /** + * Peeks at the top item without removing it + * @returns The top item or undefined + */ + peek(): T | undefined { + return this.items[this.items.length - 1]; + } + + /** + * Gets the size of the stack + * @returns The number of items + */ + size(): number { + return this.items.length; + } +} + +/** + * Generic interface for a repository + */ +export interface Repository { + findById(id: string): Promise; + findAll(): Promise; + save(item: T): Promise; + delete(id: string): Promise; +} diff --git a/demo/src/basic/classes.ts b/demo/src/basic/classes.ts new file mode 100644 index 0000000..5c7f886 --- /dev/null +++ b/demo/src/basic/classes.ts @@ -0,0 +1,92 @@ +/** + * Class examples for CODE_REF demonstration + */ + +/** + * Represents a user in the system + */ +export class User { + private name: string; + private email: string; + private age: number; + + /** + * Creates a new User instance + * @param name - User's full name + * @param email - User's email address + * @param age - User's age + */ + constructor(name: string, email: string, age: number) { + this.name = name; + this.email = email; + this.age = age; + } + + /** + * Gets the user's name + * @returns The user's name + */ + getName(): string { + return this.name; + } + + /** + * Gets the user's email + * @returns The user's email address + */ + getEmail(): string { + return this.email; + } + + /** + * Gets the user's age + * @returns The user's age + */ + getAge(): number { + return this.age; + } + + /** + * Updates the user's email + * @param newEmail - The new email address + */ + updateEmail(newEmail: string): void { + this.email = newEmail; + } + + /** + * Checks if user is an adult + * @returns True if user is 18 or older + */ + private isAdult(): boolean { + return this.age >= 18; + } + + /** + * Creates a default guest user + * @returns A new User instance for guests + */ + static createGuest(): User { + return new User('Guest', 'guest@example.com', 0); + } +} + +/** + * Represents a product in an e-commerce system + */ +export class Product { + constructor( + public id: string, + public name: string, + public price: number + ) {} + + /** + * Applies a discount to the product + * @param percentage - Discount percentage (0-100) + * @returns The discounted price + */ + applyDiscount(percentage: number): number { + return this.price * (1 - percentage / 100); + } +} diff --git a/demo/src/basic/functions.ts b/demo/src/basic/functions.ts new file mode 100644 index 0000000..8e4118b --- /dev/null +++ b/demo/src/basic/functions.ts @@ -0,0 +1,43 @@ +/** + * Basic function examples for CODE_REF demonstration + */ + +/** + * Greets a person by name + * @param name - The name of the person to greet + * @returns A greeting message + */ +export function greet(name: string): string { + return `Hello, ${name}!`; +} + +/** + * Adds two numbers together + * @param a - First number + * @param b - Second number + * @returns The sum of a and b + */ +export function add(a: number, b: number): number { + return a + b; +} + +/** + * Arrow function example + */ +export const multiply = (a: number, b: number): number => { + return a * b; +}; + +/** + * Function with multiple parameters + */ +export function formatUserInfo(firstName: string, lastName: string, age: number): string { + return `${firstName} ${lastName} (${age} years old)`; +} + +/** + * Default export function + */ +export default function welcome(): string { + return 'Welcome to the demo!'; +} diff --git a/demo/src/basic/variables.ts b/demo/src/basic/variables.ts new file mode 100644 index 0000000..bba82e5 --- /dev/null +++ b/demo/src/basic/variables.ts @@ -0,0 +1,41 @@ +/** + * Variable and constant examples for CODE_REF demonstration + */ + +/** + * API configuration constants + */ +export const API_KEY = 'demo-api-key-12345'; +export const API_ENDPOINT = 'https://api.example.com'; +export const API_VERSION = 'v1'; + +/** + * Application configuration object + */ +export const config = { + appName: 'Demo App', + version: '1.0.0', + debug: true, +}; + +/** + * Array destructuring example + */ +export const [primaryColor, secondaryColor] = ['blue', 'green']; + +/** + * Object destructuring example + */ +export const { appName, version } = config; + +/** + * Multiple const declarations + */ +export const MAX_RETRIES = 3; +export const TIMEOUT_MS = 5000; +export const DEFAULT_LOCALE = 'en-US'; + +/** + * Computed constant + */ +export const CACHE_DURATION = 60 * 60 * 1000; // 1 hour in milliseconds diff --git a/demo/src/edge-cases/multiple-symbols.ts b/demo/src/edge-cases/multiple-symbols.ts new file mode 100644 index 0000000..75bdb7e --- /dev/null +++ b/demo/src/edge-cases/multiple-symbols.ts @@ -0,0 +1,53 @@ +/** + * Multiple symbols with same name examples for CODE_REF demonstration + * This file demonstrates scenarios where line hints may be needed + */ + +/** + * First class with a process method + */ +export class DataProcessor { + /** + * Process data + * @param data - Data to process + * @returns Processed result + */ + process(data: string): string { + return data.toUpperCase(); + } + + /** + * Validate data + */ + validate(data: string): boolean { + return data.length > 0; + } +} + +/** + * Second class with a process method (same name, different implementation) + */ +export class ImageProcessor { + /** + * Process image + * @param data - Image data to process + * @returns Processed image data + */ + process(data: string): string { + return data.toLowerCase(); + } + + /** + * Validate image data + */ + validate(data: string): boolean { + return data.startsWith('data:image'); + } +} + +/** + * Utility function for processing + */ +export function processUtility(input: string): string { + return input.trim(); +} diff --git a/demo/src/edge-cases/overloads.ts b/demo/src/edge-cases/overloads.ts new file mode 100644 index 0000000..faae5de --- /dev/null +++ b/demo/src/edge-cases/overloads.ts @@ -0,0 +1,47 @@ +/** + * Function overload examples for CODE_REF demonstration + */ + +/** + * Parse value to number or string + * Overload signature for number input + */ +export function parse(input: number): string; + +/** + * Overload signature for string input + */ +export function parse(input: string): number; + +/** + * Implementation signature (handles both cases) + */ +export function parse(input: number | string): number | string { + if (typeof input === 'number') { + return input.toString(); + } else { + return parseInt(input, 10); + } +} + +/** + * Format function with overloads + * Overload for formatting dates + */ +export function format(value: Date): string; + +/** + * Overload for formatting numbers + */ +export function format(value: number, decimals: number): string; + +/** + * Implementation signature + */ +export function format(value: Date | number, decimals?: number): string { + if (value instanceof Date) { + return value.toISOString(); + } else { + return value.toFixed(decimals ?? 2); + } +} diff --git a/package.json b/package.json index f298111..8b13f65 100644 --- a/package.json +++ b/package.json @@ -46,6 +46,12 @@ "format:check": "prettier --check \"src/**/*.ts\" \"*.{js,json,md}\"", "type-check": "tsc --noEmit", "docs:validate": "tsx scripts/validate-docs.ts", + "demo:validate": "npm run build && cd demo && npx docs-coderef validate docs", + "demo:validate:valid": "npm run build && cd demo && npx docs-coderef validate docs/valid", + "demo:validate:invalid": "npm run build && cd demo && npx docs-coderef validate docs/invalid", + "demo:fix": "npm run build && cd demo && npx docs-coderef fix", + "demo:fix:dry": "npm run build && cd demo && npx docs-coderef fix --dry-run", + "demo:fix:auto": "npm run build && cd demo && npx docs-coderef fix --auto", "prepublishOnly": "npm run build && npm test" }, "engines": { From 2caab535a936d118efff7bedfadbd4a5b8d85c19 Mon Sep 17 00:00:00 2001 From: "m.osumi" Date: Thu, 1 Jan 2026 22:00:20 +0900 Subject: [PATCH 2/4] fix: update demo valid docs to pass all validations MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Changes: - class-methods.md: Convert class symbol refs to line-based refs (class symbol search not yet supported) - variables.md: Add JSDoc comments to match tool extraction - line-based.md: Update line numbers for Prettier-formatted code Now `npm run demo:validate:valid` passes all validations ✅ 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 --- demo/docs/valid/class-methods.md | 6 +++--- demo/docs/valid/line-based.md | 8 ++++---- demo/docs/valid/variables.md | 15 +++++++++++++++ 3 files changed, 22 insertions(+), 7 deletions(-) diff --git a/demo/docs/valid/class-methods.md b/demo/docs/valid/class-methods.md index 86f0878..870b880 100644 --- a/demo/docs/valid/class-methods.md +++ b/demo/docs/valid/class-methods.md @@ -6,7 +6,7 @@ This document demonstrates valid class and method CODE_REF patterns. The complete `User` class: - + ```typescript /** @@ -131,7 +131,7 @@ static createGuest(): User { A simpler class with public properties: - + ```typescript /** @@ -159,7 +159,7 @@ export class Product { The generic `Stack` class: - + ```typescript /** diff --git a/demo/docs/valid/line-based.md b/demo/docs/valid/line-based.md index 9e3231b..94bcfc3 100644 --- a/demo/docs/valid/line-based.md +++ b/demo/docs/valid/line-based.md @@ -52,11 +52,11 @@ export const multiply = (a: number, b: number): number => { }; ``` -## Multi-Parameter Function (Lines 31-40) +## Multi-Parameter Function (Lines 31-36) A function with multiple parameters: - + ```typescript /** @@ -71,11 +71,11 @@ export function formatUserInfo( } ``` -## Default Export (Lines 42-47) +## Default Export (Lines 38-43) Default export function: - + ```typescript /** diff --git a/demo/docs/valid/variables.md b/demo/docs/valid/variables.md index 32180ae..846ba21 100644 --- a/demo/docs/valid/variables.md +++ b/demo/docs/valid/variables.md @@ -9,6 +9,9 @@ The `API_KEY` constant: ```typescript +/** + * API configuration constants + */ export const API_KEY = 'demo-api-key-12345'; ``` @@ -46,6 +49,9 @@ Destructured array constants: ```typescript +/** + * Array destructuring example + */ export const [primaryColor, secondaryColor] = ['blue', 'green']; ``` @@ -56,6 +62,9 @@ Destructured object properties: ```typescript +/** + * Object destructuring example + */ export const { appName, version } = config; ``` @@ -66,6 +75,9 @@ The `MAX_RETRIES` constant: ```typescript +/** + * Multiple const declarations + */ export const MAX_RETRIES = 3; ``` @@ -84,5 +96,8 @@ The `CACHE_DURATION` computed constant: ```typescript +/** + * Computed constant + */ export const CACHE_DURATION = 60 * 60 * 1000; // 1 hour in milliseconds ``` From 3bceb6e00b72421c193495f506a6a1428123978a Mon Sep 17 00:00:00 2001 From: "m.osumi" Date: Thu, 1 Jan 2026 22:11:07 +0900 Subject: [PATCH 3/4] feat: add demo:reset npm script for quick demo restoration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add npm script to reset demo documentation to original state: - Restores demo/docs/ from git - Removes any backup files created by fix command Usage: npm run demo:reset This is more convenient than running the shell script directly. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 --- package.json | 1 + 1 file changed, 1 insertion(+) diff --git a/package.json b/package.json index 8b13f65..9ac3c1e 100644 --- a/package.json +++ b/package.json @@ -52,6 +52,7 @@ "demo:fix": "npm run build && cd demo && npx docs-coderef fix", "demo:fix:dry": "npm run build && cd demo && npx docs-coderef fix --dry-run", "demo:fix:auto": "npm run build && cd demo && npx docs-coderef fix --auto", + "demo:reset": "git checkout demo/docs/ && rm -f demo/docs/**/*.backup 2>/dev/null || true", "prepublishOnly": "npm run build && npm test" }, "engines": { From 473c97b2ee4c7b23c82c6bcae7fbf5cc4ebc1c99 Mon Sep 17 00:00:00 2001 From: "m.osumi" Date: Thu, 1 Jan 2026 22:15:23 +0900 Subject: [PATCH 4/4] docs: add demo environment documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update user-facing documentation to include the new demo environment: - README.md: Add Demo Environment section with quick start - CLAUDE.md: Add demo commands to Quick Reference - docs/development/getting-started.md: Add Demo Environment section This helps users discover and use the demo environment for testing docs-coderef functionality locally. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 --- CLAUDE.md | 14 ++++++++++++++ README.md | 27 +++++++++++++++++++++++++++ docs/development/getting-started.md | 21 +++++++++++++++++++++ 3 files changed, 62 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 5f1face..33ed744 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -35,8 +35,22 @@ npm run lint:fix # Auto-fix linting issues npm run format # Format code with Prettier npm run type-check # Run TypeScript compiler checks npm run docs:validate # Validate documentation updates +npm run demo:validate # Test with demo environment ``` +### Demo Environment + +The `demo/` directory provides a local testing environment: + +```bash +npm run demo:validate:valid # Validate correct CODE_REF usage +npm run demo:validate:invalid # See error detection examples +npm run demo:fix:dry # Preview auto-fix changes +npm run demo:reset # Reset demo to original state +``` + +See [demo/README.md](demo/README.md) for detailed usage. + ### Commit Message Format Follow [Conventional Commits](https://www.conventionalcommits.org/): diff --git a/README.md b/README.md index 6e548e9..6902ca3 100644 --- a/README.md +++ b/README.md @@ -159,6 +159,33 @@ This references lines 15-35 of the file. If the code changes, `coderef` will det For more examples and usage patterns, see [docs/user-guide/](docs/user-guide/). +## Demo Environment + +Try out `docs-coderef` with the included demo environment: + +```bash +# Clone the repository +git clone https://github.com/cawpea/docs-coderef.git +cd docs-coderef + +# Install dependencies and build +npm install +npm run build + +# Try the demo +npm run demo:validate:valid # See valid CODE_REF examples +npm run demo:validate:invalid # See error detection +npm run demo:fix:dry # Preview auto-fix +``` + +The `demo/` directory includes: + +- Sample TypeScript files with various code patterns +- Documentation with valid and invalid CODE_REF examples +- Scripts for testing validation and fixing + +See [demo/README.md](demo/README.md) for detailed instructions. + ## Configuration Create `.docs-coderefrc.json` in your project root: diff --git a/docs/development/getting-started.md b/docs/development/getting-started.md index 7900037..3faa8ad 100644 --- a/docs/development/getting-started.md +++ b/docs/development/getting-started.md @@ -29,6 +29,27 @@ npx jest src/utils/foo.test.ts # Run specific test file npx jest -t "" # Run tests matching pattern ``` +## Demo Environment + +The project includes a comprehensive demo environment for testing CODE_REF functionality: + +```bash +npm run demo:validate # Validate all demo documentation +npm run demo:validate:valid # Validate only valid examples (should pass) +npm run demo:validate:invalid # Validate invalid examples (shows errors) +npm run demo:fix:dry # Preview fixes without applying +npm run demo:fix # Interactive fix mode +npm run demo:reset # Reset demo to original state +``` + +The demo environment is located in the `demo/` directory and includes: + +- Sample TypeScript files with various code patterns +- Documentation examples (valid, invalid, and mixed) +- Shell scripts for testing + +See `demo/README.md` for detailed usage instructions. + ## Documentation Validation When making changes to user-facing code (CLI, public APIs, etc.), validate that documentation is updated: