Puaros

A TypeScript monorepo for code quality and analysis tools.

Packages

• @puaros/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

# Install dependencies
pnpm install

Development

# Build all packages
pnpm build:all

# Clean all build outputs
pnpm clean:all

# Run CLI in development mode
pnpm dev:cli

Testing

# 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

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

# 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