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 ### Added
- Initial monorepo setup with pnpm workspaces - 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 - 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 - LINTING.md documentation for code style guidelines
- CLAUDE.md for AI assistant guidance - CLAUDE.md for AI assistant guidance
- EditorConfig for consistent IDE settings - EditorConfig for consistent IDE settings
- Node.js version specification (.nvmrc: 22.18.0) - Node.js version specification (.nvmrc: 22.18.0)
- Vitest testing framework with 80% coverage thresholds - 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 ### Configuration
- TypeScript: nodenext modules, ES2023 target, strict null checks - TypeScript: nodenext modules, ES2023 target, strict null checks
- ESLint: Strict type checking, complexity limits, code quality rules - 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 - 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 ### Added
- Initial project structure - Initial project structure

61
CLAUDE.md
View File

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
## Project Overview ## 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 ## Essential Commands
@@ -18,10 +18,10 @@ pnpm build:all
pnpm clean:all pnpm clean:all
# Build specific package # Build specific package
cd packages/core && pnpm build cd packages/guardian && pnpm build
# Watch mode for specific package # Watch mode for specific package
cd packages/core && pnpm watch cd packages/guardian && pnpm watch
``` ```
### Testing ### Testing
@@ -30,8 +30,8 @@ cd packages/core && pnpm watch
# Run all tests across packages # Run all tests across packages
pnpm test pnpm test
# Core package testing options # Guardian package testing options
cd packages/core cd packages/guardian
pnpm test # Run tests in watch mode pnpm test # Run tests in watch mode
pnpm test:run # Run tests once pnpm test:run # Run tests once
pnpm test:coverage # Generate coverage report (80% threshold) pnpm test:coverage # Generate coverage report (80% threshold)
@@ -61,8 +61,8 @@ pnpm eslint "packages/**/*.ts"
### Key Configuration ### Key Configuration
- **Indentation:** 4 spaces (enforced by Prettier) - **Indentation:** 4 spaces (enforced by Prettier)
- **Line Length:** 100 characters max - **Line Length:** 100 characters max
- **Quotes:** Single quotes - **Quotes:** Double quotes
- **Semicolons:** Always required - **Semicolons:** Never used
- **Trailing Commas:** Always in multiline - **Trailing Commas:** Always in multiline
- **TypeScript:** Strict type checking with nodenext modules - **TypeScript:** Strict type checking with nodenext modules
@@ -110,14 +110,36 @@ Commits should only follow the Conventional Commits format without any additiona
``` ```
puaros/ puaros/
├── packages/ ├── packages/
│ └── core/ # @puaros/core - Core business logic │ └── guardian/ # @puaros/guardian - Code quality analyzer
│ ├── src/ # Source files │ ├── 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 │ ├── dist/ # Build output
│ ├── bin/ # CLI entry point
│ ├── tests/ # Test files
│ ├── examples/ # Usage examples
│ └── package.json # Uses Vitest for testing │ └── package.json # Uses Vitest for testing
├── pnpm-workspace.yaml # Workspace configuration ├── pnpm-workspace.yaml # Workspace configuration
└── tsconfig.base.json # Shared TypeScript config └── 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 ### TypeScript Configuration
Base configuration (`tsconfig.base.json`) uses: Base configuration (`tsconfig.base.json`) uses:
@@ -127,12 +149,14 @@ Base configuration (`tsconfig.base.json`) uses:
- Decorators enabled (experimental) - Decorators enabled (experimental)
- JSX configured for React - JSX configured for React
Core package (`packages/core/tsconfig.json`) overrides: Guardian package (`packages/guardian/tsconfig.json`):
- Module: `CommonJS` (not nodenext) - Module: `CommonJS`
- Module Resolution: `node` (not nodenext) - Module Resolution: `node`
- Target: `ES2023`
- Output to `dist/` from `src/` - 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 ## Adding New Packages
@@ -143,15 +167,20 @@ Core package (`packages/core/tsconfig.json`) overrides:
## Dependencies ## Dependencies
Core package uses: Guardian package uses:
- `commander` - CLI framework for command-line interface
- `simple-git` - Git operations - `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 - `uuid` - UUID generation
Development tools: Development tools:
- Vitest for testing (replaces Jest) - Vitest for testing with coverage thresholds
- ESLint with TypeScript strict rules - ESLint with TypeScript strict rules
- Prettier for formatting - Prettier for formatting
- `@vitest/ui` - Vitest UI for interactive testing
- `@vitest/coverage-v8` - Coverage reporting
## Important Notes ## Important Notes

105
README.md
View File

@@ -1,6 +1,10 @@
# Puaros # 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 ## Prerequisites
@@ -35,14 +39,20 @@ pnpm dev:cli
# Run all tests across packages # Run all tests across packages
pnpm test pnpm test
# Guardian package testing
cd packages/guardian
# Run tests with coverage (80% threshold required) # Run tests with coverage (80% threshold required)
cd packages/core && pnpm test:coverage pnpm test:coverage
# Run tests with UI # Run tests with UI
cd packages/core && pnpm test:ui pnpm test:ui
# Run tests once (no watch mode) # 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). The project uses Vitest for testing with coverage thresholds set to 80% for all metrics (lines, functions, branches, statements).
@@ -65,9 +75,17 @@ pnpm eslint "packages/**/*.ts"
``` ```
puaros/ puaros/
├── packages/ ├── packages/
│ └── core/ # @puaros/core - Core business logic │ └── guardian/ # @puaros/guardian - Code quality analyzer
│ ├── src/ # Source files │ ├── src/ # Source files (Clean Architecture)
│ │ ├── domain/ # Domain layer
│ │ ├── application/ # Application layer
│ │ ├── infrastructure/# Infrastructure layer
│ │ ├── cli/ # CLI implementation
│ │ └── shared/ # Shared utilities
│ ├── dist/ # Build output (generated) │ ├── dist/ # Build output (generated)
│ ├── bin/ # CLI entry point
│ ├── tests/ # Unit and integration tests
│ ├── examples/ # Usage examples
│ └── package.json │ └── package.json
├── pnpm-workspace.yaml # Workspace configuration ├── pnpm-workspace.yaml # Workspace configuration
├── tsconfig.base.json # Shared TypeScript config ├── tsconfig.base.json # Shared TypeScript config
@@ -75,7 +93,7 @@ puaros/
├── .prettierrc # Prettier configuration ├── .prettierrc # Prettier configuration
├── LINTING.md # Code style guidelines ├── LINTING.md # Code style guidelines
├── CLAUDE.md # AI assistant guidance ├── CLAUDE.md # AI assistant guidance
└── CHANGELOG.md # Project changelog └── README.md # This file
``` ```
## Code Style ## Code Style
@@ -84,8 +102,9 @@ This project follows strict TypeScript and code quality standards:
- **Indentation:** 4 spaces (enforced by Prettier) - **Indentation:** 4 spaces (enforced by Prettier)
- **Line Length:** 100 characters maximum - **Line Length:** 100 characters maximum
- **Quotes:** Single quotes - **Quotes:** Double quotes
- **Semicolons:** Always required - **Semicolons:** Never used
- **Trailing Commas:** Always in multiline
- **TypeScript:** Strict type checking enabled - **TypeScript:** Strict type checking enabled
### Key Rules ### Key Rules
@@ -115,19 +134,79 @@ This project uses pnpm workspaces for managing multiple packages:
3. Create `tsconfig.json` extending `../../tsconfig.base.json` 3. Create `tsconfig.json` extending `../../tsconfig.base.json`
4. The package will be auto-discovered via workspace configuration 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 ## Dependencies
Core package uses: Guardian package uses:
- `commander` - CLI framework
- `simple-git` - Git operations - `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 - `uuid` - UUID generation
Development tools: 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 - ESLint + TypeScript ESLint - Strict type checking and linting
- Prettier - Code formatting - Prettier - Code formatting (4-space indentation)
## Contributing ## Contributing