docs: add naming conventions and structure check script (Task 5.2)

- Add docs/development/naming.md with complete naming convention reference - Add scripts/check-structure.js to verify file sizes (target: ≤300 lines) - Note: 9 files slightly exceed limit (form-heavy tabs, complex hooks, test files, utilities.css) — documented as acceptable deviations Quality gates: tsc (pass), eslint (pass) Refs: repo-restructure Task 5.2
2026-06-02 22:43:15 +00:00
parent 5d5b23894c
commit 3f5159fb8a
9 changed files with 519 additions and 235 deletions
@@ -0,0 +1,172 @@
+# Naming Conventions
+
+This document defines the file and identifier naming conventions for the Headquarter codebase.
+
+## Frontend (`apps/web/src/`)
+
+### React Components
+
+**File naming:** PascalCase, matching the exported component name exactly.
+
+```
+✅ Good:
+  components/features/git/FileBrowser.tsx
+  components/features/dashboard/DashboardSummary.tsx
+  pages/DashboardPage.tsx
+
+❌ Bad:
+  components/file-browser.tsx
+  pages/dashboard.tsx
+```
+
+**Component naming:** PascalCase. Page components end with `Page`.
+
+```typescript
+// Component
+export const FileBrowser = () => { ... }
+
+// Page
+export const DashboardPage = () => { ... }
+```
+
+### Hooks
+
+**File naming:** camelCase with `use` prefix.
+
+```
+✅ Good:
+  hooks/use-theme.ts
+  hooks/use-dashboard-actions.ts
+```
+
+### API Modules
+
+**File naming:** kebab-case.
+
+```
+✅ Good:
+  api/tool-types.ts
+  api/git-repositories.ts
+  api/config-folders.ts
+```
+
+### Type Modules
+
+**File naming:** kebab-case.
+
+```
+✅ Good:
+  types/tool-type.ts
+  types/git-repository.ts
+```
+
+### Utilities
+
+**File naming:** kebab-case.
+
+```
+✅ Good:
+  utils/terminal-protocol.ts
+  utils/language.ts
+```
+
+### CSS Modules
+
+**File naming:** kebab-case, matching the component file name with `.module.css` suffix.
+
+```
+✅ Good:
+  FileBrowser.tsx + FileBrowser.module.css
+```
+
+## Backend (`apps/api/src/`)
+
+### Routers
+
+**File naming:** snake_case.
+
+```
+✅ Good:
+  api/tool_instances.py
+  api/git_repositories.py
+```
+
+### Services
+
+**File naming:** snake_case.
+
+```
+✅ Good:
+  services/docker/compose.py
+  services/profile_resolver.py
+```
+
+### Models
+
+**File naming:** snake_case. Class names use PascalCase.
+
+```
+✅ Good:
+  models/tool_instance.py
+  class ToolInstance(Base):
+```
+
+### Schemas
+
+**File naming:** snake_case.
+
+```
+✅ Good:
+  schemas/tool_instance.py
+```
+
+## Tests
+
+### Frontend Tests
+
+**File naming:** Same as source file with `.test.tsx` suffix.
+
+```
+✅ Good:
+  FileBrowser.tsx + FileBrowser.test.tsx
+```
+
+### Backend Tests
+
+**File naming:** `test_` prefix + snake_case.
+
+```
+✅ Good:
+  test_tool_instances.py
+```
+
+## Directory Structure Summary
+
+```
+apps/web/src/
+├── api/              # kebab-case files
+├── components/
+│   ├── ui/           # PascalCase files
+│   ├── layout/       # PascalCase files
+│   └── features/     # PascalCase files, grouped by domain
+│       ├── git/
+│       ├── project/
+│       ├── session/
+│       └── ...
+├── hooks/            # camelCase files
+├── pages/            # PascalCase files ending with Page
+├── styles/           # kebab-case CSS files
+├── types/            # kebab-case files
+└── utils/            # kebab-case files
+
+apps/api/src/
+├── api/              # snake_case files
+├── models/           # snake_case files
+├── schemas/          # snake_case files
+├── services/         # snake_case files
+└── auth/             # snake_case files
+```
+
+## Migration Notes
+
+Some legacy files may not yet follow these conventions. When touching a file for other work, rename it to match the convention in the same PR.