Skip to content

AGENTS.md

Latest commit

 

History

History
104 lines (71 loc) · 2.84 KB

AGENTS.md

File metadata and controls

104 lines (71 loc) · 2.84 KB

Codexray - Project Instructions

Project Overview

Codexray is a local-first code-health and refactoring analysis tool for TypeScript repositories. It's a CLI tool that runs entirely offline and is designed to be easy to Dockerize.

Architecture

The project follows a clean architecture with these layers:

  • CLI layer (src/cli/) - Command definitions and entry point
  • Core analysis engine (src/core/) - Scanner, analyzer, project loader
  • Rule system (src/rules/) - Rule types, registry, and implementations
  • Findings model (src/findings/) - Finding types and interfaces
  • Fix/edit model (src/fixes/) - Fix types and application logic
  • Reporters (src/reporters/) - Terminal and JSON output adapters
  • Config (src/config/) - Configuration types and defaults
  • Utils (src/utils/) - AST helper utilities

Coding Conventions

General

  • Use TypeScript strict mode
  • Prefer simple, explicit code over clever abstractions
  • Avoid overengineering
  • Keep files focused and avoid giant god files

File Organization

  • One primary export per file when practical
  • Use index.ts files for barrel exports
  • Keep tests in tests/ directory mirroring src/ structure

Naming

  • Use camelCase for variables and functions
  • Use PascalCase for types, interfaces, and classes
  • Use kebab-case for file names
  • Rule IDs use kebab-case (e.g., no-large-functions)

Imports

  • Use .js extensions for local imports (required for ESM compatibility)
  • Group imports: external → internal → local

Error Handling

  • Throw descriptive errors
  • Handle errors gracefully in CLI commands
  • Exit with appropriate codes (0 for success, 1 for errors)

Testing

  • Use Vitest for testing
  • Place tests in tests/ directory
  • Use describe/it blocks
  • Reset counters and state in beforeEach
  • Use in-memory file system for unit tests when possible

Building

npm run build  # Compile TypeScript to dist/

Running

npm start -- <command>  # Run CLI locally
node dist/cli/index.js <command>  # Run compiled CLI

Adding New Rules

  1. Create a new file in src/rules/implementations/
  2. Implement the Rule interface from src/rules/types.ts
  3. Export from src/rules/implementations/index.ts
  4. Add to builtInRules array
  5. Add tests in tests/rules/

For autofix support, implement AutoFixableRule interface.

Adding New Reporters

  1. Create a new file in src/reporters/
  2. Implement format and output functions
  3. Add to CLI commands as needed

Configuration

Configuration is via codexray.config.json or rule-specific options in CLI.

Future Extensions

The architecture supports future additions:

  • Action planning from findings
  • Local plan files
  • External issue creation (Jira, etc.)
  • Markdown reporter
  • More rules

These are extension points only - not currently implemented.