ailabs/puaros
1
0
Fork 0
mirror of https://github.com/samiyev/puaros.git synced 2025-12-27 23:06:54 +05:00
Code Issues Packages Projects Releases Wiki Activity

docs: update project documentation for guardian

Browse Source 
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).
This commit is contained in:
imfozilbek
2025-11-24 02:55:20 +05:00
parent 1d22a7d070
commit a4a4b36a8a
3 changed files with 163 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
CHANGELOG.md
View File

@@ -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

69
CLAUDE.md
View File

@@ -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

119
README.md
View File

@@ -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 <project-path>
# 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