diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..cb599eb --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,184 @@ +# AGENTS.md + +Instructions for AI coding agents working with this repository. + +## Project Overview + +Recce UI (`@datarecce/ui`) is a React component library wrapper that packages the open-source Recce project for npm distribution. + +**Key Architecture:** Git submodule pattern +- `src/` - Wrapper layer (re-exports, minimal overrides) +- `recce-source/` - Git submodule pointing to DataRecce/recce OSS repo +- `dist/` - Built output (generated, never edit) + +**Tech Stack:** React 18/19, MUI 7, TypeScript 5.9, pnpm, tsdown + +--- + +## Critical Constraints + +### Do NOT: +- Edit files in `recce-source/` directly (OSS code; use patches if needed) +- Use npm or yarn (must use pnpm; locked via .npmrc) +- Skip submodule initialization (clone with `--recursive`) +- Bypass pre-commit hooks (never use `--no-verify`) +- Edit generated files in `dist/` (regenerate via `pnpm build`) +- Add dependencies not in recce-source (keep synced with OSS) +- Use interactive git commands (`git rebase -i`, `git add -i`) +- Commit node_modules/ or dist/ + +### Always: +- Initialize submodules: `git submodule init && git submodule update` +- Use pnpm for all package operations +- Run `pnpm type:check` before committing +- Run `make sync` when updating from OSS +- Build before local testing: `make build && make link` +- Keep VERSION file and package.json version in sync + +--- + +## Essential Commands + +### Setup +```bash +git clone --recursive https://github.com/DataRecce/recce-ui.git +cd recce-ui +pnpm install +make build +``` + +### Daily Development +```bash +pnpm dev # Watch mode (rebuilds on changes) +pnpm build # Full build (tsdown + CSS aggregation) +pnpm type:check # Type check (filters OSS errors) +pnpm type:check:all # Type check including OSS errors +pnpm test # Run tests with Vitest +pnpm check:exports # Find new/stale component exports +``` + +### Submodule Management +```bash +make sync # Update submodule, sync deps, install +make verify # Full verification (sync + build + type-check + check-exports) +``` + +### Before Committing +```bash +pnpm type:check # Must pass +pnpm build # Ensure build succeeds +``` + +### Local Testing (in consumer project) +```bash +# In recce-ui: +make link + +# In consumer project: +pnpm link --global @datarecce/ui +``` + +--- + +## Repository Layout + +``` +recce-ui/ +├── src/ # Wrapper layer (edit here) +│ ├── index.ts # Main entry (re-exports) +│ ├── components/ # Component re-exports +│ ├── api/ # API utilities +│ ├── hooks/ # Custom hooks +│ ├── types/ # Type definitions +│ ├── lib/ # Custom overrides +│ └── global-styles.css # Theme CSS variables +├── recce-source/ # Git submodule (DO NOT EDIT) +│ └── js/src/ # Actual component source +├── scripts/ # Build scripts +├── dist/ # Generated output (DO NOT EDIT) +└── Makefile # Command shortcuts +``` + +## Where to Add Code + +| Change Type | Location | Notes | +|-------------|----------|-------| +| New component export | `src/components/index.ts` | Re-export from recce-source | +| New hook export | `src/hooks/index.ts` | Re-export from recce-source | +| New type export | `src/types/index.ts` | Re-export from recce-source | +| Custom override | `src/lib/` | When OSS needs wrapper-specific logic | +| Build script | `scripts/` | Build-time processing | +| Global styles | `src/global-styles.css` | Theme config, CSS variables | + +--- + +## Commit Conventions + +### Sign-off Required (DCO) +Every commit must include a sign-off line: +```bash +git commit -s -m "feat(components): add LineageView export" +``` + +### Conventional Commit Format +``` +(): + +Signed-off-by: Name +``` + +**Types:** `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore` + +**Examples:** +```bash +git commit -s -m "feat(components): add LineageView export" +git commit -s -m "fix(build): ensure global-styles loaded first" +git commit -s -m "chore(deps): sync dependencies from recce-source" +``` + +### Branch Naming +All branches from `main` with prefix: +- `feature/` - New features +- `fix/` - Bug fixes +- `hotfix/` - Critical production fixes + +### PR Requirements +- All type checks must pass +- Build must succeed +- Main branch requires PRs (no direct commits) + +--- + +## Common Pitfalls + +### Submodule Not Initialized +``` +Error: Cannot find module '../recce-source/js/src/components' +``` +**Fix:** `git submodule init && git submodule update` + +### Type Errors in OSS Code +``` +pnpm type:check:all shows errors in recce-source/ +``` +**Expected:** Use `pnpm type:check` (filters OSS errors we don't control) + +### Missing Component Export +``` +Module has no exported member 'ComponentName' +``` +**Fix:** Add re-export to `src/components/index.ts`, then `pnpm build` + +### Dependency Mismatch +``` +WARN Issues with peer dependencies found +``` +**Fix:** `pnpm run sync:deps && pnpm install` + +--- + +## Additional Resources + +- **[CLAUDE.md](./CLAUDE.md)** - Extended documentation for Claude Code (architecture deep-dives, patterns, troubleshooting) +- **[CONTRIBUTING.md](./CONTRIBUTING.md)** - Human contributor guide +- **[ARCHITECTURE.md](./ARCHITECTURE.md)** - System design documentation diff --git a/CLAUDE.md b/CLAUDE.md index 4b890b4..7a17c17 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,99 +1,31 @@ # CLAUDE.md -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. +Extended guidance for Claude Code (claude.ai/code) when working with this repository. -## Overview - -Recce UI (`@datarecce/ui`) is a React component library for building data validation and review interfaces. It provides the UI components used in [Recce](https://github.com/DataRecce/recce), a data validation tool for dbt projects. The library enables developers to create data comparison, profiling, and validation workflows with pre-built, production-ready components. - -**Key Architecture:** This is a wrapper library that packages the open-source Recce project for npm distribution. It uses a git submodule pattern where actual component source lives in `recce-source/` (pointing to the main Recce repository), while `src/` contains only re-exports and minimal customizations for the npm package. - -## Critical Constraints & Guidelines - -### Do NOT: - -- ❌ **Skip submodule initialization**: Always clone with `--recursive` flag or run `git submodule init && git submodule update` -- ❌ **Edit files in recce-source/ directly**: This is OSS code from the main Recce repo; use patches if modifications are needed -- ❌ **Use npm or yarn**: Must use `pnpm` as specified in .npmrc and package.json -- ❌ **Bypass pre-commit hooks**: Never use `--no-verify` on commits; hooks enforce quality standards -- ❌ **Commit node_modules or dist/**: These are build artifacts and dependencies (gitignored) -- ❌ **Edit generated files in dist/**: Always regenerate via `pnpm build` or `make build` -- ❌ **Publish without running build**: `prepublishOnly` hook ensures this, but never bypass it -- ❌ **Add dependencies not in recce-source**: Keep dependency lists synchronized with OSS package -- ❌ **Use interactive git commands**: Never use `git rebase -i`, `git add -i` (interactive prompts don't work) - -### Always: - -- ✅ **Initialize submodules with --recursive flag**: `git clone --recursive` or use submodule commands after clone -- ✅ **Use pnpm for package management**: Package manager is locked to pnpm via .npmrc -- ✅ **Run make sync when updating from OSS**: This updates submodule, syncs deps, and installs -- ✅ **Build before testing locally with link**: Run `make build` then `make link` for local testing -- ✅ **Run type:check before committing**: Ensure `pnpm type:check` passes to catch errors early -- ✅ **Keep dependencies in sync with recce-source**: Use `pnpm run sync:deps` to synchronize -- ✅ **Update VERSION file with package.json**: Both must match for consistency -- ✅ **Test component exports**: Run `pnpm check:exports` to find new/stale exports +> **For universal agent instructions, see [AGENTS.md](./AGENTS.md).** -## Git Development Practices +## What's in Each File -### Branch Naming +| AGENTS.md (All AI Agents) | CLAUDE.md (Claude-Specific) | +|---------------------------|----------------------------| +| Critical constraints | Architecture deep-dives | +| Essential commands | Build system internals | +| Repository layout | Code patterns & examples | +| Commit conventions | Path alias configuration | +| Common pitfalls | CSS bundling strategy | +| | Type generation details | +| | Extended troubleshooting | +| | Key principles | -All new code MUST be developed in a branch with one of these prefixes, branched directly from `main`: - -- `feature/` - New features or enhancements -- `fix/` - Bug fixes -- `hotfix/` - Critical production fixes - -```bash -# Create a new feature branch -git checkout main -git pull origin main -git checkout -b feature/my-new-feature -``` - -### Commit Requirements - -**1. Sign-off (DCO):** Every commit MUST include a "Signed-off-by:" line per the [Developer Certificate of Origin](https://developercertificate.org/): - -```bash -git commit -s -m "Your commit message" -``` - -**2. Semantic/Conventional Commits:** Use structured commit messages: - -``` -(): - -[optional body] - -[optional footer] -Signed-off-by: Your Name -``` - -**Types:** - -- `feat` - New feature -- `fix` - Bug fix -- `docs` - Documentation only -- `style` - Formatting, no code change -- `refactor` - Code change that neither fixes a bug nor adds a feature -- `test` - Adding or updating tests -- `chore` - Maintenance tasks (deps, build, CI) +--- -**Examples:** +This file provides extended guidance for Claude Code beyond the basics in AGENTS.md. -```bash -git commit -s -m "feat(components): add LineageView export" -git commit -s -m "fix(build): ensure global-styles loaded first" -git commit -s -m "docs: update CLAUDE.md with submodule workflow" -git commit -s -m "chore(deps): sync dependencies from recce-source" -``` +## Overview -**Additional Guidelines:** +Recce UI (`@datarecce/ui`) is a React component library for building data validation and review interfaces. It provides the UI components used in [Recce](https://github.com/DataRecce/recce), a data validation tool for dbt projects. The library enables developers to create data comparison, profiling, and validation workflows with pre-built, production-ready components. -- Commit frequently during development -- Use worktrees for parallel work (`git worktree --help`) -- Main branch requires PRs -- Pre-commit hooks enforce quality—never skip them +**Key Architecture:** This is a wrapper library that packages the open-source Recce project for npm distribution. It uses a git submodule pattern where actual component source lives in `recce-source/` (pointing to the main Recce repository), while `src/` contains only re-exports and minimal customizations for the npm package. ## Code Organization Philosophy @@ -261,72 +193,7 @@ recce-ui/ ## Development Commands -### Initial Setup - -**Prerequisites:** -- Node.js >= 20 (check with `node --version`) -- pnpm (install with `npm install -g pnpm`) -- Git with submodule support - -**First Time Setup:** - -```bash -# Clone repository WITH submodules -git clone --recursive https://github.com/DataRecce/recce-ui.git -cd recce-ui - -# If you forgot --recursive, initialize submodules now: -git submodule init -git submodule update - -# Install dependencies -pnpm install - -# Build the library -make build - -# Run type checking -make type-check -``` - -### Build and Development - -```bash -# Show all available commands -make help - -# Build the package (tsdown + CSS aggregation) -make build -# OR -pnpm build - -# Watch mode for development (rebuilds on file changes) -pnpm dev - -# Type checking (filters out OSS errors) -make type-check -# OR -pnpm type:check - -# Type checking including OSS errors (for debugging) -make type-check-all -# OR -pnpm type:check:all - -# Check for new/stale component exports -make check-exports -# OR -pnpm check:exports - -# Clean build artifacts -make clean - -# Full rebuild (clean + build) -make rebuild - -# Run all checks (sync + build + type-check + check-exports) -make verify -``` +> **Basic commands are in [AGENTS.md](./AGENTS.md#essential-commands).** This section covers extended workflows. ### Submodule Management @@ -702,6 +569,8 @@ alias: { ## Common Errors & Fixes +> **Quick fixes for common issues are in [AGENTS.md](./AGENTS.md#common-pitfalls).** This section provides extended troubleshooting. + ### Submodule Not Initialized **Error:**