@ihelpee/prumo-plugin-php-laravel 0.0.0-stage → 0.9.0

package/dist/rules.js

@@ -0,0 +1,506 @@
+import pkg from '../package.json' with { type: 'json' };
+import { rule, definePlugin, } from '@ihelpee/prumo/invariants';
+import { extractPhpModel } from './ast.js';
+/**
+ * Invariantes PHP/Laravel (spec `docs/especificacao-prumo-php-laravel.md` §3/§4).
+ * Os ids são canônicos e congelados; nenhum card filho pode renomeá-los sem
+ * voltar à especificação.
+ *
+ * Fronteiras honestas (Art. IV): cada regra declara o que NÃO pega.
+ * O modelo vem do subprocesso PHP (`needsData('php')`); a LEI está toda aqui.
+ */
+const MUTATING = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+/**
+ * R2.2 — piso de símbolos que contam como proteção. `throttle:api` NÃO conta
+ * (rate-limit ≠ auth). Qualquer middleware cujo nome case com
+ * /auth|permission|role|guard/i conta. `plugin.authSymbols` (spec §5.2)
+ * ACRESCENTA símbolos do consumidor sobre este piso (match exato ou glob com
+ * `*`); nunca subtrai — o piso é o mínimo estrutural da regra.
+ */
+const AUTH_SYMBOL_RE = /^(auth(:|$)|can(:|$)|verified$|EnsureEmailIsVerified$)/i;
+const AUTH_HINT_RE = /auth|permission|role|guard/i;
+function globToRe(pattern) {
+    const esc = pattern.replace(/[.*+?^${}()|[\]\\]/g, (c) => (c === '*' ? '.*' : '\\' + c));
+    return new RegExp(`^${esc}$`, 'i');
+}
+function isAuthSymbol(mw, extra) {
+    if (AUTH_SYMBOL_RE.test(mw) || AUTH_HINT_RE.test(mw))
+        return true;
+    return extra.some((s) => (s.includes('*') ? globToRe(s).test(mw) : s.toLowerCase() === mw.toLowerCase()));
+}
+/**
+ * R2.3 — exceção declarada: rota marcada com símbolo de `publicSymbols`
+ * (convenção opt-in do consumidor, ex.: `public`) é pública intencional.
+ */
+function isPublicSymbol(mw, publicSymbols) {
+    return publicSymbols.some((s) => (s.includes('*') ? globToRe(s).test(mw) : s.toLowerCase() === mw.toLowerCase()));
+}
+/** Convenção Laravel: diretórios de oráculo quando o config não é visível. */
+const DEFAULT_ORACLE_DIRS = ['tests/Oracle', 'tests/Feature/Oracle', 'oracle'];
+function model(ctx) {
+    return (ctx.get('php') ?? null);
+}
+function isOracleFile(path, oracleDirs) {
+    const p = path.replace(/\\/g, '/');
+    return oracleDirs.some((d) => p === d || p.startsWith(d.replace(/\/+$/, '') + '/'));
+}
+/** `path` está sob algum prefixo de diretório (mesma semântica de isOracleFile). */
+function isUnderAnyDir(path, dirs) {
+    const p = path.replace(/\\/g, '/');
+    return dirs.some((d) => p === d || p.startsWith(d.replace(/\/+$/, '') + '/'));
+}
+function controllersByName(m) {
+    const out = new Map();
+    for (const f of m.files) {
+        for (const c of f.controllers ?? []) {
+            if (!out.has(c.class))
+                out.set(c.class, c.middleware);
+        }
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// F2 — Invariantes de aplicação
+// ---------------------------------------------------------------------------
+/**
+ * I1 / R2.1–R2.4 — rota de mutação (`POST/PUT/PATCH/DELETE`) sem middleware
+ * de autenticação/autorização em NENHUMA camada efetiva: middleware da rota,
+ * middleware do grupo aninhado, ou middleware do controller resolvido.
+ *
+ * R2.2/R2.3 (preset §5.2): `authSymbols` acrescenta símbolos de proteção ao
+ * piso estrutural; `publicSymbols` marca rota pública intencional (opt-in do
+ * consumidor) — sem convenção declarada, rota de mutação sem auth é sempre
+ * finding.
+ *
+ * Não pega: middleware global do stack web/api (exigiria ler
+ * bootstrap/app.php/Kernel — fronteira declarada; cubra via authSymbols no
+ * controller). Rotas GET nunca são alvo.
+ */
+export function makeMutationRoutesGuarded(authSymbols, publicSymbols) {
+    return rule('mutation-routes-guarded')
+        .needsData('php')
+        .severity('error')
+        .message('rota de mutação Laravel sem middleware de auth em nenhuma camada (rota, grupo aninhado ou controller): em produção ela é pública, e actingAs() no teste forja a proteção que não existe')
+        .assert((ctx) => {
+        const m = model(ctx);
+        if (!m)
+            return [];
+        const out = [];
+        const ctrls = controllersByName(m);
+        for (const f of m.files) {
+            for (const r of f.routes ?? []) {
+                if (!MUTATING.has(r.method))
+                    continue;
+                const ctrlMw = r.controller ? (ctrls.get(r.controller) ?? []) : [];
+                const layers = [...r.routeMiddleware, ...r.groupMiddleware, ...ctrlMw];
+                if (layers.some((mw) => isPublicSymbol(mw, publicSymbols)))
+                    continue;
+                if (layers.some((mw) => isAuthSymbol(mw, authSymbols)))
+                    continue;
+                const label = r.controller
+                    ? `${r.controller}${r.handlerMethod ? '.' + r.handlerMethod : ''}`
+                    : 'Closure';
+                out.push({
+                    target: `${f.path}:${r.line} ${r.method} ${r.path} (${label})`,
+                    location: `${f.path}:${r.line}`,
+                });
+            }
+        }
+        return out;
+    })
+        .build();
+}
+/**
+ * I2 / R2.5–R2.6 — método de controller com `Request` cru consumindo payload
+ * via all()/input()/json() sem validação inline; ou payload cru com
+ * `unguard()` no corpo (mass assignment forçado, mesmo com FormRequest).
+ *
+ * Não pega: `$request->validate([...])` inline (satisfaz, R2.8) e
+ * FormRequest tipado com rules() real.
+ */
+export const formRequestValidated = rule('form-request-validated')
+    .needsData('php')
+    .severity('error')
+    .message('controller consome $request->all()/input()/json() cru sem FormRequest nem validate() — vetor clássico de mass assignment; use FormRequest com rules() ou $request->validate([...])')
+    .assert((ctx) => {
+    const m = model(ctx);
+    if (!m)
+        return [];
+    const out = [];
+    for (const f of m.files) {
+        for (const c of f.controllers ?? []) {
+            for (const meth of c.methods) {
+                const raw = meth.rawPayloadCalls.length > 0;
+                if (!raw)
+                    continue;
+                const rawRequest = meth.requestParam === 'Request';
+                if ((rawRequest && !meth.validatesInline) || meth.unguard) {
+                    out.push({
+                        target: `${f.path}:${meth.line} ${c.class}.${meth.name} usa $request->${meth.rawPayloadCalls[0]}() sem validação${meth.unguard ? ' + unguard()' : ''}`,
+                        location: `${f.path}:${meth.line}`,
+                    });
+                }
+            }
+        }
+    }
+    return out;
+})
+    .build();
+/**
+ * R2.7 — FormRequest oco: classe gerada por `php artisan make:request` sem
+ * rules() preenchido (o agente faz isso constantemente) — autorização
+ * decorativa sobre rota que parece protegida. `warn`: a classe pode ser
+ * legítima em migração progressiva.
+ */
+export const formRequestHollow = rule('form-request-hollow')
+    .needsData('php')
+    .severity('warn')
+    .message('FormRequest sem rules() preenchido: valida nada; o endpoint parece protegido por contrato e não é')
+    .assert((ctx) => {
+    const m = model(ctx);
+    if (!m)
+        return [];
+    const out = [];
+    for (const f of m.files) {
+        for (const fr of f.formRequests ?? []) {
+            if (!fr.hasRules) {
+                out.push({
+                    target: `${f.path}:${fr.line} ${fr.class} sem rules()`,
+                    location: `${f.path}:${fr.line}`,
+                });
+            }
+        }
+    }
+    return out;
+})
+    .build();
+/**
+ * I3 / R2.9–R2.11 — SQL bruto com interpolação/concatenação de variável é
+ * injeção; SQL bruto estático ou com bindings (`?`/named) é aceitável.
+ *
+ * False-positive guard (R2.11): interpolação de constante `self::`/`::CONST`
+ * e `config(...)` não é input externo — o extractor só marca T_VARIABLE, e
+ * constantes não são variáveis. Calibrado por fixture.
+ */
+export const noRawQueries = rule('no-raw-queries')
+    .needsData('php')
+    .severity('error')
+    .message('SQL bruto interpolado ou sem bindings (DB::raw/whereRaw/selectRaw/DB::select...): injeção; use bindings (`?` / named placeholders)')
+    .assert((ctx) => {
+    const m = model(ctx);
+    if (!m)
+        return [];
+    const out = [];
+    for (const f of m.files) {
+        for (const q of f.rawQueries ?? []) {
+            const staticNoBindings = (q.call === 'DB::select' || q.call === 'DB::statement') && !q.hasBindings && !q.interpolated;
+            if (!q.interpolated && !staticNoBindings)
+                continue;
+            out.push({
+                target: `${f.path}:${q.line} ${q.call} ${q.interpolated ? 'interpolado' : 'sem bindings'}`,
+                location: `${f.path}:${q.line}`,
+            });
+        }
+    }
+    return out;
+})
+    .build();
+// ---------------------------------------------------------------------------
+// F1 — Isolamento de oráculo em PHP
+// ---------------------------------------------------------------------------
+/**
+ * R3.1 — `use App\...` dentro de layout.oracle: o teste importa a unidade que
+ * deveria fiscalizar de fora. É espelho, não oráculo.
+ *
+ * Anti-burla (R3.3 / spec §6.4 / card F1): `app(Service::class)`,
+ * `resolve(...)`, `->make(...)`, `Container::make/get(...)` são IMPORT
+ * DINÂMICO — o teste que não escreveu `use App\...` ainda alcança a unidade.
+ * O extractor emite a aresta `serviceLocator` (método + arquivo inteiro);
+ * cada FQCN sob `App\` no oráculo é finding, exatamente como o `use` estático.
+ * Sem isto, o service-locator é a burla que vira a lei de cabeça para baixo.
+ */
+export function makeOracleNoSrc(oracleDirs) {
+    return rule('oracle-no-src')
+        .needsData('php')
+        .severity('error')
+        .message('teste de oráculo importa App\\ (unidade interna) — por `use` estático OU por service-locator `app(FQCN::class)` (import dinâmico): é espelho, não oráculo; exercite a rota via kernel HTTP e derive a expectativa do contrato')
+        .assert((ctx) => {
+        const m = model(ctx);
+        if (!m)
+            return [];
+        const out = [];
+        for (const f of m.files) {
+            if (!isOracleFile(f.path, oracleDirs))
+                continue;
+            const seen = new Set();
+            // 1. `use App\...` estático (por método, como antes).
+            for (const t of f.tests ?? []) {
+                for (const meth of t.methods) {
+                    for (const fqcn of meth.importsApp) {
+                        if (seen.has(fqcn))
+                            continue;
+                        seen.add(fqcn);
+                        out.push({ target: `${f.path} -> ${fqcn}`, location: f.path });
+                    }
+                }
+            }
+            // 2. Anti-burla: service-locator com FQCN sob App\ (método + arquivo).
+            const locators = [
+                ...(f.serviceLocator ?? []),
+                ...(f.tests ?? []).flatMap((t) => t.methods.flatMap((meth) => meth.serviceLocator)),
+            ];
+            for (const loc of locators) {
+                if (!/^App(\\|$)/.test(loc.fqcn))
+                    continue;
+                const key = `locator:${loc.fqcn}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                out.push({
+                    target: `${f.path}:${loc.line} -> ${loc.fqcn} (service-locator)`,
+                    location: `${f.path}:${loc.line}`,
+                });
+            }
+        }
+        return out;
+    })
+        .build();
+}
+/**
+ * R3.2 — fronteira reversa: `app/**` importando `tests/**` (espelho indireto
+ * vazando para produção). O core resolve só imports TS; o extractor PHP dá a
+ * aresta (`imports[].fqcn`), e esta regra espelha a do core TS e a do plugin
+ * python (srcNoOracle): arquivo sob `srcDirs` cujo import resolve para um
+ * namespace de teste (`Tests\...`) é finding.
+ */
+export function makeSrcNoOracle(srcDirs, testNamespaces) {
+    return rule('src-no-oracle')
+        .needsData('php')
+        .severity('error')
+        .message('implementação Laravel importa código de teste (use Tests\\...): fixture de teste vazando para produção')
+        .assert((ctx) => {
+        const m = model(ctx);
+        if (!m)
+            return [];
+        const out = [];
+        for (const f of m.files) {
+            if (!isUnderAnyDir(f.path, srcDirs))
+                continue;
+            for (const imp of f.imports ?? []) {
+                const ns = imp.fqcn.split('\\')[0] ?? '';
+                if (!testNamespaces.some((t) => t.toLowerCase() === ns.toLowerCase()))
+                    continue;
+                out.push({
+                    target: `${f.path}:${imp.line} -> ${imp.fqcn}`,
+                    location: `${f.path}:${imp.line}`,
+                });
+            }
+        }
+        return out;
+    })
+        .build();
+}
+/**
+ * R3.3 / I4 — a regra-assinatura do plugin: dentro do oráculo,
+ * `withoutMiddleware()` remove e `actingAs()` forja exatamente a camada de
+ * autorização que I1 fiscaliza. O teste passa porque a proteção foi
+ * desligada, não porque a autorização funciona.
+ *
+ * Fronteira honesta: `actingAs` para obter token via fluxo real de login é
+ * aceitável (spec §4.2); o MVP marca o sinal e o alvo nomeia o método — o
+ * waiver existe para o caso legítimo, nunca o skip silencioso.
+ */
+export function makeOracleNoAuthForge(oracleDirs) {
+    return rule('oracle-no-auth-forge')
+        .needsData('php')
+        .severity('error')
+        .message('oráculo forja/desliga autorização (withoutMiddleware/actingAs): mock circular da camada que a invariante fiscaliza; use credencial semeada + guard real')
+        .assert((ctx) => {
+        const m = model(ctx);
+        if (!m)
+            return [];
+        const out = [];
+        for (const f of m.files) {
+            if (!isOracleFile(f.path, oracleDirs))
+                continue;
+            for (const t of f.tests ?? []) {
+                for (const meth of t.methods) {
+                    if (!meth.withoutMiddleware && !meth.actingAs)
+                        continue;
+                    const how = [
+                        meth.withoutMiddleware ? 'withoutMiddleware()' : null,
+                        meth.actingAs ? 'actingAs()' : null,
+                    ].filter(Boolean).join(' + ');
+                    out.push({
+                        target: `${f.path}:${meth.line} ${t.class}.${meth.name} ${how}`,
+                        location: `${f.path}:${meth.line}`,
+                    });
+                }
+            }
+        }
+        return out;
+    })
+        .build();
+}
+/**
+ * R3.4 / I5 — fakes de container dentro do oráculo substituem unidades por
+ * crença do agente: espelho por construção.
+ */
+export function makeOracleNoContainerFake(oracleDirs) {
+    return rule('oracle-no-container-fake')
+        .needsData('php')
+        .severity('error')
+        .message('oráculo usa fake/mock/swap de container (mock/partialMock/swap/fake/Container::set): expectativa derivada da crença sobre a unidade')
+        .assert((ctx) => {
+        const m = model(ctx);
+        if (!m)
+            return [];
+        const out = [];
+        for (const f of m.files) {
+            if (!isOracleFile(f.path, oracleDirs))
+                continue;
+            for (const t of f.tests ?? []) {
+                for (const meth of t.methods) {
+                    if (meth.containerFakes.length === 0)
+                        continue;
+                    out.push({
+                        target: `${f.path}:${meth.line} ${t.class}.${meth.name} ${meth.containerFakes.join('/')}`,
+                        location: `${f.path}:${meth.line}`,
+                    });
+                }
+            }
+        }
+        return out;
+    })
+        .build();
+}
+/**
+ * I6 / R3.5 — teste cujo corpo é só mock + assertCalled, sem asserção de
+ * domínio, é teste-espelho: verifica que o mock foi chamado, não que o
+ * negócio aconteceu. `warn` no MVP (heurística de corpo é frágil).
+ */
+export const testMockOnly = rule('test-mock-only')
+    .needsData('php')
+    .severity('warn')
+    .message('teste só verifica que o mock foi chamado (expects/assertCalled) sem asserção de domínio: teste-espelho')
+    .assert((ctx) => {
+    const m = model(ctx);
+    if (!m)
+        return [];
+    const out = [];
+    for (const f of m.files) {
+        for (const t of f.tests ?? []) {
+            for (const meth of t.methods) {
+                if (!meth.mockOnly)
+                    continue;
+                out.push({
+                    target: `${f.path}:${meth.line} ${t.class}.${meth.name}`,
+                    location: `${f.path}:${meth.line}`,
+                });
+            }
+        }
+    }
+    return out;
+})
+    .build();
+// ---------------------------------------------------------------------------
+// Higiene do extractor (R1.3/R1.4) — nunca silencioso
+// ---------------------------------------------------------------------------
+/**
+ * R1.3 — arquivo que o tokenizador não leu (sintaxe ilegível) é finding
+ * `error`, nunca skip silencioso: gate que pula mudo reporta mais saúde do
+ * que existe.
+ */
+export const phpParseError = rule('php-parse-error')
+    .needsData('php')
+    .severity('error')
+    .message('arquivo PHP não tokenizado pelo extractor (sintaxe ilegível): o gate não fiscalizou este arquivo')
+    .assert((ctx) => {
+    const m = model(ctx);
+    if (!m)
+        return [];
+    const out = [];
+    for (const f of m.files) {
+        if (!f.error)
+            continue;
+        out.push({ target: `${f.path} (${f.error})`, location: f.path });
+    }
+    return out;
+})
+    .build();
+/**
+ * R1.4 — `php` ausente no host: o extractor retornou null. O gate NÃO pode
+ * fingir que fiscalizou PHP: finding `warn` nomeia o runtime ausente e o
+ * `prumo doctor`/CI deve instalar o binário. Skip silencioso é a falsa
+ * sensação que a spec §8 lista como risco grave.
+ */
+export const phpRuntimeMissing = rule('php-runtime-missing')
+    .needsData('php')
+    .severity('warn')
+    .message('binário `php` ausente no host: invariantes PHP/Laravel não rodaram; instale PHP >= 8.1 no CI (skip NÃO é silencioso)')
+    .assert((ctx) => {
+    const m = ctx.get('php');
+    if (m !== null)
+        return [];
+    return [{ target: 'php ausente no PATH' }];
+})
+    .build();
+// ---------------------------------------------------------------------------
+// Plugin
+// ---------------------------------------------------------------------------
+function buildRules(opts) {
+    // As regras capturam a config via closure (factory): o RuleContext do core
+    // não expõe a config do consumidor, então as opções (spec §5.2) entram pelo
+    // factory `phpLaravel({ oracleDirs, authSymbols, publicSymbols, ... })`.
+    return [
+        makeMutationRoutesGuarded(opts.authSymbols, opts.publicSymbols),
+        formRequestValidated,
+        formRequestHollow,
+        noRawQueries,
+        makeOracleNoSrc(opts.oracleDirs),
+        makeSrcNoOracle(opts.srcDirs, opts.testNamespaces),
+        makeOracleNoAuthForge(opts.oracleDirs),
+        makeOracleNoContainerFake(opts.oracleDirs),
+        testMockOnly,
+        phpParseError,
+        phpRuntimeMissing,
+    ];
+}
+/**
+ * O plugin oficial PHP/Laravel do Prumo.
+ *
+ * Analisa, nunca executa: o subprocesso PHP só tokeniza (stdlib
+ * `token_get_all`); nenhuma linha do código analisado roda. `php` ausente →
+ * skip honesto com finding `php-runtime-missing`, nunca gate mudo.
+ */
+export function phpLaravel(options = {}) {
+    const opts = {
+        oracleDirs: options.oracleDirs ?? DEFAULT_ORACLE_DIRS,
+        authSymbols: options.authSymbols ?? [],
+        publicSymbols: options.publicSymbols ?? [],
+        srcDirs: options.srcDirs ?? ['app'],
+        testNamespaces: options.testNamespaces ?? ['Tests'],
+    };
+    return definePlugin({
+        name: 'php-laravel',
+        version: pkg.version,
+        description: 'PHP/Laravel invariants: guarded mutation routes, FormRequest discipline, parameterized SQL, oracle isolation (no auth forge, no container fakes, anti-burla service-locator).',
+        extractors: {
+            php: async (ctx) => {
+                try {
+                    return await extractPhpModel(ctx.root);
+                }
+                catch (err) {
+                    // timeout/JSON inválido: modelo vazio com erro marcado — as regras
+                    // de app ficam mudas, php-parse-error fala (nunca silencioso).
+                    const msg = err instanceof Error ? err.message : String(err);
+                    return { version: 1, files: [{ path: '(extractor)', kind: 'other', error: msg }] };
+                }
+            },
+        },
+        rules: buildRules(opts),
+    });
+}
+/** Preset com a convenção padrão de oráculo (usa em invariants/rules.ts). */
+export const phpLaravelPreset = phpLaravel().rules;
+export default phpLaravel;

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@ihelpee/prumo-plugin-php-laravel",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.9.0",
+  "type": "module",
+  "description": "PHP/Laravel plugin for Prumo: guarded mutation routes, FormRequest discipline, parameterized SQL, and oracle isolation invariants.",
+  "author": "Alex Gotardi <alexgotardi@gmail.com> (https://github.com/alexgotardi)",
+  "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",
+    "php",
+    "package.json",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ihelpee/prumo.git"
+  },
+  "engines": {
+    "node": ">=20.11",
+    "php": ">=8.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@ihelpee/prumo": "0.9.0"
+  }
 }