@puaros/guardian - Research-backed code quality guardian for vibe coders and enterprise teams. Detects hardcoded values, secrets, circular dependencies, architecture violations, and anemic domain models. Every rule is based on academic research, industry standards (OWASP, SonarQube), and authoritative books (Martin Fowler, Uncle Bob, Eric Evans). 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

Create packages/your-package/ directory
Add package.json with name @puaros/your-package
Create tsconfig.json extending ../../tsconfig.base.json
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

📚 Research-Backed Rules

Guardian's detection rules are based on decades of software engineering research and industry best practices:

Academic Research: MIT Course 6.031, ScienceDirect peer-reviewed studies (2020-2023), IEEE papers on Technical Debt
Industry Standards: SonarQube (400,000+ organizations), Google/Airbnb/Microsoft style guides, OWASP security standards
Authoritative Books:
- Clean Architecture (Robert C. Martin, 2017)
- Implementing Domain-Driven Design (Vaughn Vernon, 2013)
- Domain-Driven Design (Eric Evans, 2003)
- Patterns of Enterprise Application Architecture (Martin Fowler, 2002)
Security Standards: OWASP Secrets Management, GitHub Secret Scanning (350+ patterns)

Every rule links to research citations - see Why Guardian's Rules Matter and Full Research Citations for complete academic papers, books, and expert references.

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

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

README.md

Puaros

Packages