QT/sure

mirror of https://github.com/we-promise/sure.git synced 2026-09-08 08:04:15 +00:00

Files

T

Juan José Mata 157daf5176 Consolidate repository instructions after auditing their history (#3409 )

* Document instruction inventory and preservation decisions

Trace main history from September 2025 through September 2026, including earlier policy origins. Record preserved requirements, detailed-guide destinations, stale facts, harness boundaries and explicit policy-strength decisions before consolidating instruction sources.

* Consolidate repository instructions into shared guidance

Keep AGENTS concise and vendor neutral, move detailed conventions into shared guides, and use thin adapters with preserved Cursor scopes. Preserve the strict pre-PR checks globally and document the stronger scope, retired migration pin and rule-generation trigger. Update existing API guidance verification without changing application behavior.

* Narrow the always-on Cursor UI adapter and correct the SimpleFIN comment

Split the design-system guidance out of docs/llm-guides/ui.md into
docs/llm-guides/design-system.md. The ui-ux-design-guidelines rule is
alwaysApply: true, so importing all of ui.md loaded the Stimulus,
localization and ViewComponent guidance (previously confined to scoped
rules) on every Cursor session; the always-on adapter now imports only the
design-system guide, matching the scope it had before the consolidation.
view_conventions and stimulus_conventions keep the full UI guide.

Also correct the stale Provider::Simplefin header comment: pending
inclusion defaults on and is resolved by the importer (explicit argument,
then SIMPLEFIN_INCLUDE_PENDING, then Setting.syncs_include_pending); the
previous comment described the flag as default-off.

* Read guidance files as UTF-8 in the API consistency validators

The frontmatter regex match ran against content read with the locale
default external encoding; the Cursor rule's description contains an em
dash, so under US-ASCII (LC_ALL=C) Regexp#match raised ArgumentError,
breaking the standalone no-Rails fallback the docs point contributors to.
Read all checked files with an explicit UTF-8 encoding in both the
standalone script and the Rails test.

2026-09-06 07:14:43 +02:00

2.8 KiB

Raw Blame History

API endpoint consistency (post-commit checklist)

When adding or modifying API v1 endpoints, follow this checklist after every API endpoint commit so behavior, docs, and auth stay consistent. Runtime endpoints also support OAuth; the API-key-only requirement below applies to the behavioral test and documentation patterns.

1. Minitest behavioral coverage

Location: test/controllers/api/v1/{resource}_controller_test.rb
Scope: All new or changed actions must have Minitest coverage here. Do not rely on rswag specs for behavioral assertions.
Pattern:
- Use ApiKey.create! (read and read_write scopes) and api_headers(api_key) → { "X-Api-Key" => api_key.display_key }. Do not use OAuth/Bearer in these tests.
- Cover: index/show (and create/update/destroy for write endpoints), read-only key blocking writes (403), invalid params (422), invalid date (422), not found (404), missing auth (401).
- Follow existing API v1 test style: see valuations_controller_test.rb and transactions_controller_test.rb.

2. rswag is docs-only

Location: spec/requests/api/v1/{resource}_spec.rb
Rule: These specs exist only for OpenAPI generation. Do not add expect(...) or assert_* (or any behavioral assertions). Use run_test! without custom assertion blocks so the spec only documents request/response and regenerates docs/api/openapi.yaml.
Regenerate: After edits, run RAILS_ENV=test bundle exec rake rswag:specs:swaggerize.

3. Same API key auth in all rswag specs

Rule: Every request spec in spec/requests/api/v1/ must use the same API key auth pattern so generated docs are consistent.

Pattern (match holdings_spec, trades_spec, transactions_spec, etc.):

let(:api_key) do
  key = ApiKey.generate_secure_key
  ApiKey.create!(
    user: user,
    name: 'API Docs Key',
    key: key,
    scopes: %w[read_write],
    source: 'web'
  )
end

let(:'X-Api-Key') { api_key.plain_key }

Do not use Doorkeeper/OAuth in these specs (no Doorkeeper::Application, Doorkeeper::AccessToken, or Authorization: "Bearer ..."). Use API key only.

OpenAPI schemas and verification

Adding or modifying an API endpoint requires corresponding documentation specs. Define reusable schemas in spec/swagger_helper.rb. Generated documentation lives in docs/api/openapi.yaml.

Verify the guidance without booting Rails:

ruby test/support/verify_api_endpoint_consistency.rb
ruby test/support/verify_api_endpoint_consistency.rb --compliance

The second command reports existing API compliance issues; its inventory is not a replacement for running the behavioral tests or regenerating OpenAPI documentation.

2.8 KiB Raw Blame History