Skip to content

AGENTS.md

Latest commit

 

History

History
175 lines (132 loc) · 8.74 KB

AGENTS.md

File metadata and controls

175 lines (132 loc) · 8.74 KB
Raw

SlickGrid Universal repository guidance

Project context

This is a pnpm monorepo for SlickGrid Universal:

  • packages/ contains shared/core packages.
  • frameworks/ contains Angular, React, Vue, and Aurelia wrappers.
  • frameworks-plugins/ contains framework-specific plugins.
  • demos/ contains demo applications; Angular demos are under frameworks/angular-slickgrid/src/demos.
  • test/ contains shared test configuration and Cypress support.

Changes in packages/ can affect every framework. Preserve backward compatibility: prefer additive changes, overloads, and deprecations over breaking API changes. The framework has many options; ensure new options do not contradict or interfere with existing ones.

Working rules

  • Use pnpm 11 and the Node version declared in package.json.
  • Keep changes focused and follow nearby code patterns.
  • Use madge for JavaScript/TypeScript dependency impact and madge --circular for circular dependency checks when available.
  • Prefer non-SVG output for machine use; use SVG only for visualization.
  • Use strict TypeScript and preserve existing public API naming and behavior.
  • Prefer interface for object shapes when consistent with surrounding code.
  • Use protected for class methods that may be extended.
  • Follow existing naming conventions, such as _privateField and publicMethod.
  • Avoid circular dependencies. Use madge --circular when dependency impact needs verification.
  • For plugin changes, preserve existing init(), dispose(), getOptions(), and setOptions() lifecycle methods where applicable. Use BindingEventService for DOM event binding and cleanup.
  • Plugins extend SlickGrid and use SlickEventHandler where applicable. Support both grid options and column definition options.
  • When changing shared behavior, check all four framework wrappers and relevant demos.
  • Never edit generated dist/ output unless explicitly requested.
  • When drafting a pull request, follow .github/pull_request_template.md, including its conventional-commit title requirement and applicable sections and checklist items.
  • Return PR titles and descriptions as raw Markdown inside a fenced markdown code block so they can be copied directly.
  • Keep interactions and commit messages concise while preserving clarity.

Testing and quality

  • Unit tests use Vitest with test/vitest.config.mts.
  • Vitest unit tests use .spec.ts files; Cypress E2E tests use .cy.ts files under test/cypress/e2e/.
  • E2E tests use Cypress with test/cypress.config.ts.
  • Cypress tests use testIsolation: false; preserve their execution order and inherited state.
  • Cypress tests are serial: new tests inherit the grid/page state left by previous tests, so do not assume a fresh page or selection and do not reorder tests without checking dependencies.
  • Tests commonly live in __tests__/ subdirectories. Native/vanilla tests are under packages/; Angular-specific tests are under frameworks/angular-slickgrid/.
  • For the Vanilla demo suite, start the watch server with pnpm serve:vite, then run the root Cypress CI suite with pnpm cypress:ci. To run one spec while iterating, pass its path directly (for example, pnpm cypress:ci --spec test/cypress/e2e/example33.cy.ts).
  • Framework demos provide headless Cypress CI scripts. Start the matching demo server first (pnpm angular:serve, pnpm aurelia:serve, pnpm react:serve, or pnpm vue:serve).
  • Run the corresponding root CI command: pnpm angular:cypress:ci, pnpm aurelia:cypress:ci, pnpm react:cypress:ci, or pnpm vue:cypress:ci (for example, pnpm aurelia:cypress:ci). These commands use each framework's Cypress config and are preferred for validating framework-specific E2E suites.
  • Add or update tests for behavior changes, especially in core packages.
  • Maintain 100% statement, branch, function, and line coverage for changed production code. Scope coverage collection to the changed source files while including all tests needed to exercise them; passing tests alone is not sufficient.
  • Before committing, verify 100% line coverage for every changed production source file with unit tests. Do not rely on aggregate coverage: scope the report to the changed files and include all relevant tests. For changed test, documentation, or configuration files that are not production-code coverage targets, run the applicable tests or checks instead.
  • While actively iterating with the user, prefer cheap validation such as TypeScript diagnostics, targeted browser/manual checks, or focused benchmarks. Do not run Vitest entire test suite after every small prompt or exploratory edit; save focused Vitest runs for stable checkpoints, when the user asks, or final validation before handing off.
  • Run the smallest relevant checks first, then broader checks when practical:
pnpm test
pnpm lint
pnpm prettier:check
pnpm build
  • Use pnpm lint:fix and pnpm prettier:write only when autofix or formatting changes are intended.
  • Check the applicable .oxlintrc.json when working in Angular or framework-plugin code. The repository has three configurations: root .oxlintrc.json, frameworks/angular-slickgrid/.oxlintrc.json, and frameworks-plugins/angular-row-detail-plugin/.oxlintrc.json.

Documentation

Update corresponding framework documentation under frameworks/*/docs/ when applicable. Include code examples that work across all supported frameworks.

Common commands

  • pnpm build builds all packages and frameworks; it is also the Build Everything task.
  • pnpm lint runs OXLint across the repository.
  • pnpm lint:fix applies available OXLint fixes.
  • pnpm prettier:check checks formatting; pnpm prettier:write formats files.
  • pnpm test runs Vitest; pnpm test:coverage runs Vitest with coverage.
  • pnpm dev starts the Vanilla demo; use pnpm dev:angular, pnpm dev:react, pnpm dev:vue, or pnpm dev:aurelia for framework demos.

Monorepo structure

  • Changes to packages/ affect all framework wrappers.
  • Framework wrappers depend on core packages; prefer relative imports within packages.
  • Avoid circular dependencies.

Code review focus

  • Verify tests pass and coverage remains high.
  • Check impact across all four framework implementations.
  • Ensure new options do not contradict or overlap with existing ones.
  • Check that examples work in all framework demos.

Completion checklist

  • Review the diff for unrelated changes and accidental generated files.
  • Verify affected tests, lint, and formatting.
  • Mention any checks that could not be run and why.

RTK - Token-Optimized CLI

rtk is a CLI proxy that filters and compresses command output, saving 60-90% tokens.

Rule

When rtk is available, prefer rtk <command> for terminal commands.

Use this as the default-first policy for tests, lint/typecheck/build, git, and diagnostics commands. Apply the same pattern to analogous commands.

Examples:

vitest                     -> rtk vitest
jest                       -> rtk jest
git status                 -> rtk git status
tsc                        -> rtk tsc
ls                         -> rtk ls .

Git mappings:

git status                 -> rtk git status
git log -n 10              -> rtk git log -n 10
git diff                   -> rtk git diff

If rtk is unavailable, run the raw command instead of failing.

For Vitest, default to rtk vitest run. Use direct repo-root paths for focused specs and test/vitest.config.mts, for example:

rtk vitest run --config test/vitest.config.mts packages/common/src/services/foo.spec.ts

Prefer vitest run over pnpm exec vitest when the Vitest binary is available.

For Cypress, default to rtk cypress run --config-file test/cypress.config.ts --spec <spec-path>. If Cypress is not on PATH, use pnpm exec cypress run --config-file test/cypress.config.ts --spec <spec-path>.

Low-token availability check

For PowerShell terminals, check once per terminal session and cache the result:

if (-not $env:RTK_AVAILABLE) {
	if (Get-Command rtk -ErrorAction SilentlyContinue) {
		$env:RTK_AVAILABLE = '1'
	}
	else {
		$env:RTK_AVAILABLE = '0'
	}
}

For bash/zsh terminals:

if [ -z "${RTK_AVAILABLE+x}" ]; then
  if command -v rtk >/dev/null 2>&1; then
    export RTK_AVAILABLE=1
  else
    export RTK_AVAILABLE=0
  fi
fi

Use rtk only when the cached availability flag is enabled. Do not re-run the availability check before every command. If an rtk command unexpectedly fails because it is unavailable, set the flag to 0 and retry once without rtk.

Meta commands

Use these directly:

rtk gain              # Token savings dashboard
rtk gain --history    # Per-command savings history
rtk discover          # Find missed rtk opportunities
rtk proxy <cmd>       # Run raw (no filtering) but track usage