@ihelpee/prumo-plugin-python-fastapi 0.8.3 → 0.9.0

package/README.md

@@ -1,18 +1,18 @@
 # @ihelpee/prumo-plugin-python-fastapi
 
-Invariantes Python/FastAPI para o [Prumo](../../packages/prumo): guards de auth em rotas de mutação, validação Pydantic v2 em DTOs de request e isolamento de oráculo pytest — inclusive contra burla por `importlib`.
+Python/FastAPI invariants for [Prumo](../../packages/prumo): auth guards on mutation routes, Pydantic v2 validation on request DTOs, and pytest oracle isolation — including against `importlib` bypass.
 
-**A lei fica no core Node.** Este pacote é um plugin npm (spec §4.2 — nunca um pacote PyPI): ele embute um único script Python stdlib (`python/ast_extractor.py`) que apenas serializa AST em JSON canônico v1 via subprocesso isolado. O parser decide zero; "é violação?" é 100% do motor. O app do consumidor nunca dá boot e nada do código analisado é importado/executado.
+**The law lives in the Node core.** This package is an npm plugin (spec §4.2 — never a PyPI package): it embeds a single stdlib-only Python script (`python/ast_extractor.py`) that merely serializes the AST into canonical JSON v1 via an isolated subprocess. The parser decides nothing; "is this a violation?" is 100% the engine's job. The consumer app is never booted and none of the analyzed code is imported or executed.
 
-## Instalação
+## Installation
 
 ```bash
 pnpm add -D @ihelpee/prumo-plugin-python-fastapi
 ```
 
-Requer `python3 >= 3.9` no PATH do host do gate (não do deploy). Sem Python, os invariantes Python viram no-op com motivo explícito no report — nunca silencioso.
+Requires `python3 >= 3.9` on the gate host's PATH (not the deployment target). Without Python, the Python invariants become a no-op with an explicit reason in the report — never silent.
 
-## Uso
+## Usage
 
 ```ts
 // prumo.config.ts
@@ -33,9 +33,9 @@ export default defineConfig({
 });
 ```
 
-> Registre em `invariants:` — o campo `plugins:` da doc antiga é inerte (spec §4.4).
+> Register under `invariants:` — the `plugins:` field from the old docs is inert (spec §4.4).
 
-Ou via arquivo de regras (onde vivem os waivers):
+Or via a rules file (where the waivers live):
 
 ```ts
 // .prumo/invariants/rules.ts
@@ -43,32 +43,33 @@ import { pythonFastapiPreset } from '@ihelpee/prumo-plugin-python-fastapi';
 export default pythonFastapiPreset;
 ```
 
-## Opções (`pythonFastapi(options?)`)
+## Options (`pythonFastapi(options?)`)
 
-| Opção | Default | Efeito |
+| Option | Default | Effect |
 |---|---|---|
-| `srcDirs` | `['app']` | Diretórios de produção (módulos Python) |
-| `oracleDirs` | `['tests/oracle']` | Diretórios onde importar `app.*` é espelho |
-| `testRoots` | `['tests']` | Fronteira reversa R2.7 (produção não importa fixture) |
-| `packageRoot` | `'app'` | Pacote raiz para resolver imports relativos |
-| `entrypoints` | `['app.main']` | Composition roots permitidos ao oráculo (black-box por ASGI) |
-| `authSymbols` | `get_current_user`, `current_user`, `get_current_active_user`, `require_auth`, `auth_required` | Símbolos reconhecidos como guard em `Depends(...)` |
-| `publicSymbols` | `[]` | Convenção de rota intencionalmente pública (FastAPI não tem `@Public` nativo) |
+| `srcDirs` | `['app']` | Production directories (Python modules) |
+| `oracleDirs` | `['tests/oracle']` | Directories where importing `app.*` is a mirror |
+| `testRoots` | `['tests']` | Reverse boundary R2.7 (production must not import fixtures) |
+| `packageRoot` | `'app'` | Root package used to resolve relative imports |
+| `entrypoints` | `['app.main']` | Composition roots the oracle may use (black-box via ASGI) |
+| `authSymbols` | `get_current_user`, `current_user`, `get_current_active_user`, `require_auth`, `auth_required` | Symbols recognized as an auth guard in `Depends(...)` |
+| `publicSymbols` | `[]` | Convention for intentionally public routes (FastAPI has no native `@Public`) |
 
-## Invariantes
+## Invariants
 
-| Regra | Sev | Pega | Não pega |
+| Rule | Sev | Catches | Does not catch |
 |---|---|---|---|
-| `mutation-routes-guarded` | error | `POST/PUT/PATCH/DELETE` sem `Depends` de auth no handler, sem `dependencies=` no decorator e sem `APIRouter(dependencies=)`/`include_router(dependencies=)` (inclusive cross-file) | rotas de leitura; rotas marcadas via `publicSymbols` |
-| `dto-has-validation` | error | model Pydantic usado como **body** com campo sem `Field(...)`/`Annotated`/`con*`/`EmailStr`/validator | `response_model` (saída não valida input); `Optional` sem default (opcional legítimo) |
-| `route-has-response-model` | warn | mutação sem `response_model` (risco de vazar ORM/dict cru) | rotas de leitura |
-| `no-cross-feature-import` | warn | `app/<A>/` importando `app/<B>/` (absoluto, relativo e dinâmico) | entrypoint/composition root; módulos compartilhados (`common`, `core`, `auth`, …) |
-| `monetary-is-integer` | warn | campo monetário (`price`, `amount`, …) tipado `float` | `Decimal`, inteiro em centavos |
-| `oracle-no-src` | error | `tests/oracle/**` importando unidade de `app/` — **inclusive** `importlib.import_module`/`__import__` (anti-burla R2.4) | import do entrypoint (`app.main`): oráculo black-box sobe o app pelo composition root |
-| `src-no-oracle` | error | `app/**` importando `tests/**` (fixture vazando para produção) | — |
-| `python-parse-error` | error | `SyntaxError` por arquivo; timeout do parser; `python3` ausente (via `erroredRules`, gate não crasha) | — |
-
-## Exemplo — o buraco invisível do FastAPI
+| `mutation-routes-guarded` | error | `POST/PUT/PATCH/DELETE` without an auth `Depends` on the handler, without `dependencies=` on the decorator, and without `APIRouter(dependencies=)`/`include_router(dependencies=)` (including cross-file) | read routes; routes marked via `publicSymbols` |
+| `dto-has-validation` | error | a Pydantic model used as **body** with a field lacking `Field(...)`/`Annotated`/`con*`/`EmailStr`/validator | `response_model` (output does not validate input); `Optional` without default (legitimate optional); `pydantic.v1` files (handled by the sibling rule below) |
+| `dto-has-validation-pydantic-v1` | warn | same predicate as `dto-has-validation` for files containing `import pydantic.v1` (R3.6: v1 is deprecated — downgraded to warn) | models in v2 files; fields with `@validator`/`Field(regex=...)` v1 (recognized constraint) |
+| `route-has-response-model` | warn | mutation without `response_model` (risk of leaking raw ORM/dict) | read routes |
+| `no-cross-feature-import` | warn | `app/<A>/` importing `app/<B>/` (absolute, relative, and dynamic) | entrypoint/composition root; shared modules (`common`, `core`, `auth`, …) |
+| `monetary-is-integer` | warn | monetary field (`price`, `amount`, …) typed as `float` | `Decimal`, integer in cents |
+| `oracle-no-src` | error | `tests/oracle/**` importing a unit from `app/` — **including** `importlib.import_module`/`__import__` (anti-bypass R2.4) | importing the entrypoint (`app.main`): a black-box oracle boots the app through the composition root |
+| `src-no-oracle` | error | `app/**` importing `tests/**` (fixtures leaking into production) | — |
+| `python-parse-error` | error | `SyntaxError` per file; parser timeout; missing `python3` (via `erroredRules`, the gate does not crash) | — |
+
+## Example — FastAPI's invisible hole
 
 ```python
 # app/orders/router.py — a rota FUNCIONA sem token; o teste com AsyncClient
@@ -92,10 +93,17 @@ class CreateOrderIn(BaseModel):
     email: Annotated[str, Field(max_length=255)]        # ok
 ```
 
-## Contrato de AST (JSON canônico v1)
+## AST contract (canonical JSON v1)
+
+`python/ast_extractor.py --files <...>` emits `{"version": 1, "files": [...]}` with per-file `imports`, `dynamic_imports`, `routes`, `models`, `routers`, `include_routers`, `pydantic_v1` (spec §1.4). The format is frozen and versioned; `SyntaxError` becomes `{"path", "error": "syntax"}` with exit 0.
+
+---
+
+## License & Brand
 
-`python/ast_extractor.py --files <...>` emite `{"version": 1, "files": [...]}` com `imports`, `dynamic_imports`, `routes`, `models`, `routers`, `include_routers`, `pydantic_v1` por arquivo (spec §1.4). Formato congelado e versionado; `SyntaxError` vira `{"path", "error": "syntax"}` com exit 0.
+Copyright © 2026 **IHELPEE TECNOLOGIA LTDA** (<https://ihelpee.com>). All rights reserved.
+Created and authored by [Alex Gotardi](https://github.com/alexgotardi).
 
-## Licença
+Licensed under the [Apache License, Version 2.0](https://github.com/ihelpee/prumo/blob/main/LICENSE) (the "License"); you may not use this file except in compliance with the License. A copy is available at <http://www.apache.org/licenses/LICENSE-2.0>.
 
-Apache-2.0
+The **"Prumo"** name and logo are trademarks of IHELPEE TECNOLOGIA LTDA and are **not** licensed under the Apache 2.0 license.

package/dist/rules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../src/rules.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,OAAO,EAGb,MAAM,2BAA2B,CAAC;AAanC,MAAM,WAAW,mBAAmB;IAClC,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qGAAqG;IACrG,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,sEAAsE;IACtE,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAmWD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,mBAAwB,GAAG,WAAW,CA4B5E;AAED,8FAA8F;AAC9F,eAAO,MAAM,mBAAmB,EAAE,OAAO,EAA0B,CAAC"}
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../src/rules.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,OAAO,EAGb,MAAM,2BAA2B,CAAC;AAanC,MAAM,WAAW,mBAAmB;IAClC,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qGAAqG;IACrG,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,sEAAsE;IACtE,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAwXD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,mBAAwB,GAAG,WAAW,CA6B5E;AAED,8FAA8F;AAC9F,eAAO,MAAM,mBAAmB,EAAE,OAAO,EAA0B,CAAC"}

package/dist/rules.js

@@ -1,3 +1,4 @@
+import pkg from '../package.json' with { type: 'json' };
 import { rule, definePlugin, } from '@ihelpee/prumo/invariants';
 import { extractPythonModel } from './ast.js';
 /**
@@ -165,38 +166,58 @@ const mutationRoutesGuarded = (opts) => rule('mutation-routes-guarded')
  * constraint de domínio nem validator. `Optional` sem default não é
  * violação (opcional legítimo). Fronteira honesta: response_model não é
  * alvo — serialização de saída não valida input.
+ *
+ * R3.6 (downgrade v1) — o extractor serializa `pydantic_v1` por arquivo
+ * (import `pydantic.v1`/`pydantic.v1.*`). A spec exige que Pydantic v1
+ * (`@validator`, `Field(regex=...)`) seja `warn`, não `error`: v1 está
+ * deprecado e a equipe pode estar em migração. Como a severidade é por
+ * regra (não por alvo), a lei é espelhada em duas regras irmãs com o mesmo
+ * predicado, particionadas pelo flag do arquivo onde o MODEL está definido
+ * (é lá que vivem `@validator`/`Field(regex=...)`):
+ *   - `dto-has-validation`            → arquivos v2 (error)
+ *   - `dto-has-validation-pydantic-v1` → arquivos v1 (warn)
+ * O downgrade é keyed no arquivo do model, não no da rota: a constraint
+ * ausente é um fato do model.
  */
-const dtoHasValidation = rule('dto-has-validation')
-    .needsData('python')
-    .message('modelo Pydantic usado como body de rota sem Field(...)/Annotated/constraint/validator no campo: o FastAPI valida o que existe e ignora o que falta')
-    .assert((ctx) => {
-    const m = modelIfAvailable(ctx);
-    if (!m)
-        return [];
-    const bodyModels = new Set();
-    for (const file of m.files) {
-        for (const r of file.routes ?? []) {
-            if (r.body_model)
-                bodyModels.add(r.body_model);
+function dtoHasValidationFor(pydanticV1) {
+    return rule(pydanticV1 ? 'dto-has-validation-pydantic-v1' : 'dto-has-validation')
+        .severity(pydanticV1 ? 'warn' : 'error')
+        .needsData('python')
+        .message(pydanticV1
+        ? 'modelo Pydantic v1 (import pydantic.v1) usado como body de rota sem Field(...)/constraint/validator no campo: v1 está deprecado — downgrade para warn (R3.6); migre para v2 e a ausência volta a ser error'
+        : 'modelo Pydantic usado como body de rota sem Field(...)/Annotated/constraint/validator no campo: o FastAPI valida o que existe e ignora o que falta')
+        .assert((ctx) => {
+        const m = modelIfAvailable(ctx);
+        if (!m)
+            return [];
+        const bodyModels = new Set();
+        for (const file of m.files) {
+            for (const r of file.routes ?? []) {
+                if (r.body_model)
+                    bodyModels.add(r.body_model);
+            }
         }
-    }
-    const out = [];
-    for (const file of m.files) {
-        for (const mod of file.models ?? []) {
-            if (!bodyModels.has(mod.name))
+        const out = [];
+        for (const file of m.files) {
+            // Partição R3.6: cada regra irmã vê apenas os arquivos da sua versão.
+            if (Boolean(file.pydantic_v1) !== pydanticV1)
                 continue;
-            const bad = mod.fields.filter((f) => !f.has_constraint && !f.has_validator);
-            if (bad.length === 0)
-                continue;
-            out.push({
-                target: `${mod.name}.${bad.map((f) => f.name).join(', ')}`,
-                location: `${file.path}:${mod.line}`,
-            });
+            for (const mod of file.models ?? []) {
+                if (!bodyModels.has(mod.name))
+                    continue;
+                const bad = mod.fields.filter((f) => !f.has_constraint && !f.has_validator);
+                if (bad.length === 0)
+                    continue;
+                out.push({
+                    target: `${mod.name}.${bad.map((f) => f.name).join(', ')}`,
+                    location: `${file.path}:${mod.line}`,
+                });
+            }
         }
-    }
-    return out;
-})
-    .build();
+        return out;
+    })
+        .build();
+}
 /**
  * R3.8 — rota de mutação sem response_model: o handler devolve o ORM/dict
  * cru e vaza campos internos (password_hash). Warn: heurística de contrato.
@@ -383,7 +404,7 @@ export function pythonFastapi(options = {}) {
     const publicSymbols = options.publicSymbols ?? [];
     return definePlugin({
         name: 'python-fastapi',
-        version: '0.1.0',
+        version: pkg.version,
         description: 'Python/FastAPI invariants: mutation-route auth guards (Depends/router/include_router), Pydantic v2 body validation, oracle isolation (incl. importlib anti-burla).',
         extractors: {
             python: (ctx) => extractPythonModel(ctx.root),
@@ -391,7 +412,8 @@ export function pythonFastapi(options = {}) {
         rules: [
             pythonParseHealth,
             mutationRoutesGuarded({ authSymbols, publicSymbols }),
-            dtoHasValidation,
+            dtoHasValidationFor(false),
+            dtoHasValidationFor(true),
             routeHasResponseModel,
             noCrossFeatureImport({ packageRoot, entrypoints }),
             monetaryIsFloat,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ihelpee/prumo-plugin-python-fastapi",
-  "version": "0.8.3",
+  "version": "0.9.0",
   "type": "module",
   "description": "Python/FastAPI plugin for Prumo: mutation-route auth guards (Depends), Pydantic v2 DTO validation, and oracle isolation for pytest.",
   "author": "Alex Gotardi <alexgotardi@gmail.com>",
@@ -33,6 +33,6 @@
     "access": "public"
   },
   "dependencies": {
-    "@ihelpee/prumo": "0.8.3"
+    "@ihelpee/prumo": "0.9.0"
   }
 }