From a4a4b36a8aa306a3253553e6a387a25c2bdcddce Mon Sep 17 00:00:00 2001 From: imfozilbek Date: Mon, 24 Nov 2025 02:55:20 +0500 Subject: [PATCH] docs: update project documentation for guardian Update README, CLAUDE.md, and CHANGELOG for guardian package. Add guardian package documentation and remove core references. Update repository URLs to samiyev/puaros and add official website link (puaros.ailabs.uz). --- CHANGELOG.md | 20 ++++++--- CLAUDE.md | 69 ++++++++++++++++++++--------- README.md | 119 ++++++++++++++++++++++++++++++++++++++++++--------- 3 files changed, 163 insertions(+), 45 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a73b8a3..7e15ab1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,23 +9,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added - Initial monorepo setup with pnpm workspaces -- `@puaros/core` package with TypeScript and Vitest configuration +- `@puaros/guardian` package - code quality guardian for vibe coders and enterprise teams +- TypeScript with strict type checking and Vitest configuration - ESLint strict TypeScript rules with 4-space indentation -- Prettier code formatting (4 spaces, single quotes) +- Prettier code formatting (4 spaces, double quotes, no semicolons) - 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 +- Guardian dependencies: commander, simple-git, tree-sitter, 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 +- Prettier: 100 char line length, double quotes, no semicolons, trailing commas - Test coverage: 80% threshold for lines, functions, branches, statements -## [0.0.1] - 2025-01-23 +### Guardian Package +- Hardcode detection (magic numbers, strings) +- Circular dependency detection +- Naming convention enforcement +- Architecture violation detection +- CLI tool with `guardian` command +- 159 tests, all passing +- Clean Architecture implementation + +## [0.0.1] - 2025-11-24 ### Added - Initial project structure diff --git a/CLAUDE.md b/CLAUDE.md index 475cdfe..47a08ff 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## 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`). +Puaros is a TypeScript monorepo using pnpm workspaces. Currently contains the `@puaros/guardian` package - a code quality guardian for detecting hardcoded values, circular dependencies, and architecture violations. The project uses Node.js 22.18.0 (see `.nvmrc`). ## Essential Commands @@ -18,10 +18,10 @@ pnpm build:all pnpm clean:all # Build specific package -cd packages/core && pnpm build +cd packages/guardian && pnpm build # Watch mode for specific package -cd packages/core && pnpm watch +cd packages/guardian && pnpm watch ``` ### Testing @@ -30,8 +30,8 @@ cd packages/core && pnpm watch # Run all tests across packages pnpm test -# Core package testing options -cd packages/core +# Guardian package testing options +cd packages/guardian pnpm test # Run tests in watch mode pnpm test:run # Run tests once pnpm test:coverage # Generate coverage report (80% threshold) @@ -61,8 +61,8 @@ pnpm eslint "packages/**/*.ts" ### Key Configuration - **Indentation:** 4 spaces (enforced by Prettier) - **Line Length:** 100 characters max -- **Quotes:** Single quotes -- **Semicolons:** Always required +- **Quotes:** Double quotes +- **Semicolons:** Never used - **Trailing Commas:** Always in multiline - **TypeScript:** Strict type checking with nodenext modules @@ -110,14 +110,36 @@ Commits should only follow the Conventional Commits format without any additiona ``` 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 +│ └── guardian/ # @puaros/guardian - Code quality analyzer +│ ├── src/ # Source files (Clean Architecture layers) +│ │ ├── domain/ # Domain layer (entities, value objects) +│ │ ├── application/ # Application layer (use cases, DTOs) +│ │ ├── infrastructure/ # Infrastructure layer (parsers, analyzers) +│ │ ├── cli/ # CLI implementation +│ │ └── shared/ # Shared utilities +│ ├── dist/ # Build output +│ ├── bin/ # CLI entry point +│ ├── tests/ # Test files +│ ├── examples/ # Usage examples +│ └── package.json # Uses Vitest for testing +├── pnpm-workspace.yaml # Workspace configuration +└── tsconfig.base.json # Shared TypeScript config ``` +### Guardian Package Architecture + +The guardian package follows Clean Architecture principles: +- **Domain Layer**: Core business logic (entities, value objects, domain events) +- **Application Layer**: Use cases, DTOs, and mappers +- **Infrastructure Layer**: External concerns (parsers, analyzers, file scanners) +- **CLI Layer**: Command-line interface implementation + +Key features: +- Hardcode detection (magic numbers, strings) +- Circular dependency detection +- Naming convention validation +- CLI tool with `guardian` command + ### TypeScript Configuration Base configuration (`tsconfig.base.json`) uses: @@ -127,12 +149,14 @@ Base configuration (`tsconfig.base.json`) uses: - Decorators enabled (experimental) - JSX configured for React -Core package (`packages/core/tsconfig.json`) overrides: -- Module: `CommonJS` (not nodenext) -- Module Resolution: `node` (not nodenext) +Guardian package (`packages/guardian/tsconfig.json`): +- Module: `CommonJS` +- Module Resolution: `node` +- Target: `ES2023` - Output to `dist/` from `src/` +- Strict type checking enabled -**Important:** The core package uses CommonJS output despite base config using nodenext. +**Important:** The guardian package uses CommonJS output for compatibility. ## Adding New Packages @@ -143,15 +167,20 @@ Core package (`packages/core/tsconfig.json`) overrides: ## Dependencies -Core package uses: +Guardian package uses: +- `commander` - CLI framework for command-line interface - `simple-git` - Git operations -- `tree-sitter-*` - Code parsing (JavaScript/TypeScript) +- `tree-sitter` - Abstract syntax tree parsing +- `tree-sitter-javascript` - JavaScript parser +- `tree-sitter-typescript` - TypeScript parser - `uuid` - UUID generation Development tools: -- Vitest for testing (replaces Jest) +- Vitest for testing with coverage thresholds - ESLint with TypeScript strict rules - Prettier for formatting +- `@vitest/ui` - Vitest UI for interactive testing +- `@vitest/coverage-v8` - Coverage reporting ## Important Notes diff --git a/README.md b/README.md index f8bc4e0..a6de53b 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,10 @@ # Puaros -A TypeScript monorepo for Puaros project. +A TypeScript monorepo for code quality and analysis tools. + +## Packages + +- **[@puaros/guardian](./packages/guardian)** - Code quality guardian for vibe coders and enterprise teams. Detects hardcoded values, circular dependencies, and architecture violations. Perfect for AI-assisted development and enforcing Clean Architecture at scale. ## Prerequisites @@ -35,14 +39,20 @@ pnpm dev:cli # Run all tests across packages pnpm test +# Guardian package testing +cd packages/guardian + # Run tests with coverage (80% threshold required) -cd packages/core && pnpm test:coverage +pnpm test:coverage # Run tests with UI -cd packages/core && pnpm test:ui +pnpm test:ui # Run tests once (no watch mode) -cd packages/core && pnpm test:run +pnpm test:run + +# Run tests in watch mode +pnpm test:watch ``` The project uses Vitest for testing with coverage thresholds set to 80% for all metrics (lines, functions, branches, statements). @@ -65,17 +75,25 @@ pnpm eslint "packages/**/*.ts" ``` puaros/ ├── packages/ -│ └── core/ # @puaros/core - Core business logic -│ ├── src/ # Source files -│ ├── dist/ # Build output (generated) +│ └── guardian/ # @puaros/guardian - Code quality analyzer +│ ├── src/ # Source files (Clean Architecture) +│ │ ├── domain/ # Domain layer +│ │ ├── application/ # Application layer +│ │ ├── infrastructure/# Infrastructure layer +│ │ ├── cli/ # CLI implementation +│ │ └── shared/ # Shared utilities +│ ├── dist/ # Build output (generated) +│ ├── bin/ # CLI entry point +│ ├── tests/ # Unit and integration tests +│ ├── examples/ # Usage examples │ └── package.json -├── pnpm-workspace.yaml # Workspace configuration -├── tsconfig.base.json # Shared TypeScript config -├── eslint.config.mjs # ESLint configuration -├── .prettierrc # Prettier configuration -├── LINTING.md # Code style guidelines -├── CLAUDE.md # AI assistant guidance -└── CHANGELOG.md # Project changelog +├── pnpm-workspace.yaml # Workspace configuration +├── tsconfig.base.json # Shared TypeScript config +├── eslint.config.mjs # ESLint configuration +├── .prettierrc # Prettier configuration +├── LINTING.md # Code style guidelines +├── CLAUDE.md # AI assistant guidance +└── README.md # This file ``` ## Code Style @@ -84,8 +102,9 @@ This project follows strict TypeScript and code quality standards: - **Indentation:** 4 spaces (enforced by Prettier) - **Line Length:** 100 characters maximum -- **Quotes:** Single quotes -- **Semicolons:** Always required +- **Quotes:** Double quotes +- **Semicolons:** Never used +- **Trailing Commas:** Always in multiline - **TypeScript:** Strict type checking enabled ### Key Rules @@ -115,19 +134,79 @@ This project uses pnpm workspaces for managing multiple packages: 3. Create `tsconfig.json` extending `../../tsconfig.base.json` 4. The package will be auto-discovered via workspace configuration +## Guardian Package + +The `@puaros/guardian` package is a code quality analyzer for both individual developers and enterprise teams: + +### Features + +- **Hardcode Detection**: Detects magic numbers and magic strings with context-aware analysis +- **Circular Dependency Detection**: Finds import cycles in your codebase +- **Naming Convention Validation**: Enforces layer-based naming rules (Domain, Application, Infrastructure) +- **Architecture Governance**: Enforces Clean Architecture boundaries across teams +- **CLI Tool**: Command-line interface with `guardian` command +- **CI/CD Integration**: JSON/Markdown output for automation pipelines + +### Use Cases + +**For Vibe Coders:** +- ⚡ AI writes code → Guardian reviews → AI fixes → Ship +- 🎯 Catch hardcoded secrets before production +- 📚 Learn Clean Architecture patterns as you code + +**For Enterprise Teams:** +- 🏢 Enforce architectural standards across 100+ developers +- 🔒 Prevent security incidents (hardcoded credentials) +- 📊 Track technical debt metrics over time +- 👥 Faster onboarding with automated feedback +- 🤖 Safe AI adoption with quality gates + +### Architecture + +Built with Clean Architecture principles: +- **Domain Layer**: Core business logic (entities, value objects, domain services) +- **Application Layer**: Use cases, DTOs, and mappers +- **Infrastructure Layer**: External concerns (parsers, analyzers, file scanners) +- **CLI Layer**: Command-line interface + +### Usage + +```bash +# Install dependencies +cd packages/guardian && pnpm install + +# Build the package +pnpm build + +# Run tests +pnpm test + +# Use the CLI (after building) +node bin/guardian.js analyze + +# CI/CD integration +guardian check ./src --format json > report.json +guardian check ./src --fail-on hardcode --fail-on circular +``` + ## Dependencies -Core package uses: +Guardian package uses: +- `commander` - CLI framework - `simple-git` - Git operations -- `tree-sitter`, `tree-sitter-javascript`, `tree-sitter-typescript` - Code parsing +- `tree-sitter` - Abstract syntax tree parsing +- `tree-sitter-javascript` - JavaScript parser +- `tree-sitter-typescript` - TypeScript parser - `uuid` - UUID generation Development tools: -- Vitest - Testing framework +- Vitest - Testing framework with 80% coverage thresholds +- `@vitest/ui` - Interactive testing UI +- `@vitest/coverage-v8` - Coverage reporting - ESLint + TypeScript ESLint - Strict type checking and linting -- Prettier - Code formatting +- Prettier - Code formatting (4-space indentation) ## Contributing