From dbfe038d3450467f86599e53e1313da7ada4acc1 Mon Sep 17 00:00:00 2001 From: imfozilbek Date: Sun, 23 Nov 2025 21:19:55 +0500 Subject: [PATCH] docs: add project documentation Add CLAUDE.md with development guidelines and CHANGELOG.md for tracking changes --- CHANGELOG.md | 32 +++++++++++ CLAUDE.md | 153 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 185 insertions(+) create mode 100644 CHANGELOG.md create mode 100644 CLAUDE.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..a73b8a3 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,32 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +### Added +- Initial monorepo setup with pnpm workspaces +- `@puaros/core` package with TypeScript and Vitest configuration +- ESLint strict TypeScript rules with 4-space indentation +- Prettier code formatting (4 spaces, single quotes) +- LINTING.md documentation for code style guidelines +- CLAUDE.md for AI assistant guidance +- EditorConfig for consistent IDE settings +- Node.js version specification (.nvmrc: 22.18.0) +- Vitest testing framework with 80% coverage thresholds +- Core dependencies: simple-git, tree-sitter (JavaScript/TypeScript), uuid + +### Configuration +- TypeScript: nodenext modules, ES2023 target, strict null checks +- ESLint: Strict type checking, complexity limits, code quality rules +- Prettier: 100 char line length, single quotes, trailing commas +- Test coverage: 80% threshold for lines, functions, branches, statements + +## [0.0.1] - 2025-01-23 + +### Added +- Initial project structure +- Monorepo workspace configuration \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..a4e4149 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,153 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +Puaros is a TypeScript monorepo using pnpm workspaces. Currently contains the `@puaros/core` package for core business logic. The project uses Node.js 22.18.0 (see `.nvmrc`). + +## Essential Commands + +### Build & Development + +```bash +# Build all packages +pnpm build:all + +# Clean all builds +pnpm clean:all + +# Build specific package +cd packages/core && pnpm build + +# Watch mode for specific package +cd packages/core && pnpm watch +``` + +### Testing + +```bash +# Run all tests across packages +pnpm test + +# Core package testing options +cd packages/core +pnpm test # Run tests in watch mode +pnpm test:run # Run tests once +pnpm test:coverage # Generate coverage report (80% threshold) +pnpm test:ui # Open Vitest UI +pnpm test:watch # Explicit watch mode +``` + +Tests use Vitest with coverage thresholds set to 80% for lines, functions, branches, and statements. + +### Linting & Formatting + +```bash +# Format all TypeScript files +pnpm format + +# Lint and auto-fix all TypeScript files +pnpm lint + +# Check linting without fixing +pnpm eslint "packages/**/*.ts" +``` + +## Code Style Requirements + +**Critical: This project uses 4-space indentation, not 2 spaces.** + +### Key Configuration +- **Indentation:** 4 spaces (enforced by Prettier) +- **Line Length:** 100 characters max +- **Quotes:** Single quotes +- **Semicolons:** Always required +- **Trailing Commas:** Always in multiline +- **TypeScript:** Strict type checking with nodenext modules + +### TypeScript Rules to Follow + +From `eslint.config.mjs` and detailed in `LINTING.md`: + +1. **Type Safety (warnings, must address):** + - Avoid `any` type - use proper typing + - Declare explicit function return types + - No floating promises (always await or handle) + - No unsafe type operations + +2. **Code Quality (errors, must fix):** + - Use `const` for non-reassigned variables + - Always use `===` instead of `==` + - Always use curly braces for conditionals/loops + - Handle all promises (no floating promises) + - No `console.log` (use `console.warn`/`console.error` or proper logger) + +3. **Complexity Limits (warnings):** + - Max cyclomatic complexity: 15 + - Max function parameters: 5 + - Max lines per function: 100 + - Max nesting depth: 4 + +## Git Commit Format + +Follow Conventional Commits format. See `.gitmessage` for full rules. + +Format: `: ` (imperative mood, no caps, max 50 chars) + +**IMPORTANT: Do NOT add "Generated with Claude Code" footer or "Co-Authored-By: Claude" to commit messages.** +Commits should only follow the Conventional Commits format without any additional attribution. + +## Monorepo Structure + +``` +puaros/ +├── packages/ +│ └── core/ # @puaros/core - Core business logic +│ ├── src/ # Source files +│ ├── dist/ # Build output +│ └── package.json # Uses Vitest for testing +├── pnpm-workspace.yaml # Workspace configuration +└── tsconfig.base.json # Shared TypeScript config +``` + +### TypeScript Configuration + +Base configuration (`tsconfig.base.json`) uses: +- Module: `nodenext` with `nodenext` resolution +- Target: `ES2023` +- Strict null checks enabled +- Decorators enabled (experimental) +- JSX configured for React + +Core package (`packages/core/tsconfig.json`) overrides: +- Module: `CommonJS` (not nodenext) +- Module Resolution: `node` (not nodenext) +- Output to `dist/` from `src/` + +**Important:** The core package uses CommonJS output despite base config using nodenext. + +## Adding New Packages + +1. Create `packages/new-package/` directory +2. Add `package.json` with name `@puaros/new-package` +3. Create `tsconfig.json` extending `../../tsconfig.base.json` +4. Package auto-discovered via `pnpm-workspace.yaml` glob pattern + +## Dependencies + +Core package uses: +- `simple-git` - Git operations +- `tree-sitter-*` - Code parsing (JavaScript/TypeScript) +- `uuid` - UUID generation + +Development tools: +- Vitest for testing (replaces Jest) +- ESLint with TypeScript strict rules +- Prettier for formatting + +## Important Notes + +- **Always run `pnpm format` before committing** to ensure 4-space indentation +- **Fix ESLint warnings incrementally** - they indicate real type safety issues +- **Coverage is enforced** - maintain 80% coverage for all metrics when running `pnpm test:coverage` \ No newline at end of file