alint AGENTS.md

alint Agent Guide

• pnpm workspace, TypeScript, Vitest, ESLint.
• Components:
  • packages/cli: CLI entrypoint, argument parsing, setup/config commands, reporter output, and handoff into core.
  • packages/config: project config loading plus global/local setup TOML paths, parsing, merging, and writing.
  • packages/core: public rule/plugin DSL, run engine, source extraction/runtime, model resolution, diagnostics, cache, and usage tracking.
  • packages/plugin-example: example rule plugin that exercises the public SDK and model-backed rule flow.

Structure & Responsibilities

• Build pipeline refs: .github/workflows; lint rules in eslint.config.ts.

Commands (pnpm with filters)

Use pnpm workspace filters to scope tasks. Examples below are generic; replace the filter with the target workspace name (e.g. @alint-js/core, etc.).

• Typecheck
  • pnpm -F <package.json name> typecheck
  • Example: pnpm -F @alint-js/cli typecheck (runs tsc).
• Unit tests (Vitest)
  • Targeted: pnpm exec vitest run <path/to/file> e.g. pnpm exec vitest run packages/cli/src/cli/cli.test.ts (not recommended as we prefer to run entire package test instead of file)
  • Workspace: pnpm -F <package.json name> exec vitest run e.g. pnpm -F @alint-js/cli exec vitest run
  • Root pnpm test:run: runs all tests across registered projects. If no tests are found, check vitest.config.ts include patterns.
  • Root vitest.config.ts includes packages/cli and other projects; each app/package can have its own vitest.config.
• Lint
  • pnpm lint and pnpm lint:fix
  • Formatting is handled via ESLint; pnpm lint:fix applies formatting.
• Build
  • pnpm -F <package.json name> build
  • Example: pnpm -F @alint-js/cli build (typecheck + electron-vite build).

Development Practices

• Favor clear module boundaries; shared logic goes in packages/.
• Keep runtime entrypoints lean; move heavy logic into services/modules.
• Prefer functional patterns + DI (injeca) for testability.
• Use Valibot for schema validation; keep schemas close to their consumers.
• Use Eventa (@moeru/eventa) for structured IPC/RPC contracts where needed.
• Use errorMessageFrom(error) from @moeru/std to extract error messages instead of manual patterns like error instanceof Error ? error.message : String(error). Pair with ?? 'fallback' when a default is needed.
• Do not add backward-compatibility guards. If extended support is required, write refactor docs and spin up another Codex or Claude Code instance via shell command to complete the implementation with clear instructions and the expected post-refactor shape.
• If the refactor scope is small, do a progressive refactor step by step.
• When modifying code, always check for opportunities to do small, minimal progressive refactors alongside the change.