Skip to content

AGENTS.md

Latest commit

 

History

History
114 lines (86 loc) · 5.3 KB

AGENTS.md

File metadata and controls

114 lines (86 loc) · 5.3 KB
Raw

Apex Log Analyzer

VS Code extension for analyzing Salesforce debug logs with interactive visualizations (flame charts, call trees, SOQL/DML breakdowns).

Canonical agent instructions for all tools. Claude Code loads this via CLAUDE.md. Area-specific rules live in .claude/rules/ — see the Rules manifest below.

Monorepo structure

  • lana/ — VS Code extension (TypeScript)
  • log-viewer/ — webview UI (TypeScript; lit / html / css)
  • The log parser is the @apexdevtools/apex-log-parser package, released from apex-dev-tools/apex-log-parser. Both lana/ and log-viewer/ depend on it. Import everything from the root export.
  • lana-docs/ — Docusaurus documentation
  • sample-app/ — sample Salesforce app with test logs

Commands

Always use pnpm.

  • pnpm watch — dev build with hot reload
  • pnpm build — production build
  • pnpm test — run tests (before committing)
  • pnpm lint — oxlint + prettier --check + tsc -b, run concurrently. The single pre-commit gate, so typecheck on top of it is wasted.
  • pnpm exec jest --selectProjects <log-viewer|lana|docs> — scoped tests, matching what CI runs per runner.
  • pnpm format — auto-format

DEVELOPING.md covers the rest, including the *:fast rolldown variants and their caveats.

Dev host — launch with code-insiders --profile lana-dev $PWD/sample-app $PWD/sample-app/debug-logs/sample-log.log --extensionDevelopmentPath=$PWD/lana, use the CLI of the launched editor, code-insiders or code

Core principles

  • Type safety — strict TypeScript, no any (use unknown + justification if unavoidable).
  • Naming — not linted. camelCase by default; PascalCase types; variables may also be UPPER_CASE or PascalCase (enum-like objects); static readonly class constants may be UPPER_CASE. Object keys that mirror external data (Salesforce fields, log event names) keep their source form.
  • Modularity — keep lana/ and log-viewer/ independent; cross-package contracts only.
  • Performance — handle large logs (50MB+, 500k+ lines) without blocking the UI.
  • UX — discoverable, accessible, actionable errors.
  • Testing — features and bug fixes ship with tests; CI blocks failures.
  • Comments — default to none. The bar: without this line a competent reader would make a wrong change. That means an outside constraint, or a deliberate choice that reads as a mistake. Not a why the code already shows, not a summary, not a signpost, never a test or a name restated. One line. JSDoc on exported API only. A comment you had to think up to justify is one to delete.

How to work

Think before coding

  • Read the code beside yours first. Navigate with LSP, ast-grep or rg; read a whole file last, and only the range you need.
  • Most "new" helpers already exist. Look in log-viewer/src/core/utility/, log-viewer/src/components/, log-viewer/src/tabulator/ and log-viewer/src/features/*/services/.
  • Where two modules share state, name one source of truth. Do not give each half the job.
  • State a plan first for anything that crosses the lana/ to log-viewer/ boundary, or that changes the message contract.

Simplicity first

  • The smallest change that fully solves the goal. No abstraction until the second caller exists.
  • CSS: no !important, and no 1px nudges. Fix the structure instead.
  • A retired workaround is commented out with a note on when to re-add it, not left live behind a runtime check.

Surgical changes

  • Every changed line traces to the request. No drive-by reformatting or renaming, since pnpm format owns style. A bug seen in passing is mentioned, not fixed.
  • Never hand-edit the vendored tabulator_esm.mjs beyond the sanctioned documented patches.
  • The root README.md, CHANGELOG.md and LICENSE.txt are the sources of truth. The lana/ copies are build output.

Finish the job

  • Restate the acceptance test before you start. Finish the whole scope, and say plainly what you left out and why.
  • Prove it with the real command, not by reading the code. Report a failure with its own output, and never call something done unverified.
  • In log-viewer/, the performance budgets in .claude/rules/log-viewer.md are part of the acceptance bar, measured on sample-app/ logs.

Critical boundary

log-viewer/ MUST NOT import vscode or anything from lana/. The two packages communicate via message passing only.

Workflow

  • Conventional commits (feat:, fix:, build:, chore:, ci:, docs:, style:, refactor:, perf:, test:). Don't auto-commit.
  • Branches: feat-* for features, bug-* for defects.
  • Releases follow SemVer; breaking changes need a migration guide.
  • A user-visible change updates CHANGELOG. A refactor, a test or the mechanism behind a fix does not. See the changelog-entry skill in .claude/skills/.
  • Never reference Anthropic or Claude in commit messages, PRs, etc.

Rules manifest

Area-specific rules load on demand (Claude Code, scoped by path):

  • .claude/rules/log-viewer.md — webview/UI: boundary, performance budgets, lit component rules, --lana-* appearance tokens, key paths.
  • .claude/rules/lana.md — VS Code extension: UX, command paths.

Some modules also carry their own AGENTS.md. Read it before you change that module.