|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +Hyperdash Angular (`@hypertrace/hyperdash-angular`) is an Angular library providing dashboard runtime capabilities. It wraps the core `@hypertrace/hyperdash` library with Angular services, components, and directives. |
| 8 | + |
| 9 | +**Structure**: Monorepo with a publishable library (`projects/hyperdash-angular/`) and demo app (`src/`). |
| 10 | + |
| 11 | +## Common Commands |
| 12 | + |
| 13 | +```bash |
| 14 | +# Development |
| 15 | +npm start # Dev server at localhost:4200 |
| 16 | +npm run build # Build app and library |
| 17 | + |
| 18 | +# Testing |
| 19 | +npm test # Run tests (watch mode) |
| 20 | +npm run test:ci:lib # Library tests only (CI mode) |
| 21 | +npm run test:ci:app # App tests only (CI mode) |
| 22 | +npm run test:ci # Full CI suite (lint + all tests) |
| 23 | + |
| 24 | +# Code Quality |
| 25 | +npm run lint # Run ESLint |
| 26 | +npm run commit # Interactive conventional commit (commitizen) |
| 27 | +``` |
| 28 | + |
| 29 | +## Architecture |
| 30 | + |
| 31 | +### Injectable Wrappers Pattern |
| 32 | + |
| 33 | +Core `@hypertrace/hyperdash` classes are wrapped as Angular injectable services following the pattern `[ClassName]Service`: |
| 34 | + |
| 35 | +- `DashboardManagerService`, `ModelManagerService`, `ThemeManagerService`, etc. |
| 36 | +- Always use the service wrapper (e.g., `DashboardManagerService`) rather than the core class directly. |
| 37 | + |
| 38 | +### Module System |
| 39 | + |
| 40 | +- `DashboardCoreModule`: Main runtime module with default property types and deserializers |
| 41 | +- `DashboardCoreModule.with(metadata)`: Extend with custom types, models, renderers, editors, deserializers |
| 42 | +- `DashboardEditorModule`: Separate module for editing capabilities |
| 43 | + |
| 44 | +### Key Injection Tokens |
| 45 | + |
| 46 | +- `MODEL_PROPERTY_TYPES`: Register custom property types |
| 47 | +- `DASHBOARD_DESERIALIZERS`: Register custom deserializers |
| 48 | + |
| 49 | +### Rendering |
| 50 | + |
| 51 | +- `DashboardComponent` (`<hda-dashboard>`): Main rendering component |
| 52 | +- `DashboardModelDirective` (`hdaDashboardModel`): Injects models into template context |
| 53 | +- `ThemePropertyPipe`: Theme-aware property rendering |
| 54 | + |
| 55 | +## Code Conventions |
| 56 | + |
| 57 | +### Selectors |
| 58 | + |
| 59 | +- **Library components**: `hda-*` prefix (kebab-case) |
| 60 | +- **Library directives**: `hda*` prefix (camelCase) |
| 61 | +- **App components**: `app-*` prefix |
| 62 | + |
| 63 | +### TypeScript |
| 64 | + |
| 65 | +- Strict mode enabled with `noUnusedLocals`, `noUnusedParameters`, `strictNullChecks` |
| 66 | +- Explicit access modifiers required (public/private/protected) |
| 67 | +- No `any` types allowed |
| 68 | +- Parameter properties preferred: `constructor(private readonly service: Service)` |
| 69 | + |
| 70 | +### Testing |
| 71 | + |
| 72 | +- Jest with `@ngneat/spectator` for component testing |
| 73 | +- Test files: `*.test.ts` or `*.spec.ts` |
| 74 | +- Coverage excludes: `*.module.ts`, `public_api.ts`, `test/` directory |
| 75 | + |
| 76 | +### Commits |
| 77 | + |
| 78 | +- Conventional commits required (enforced via commitlint) |
| 79 | +- Use `npm run commit` for interactive commit wizard |
| 80 | +- Pre-commit hook runs Prettier on staged files |
| 81 | + |
| 82 | +## ESLint Rules of Note |
| 83 | + |
| 84 | +- Max 500 lines per file |
| 85 | +- Template conditional complexity: max 4 |
| 86 | +- Template cyclomatic complexity: max 5 |
| 87 | +- No inline templates > 10 lines |
| 88 | +- Arrow functions: `as-needed` body style |
| 89 | +- Prefer template literals over string concatenation |
0 commit comments