AGENTS.md

Project Overview

This is the InversifyJS monorepo - a TypeScript dependency injection library ecosystem. The repository contains multiple packages organized into categories:

• Framework packages: Core framework and HTTP functionality
• Container packages: DI container implementation, plugins, and examples
• Foundation packages: Shared tooling (ESLint, Prettier, TypeScript configs)
• Documentation packages: Code examples and website services
• Logger package: Logging utilities
• JSON Schema packages: Schema validation utilities
• Open API packages: OpenAPI integration

Build and Test Commands

Setup

# Install dependencies
pnpm install

# Build all packages
pnpm run build

# Run all tests
pnpm test

Development Workflow

# Format code
pnpm run format

# Lint code
pnpm run lint

# Run tests for a specific package
pnpm run --filter "@inversifyjs/package-name" test

# Run only unit tests
pnpm run test:unit

# Run only integration tests  
pnpm run test:integration

# Run tests with coverage
pnpm run test:coverage

Working with Specific Packages

# Build a specific package
pnpm run --filter "@inversifyjs/package-name" build

# Test a specific package
pnpm run --filter "@inversifyjs/package-name" test

# Format a specific package
pnpm run --filter "@inversifyjs/package-name" format

Code Style Guidelines

• TypeScript: Strict mode enabled across all packages
• Testing: Use Vitest with extensive unit and integration test coverage
• Mocking: External modules are mocked using vitest.fn()
• Formatting: Prettier configuration shared via @inversifyjs/foundation-prettier-config
• Linting: ESLint configuration shared via @inversifyjs/foundation-eslint-config

Testing Instructions

The project follows a comprehensive testing strategy with multiple test types:

Test Types

• Unit Tests (*.spec.ts): Test individual functions/classes in isolation
• Integration Tests (*.int.spec.ts): Test component interactions
• End-to-End Tests: Full system tests (some packages)
• Type Tests (*.spec-d.ts): TypeScript type checking tests

Test Structure

Follow the structured testing patterns documented in:

• Unit Testing Guidelines
• Test Fixtures Guidelines

Key Testing Principles

1. Four-layer describe structure: Class → Method → Input → Flow scopes
2. Vitest mocking: Use vitest.fn() and vitest.mock() for external dependencies
3. Fixture classes: Create reusable test fixtures with static methods
4. Clear naming: Use descriptive test names with "when called, and [condition]" pattern

Running Tests

# Run all tests
pnpm test

# Run only unit tests
pnpm run test:unit

# Run only integration tests
pnpm run test:integration

# Run tests for uncommitted changes
pnpm run test:uncommitted

# Run with coverage
pnpm run test:coverage

Package Types and Structure

Core Library Packages

Main implementation packages with ESM-only builds:

• /packages/framework/core/ - Framework core
• /packages/container/libraries/ - Container implementations
• /packages/logger/ - Logging utilities

Standard structure:

• src/ - TypeScript source code
• lib/ - ES Module build output ("type": "module")
• vitest.config.mjs - Test configuration
• Standard scripts: build, test, lint, format

Example Packages

Demonstration packages (usually no tests):

• /packages/container/examples/ - Usage examples
• /packages/docs/tools/ - Code examples for documentation

Foundation Packages

Shared tooling and configuration:

• /packages/foundation/tools/ - Shared configs (ESLint, Prettier, TypeScript, etc.)

Documentation Services

Docusaurus-based documentation sites:

• /packages/docs/services/ - Documentation websites

Monorepo Architecture

Workspace Configuration

• Package Manager: pnpm with workspaces
• Build Tool: Turbo for task orchestration
• Dependency Management: Workspace protocol for internal dependencies

Build System

• TypeScript: tsc compiles directly to lib/ as ESM ("type": "module")
• SWC: Fast TypeScript compilation for tests
• Turbo: Cached, parallelized builds

Quality Assurance

• Pre-commit Hooks: Husky with lint-staged
• Commitlint: Conventional commit messages
• Changesets: Version management and changelogs

Security Considerations

• All packages use workspace protocol for internal dependencies
• Development dependencies are pinned to specific versions
• No known security vulnerabilities in production dependencies
• Type-safe dependency injection prevents runtime injection attacks

Pull Request Guidelines

1. Branch Naming: Use descriptive feature branch names
2. Commit Messages: Follow conventional commit format
3. Testing: All changes must include appropriate tests
4. Build: Ensure pnpm run build passes
5. Linting: Ensure pnpm run lint passes
6. Coverage: Maintain or improve test coverage
7. Documentation: Update relevant docs for public API changes

Performance Considerations

• Turbo caching significantly speeds up repeated builds

Common Tasks

Adding a New Package

1. Create package directory following existing structure
2. Add to pnpm-workspace.yaml
3. Configure package.json with standard scripts
4. Add appropriate tsconfig files
5. Configure Vitest, ESLint, and Prettier
6. Add to Turbo build pipeline if needed

Debugging Build Issues

• Check Turbo cache: builds are cached by input file hashes
• Verify TypeScript configurations for target output format
• Ensure all workspace dependencies are properly declared
• Use --filter flag to isolate specific package issues

Working with Dependencies

• Use workspace:* protocol for internal dependencies
• Run pnpm install after adding new dependencies
• Check knip output for unused dependencies: pnpm run unused

This is NOT the Turborepo you know

Turborepo configuration, task behavior, and CLI commands can vary between installed versions and may differ from your training data. Resolve the turbo package from this file's directory or relevant workspace; in monorepos, it may not be visible from the repository root. For example, run node -p "require.resolve('turbo/package.json')" from a workspace that depends on turbo.

Read docs/README.md inside that installed package first, then read the relevant pages from its docs/ directory before changing Turborepo configuration or commands. Heed deprecation notices. These bundled docs match the installed package version and are available without network access.

This block is written and re-added by turbo before repository-scoped commands when an AI agent is detected. In the Turborepo source repository, its template is defined in crates/turborepo-cli/src/cli/agent_guidance.rs. Removing the managed block while updates are enabled means a later qualifying invocation will add it again. Set "agentGuidance": false in the root turbo.json or turbo.jsonc to opt out; this does not remove an existing block. Keep the block committed with your work to avoid an uncommitted change on the next agent invocation.