Skip to content

Latest commit

 

History

History
108 lines (75 loc) · 3.59 KB

CONTRIBUTING.md

File metadata and controls

108 lines (75 loc) · 3.59 KB

Contributing to VisualCompiler

Thanks for taking the time to contribute.

Table of Contents

Code of Conduct

Be respectful and constructive. Harassment, discrimination, and personal attacks will not be tolerated.

Getting Started

Prerequisites: Node.js 20+, npm.

git clone <repo-url>
cd VisualCompiler
npm install
npx playwright install --with-deps
npm run dev

Development Workflow

  1. Fork the repo and create a branch from main.
  2. Branch names should be descriptive: fix/flex-wrap-detection, feat/gap-inference, test/sparse-grid-fixtures.
  3. Keep commits focused — one logical change per commit.
  4. Run the full test suite before opening a PR.
npm run test:unit   # Vitest unit tests
npm run test:e2e    # Playwright browser tests
npm run build       # TypeScript + Vite production build
npm run lint        # ESLint

All four must pass cleanly.

Submitting Changes

  • Open a pull request against main.
  • Fill in the PR template — describe the problem, approach, and how you tested it.
  • Link the related issue if one exists.
  • Keep PRs small and focused. Large refactors should be discussed in an issue first.
  • A maintainer will review and may request changes before merging.

Issue Guidelines

Bug reports should include:

  • Steps to reproduce (ideally a minimal canvas arrangement in JSON).
  • Expected vs actual inference output.
  • Browser and OS version if it's a rendering or interaction bug.

Feature requests should explain the use case, not just the desired API. If it touches the inference pipeline, describe the layout pattern it targets.

Inference Pipeline

The core algorithm lives in src/inference/. Before touching it:

  1. Read src/inference/index.ts to understand the pipeline order.
  2. Each stage has a dedicated file — prefer changing one stage at a time.
  3. Algorithm invariants are documented in comments inside each file and in MEMORY.md. Do not violate them without discussion:
    • detectTracks clusters left edges only (not left+right combined).
    • decide uses additive scoring, not residual error.
    • Tail-missing detection requires monotonically decreasing item counts.
  4. Add or update fixtures in tests/fixtures/ for any new layout pattern you target.
  5. Add unit tests in src/inference/__tests__/ for any new scoring or classification logic.

Testing

  • Unit tests (src/inference/__tests__/): cover individual pipeline stages. Use plain objects — no DOM required.
  • Fixture tests (tests/inference.spec.ts): read JSON fixtures from tests/fixtures/ and assert inference output end-to-end.
  • Browser tests (tests/canvas.spec.ts): use Playwright and inject state via window.__canvasStore.

When adding a new layout pattern, add a fixture JSON file and at least one fixture test assertion before opening a PR.

Style Guide

  • TypeScript strict mode — no any without justification.
  • No default exports in src/inference/ — named exports only.
  • Prefer pure functions. Side effects should be isolated to store actions and React components.
  • Do not add comments that restate what the code does; only comment on why when the reason is non-obvious.
  • Keep each inference stage file focused on its single responsibility. Do not add layout logic to emit.ts.