# Repository Guidelines

## Project Structure & Module Organization
- `src/` TypeScript sources for the VS Code extension (entry: `extension.ts`).
- `src/webview/` static assets for the dashboard webview copied to `out/` on build.
- `out/` compiled JavaScript (generated; do not edit).
- `.tests/` Jest tests, mocks for `vscode` and `sqlite3`.
- Key modules: analyzers (`ai-analyzer.ts`, `code-operation-analyzer.ts`, `timing-analyzer.ts`), storage/DB (`ai-code-storage.ts`, `database.ts`), UI (`dashboard-webview.ts`).

## Build, Test, and Development Commands
- `npm install` install dependencies.
- `npm run compile` build TypeScript and copy webview assets to `out/`.
- `npm run watch` rebuild on change.
- `npm run lint` run ESLint over `src/`.
- `npm test` run Jest (ts-jest) with repo mocks and produce coverage.
- `npm run package` build a `.vsix` via `vsce`.
- `npm run watcher` optional helper to watch Cursor DB events (dev aid).

## Coding Style & Naming Conventions
- Language: TypeScript (Node ≥16, VS Code engine ^1.74).
- Indentation: 2 spaces; prefer semicolons.
- ESLint: `@typescript-eslint` rules enabled; variables/classes must be `camelCase`/`PascalCase`.
- Filenames: `kebab-case.ts` (e.g., `document-monitor.ts`). Classes/interfaces: `PascalCase`. Functions/vars: `camelCase`.
- Place shared helpers in `src/utils/`. Do not import from `out/`.

## Testing Guidelines
- Framework: Jest with `ts-jest`. Tests live in `.tests/` and end with `.test.ts` (e.g., `.tests/database.test.ts`).
- Mocks: repo provides `vscode` and `sqlite3` mocks; tests should not hit real VS Code or local DBs.
- Commands: `npm test` or `npm test -- --coverage`. Aim for ≥80% line coverage on changed areas.

## Commit & Pull Request Guidelines
- Current history contains short WIP commits (`--wip-- [skip ci]`). For contributions, use Conventional Commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`.
- PRs must include: clear description, linked issues, screenshots/GIFs for UI changes (dashboard), and notes on testing.
- Before opening a PR: run `npm run lint`, `npm test`, and `npm run compile`. Do not commit `out/` or `.vsix` artifacts.

## Security & Configuration Tips
- Never commit personal data from `~/.ailens/` or Cursor databases; tests must use mocks.
- User settings keys exposed by the extension: `ailens.autoStart`, `ailens.showNotifications`, `ailens.debug`.
- Keep file I/O and DB access defensive (read-only where possible) and behind typed interfaces in `src/`.