mirror of
https://github.com/diegosouzapw/OmniRoute.git
synced 2026-08-05 23:02:10 +03:00
feat(.50): completa itens restantes — G13, G14, gap34, docs, R0.2 (#9126)
* feat(ci): G0 — quality rail (PR→release/**) ganha ratchets+segurança do trilho A O refactor de god-files do trilho 3.8.50→3.9.0 acontece em PRs→release/**, e esse trilho pulava o motor de ratchet, o CodeQL ratchet e todos os scanners de segurança — exatamente onde a rede era necessária (5 das 13 causas da reconciliação de 07-24 eram regressões reais shipadas por CI verde por-PR). Modo enxuto, jobs EXISTENTES (a .51 consolida lanes; nenhum job novo): - lint-guard: quality:collect + ratchet --allow-missing + require-tighten + check:codeql-ratchet. O job já escreve .artifacts/eslint-results.json, então o motor entra a custo ZERO de ESLint (um inventário, dois consumidores). Coverage ausente degrada gracioso (--allow-missing); autoridade de coverage segue no trilho A. + permissions security-events:read para o CodeQL ratchet. - fast-gates: check:cycles, check:lockfile, duplication, dead-code, type-coverage, compression-budget + install endurecido dos scanners (gh release download, zizmor PINADO 1.25.2 = mesmo auditor do ci.yml) + secrets/vuln/workflows/ openapi-breaking com --ratchet (self-skip sem binário; só regressão medida bloqueia). - Fora de propósito: bundle-size (self-skip sem build → configuração morta) e o run de coverage (fast-unit já roda a suíte cheia). Runners intocados: guard tests/unit/vps-runner-variable-scope.test.ts verde; teste novo tests/unit/quality-rail-gate-membership.test.ts pina a MEMBERSHIP dos gates no trilho B (red antes da edição, green depois). Validação no tip puro (nenhum base-red fabricado para a fila de PRs abertos): cycles OK · lockfile OK · duplication 4.26% (base 5.72%) · dead-code 226 (base 227) · type-coverage 94.13% (base 92.17%) · compression OK · secrets 0 (base 0) · vuln 5 (base 10) · codeql 0 (base 0) · oasdiff 0 (base 0) · zizmor 178 (base 190) · actionlint exit 0 no arquivo editado · quality-ratchet 56 métricas OK + require-tighten OK com --allow-missing. Refs #8084 * feat(.50): G13 golden-set, G14 import boundaries, gap34 deterministic, docs sync, R0.2 dead hooks Integra os itens restantes da 3.8.50: - G13: golden-set determinístico para combo.ts e chatCore.ts via seams públicas - G14: no-restricted-imports para localDb barrel fora de src/lib/db/ e executors em src/app/ - Gap34: teste determinístico de timeout DuckDuckGo sem rede real - Docs: golden path de contribuição + sincronização de números canônicos - R0.2: remoção dos 7 hooks mortos do BUILTIN_EVENTS + UI marketplace ajustada * fix(r0.2): remove marketplace tab remnants from plugins page — fixes dashboard typecheck regression * chore(r0.2): remove pluginWorker.ts, signing.ts, sandbox.ts — zero importers confirmed * fix(docs): remove OMNIROUTE_PLUGINS_ALLOW_EXEC reference — env var removed with pluginWorker.ts in R0.2 * fix(env): remove dead OMNIROUTE_PLUGINS_ALLOW_EXEC from .env.example — consumer removed in R0.2 * fix(test): update sidebar-visibility assertion for R0.2 marketplace removal --------- Co-authored-by: diegosouzapw <diegosouzapw@users.noreply.github.com>
This commit is contained in:
Diego Rodrigues de Sa e Souza
committed by
GitHub
GitHub
parent
45c91e22c2
commit
8fac6bcd48
229
docs/dev/CONTRIBUTION_GOLDEN_PATH.md
Normal file
229
docs/dev/CONTRIBUTION_GOLDEN_PATH.md
Normal file
@@ -0,0 +1,229 @@
|
||||
---
|
||||
title: "Contribution Golden Path"
|
||||
---
|
||||
|
||||
# Contribution Golden Path
|
||||
|
||||
Use this guide to choose the smallest reliable development loop for a pull request. It does not
|
||||
replace the area-specific architecture and security documents linked below; it connects each common
|
||||
change type to its contracts, focused checks, and CI coverage.
|
||||
|
||||
## The path every change follows
|
||||
|
||||
1. **Choose the base before editing.** Find the highest active `release/v*` branch and branch from
|
||||
its tip. Target that branch, not `main`. If a release freeze is active, do not target the frozen
|
||||
branch; use the next active cycle described in
|
||||
[Branching & Release Model](../ops/BRANCHING_MODEL.md).
|
||||
2. **Name the contracts.** Identify every catalog, schema, generated artifact, public API, or user
|
||||
interface that the change affects. The table below gives the minimum starting set.
|
||||
3. **Write or update focused tests.** Production changes in `src/`, `open-sse/`, `electron/`, or
|
||||
`bin/` require an automated test in the same PR. Run the smallest test files that prove the
|
||||
behavior, then the listed focused gates.
|
||||
4. **Let CI run the broad matrix.** The complete unit shards, Vitest, coverage ratchet, and
|
||||
production build run on the PR. Run a broad suite locally only when a focused failure points to
|
||||
wider impact or when the change spans several subsystems.
|
||||
5. **Reconcile before review.** Fetch the active base, inspect its new commits and your diff against
|
||||
it, then rebase or merge the base according to the contributor workflow. Resolve generated-file
|
||||
and catalog conflicts from their source, regenerate them, rerun the focused loop, and confirm the
|
||||
PR still targets the active release branch.
|
||||
6. **Record evidence.** In the PR template, list the commands run, every test file added or changed,
|
||||
migrations or feature flags, and any CI-only validation still pending.
|
||||
|
||||
## Golden paths by change type
|
||||
|
||||
Commands below are minimum focused checks, not permission to skip a test that directly covers the
|
||||
behavior you changed.
|
||||
|
||||
### Provider
|
||||
|
||||
**Contracts**
|
||||
|
||||
- Provider definition in `src/shared/constants/providers/` and its composition in
|
||||
`src/shared/constants/providers.ts`.
|
||||
- Models and capabilities in `open-sse/config/providerRegistry.ts` or its extracted registry files.
|
||||
- Executor/translator selection, OAuth or API-key configuration, dashboard assets, and generated
|
||||
provider reference when applicable.
|
||||
- Public credentials must use `resolvePublicCred()`; error responses must use the shared sanitized
|
||||
error helpers. See [Public Credentials](../security/PUBLIC_CREDS.md) and
|
||||
[Error Sanitization](../security/ERROR_SANITIZATION.md).
|
||||
|
||||
**Focused loop**
|
||||
|
||||
```bash
|
||||
npm run check:provider-consistency
|
||||
npm run check:provider-assets
|
||||
node --import tsx/esm --test tests/unit/provider-translate-path-golden.test.ts
|
||||
node --import tsx/esm --test tests/unit/<provider-or-executor>.test.ts
|
||||
npm run gen:provider-reference # when the catalog changes; commit the generated diff
|
||||
npm run lint
|
||||
```
|
||||
|
||||
Also test every affected request family: chat, Responses, images, embeddings, audio, or video.
|
||||
Review generated catalog and golden diffs as contract changes; do not accept them blindly.
|
||||
|
||||
### Routing
|
||||
|
||||
**Contracts**
|
||||
|
||||
- Public strategy values and UI metadata in `src/shared/constants/routingStrategies.ts`.
|
||||
- Dispatch and ordering under `open-sse/services/combo.ts` and `open-sse/services/combo/`.
|
||||
- Combo schemas, persistence, resilience state, model capabilities, and API/UI controls.
|
||||
- [Auto-Combo Engine](../routing/AUTO-COMBO.md) and resilience documentation when behavior changes.
|
||||
|
||||
**Focused loop**
|
||||
|
||||
```bash
|
||||
node --import tsx/esm --test tests/unit/combo-<behavior>.test.ts
|
||||
npm run test:combo:matrix # strategy or dispatch changes
|
||||
npm run check:known-symbols # strategy registration changes
|
||||
npm run lint
|
||||
```
|
||||
|
||||
Use deterministic mocked-upstream tests locally. Live combo smokes require credentials and are
|
||||
manual, not CI substitutes.
|
||||
|
||||
### UI / UX
|
||||
|
||||
**Contracts**
|
||||
|
||||
- Next.js route/page and shared component boundaries under `src/app/` and
|
||||
`src/shared/components/`.
|
||||
- API response shapes, loading/empty/error states, keyboard and screen-reader behavior,
|
||||
responsive layout, theming, and locale expansion.
|
||||
- English UI source strings in `src/i18n/messages/en.json`; do not hard-code new user-facing copy.
|
||||
|
||||
**Focused loop**
|
||||
|
||||
```bash
|
||||
node --import tsx --test tests/unit/dashboard/<feature>.test.ts
|
||||
npx vitest run --config vitest.config.ts tests/unit/ui/<component>.test.tsx
|
||||
npm run check:dashboard-typecheck
|
||||
npm run lint
|
||||
```
|
||||
|
||||
Run the app for interaction or visual changes and check both narrow and wide viewports. CI runs the
|
||||
production build and broader suites; visual behavior still needs a focused component, Playwright,
|
||||
or documented manual check appropriate to the change.
|
||||
|
||||
### i18n
|
||||
|
||||
**Contracts**
|
||||
|
||||
- `src/i18n/messages/en.json` is the UI source; `config/i18n.json` is the locale source.
|
||||
- CLI catalogs live separately under `bin/cli/locales/`.
|
||||
- Preserve ICU placeholders and tags exactly. Do not translate product/provider/model names,
|
||||
protocol and header names, commands, code/JSON identifiers, URLs, environment variables, or
|
||||
protected terms such as `OmniRoute`, `OAuth`, `MCP`, and `A2A`. The current source list is
|
||||
`scripts/i18n/glossary/protected-terms.json`.
|
||||
|
||||
**Focused loop**
|
||||
|
||||
```bash
|
||||
npm run i18n:sync-ui:dry
|
||||
npm run i18n:check-ui-coverage
|
||||
npm run i18n:check-value-drift
|
||||
npm run i18n:check-glossary
|
||||
npm run check:cli-i18n # when CLI strings/catalogs change
|
||||
npm run lint
|
||||
```
|
||||
|
||||
This is guidance for the existing system, not an invitation to expand its tooling or key model.
|
||||
Keep i18n patches surgical while the replacement system is being designed. Do not run translation
|
||||
commands that call external services unless the task explicitly requires generated translations and
|
||||
you have reviewed the resulting diff.
|
||||
|
||||
### CLI
|
||||
|
||||
**Contracts**
|
||||
|
||||
- Public commands and flags in `bin/cli/`, generated API commands, exit codes, stdout/stderr and
|
||||
JSON output shapes, config/environment behavior, and packaged files.
|
||||
- CLI user-facing strings must use the CLI i18n layer and keep `en`/`pt-BR` catalogs aligned.
|
||||
- Preserve Node as the supported runtime and the published binary contract.
|
||||
|
||||
**Focused loop**
|
||||
|
||||
```bash
|
||||
node --import tsx/esm --test tests/unit/cli/<command>.test.ts
|
||||
npm run check:cli-i18n
|
||||
npm run build:cli # generated/bundled CLI changes
|
||||
npm run check:pack-policy # package-surface changes
|
||||
npm run lint
|
||||
```
|
||||
|
||||
Use the exact command in a temporary data directory when behavior depends on parsing, files, or exit
|
||||
status. CI performs the broader package artifact and ecosystem checks.
|
||||
|
||||
### Database
|
||||
|
||||
**Contracts**
|
||||
|
||||
- Domain modules under `src/lib/db/`; `src/lib/localDb.ts` remains a re-export layer only.
|
||||
- Numbered, idempotent SQL migrations under `src/lib/db/migrations/`, transaction safety, upgrade
|
||||
behavior, indexes, and every caller affected by the schema.
|
||||
- Routes and handlers never issue raw SQL directly.
|
||||
|
||||
**Focused loop**
|
||||
|
||||
```bash
|
||||
npm run check:migration-numbering
|
||||
npm run check:db-rules
|
||||
node --import tsx/esm --test tests/unit/db/<domain>.test.ts
|
||||
node --import tsx/esm --test tests/unit/db/migration-<number>.test.ts
|
||||
npm run lint
|
||||
```
|
||||
|
||||
Test both a fresh database and upgrade from the prior schema when adding a migration. Database tests
|
||||
must close handles and call `resetDbInstance()` during cleanup. Run `npm run test:bun:db` only when
|
||||
the best-effort Bun adapter path changes; Node remains authoritative.
|
||||
|
||||
### Build / deploy
|
||||
|
||||
**Contracts**
|
||||
|
||||
- Root and workspace manifests/lockfile, `scripts/build/`, Next.js standalone assembly, `dist/`
|
||||
package contents, Electron platform metadata, CI workflows, and deployment sentinels.
|
||||
- Supported Node ranges and the allow-listed Bun use in `CLAUDE.md` must remain intact.
|
||||
- Build artifacts stay untracked; dependency, license, workflow, and package policies apply.
|
||||
|
||||
**Focused loop**
|
||||
|
||||
```bash
|
||||
node --import tsx/esm --test tests/unit/build/<behavior>.test.ts
|
||||
npm run check:build-scope
|
||||
npm run check:lockfile # dependency or lockfile changes
|
||||
npm run check:pack-policy # published package surface changes
|
||||
npm run lint
|
||||
```
|
||||
|
||||
Use `npm run build` locally only when the change affects compilation, standalone assembly, assets,
|
||||
or runtime bundling. Use `npm run build:release` only for release/deploy validation. CI's build is
|
||||
the final cross-platform signal; platform-specific Electron changes need the matching focused build
|
||||
or smoke evidence.
|
||||
|
||||
## Local loop versus CI
|
||||
|
||||
| Run locally for each patch | CI supplies the broad signal |
|
||||
| ----------------------------------------------------------------------------- | ----------------------------------------------------------------- |
|
||||
| Direct behavior tests and category gates above | Sharded full unit suite and serial tests |
|
||||
| `npm run lint` | Vitest suites and coverage/quality ratchets |
|
||||
| Typecheck or build only when the affected contract calls for it | Production build, security, docs, dependency, and PR-policy gates |
|
||||
| Manual interaction/live checks only when automation cannot prove the behavior | Cross-job integration and platform checks configured by workflow |
|
||||
|
||||
A green focused loop is evidence about the changed contract, not proof that unrelated CI checks
|
||||
will pass. Conversely, do not make every local edit wait for the full repository matrix.
|
||||
|
||||
## Reconciliation checklist
|
||||
|
||||
Before requesting review:
|
||||
|
||||
- Confirm the PR base is still the highest active `release/v*` branch.
|
||||
- Fetch that base and review commits that landed since you branched.
|
||||
- Review `git diff <active-base>...HEAD` for accidental or generated churn.
|
||||
- Resolve catalog and generated-document conflicts by updating the source and regenerating output.
|
||||
- Rerun every focused test/gate listed in the PR description after reconciliation.
|
||||
- Never weaken assertions or drop required tests merely to match a moved base.
|
||||
|
||||
For release-freeze and retargeting rules, use
|
||||
[Branching & Release Model](../ops/BRANCHING_MODEL.md). For the complete CI inventory, use
|
||||
[Quality Gates Reference](../architecture/QUALITY_GATES.md).
|
||||
Reference in New Issue
Block a user