mirror of
https://github.com/we-promise/sure.git
synced 2026-04-07 14:31:25 +00:00
8fcd2912cb
* Add LLM prompt for API endpoint consistency (fixes #944) - Add .cursor/rules/api-endpoint-consistency.mdc: checklist that applies when editing app/controllers/api/v1, spec/requests/api/v1, or test/controllers/api/v1. Enforces (1) Minitest-only behavioral coverage for new endpoints, (2) rswag docs-only (no expect/assert), (3) same API key auth pattern in all rswag specs. - Reference the rule in AGENTS.md under API Development Guidelines. * Add tests for API endpoint consistency implementation - Minitest: test/api_endpoint_consistency_rule_test.rb checks rule file exists, globs, and all three sections (Minitest, rswag docs-only, API key auth) plus AGENTS.md reference. - Standalone: test/support/verify_api_endpoint_consistency.rb runs same checks without loading Rails (use when app fails to boot). - Rule: add mdc: links for Cursor, note valuations_spec OAuth outlier. * Address review: add --compliance check, CLAUDE.md section - Verification script: --compliance scans current APIs and reports rswag OAuth vs API key, missing Minitest for controllers, expect/assert. - CLAUDE.md: add Post-commit API consistency subsection under API Development Guidelines (links to rule, documents script + --compliance). --------- Co-authored-by: mkdev11 <jaysmth689+github@users.noreply.github.com>
80 lines
5.4 KiB
Markdown
80 lines
5.4 KiB
Markdown
# Repository Guidelines
|
||
|
||
## Project Structure & Module Organization
|
||
- Code: `app/` (Rails MVC, services, jobs, mailers, components), JS in `app/javascript/`, styles/assets in `app/assets/` (Tailwind, images, fonts).
|
||
- Config: `config/`, environment examples in `.env.local.example` and `.env.test.example`.
|
||
- Data: `db/` (migrations, seeds), fixtures in `test/fixtures/`.
|
||
- Tests: `test/` mirroring `app/` (e.g., `test/models/*_test.rb`).
|
||
- Tooling: `bin/` (project scripts), `docs/` (guides), `public/` (static), `lib/` (shared libs).
|
||
|
||
## Build, Test, and Development Commands
|
||
- Setup: `cp .env.local.example .env.local && bin/setup` — install deps, set DB, prepare app.
|
||
- Run app: `bin/dev` — starts Rails server and asset/watchers via `Procfile.dev`.
|
||
- Test suite: `bin/rails test` — run all Minitest tests; add `TEST=test/models/user_test.rb` to target a file.
|
||
- Lint Ruby: `bin/rubocop` — style checks; add `-A` to auto-correct safe cops.
|
||
- Lint/format JS/CSS: `npm run lint` and `npm run format` — uses Biome.
|
||
- Security scan: `bin/brakeman` — static analysis for common Rails issues.
|
||
|
||
## Coding Style & Naming Conventions
|
||
- Ruby: 2-space indent, `snake_case` for methods/vars, `CamelCase` for classes/modules. Follow Rails conventions for folders and file names.
|
||
- Views: ERB checked by `erb-lint` (see `.erb_lint.yml`). Avoid heavy logic in views; prefer helpers/components.
|
||
- JavaScript: `lowerCamelCase` for vars/functions, `PascalCase` for classes/components. Let Biome format code.
|
||
- Commit small, cohesive changes; keep diffs focused.
|
||
|
||
## Testing Guidelines
|
||
- Framework: Minitest (Rails). Name files `*_test.rb` and mirror `app/` structure.
|
||
- Run: `bin/rails test` locally and ensure green before pushing.
|
||
- Fixtures/VCR: Use `test/fixtures` and existing VCR cassettes for HTTP. Prefer unit tests plus focused integration tests.
|
||
|
||
## Commit & Pull Request Guidelines
|
||
- Commits: Imperative subject ≤ 72 chars (e.g., "Add account balance validation"). Include rationale in body and reference issues (`#123`).
|
||
- PRs: Clear description, linked issues, screenshots for UI changes, and migration notes if applicable. Ensure CI passes, tests added/updated, and `rubocop`/Biome are clean.
|
||
|
||
## Security & Configuration Tips
|
||
- Never commit secrets. Start from `.env.local.example`; use `.env.local` for development only.
|
||
- Run `bin/brakeman` before major PRs. Prefer environment variables over hard-coded values.
|
||
|
||
## API Development Guidelines
|
||
|
||
### OpenAPI Documentation (MANDATORY)
|
||
When adding or modifying API endpoints in `app/controllers/api/v1/`, you **MUST** create or update corresponding OpenAPI request specs for **DOCUMENTATION ONLY**:
|
||
|
||
1. **Location**: `spec/requests/api/v1/{resource}_spec.rb`
|
||
2. **Framework**: RSpec with rswag for OpenAPI generation
|
||
3. **Schemas**: Define reusable schemas in `spec/swagger_helper.rb`
|
||
4. **Generated Docs**: `docs/api/openapi.yaml`
|
||
5. **Regenerate**: Run `RAILS_ENV=test bundle exec rake rswag:specs:swaggerize` after changes
|
||
|
||
### Post-commit API consistency (LLM checklist)
|
||
After every API endpoint commit, ensure: (1) **Minitest** behavioral coverage in `test/controllers/api/v1/{resource}_controller_test.rb` (no behavioral assertions in rswag); (2) **rswag** remains docs-only (no `expect`/`assert_*` in `spec/requests/api/v1/`); (3) **rswag auth** uses the same API key pattern everywhere (`X-Api-Key`, not OAuth/Bearer). Full checklist: [.cursor/rules/api-endpoint-consistency.mdc](.cursor/rules/api-endpoint-consistency.mdc).
|
||
|
||
## Providers: Pending Transactions and FX Metadata (SimpleFIN/Plaid/Lunchflow)
|
||
|
||
- Pending detection
|
||
- SimpleFIN: pending when provider sends `pending: true`, or when `posted` is blank/0 and `transacted_at` is present.
|
||
- Plaid: pending when Plaid sends `pending: true` (stored at `transaction.extra["plaid"]["pending"]` for bank/credit transactions imported via `PlaidEntry::Processor`).
|
||
- Lunchflow: pending when API returns `isPending: true` in transaction response (stored at `transaction.extra["lunchflow"]["pending"]`).
|
||
- Storage (extras)
|
||
- Provider metadata lives on `Transaction#extra`, namespaced (e.g., `extra["simplefin"]["pending"]`).
|
||
- SimpleFIN FX: `extra["simplefin"]["fx_from"]`, `extra["simplefin"]["fx_date"]`.
|
||
- UI
|
||
- Shows a small “Pending” badge when `transaction.pending?` is true.
|
||
- Variability
|
||
- Some providers don’t expose pendings; in that case nothing is shown.
|
||
- Configuration (default-off)
|
||
- SimpleFIN runtime toggles live in `config/initializers/simplefin.rb` via `Rails.configuration.x.simplefin.*`.
|
||
- Lunchflow runtime toggles live in `config/initializers/lunchflow.rb` via `Rails.configuration.x.lunchflow.*`.
|
||
- ENV-backed keys:
|
||
- `SIMPLEFIN_INCLUDE_PENDING=1` (forces `pending=1` on SimpleFIN fetches when caller didn’t specify a `pending:` arg)
|
||
- `SIMPLEFIN_DEBUG_RAW=1` (logs raw payload returned by SimpleFIN)
|
||
- `LUNCHFLOW_INCLUDE_PENDING=1` (forces `include_pending=true` on Lunchflow API requests)
|
||
- `LUNCHFLOW_DEBUG_RAW=1` (logs raw payload returned by Lunchflow)
|
||
|
||
### Provider support notes
|
||
|
||
- SimpleFIN: supports pending + FX metadata; stored under `extra["simplefin"]`.
|
||
- Plaid: supports pending when the upstream Plaid payload includes `pending: true`; stored under `extra["plaid"]`.
|
||
- Plaid investments: investment transactions currently do not store pending metadata.
|
||
- Lunchflow: supports pending via `include_pending` query parameter; stored under `extra["lunchflow"]`.
|
||
- Manual/CSV imports: no pending concept.
|