|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Commands |
| 6 | + |
| 7 | +### Development |
| 8 | +- `pnpm test` - Run tests using Vitest |
| 9 | +- `pnpm run build` - Build the TypeScript project |
| 10 | +- `pnpm run clean` - Clean build artifacts |
| 11 | +- `pnpm run eslint` - Run ESLint linting |
| 12 | +- `pnpm run eslint:fix` - Run ESLint with auto-fix |
| 13 | + |
| 14 | +### Package Management |
| 15 | +- Uses pnpm as package manager (required, enforced by preinstall hook) |
| 16 | +- `pnpm install` - Install dependencies |
| 17 | + |
| 18 | +## Architecture |
| 19 | + |
| 20 | +This is a TypeScript implementation of PHPDoc parser inspired by PHPStan's phpdoc-parser, focusing on parsing PHPDoc comments into an Abstract Syntax Tree (AST). |
| 21 | + |
| 22 | +### Core Components |
| 23 | + |
| 24 | +**Lexical Analysis (`src/phpdoc-parser/lexer/`)** |
| 25 | +- `lexer.ts` - Tokenizes PHPDoc strings using regex patterns |
| 26 | +- Handles 20+ token types (identifiers, types, operators, brackets, etc.) |
| 27 | + |
| 28 | +**Parsing (`src/phpdoc-parser/parser/`)** |
| 29 | +- `php-doc-parser.ts` - Main parser that converts tokens to AST nodes |
| 30 | +- `type-parser.ts` - Handles type parsing (generics, unions, intersections) |
| 31 | +- `const-expr-parser.ts` - Parses constant expressions |
| 32 | +- `token-iterator.ts` - Token stream management with savepoint/rollback |
| 33 | +- `string-unescaper.ts` - String literal processing |
| 34 | + |
| 35 | +**AST Nodes (`src/phpdoc-parser/ast/`)** |
| 36 | +- Base interfaces: `node.ts`, `base-node.ts` |
| 37 | +- **php-doc/**: PHPDoc-specific nodes (tags, text, parameters, etc.) |
| 38 | +- **type/**: Type system nodes (unions, intersections, generics, arrays) |
| 39 | +- **const-expr/**: Constant expression nodes (strings, numbers, arrays) |
| 40 | + |
| 41 | +**Printing (`src/phpdoc-parser/printer/`)** |
| 42 | +- `printer.ts` - Converts AST back to formatted PHPDoc |
| 43 | +- `differ.ts` - Format-preserving printing with diff tracking |
| 44 | +- Supports both clean formatting and original format preservation |
| 45 | + |
| 46 | +**Transpilation (`src/phpdoc-parser/transpiler/`)** |
| 47 | +- `php-doc-to-typescript-type-transpiler.ts` - Converts PHPDoc types to TypeScript |
| 48 | + |
| 49 | +### Key Patterns |
| 50 | + |
| 51 | +- **Three-phase processing**: Lexing → Parsing → AST manipulation |
| 52 | +- **Visitor pattern**: `node-traverser.ts` and `cloning-visitor.ts` for AST transformation |
| 53 | +- **Attribute system**: Nodes can store metadata (line numbers, indexes) for format preservation |
| 54 | +- **Error handling**: Invalid syntax produces `InvalidTagValueNode` or `InvalidTypeNode` rather than throwing |
| 55 | +- **Format preservation**: Printer can maintain original formatting using token metadata |
| 56 | + |
| 57 | +### Supported PHPDoc Features |
| 58 | + |
| 59 | +- Standard tags: `@param`, `@return`, `@var`, `@throws`, `@deprecated`, etc. |
| 60 | +- Advanced types: Generics, union/intersection types, conditional types, array shapes |
| 61 | +- Template types and type aliases |
| 62 | +- PHPStan/Psalm extensions |
| 63 | +- Assertion tags for static analysis |
| 64 | + |
| 65 | +## Project Structure |
| 66 | + |
| 67 | +- `src/index.ts` - Main entry point exporting all public APIs |
| 68 | +- `tests/` - Test files organized by component (lexer, parser, printer, transpiler) |
| 69 | +- TypeScript build configuration in `tsconfig.build.json` |
0 commit comments