puaros/README.md

# Puaros

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

- Node.js 22.18.0 (use `nvm use` to automatically switch to the correct version)
- pnpm (package manager)

## Getting Started

### Installation

```bash
# Install dependencies
pnpm install
```

### Development

```bash
# Build all packages
pnpm build:all

# Clean all build outputs
pnpm clean:all

# Run CLI in development mode
pnpm dev:cli
```

### Testing

```bash
# Run all tests across packages
pnpm test

# Guardian package testing
cd packages/guardian

# Run tests with coverage (80% threshold required)
pnpm test:coverage

# Run tests with UI
pnpm test:ui

# Run tests once (no watch mode)
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).

### Code Quality

```bash
# Format all code (IMPORTANT: uses 4-space indentation)
pnpm format

# Lint and auto-fix
pnpm lint

# Check linting without fixing
pnpm eslint "packages/**/*.ts"
```

## Project Structure

```
puaros/
├── packages/
│   └── 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
└── README.md                  # This file
```

## Code Style

This project follows strict TypeScript and code quality standards:

- **Indentation:** 4 spaces (enforced by Prettier)
- **Line Length:** 100 characters maximum
- **Quotes:** Double quotes
- **Semicolons:** Never used
- **Trailing Commas:** Always in multiline
- **TypeScript:** Strict type checking enabled

### Key Rules

- No `any` type without explicit reasoning
- Explicit function return types required
- No floating promises - always await or handle
- Use `const` for non-reassigned variables
- Always use `===` instead of `==`
- Curly braces required for all control structures
- No `console.log` (use `console.warn`/`console.error` or proper logger)

See [LINTING.md](./LINTING.md) for detailed code style guidelines.

## Monorepo Structure

This project uses pnpm workspaces for managing multiple packages:

- **Packages** are located in `packages/*`
- All packages share TypeScript configuration via `tsconfig.base.json`
- Dependencies are hoisted and shared when possible

### Adding a New Package

1. Create `packages/your-package/` directory
2. Add `package.json` with name `@puaros/your-package`
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

Guardian package uses:

- `commander` - CLI framework
- `simple-git` - Git operations
- `tree-sitter` - Abstract syntax tree parsing
- `tree-sitter-javascript` - JavaScript parser
- `tree-sitter-typescript` - TypeScript parser
- `uuid` - UUID generation

Development tools:

- 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 (4-space indentation)

## Contributing

1. Ensure Node.js version matches `.nvmrc` (22.18.0)
2. Run `pnpm format` before committing to ensure consistent formatting
3. All tests must pass with 80% coverage
4. Fix all ESLint warnings - they indicate real type safety issues

## License

MIT - Copyright (c) Fozilbek Samiyev