# Lodestar — Declare your architecture. Enforce it.

Intra-package architecture enforcement for TypeScript/JavaScript — layer dependencies, module boundaries, circular imports. Plus file structure validation and tool config generation. Define rules in `lodestar.config.ts`, enforce in CI, visualize as diagrams.

## The Problem

Every project has unwritten architecture rules — "domain shouldn't import infra", "use the barrel, not internals", "no circular dependencies". These rules live in people's heads and erode silently.

## The Solution

```ts
// lodestar.config.ts
import { defineConfig } from '@retemper/lodestar';
import { pluginArchitecture } from '@retemper/lodestar-plugin-architecture';

export default defineConfig({
  plugins: [pluginArchitecture],
  rules: {
    'architecture/layers': {
      severity: 'error',
      options: {
        layers: [
          { name: 'domain', path: 'src/domain/**' },
          { name: 'application', path: 'src/application/**', canImport: ['domain'] },
          { name: 'infra', path: 'src/infra/**', canImport: ['domain', 'application'] },
        ],
      },
    },
  },
});
```

## Commands

- `lodestar check` — enforce architecture rules
- `lodestar graph --layers` — visualize layer-level architecture
- `lodestar graph` — visualize file-level dependency graph
- `lodestar impact <file>` — show files affected by a change
- `lodestar init` — create config file
- `lodestar watch` — re-check on file changes (incremental)

## Rules (plugin-architecture)

- `architecture/layers` — dependency direction between layers
- `architecture/modules` — module boundary encapsulation (barrel imports)
- `architecture/no-circular` — circular dependency detection
- `architecture/no-circular-packages` — circular package dependency detection

## Rules (plugin-structure)

- `structure/directory-exists` — required directories/files must exist (auto-fix)
- `structure/no-forbidden-path` — forbidden paths must not exist
- `structure/paired-files` — source files must have companion files (auto-fix)

## Reporters

Built-in: console (default), JSON. Plugins: @retemper/lodestar-reporter-junit, @retemper/lodestar-reporter-sarif.

## Adapters

Generate tool configs from lodestar.config.ts: ESLint, Prettier, Biome, Husky, lint-staged, Commitlint, Knip, Stylelint.

## Links

- Docs: https://retemper.github.io/lodestar/
- GitHub: https://github.com/retemper/lodestar
- Full API: /llm-full.txt