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

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,69 @@
-# Temporary Holding Version
+# @ihelpee/prumo-plugin-php-laravel
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+PHP/Laravel invariants for [Prumo](https://github.com/ihelpee/prumo). It analyzes, never executes: the PHP subprocess only tokenizes with `token_get_all` (stdlib) and serializes the canonical AST into JSON — not a single line of the analyzed code runs, and the gate never touches the target project's `vendor/`.
+
+## Installation
+
+```bash
+npm install -D @ihelpee/prumo-plugin-php-laravel
+```
+
+Requires `php >= 8.1` on the gate host (not in the analyzed project). Without `php`, the gate reports `php-runtime-missing` (warn) instead of pretending it audited.
+
+## Usage
+
+```ts
+// prumo.config.ts do consumidor Laravel
+import { defineConfig } from '@ihelpee/prumo';
+import { phpLaravel } from '@ihelpee/prumo-plugin-php-laravel';
+
+export default defineConfig({
+  layout: {
+    src: ['app'],
+    oracle: ['tests/Oracle'],
+    contract: ['.prumo/contract'],
+    invariants: ['.prumo/invariants'],
+    intent: ['.prumo/intent'],
+    waivers: ['.prumo/waivers'],
+  },
+  invariants: [phpLaravel({
+    oracleDirs: ['tests/Oracle'],   // convenção de oráculo (default: tests/Oracle, tests/Feature/Oracle, oracle)
+    authSymbols: ['2fa'],           // R2.2: símbolos ADICIONAIS que contam como auth (exato ou glob `*`)
+    publicSymbols: ['public'],      // R2.3: convenção opt-in de rota intencionalmente pública
+    srcDirs: ['app'],               // R3.2: prefixos de produção p/ fronteira reversa
+    testNamespaces: ['Tests'],      // R3.2: namespaces que são código de teste
+  })],
+  testFilePatterns: ['tests/**/*.php', 'tests/**/*Test.php', 'tests/**/*_test.php'],
+});
+```
+
+## Invariants
+
+| Rule | Sev | Catches | Does not catch |
+|---|---|---|---|
+| `mutation-routes-guarded` | error | `Route::post/put/patch/delete` without auth on the route, on the nested group, or on the controller; `throttle:api` does NOT count as auth | global middleware of the `web`/`api` stack (read `bootstrap/app.php`/`Kernel` yourself); GET |
+| `form-request-validated` | error | raw `Request` with `all()/input()/json()` without `validate()`; raw payload + `unguard()` | inline `$request->validate([...])`; FormRequest with `rules()` |
+| `form-request-hollow` | warn | FormRequest without a filled-in `rules()` | — |
+| `no-raw-queries` | error | interpolated `DB::raw/whereRaw/selectRaw/DB::select...` or without bindings | raw SQL with `?`/named bindings |
+| `oracle-no-src` | error | `use App\...` **or service-locator `app(FQCN::class)`/`resolve`/`->make`/`Container::make\|get`** inside `oracleDirs` (anti-bypass: a dynamic import is an import) | entrypoint (`bootstrap/app.php`) |
+| `src-no-oracle` | error | `app/**` with `use Tests\...` (test fixtures leaking into production) | — |
+| `oracle-no-auth-forge` | error | `withoutMiddleware()`/`actingAs()` in the oracle | real login via the HTTP kernel (waiver for the legitimate case) |
+| `oracle-no-container-fake` | error | `mock/partialMock/swap/fake/Container::set` in the oracle | — |
+| `test-mock-only` | warn | tests with only `expects/assertCalled` and no domain assertion | — |
+| `php-parse-error` | error | a file the tokenizer could not read (invalid syntax detected via `TOKEN_PARSE`) | — |
+| `php-runtime-missing` | warn | `php` missing on the host | — |
+
+## Why a PHP subprocess instead of `nikic/php-parser`?
+
+`npx prumo gate` in a Laravel repo must work without `composer install` of the parser. The `php/ast_extractor.php` script is stdlib-only and embedded in the npm package (`files: ["php"]`). `nikic/php-parser` packaged into the plugin is the declared upgrade path for the `fix`/`prune` phase — never the consumer's `vendor/`. The law lives in the Node core; PHP is just a parser.
+
+---
+
+## License & Brand
+
+Copyright © 2026 **IHELPEE TECNOLOGIA LTDA** (<https://ihelpee.com>). All rights reserved.
+Created and authored by [Alex Gotardi](https://github.com/alexgotardi).
+
+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>.
+
+The **"Prumo"** name and logo are trademarks of IHELPEE TECNOLOGIA LTDA and are **not** licensed under the Apache 2.0 license.

package/dist/ast.d.ts

@@ -0,0 +1,114 @@
+/**
+ * AST Extractor PHP — ponte Node ↔ subprocesso PHP isolado.
+ *
+ * DECISÃO D2/D3 da spec: a LEI mora no core Node; o PHP é só um serializador.
+ * Este módulo invoca `php <pkg>/php/ast_extractor.php` via subprocesso com
+ * timeout, lê o JSON canônico v1 do stdout e o tipa. Nenhuma heurística de
+ * violação acontece aqui — só transporte e tipagem.
+ *
+ * R1.4: `php` ausente no host → retorna `null` (o check vira `skip` com
+ * motivo explícito no rules.ts). Nunca lança: gate que crasha é gate morto.
+ */
+export interface PhpImport {
+    fqcn: string;
+    line: number;
+    use: boolean;
+}
+export interface PhpRoute {
+    method: string;
+    path: string;
+    handler: string;
+    controller: string | null;
+    handlerMethod: string | null;
+    routeMiddleware: string[];
+    groupMiddleware: string[];
+    line: number;
+}
+export interface PhpControllerMethod {
+    name: string;
+    line: number;
+    requestParam: string | null;
+    rawPayloadCalls: string[];
+    validatesInline: boolean;
+    unguard: boolean;
+}
+export interface PhpController {
+    class: string;
+    middleware: string[];
+    methods: PhpControllerMethod[];
+}
+export interface PhpFormRequest {
+    class: string;
+    authorize: boolean;
+    authorizeRaw: string;
+    hasRules: boolean;
+    line: number;
+}
+export interface PhpRawQuery {
+    call: string;
+    interpolated: boolean;
+    hasBindings: boolean;
+    line: number;
+}
+export interface PhpServiceLocator {
+    fqcn: string;
+    line: number;
+}
+export interface PhpTestMethod {
+    name: string;
+    line: number;
+    withoutMiddleware: boolean;
+    actingAs: boolean;
+    containerFakes: string[];
+    mockOnly: boolean;
+    importsApp: string[];
+    /** Anti-burla (spec §6.4): `app(FQCN::class)`/`resolve`/`make`/`Container::*` — import dinâmico. */
+    serviceLocator: PhpServiceLocator[];
+}
+export interface PhpTestClass {
+    class: string;
+    traits: string[];
+    methods: PhpTestMethod[];
+}
+export interface PhpFile {
+    path: string;
+    kind: 'routes' | 'controller' | 'formrequest' | 'test' | 'model' | 'other';
+    error?: string;
+    imports?: PhpImport[];
+    routes?: PhpRoute[];
+    controllers?: PhpController[];
+    formRequests?: PhpFormRequest[];
+    rawQueries?: PhpRawQuery[];
+    tests?: PhpTestClass[];
+    /** Anti-burla (spec §6.4): service-locators do arquivo inteiro (setUp, helpers de topo). */
+    serviceLocator?: PhpServiceLocator[];
+}
+export interface PhpModel {
+    version: 1;
+    files: PhpFile[];
+}
+/**
+ * Walk determinístico de arquivos `.php` sob `root`, ordenado por caminho.
+ * O core só faz glob `.ts/.tsx`, então o plugin anda pelos `.php` ele mesmo
+ * (R1.6). Ordem importa: o report precisa ser byte-idêntico entre execuções.
+ */
+export declare function walkPhp(root: string, dir?: string): Promise<string[]>;
+export interface PhpExtractorOptions {
+    /** Binário php (default `php`). */
+    phpBin?: string;
+    /** Timeout do subprocesso em ms (default 15000 — R1.5). */
+    timeoutMs?: number;
+}
+/**
+ * Executa o extractor PHP e retorna o modelo canônico, ou `null` quando o
+ * binário `php` está ausente (R1.4). Timeout estourado lança — o rules.ts
+ * captura e reporta `php-parse-timeout` (R1.5).
+ */
+export declare function runPhpExtractor(root: string, files: string[], opts?: PhpExtractorOptions): Promise<PhpModel | null>;
+/**
+ * Extrator registrado no motor via `definePlugin`. O motor chama com o
+ * `RuleContext`; aqui andamos pelos `.php` do root e invocamos o subprocesso.
+ * Retorna `null` quando `php` está ausente — as regras tratam `null` como skip.
+ */
+export declare function extractPhpModel(root: string): Promise<PhpModel | null>;
+//# sourceMappingURL=ast.d.ts.map

package/dist/ast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast.d.ts","sourceRoot":"","sources":["../src/ast.ts"],"names":[],"mappings":"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"}

package/dist/ast.js

@@ -0,0 +1,126 @@
+import { spawn } from 'node:child_process';
+import { readdir, stat } from 'node:fs/promises';
+import { join, extname, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Diretórios que o extractor NUNCA toca (R1.2). */
+const SKIP_DIRS = new Set([
+    'node_modules',
+    'vendor',
+    'storage',
+    'dist',
+    'build',
+    '.git',
+    '.idea',
+    'bootstrap',
+]);
+/**
+ * Walk determinístico de arquivos `.php` sob `root`, ordenado por caminho.
+ * O core só faz glob `.ts/.tsx`, então o plugin anda pelos `.php` ele mesmo
+ * (R1.6). Ordem importa: o report precisa ser byte-idêntico entre execuções.
+ */
+export async function walkPhp(root, dir = '.') {
+    const abs = join(root, dir);
+    const out = [];
+    let entries;
+    try {
+        entries = await readdir(abs);
+    }
+    catch {
+        return out;
+    }
+    for (const name of entries.sort()) {
+        if (SKIP_DIRS.has(name))
+            continue;
+        const full = join(abs, name);
+        const rel = dir === '.' ? name : `${dir}/${name}`;
+        const st = await stat(full).catch(() => null);
+        if (!st)
+            continue;
+        if (st.isDirectory()) {
+            out.push(...(await walkPhp(root, rel)));
+        }
+        else if (extname(name) === '.php') {
+            out.push(rel);
+        }
+    }
+    return out;
+}
+/** Caminho absoluto do script PHP embutido, válido em src (dev) e dist (prod). */
+function extractorScriptPath() {
+    // src/ast.ts e dist/ast.js estão ambos a um nível da raiz do pacote, então
+    // `../php/ast_extractor.php` resolve nos dois casos.
+    const here = dirname(fileURLToPath(import.meta.url));
+    return resolve(here, '..', 'php', 'ast_extractor.php');
+}
+/**
+ * Executa o extractor PHP e retorna o modelo canônico, ou `null` quando o
+ * binário `php` está ausente (R1.4). Timeout estourado lança — o rules.ts
+ * captura e reporta `php-parse-timeout` (R1.5).
+ */
+export async function runPhpExtractor(root, files, opts = {}) {
+    if (files.length === 0)
+        return { version: 1, files: [] };
+    const phpBin = opts.phpBin ?? process.env['PRUMO_PHP_BIN'] ?? 'php';
+    const timeoutMs = opts.timeoutMs ?? 15000;
+    const script = extractorScriptPath();
+    const { stdout, code, timedOut, notFound } = await spawnPhp(phpBin, script, root, files, timeoutMs);
+    if (notFound)
+        return null; // R1.4 — php ausente: skip com motivo.
+    if (timedOut)
+        throw new Error('php-parse-timeout'); // R1.5
+    if (code !== 0) {
+        // O script sempre sai 0; saída não-zero é ambiente quebrado → skip honesto.
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(stdout);
+        if (parsed.version !== 1)
+            return { version: 1, files: [] };
+        return parsed;
+    }
+    catch {
+        throw new Error('php-parse-error');
+    }
+}
+function spawnPhp(phpBin, script, root, files, timeoutMs) {
+    return new Promise((res) => {
+        const child = spawn(phpBin, [script, '--root', root, '--files', ...files], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGKILL');
+        }, timeoutMs);
+        child.stdout.on('data', (b) => {
+            stdout += b.toString('utf8');
+        });
+        child.stderr.on('data', (b) => {
+            stderr += b.toString('utf8');
+        });
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            res({ stdout: '', code: -1, timedOut: false, notFound: err.code === 'ENOENT' });
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            if (timedOut) {
+                res({ stdout: '', code: -1, timedOut: true, notFound: false });
+                return;
+            }
+            void stderr; // stderr é diagnóstico; nunca entra no JSON.
+            res({ stdout, code: code ?? -1, timedOut: false, notFound: false });
+        });
+    });
+}
+/**
+ * Extrator registrado no motor via `definePlugin`. O motor chama com o
+ * `RuleContext`; aqui andamos pelos `.php` do root e invocamos o subprocesso.
+ * Retorna `null` quando `php` está ausente — as regras tratam `null` como skip.
+ */
+export async function extractPhpModel(root) {
+    const files = await walkPhp(root);
+    return runPhpExtractor(root, files);
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './ast.js';
+export * from './rules.js';
+export { phpLaravel as default } from './rules.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,UAAU,IAAI,OAAO,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from './ast.js';
+export * from './rules.js';
+export { phpLaravel as default } from './rules.js';

package/dist/rules.d.ts

@@ -0,0 +1,120 @@
+import { type RuleDef, type PrumoPlugin } from '@ihelpee/prumo/invariants';
+export interface PhpLaravelOptions {
+    /** Caminhos (prefixos relativos) tratados como layout.oracle. */
+    oracleDirs?: string[];
+    /** R2.2 — símbolos ADICIONAIS que contam como auth (exato ou glob `*`). */
+    authSymbols?: string[];
+    /** R2.3 — convenção opt-in de rota intencionalmente pública. Default: []. */
+    publicSymbols?: string[];
+    /** Prefixos de caminho de produção p/ `src-no-oracle` (R3.2). Default: ['app']. */
+    srcDirs?: string[];
+    /** Prefixos de namespace que são código de teste (R3.2). Default: ['Tests']. */
+    testNamespaces?: string[];
+}
+/**
+ * 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 declare function makeMutationRoutesGuarded(authSymbols: string[], publicSymbols: string[]): RuleDef;
+/**
+ * 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 declare const formRequestValidated: RuleDef;
+/**
+ * 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 declare const formRequestHollow: RuleDef;
+/**
+ * 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 declare const noRawQueries: RuleDef;
+/**
+ * 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 declare function makeOracleNoSrc(oracleDirs: string[]): RuleDef;
+/**
+ * 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 declare function makeSrcNoOracle(srcDirs: string[], testNamespaces: string[]): RuleDef;
+/**
+ * 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 declare function makeOracleNoAuthForge(oracleDirs: string[]): RuleDef;
+/**
+ * R3.4 / I5 — fakes de container dentro do oráculo substituem unidades por
+ * crença do agente: espelho por construção.
+ */
+export declare function makeOracleNoContainerFake(oracleDirs: string[]): RuleDef;
+/**
+ * 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 declare const testMockOnly: RuleDef;
+/**
+ * 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 declare const phpParseError: RuleDef;
+/**
+ * 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 declare const phpRuntimeMissing: RuleDef;
+/**
+ * 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 declare function phpLaravel(options?: PhpLaravelOptions): PrumoPlugin;
+/** Preset com a convenção padrão de oráculo (usa em invariants/rules.ts). */
+export declare const phpLaravelPreset: RuleDef[];
+export default phpLaravel;
+//# sourceMappingURL=rules.d.ts.map

package/dist/rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../src/rules.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,OAAO,EAGZ,KAAK,WAAW,EACjB,MAAM,2BAA2B,CAAC;AA6CnC,MAAM,WAAW,iBAAiB;IAChC,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,6EAA6E;IAC7E,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,mFAAmF;IACnF,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,gFAAgF;IAChF,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AA+BD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,MAAM,EAAE,EACrB,aAAa,EAAE,MAAM,EAAE,GACtB,OAAO,CA+BT;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,SA2BvB,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,SAsBpB,CAAC;AAEX;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,SAuBf,CAAC;AAMX;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,OAAO,CA2C7D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,cAAc,EAAE,MAAM,EAAE,GAAG,OAAO,CAyBpF;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,OAAO,CA8BnE;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,OAAO,CA0BvE;AAED;;;;GAIG;AACH,eAAO,MAAM,YAAY,SAuBf,CAAC;AAMX;;;;GAIG;AACH,eAAO,MAAM,aAAa,SAgBhB,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,SAWpB,CAAC;AAyBX;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,WAAW,CA2BvE;AAED,6EAA6E;AAC7E,eAAO,MAAM,gBAAgB,EAAE,OAAO,EAAuB,CAAC;AAE9D,eAAe,UAAU,CAAC"}