@ihelpee/prumo-plugin-python-fastapi 0.0.0-stage → 0.9.0

package/dist/rules.js

@@ -0,0 +1,426 @@
+import pkg from '../package.json' with { type: 'json' };
+import { rule, definePlugin, } from '@ihelpee/prumo/invariants';
+import { extractPythonModel } from './ast.js';
+/**
+ * Invariantes Python/FastAPI (spec `docs/especificacao-prumo-python.md` §2/§3).
+ *
+ * A lei fica 100% aqui (core Node). O subprocesso Python é parser, não
+ * oráculo: serializa AST em JSON e decide zero. Cada regra declara o que NÃO
+ * pega (fronteiras honestas, Art. IV).
+ */
+const MUTATING = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+const DEFAULT_AUTH_SYMBOLS = [
+    'get_current_user',
+    'current_user',
+    'get_current_active_user',
+    'require_auth',
+    'auth_required',
+];
+const SHARED = new Set(['common', 'shared', 'core', 'config', 'database', 'schemas', 'models', 'deps', 'dependencies', 'auth']);
+const MONETARY_NAME = /(price|amount|total|cost|balance|salary|subtotal|discount|fee)/i;
+function model(ctx) {
+    return ((ctx.get('python') ?? {
+        version: 1,
+        files: [],
+        pythonAvailable: false,
+        timedOut: false,
+    }));
+}
+/**
+ * R1.4 — python3 ausente: as regras de domínio viram no-op (skip com motivo
+ * vive em `python-parse-error`, que é a única que reporta a indisponibilidade
+ * via erro de regra — visível em `erroredRules`, nunca crash do gate).
+ */
+function modelIfAvailable(ctx) {
+    const m = model(ctx);
+    return m.pythonAvailable ? m : null;
+}
+/**
+ * R1.3/R1.4/R1.5 — o parser nunca é silencioso.
+ * SyntaxError vira finding `error`; timeout vira finding próprio;
+ * `python3` ausente vira finding `warn` com motivo (a lei não foi
+ * verificada: aparece, conta, é promovível — e `--fail-on-warn` bloqueia).
+ * As demais regras viram no-op nesse caso (skip com motivo, nunca crash).
+ */
+const pythonParseHealth = rule('python-parse-error')
+    .needsData('python')
+    .message('arquivo Python não pôde ser parseado (SyntaxError) ou o parser não rodou — invariante não verificado')
+    .assert((ctx) => {
+    const m = model(ctx);
+    if (!m.pythonAvailable) {
+        return [
+            {
+                target: `parser Python indisponível: ${m.reason ?? 'motivo desconhecido'} — invariantes Python não verificados`,
+            },
+        ];
+    }
+    const out = [];
+    for (const f of m.files) {
+        if (f.error === 'syntax') {
+            out.push({ target: `${f.path} (SyntaxError)`, location: f.path });
+        }
+        else if (f.error === 'unreadable') {
+            out.push({ target: `${f.path} (ilegível)`, location: f.path });
+        }
+    }
+    if (m.timedOut) {
+        out.push({ target: 'python-parse-timeout (subprocesso morto no timeout — parse patológico?)' });
+    }
+    return out;
+})
+    .build();
+/** Dependências de router resolvidas: definição `APIRouter(...)` no próprio arquivo (R3.3). */
+function routerLevelDeps(file) {
+    const deps = new Map();
+    for (const r of file.routers ?? []) {
+        deps.set(r.var, [...(deps.get(r.var) ?? []), ...r.dependencies]);
+    }
+    for (const inc of file.include_routers ?? []) {
+        if (inc.dependencies.length === 0)
+            continue;
+        const varName = inc.target.split('.').pop() ?? inc.target;
+        deps.set(varName, [...(deps.get(varName) ?? []), ...inc.dependencies]);
+    }
+    return deps;
+}
+const fileModule = (path) => path.replace(/\.py$/, '').replace(/\//g, '.');
+/**
+ * R3.3 cross-file: `app.include_router(billing_router, dependencies=[...])`
+ * em `main.py` protege as rotas declaradas em OUTRO arquivo
+ * (`app/billing/router.py`). Resolve o alias do import (`import router as
+ * billing_router`) para o módulo de origem e propaga as dependências para o
+ * módulo do router — sem isto, a camada que mais existe na prática seria
+ * cega e a regra geraria falso-positivo em todo app FastAPI idiomático.
+ */
+function moduleRouterDeps(m) {
+    const deps = new Map();
+    for (const file of m.files) {
+        const local = routerLevelDeps(file);
+        const localModule = fileModule(file.path);
+        for (const [varName, list] of local) {
+            // dependências definidas na própria arquivo valem para o módulo.
+            deps.set(localModule, [...(deps.get(localModule) ?? []), ...list]);
+        }
+        for (const inc of file.include_routers ?? []) {
+            if (inc.dependencies.length === 0)
+                continue;
+            const alias = inc.target.split('.').pop() ?? inc.target;
+            // alias → módulo de origem via imports do arquivo que monta.
+            let sourceModule = null;
+            for (const imp of file.imports ?? []) {
+                if (imp.names.includes(alias)) {
+                    sourceModule = imp.module;
+                    break;
+                }
+            }
+            // alias local (mesmo arquivo) ou montagem de app raiz: mantém por módulo atual.
+            const key = sourceModule ?? localModule;
+            deps.set(key, [...(deps.get(key) ?? []), ...inc.dependencies]);
+        }
+    }
+    return deps;
+}
+function routesOf(m) {
+    const byModule = moduleRouterDeps(m);
+    const out = [];
+    for (const file of m.files) {
+        const moduleDeps = byModule.get(fileModule(file.path)) ?? [];
+        for (const route of file.routes ?? []) {
+            out.push({ file, route, routerDeps: moduleDeps });
+        }
+    }
+    return out;
+}
+/**
+ * R3.1–R3.4 — rota de mutação sem auth em NENHUMA camada:
+ * Depends de auth no handler, dependencies no decorator, nem camada de
+ * router (APIRouter/include_router — a que mais gera falso-negativo).
+ * Não pega: rota de leitura; rota marcada pública via publicSymbols.
+ */
+const mutationRoutesGuarded = (opts) => rule('mutation-routes-guarded')
+    .needsData('python')
+    .message('rota de mutação FastAPI sem Depends de auth no handler, no decorator nem na camada do router (a ausência é invisível: a rota funciona sem token)')
+    .assert((ctx) => {
+    const m = modelIfAvailable(ctx);
+    if (!m)
+        return [];
+    const out = [];
+    for (const { file, route, routerDeps } of routesOf(m)) {
+        if (!MUTATING.has(route.method))
+            continue;
+        const allDeps = [...route.param_depends, ...route.router_dependencies, ...routerDeps];
+        if (allDeps.some((d) => opts.publicSymbols.includes(d)))
+            continue;
+        if (allDeps.some((d) => opts.authSymbols.includes(d)))
+            continue;
+        out.push({
+            target: `${route.method} ${route.path} (${route.handler})`,
+            location: `${file.path}:${route.line}`,
+        });
+    }
+    return out;
+})
+    .build();
+/**
+ * R3.5–R3.7 — Pydantic model usado como BODY de rota com campo sem
+ * 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.
+ */
+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) {
+            // Partição R3.6: cada regra irmã vê apenas os arquivos da sua versão.
+            if (Boolean(file.pydantic_v1) !== pydanticV1)
+                continue;
+            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();
+}
+/**
+ * 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.
+ */
+const routeHasResponseModel = rule('route-has-response-model')
+    .severity('warn')
+    .needsData('python')
+    .message('rota de mutação sem response_model: risco de vazar o ORM/dict cru (password_hash) na resposta')
+    .assert((ctx) => {
+    const m = modelIfAvailable(ctx);
+    if (!m)
+        return [];
+    const out = [];
+    for (const { file, route } of routesOf(m)) {
+        if (!MUTATING.has(route.method))
+            continue;
+        if (route.response_model)
+            continue;
+        out.push({
+            target: `${route.method} ${route.path} (${route.handler})`,
+            location: `${file.path}:${route.line}`,
+        });
+    }
+    return out;
+})
+    .build();
+function featureOfModule(module, packageRoot) {
+    const parts = module.split('.');
+    if (parts[0] !== packageRoot)
+        return null;
+    const feature = parts[1];
+    if (!feature || SHARED.has(feature))
+        return null;
+    return feature;
+}
+/**
+ * R3.9 — `app/<featureA>/` importando `app/<featureB>/` (fronteira de
+ * contexto). Warn no MVP: layouts Python variam demais.
+ */
+const noCrossFeatureImport = (opts) => rule('no-cross-feature-import')
+    .severity('warn')
+    .needsData('python')
+    .message('import entre features do pacote raiz (fronteira de contexto atravessada)')
+    .assert((ctx) => {
+    const m = modelIfAvailable(ctx);
+    if (!m)
+        return [];
+    const out = [];
+    for (const file of m.files) {
+        const fileModule = file.path.replace(/\.py$/, '').replace(/\//g, '.');
+        // Composition root cabula features de propósito: entrypoint é isento.
+        if (opts.entrypoints.includes(fileModule))
+            continue;
+        const fromFeature = featureOfModule(fileModule, opts.packageRoot);
+        for (const imp of file.imports ?? []) {
+            const toFeature = featureOfModule(imp.module, opts.packageRoot);
+            if (!fromFeature || !toFeature || fromFeature === toFeature)
+                continue;
+            out.push({ target: `${file.path}:${imp.line} -> ${imp.module}`, location: file.path });
+        }
+    }
+    return out;
+})
+    .build();
+/**
+ * R3.10 — campo monetário como `float`. `Decimal` é aceitável; `float` é
+ * o anti-padrão (erro de arredondamento binário em dinheiro).
+ */
+const monetaryIsFloat = rule('monetary-is-integer')
+    .severity('warn')
+    .needsData('python')
+    .message('campo monetário tipado como float — use Decimal ou inteiro em centavos')
+    .assert((ctx) => {
+    const m = modelIfAvailable(ctx);
+    if (!m)
+        return [];
+    const out = [];
+    for (const file of m.files) {
+        for (const mod of file.models ?? []) {
+            for (const f of mod.fields) {
+                if (!MONETARY_NAME.test(f.name))
+                    continue;
+                if (!/^(float|double)$/.test(f.annotation.toLowerCase()))
+                    continue;
+                out.push({ target: `${mod.name}.${f.name}: ${f.annotation}`, location: `${file.path}:${mod.line}` });
+            }
+        }
+    }
+    return out;
+})
+    .build();
+/** Aresta de import Python (estática + dinâmica anti-burla) como string de módulo. */
+function moduleEdges(file) {
+    const out = [];
+    for (const imp of file.imports ?? [])
+        out.push({ module: imp.module, line: imp.line, dynamic: false });
+    for (const dyn of file.dynamic_imports ?? [])
+        out.push({ module: dyn.module, line: dyn.line, dynamic: true });
+    return out;
+}
+const startsWithModule = (module, prefix) => module === prefix || module.startsWith(prefix + '.');
+const dirToModulePrefix = (dir) => dir.replace(/\\/g, '/').replace(/\/+$/, '').replace(/\/__init__.*$/, '').replace(/\//g, '.');
+/**
+ * A LEI, traduzida para Python (§2): `tests/oracle/` é proibido de importar
+ * as unidades de `app/`. Cobre absolute (R2.1), plain (R2.2), relative
+ * resolvido (R2.3) e dynamic importlib/__import__ (R2.4 — sem isto o agente
+ * burla o gate trocando import por importlib). Entrypoint/composition root
+ * (ex.: `app.main`) é permitido: oráculo black-box sobe o app pelo
+ * entrypoint público, não importa a unidade sob teste.
+ */
+const oracleNoSrc = (opts) => rule('oracle-no-src')
+    .needsData('python')
+    .message('teste de oráculo importa unidade de produção: é espelho, não oráculo. Suba o app pelo entrypoint (ex.: app.main) e derive a expectativa do contrato')
+    .assert((ctx) => {
+    const m = modelIfAvailable(ctx);
+    if (!m)
+        return [];
+    const srcPrefixes = opts.srcDirs.map(dirToModulePrefix);
+    const oraclePrefixes = opts.oracleDirs.map(dirToModulePrefix);
+    const out = [];
+    for (const file of m.files) {
+        const fileModule = file.path.replace(/\.py$/, '').replace(/\//g, '.');
+        if (!oraclePrefixes.some((p) => fileModule === p || fileModule.startsWith(p + '.')))
+            continue;
+        for (const edge of moduleEdges(file)) {
+            if (!srcPrefixes.some((p) => startsWithModule(edge.module, p)))
+                continue;
+            if (opts.entrypoints.includes(edge.module))
+                continue;
+            out.push({
+                target: `${file.path}:${edge.line} -> ${edge.module}${edge.dynamic ? ' (dynamic import)' : ''}`,
+                location: file.path,
+            });
+        }
+    }
+    return out;
+})
+    .build();
+/**
+ * R2.7 — fronteira reversa: produção proibida de importar fixture de teste
+ * (equivalente exato do `src-no-oracle` do core TS).
+ */
+const srcNoOracle = (opts) => rule('src-no-oracle')
+    .needsData('python')
+    .message('implementação importa fixture de teste: espelho indireto vazando para produção')
+    .assert((ctx) => {
+    const m = modelIfAvailable(ctx);
+    if (!m)
+        return [];
+    const srcPrefixes = opts.srcDirs.map(dirToModulePrefix);
+    const out = [];
+    for (const file of m.files) {
+        const fileModule = file.path.replace(/\.py$/, '').replace(/\//g, '.');
+        if (!srcPrefixes.some((p) => startsWithModule(fileModule, p)))
+            continue;
+        for (const edge of moduleEdges(file)) {
+            if (!opts.testRoots.some((t) => startsWithModule(edge.module, t)))
+                continue;
+            out.push({
+                target: `${file.path}:${edge.line} -> ${edge.module}`,
+                location: file.path,
+            });
+        }
+    }
+    return out;
+})
+    .build();
+/**
+ * O Plugin oficial Python/FastAPI para o Prumo (spec §4.2: plugin npm,
+ * NUNCA pacote PyPI — a lei mora no core Node; o `.py` embutido é parser).
+ *
+ * Uso (spec §4.4 — `invariants:`, não o campo inerte `plugins:`):
+ *
+ *   import { pythonFastapi } from '@ihelpee/prumo-plugin-python-fastapi';
+ *   export default defineConfig({ invariants: [ pythonFastapi() ], ... });
+ */
+export function pythonFastapi(options = {}) {
+    const srcDirs = options.srcDirs ?? ['app'];
+    const oracleDirs = options.oracleDirs ?? ['tests/oracle'];
+    const testRoots = options.testRoots ?? [...new Set([...oracleDirs.map((d) => d.split('/')[0]), 'tests'])];
+    const packageRoot = options.packageRoot ?? srcDirs[0] ?? 'app';
+    const entrypoints = options.entrypoints ?? [`${packageRoot}.main`];
+    const authSymbols = options.authSymbols ?? DEFAULT_AUTH_SYMBOLS;
+    const publicSymbols = options.publicSymbols ?? [];
+    return definePlugin({
+        name: 'python-fastapi',
+        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),
+        },
+        rules: [
+            pythonParseHealth,
+            mutationRoutesGuarded({ authSymbols, publicSymbols }),
+            dtoHasValidationFor(false),
+            dtoHasValidationFor(true),
+            routeHasResponseModel,
+            noCrossFeatureImport({ packageRoot, entrypoints }),
+            monetaryIsFloat,
+            oracleNoSrc({ srcDirs, oracleDirs, entrypoints }),
+            srcNoOracle({ srcDirs, testRoots }),
+        ],
+    });
+}
+/** Preset com defaults FastAPI canônicos (`app/`, `tests/oracle/`, entrypoint `app.main`). */
+export const pythonFastapiPreset = pythonFastapi().rules;

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@ihelpee/prumo-plugin-python-fastapi",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "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>",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "python",
+    "package.json",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ihelpee/prumo.git"
+  },
+  "engines": {
+    "node": ">=20.11",
+    "python": ">=3.9"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@ihelpee/prumo": "0.9.0"
+  }
 }