Skip to content

AGENTS.md

Latest commit

 

History

History
101 lines (89 loc) · 5.13 KB

AGENTS.md

File metadata and controls

101 lines (89 loc) · 5.13 KB
Raw

Quasar Repository Agent Guide

Applies repo-wide; a nested AGENTS.md takes precedence for its directory (most packages have one — check).

When editing any AGENTS.md (this one included), keep it to commands, package-specific gotchas and pointers into code. State repo-wide mechanics once — here, not per package; leave design rationale to code comments; drop whatever an agent can discover from the code or never acts on. Exception: procedures that must be followed exactly (e.g. /ui's Specs workflow) earn their length.

Workflow

  • pnpm workspace; run commands from the repo root unless a package's docs say otherwise.
  • Formatting oxfmt, linting oxlint (root lint/lint:check scripts, lint-staged pre-commit). Never introduce Prettier, ESLint or any other formatter/linter.
  • Before changing a package, inspect its package.json, nearby tests and READMEs.
  • Keep changes focused; don't modify, discard or commit unrelated work already in the worktree.
  • Follow existing code/test patterns. Any user-observable change (options, defaults, requirements, behavior, performance, setup) is incomplete until related tests, types, API JSON and the covering docs/src/pages pages — including their docs/src/examples components — (search there for the option/feature name) are updated in the same change set.

Code style

  • Never compare a native method's guaranteed-strict-boolean result (RegExp.test(), some()/every()/includes(), has(), startsWith()/endsWith(), Object.hasOwn(), Number.isNaN(), existsSync(), …) against === true/=== false; use it directly or negate with !.
  • DO keep explicit comparisons for non-guaranteed booleans: user-provided options, possibly-undefined values, project functions (their implementation can drift to non-boolean returns and silently break truthiness-based call sites).
  • A ref that holds a DOM element or a component instance/definition is never a ref(): shallowRef(null) in render-function code, useTemplateRef() in SFCs (<script setup> and setup() alike).

Generated Quasar configuration

  • quasar dev/build generate .quasar/ (tsconfig + type files); quasar prepare does the same without a dev server or build.
  • Prepare after a fresh/clean checkout, after dependency/config changes affecting generated types, and whenever lint/typechecking reports .quasar/tsconfig.json missing or unreadable.
  • Root pnpm prepare:types prepares all packages defining that script; pnpm --dir <app-dir> exec quasar prepare --silent prepares one app.
  • .quasar is generated output; never edit or commit it.

Validation

  • Narrowest relevant test while developing; the package's complete relevant suite before handoff.
  • Root pnpm test:all runs every package's full suite — hours long, meant for release-grade sweeps, never routine development.
  • Tests, dev servers and builds that need the built ui package self-heal: they build it only when ui/dist is missing or stale (ui/build/build-stamp.js), so expect an occasional multi-minute ui build mid-command. The scaffolding e2e suites install the monorepo's own packages through a throwaway local registry (create-quasar/test/e2e/local-registry.js) — published npm packages are never tested; after publishing a release train, sanity-check the uploads with npm create quasar@latest in a temp dir.
  • Run pnpm lint when linted source may be affected: it runs oxfmt (rewrites in place) then oxlint --fix; review the diff and hand-fix what oxlint still reports. pnpm lint:check is a read-only CI gate — not for finding issues.
  • Run git diff --check before committing.
  • Never weaken assertions, ignore generated cases or change production behavior just to make a failing test pass; diagnose the contract first.
  • Don't scatter fixture-content or presentation-formatting literals through assertions. Prefer, in order: derive the expected value from the fixture itself; assert semantic shape via regex (label + value, never column padding); else declare ONE named constant documenting the owning file, with a breadcrumb comment at the fixture pointing back. Test-created values may be asserted directly.
  • Tests may write only to OS temp dirs or gitignored generated paths. A test that must mutate a tracked repo file follows app-vite's e2e backup/restore protocol (pristine copy to a gitignored sibling before modifying, self-heal from it on the next run) so a killed run can never leave the worktree dirty.
  • Report every validation command run and its outcome; if one can't run, state the exact blocker.

Pull requests

  • One logical change per PR; describe root cause/motivation, user/developer impact and validation results.
  • Call out public API, SSR, hydration, platform, accessibility or security implications when applicable.
  • No unrelated dependency, lockfile, formatting or generated-file changes.
  • Automated review output (CodeRabbitAI etc.) is advisory: verify each claim against current code, tests, generated Specs and the intended contract; apply valid findings, reject or explain the rest — never change code or weaken tests merely to satisfy a bot.