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

package/php/ast_extractor.php

@@ -0,0 +1,1090 @@
+<?php
+/**
+ * Prumo — AST Extractor PHP/Laravel (stdlib-only).
+ *
+ * DECISÃO D2/D3 da spec (`docs/especificacao-prumo-php-laravel.md`): a LEI mora
+ * no core Node. Este script é apenas um SERIALIZADOR: tokeniza com
+ * `token_get_all` (stdlib do PHP) e emite a AST canônica v1 em JSON no stdout.
+ * Nenhuma decisão de violação acontece aqui.
+ *
+ * Invariantes deste arquivo:
+ *  - R1.1: usa apenas stdlib (token_get_all, json). Zero require de terceiros.
+ *  - R1.2: nunca `include`/`require`/`eval` do código analisado; nunca lê
+ *          vendor/, node_modules/, storage/.
+ *  - R1.3: arquivo com erro de tokenização não derruba o run: emite
+ *          { path, error: "syntax" } e segue. O processo sempre sai 0.
+ *
+ * Uso: php ast_extractor.php --root <raiz> --files <rel1> <rel2> ...
+ */
+
+declare(strict_types=1);
+
+// R1.3: stdout é o CANAL DO JSON. Qualquer warning/notice vai para stderr,
+// nunca polui o stdout (o core faz JSON.parse do stdout).
+ini_set('display_errors', 'stderr');
+error_reporting(E_ALL);
+
+// ---------------------------------------------------------------------------
+// Operadores de membro
+//
+// `->` é T_OBJECT_OPERATOR, `?->` é T_NULLSAFE_OBJECT_OPERATOR, `::` é
+// T_DOUBLE_COLON. Nenhum deles é um caractere literal no token stream do PHP.
+// Toda heurística de "receptor->método(" passa por aqui.
+// ---------------------------------------------------------------------------
+
+function isArrow(array $tok): bool {
+    return is_int($tok['t'])
+        && ($tok['t'] === T_OBJECT_OPERATOR || $tok['t'] === T_NULLSAFE_OBJECT_OPERATOR);
+}
+
+function isDoubleColon(array $tok): bool {
+    return is_int($tok['t']) && $tok['t'] === T_DOUBLE_COLON;
+}
+
+/** `->`, `?->` ou `::` — qualquer acesso a membro. */
+function isMemberOp(array $tok): bool {
+    return isArrow($tok) || isDoubleColon($tok);
+}
+
+// ---------------------------------------------------------------------------
+// Tokenização
+// ---------------------------------------------------------------------------
+
+/**
+ * @return array<int,array{t:int|string,s:string,l:int}>|null null em erro de parse.
+ *
+ * R1.3 (sondado em PHP 8.3): `token_get_all` SIMPLES não lança ParseError em
+ * string não terminada, comentário não terminado, octal inválido ou chamada
+ * não fechada — o arquivo inválido entraria mudo no gate. `TOKEN_PARSE` roda
+ * o parser real por cima do token stream e lança ParseError exatamente
+ * nesses casos: é a detecção de sintaxe inválida exigida pela spec.
+ */
+function tokenize(string $src): ?array {
+    try {
+        $raw = @token_get_all($src, TOKEN_PARSE);
+    } catch (\Throwable $e) {
+        return null;
+    }
+    if (!is_array($raw)) {
+        return null;
+    }
+    $out = [];
+    foreach ($raw as $tok) {
+        if (is_array($tok)) {
+            $out[] = ['t' => $tok[0], 's' => $tok[1], 'l' => $tok[2]];
+        } else {
+            $last = $out ? $out[count($out) - 1]['l'] : 1;
+            $out[] = ['t' => $tok, 's' => $tok, 'l' => $last];
+        }
+    }
+    return $out;
+}
+
+function isTrivia(array $tok): bool {
+    return is_int($tok['t'])
+        && ($tok['t'] === T_WHITESPACE || $tok['t'] === T_COMMENT || $tok['t'] === T_DOC_COMMENT);
+}
+
+/** Índices dos tokens não-triviais. */
+function significant(array $toks): array {
+    $idx = [];
+    foreach ($toks as $k => $tok) {
+        if (isTrivia($tok)) continue;
+        $idx[] = $k;
+    }
+    return $idx;
+}
+
+function rawText(array $toks, int $from, int $to): string {
+    $parts = [];
+    for ($k = $from; $k <= $to && $k < count($toks); $k++) {
+        $parts[] = $toks[$k]['s'];
+    }
+    return implode('', $parts);
+}
+
+/** Índice do token que fecha o delimitador aberto em `open`, ou -1. */
+function matchDelim(array $toks, int $open): int {
+    $openCh = is_string($toks[$open]['t']) ? $toks[$open]['s'] : '';
+    $closeMap = ['(' => ')', '[' => ']', '{' => '}'];
+    if (!isset($closeMap[$openCh])) return -1;
+    $closeCh = $closeMap[$openCh];
+    $depth = 0;
+    for ($k = $open; $k < count($toks); $k++) {
+        $t = $toks[$k];
+        if (is_string($t['t'])) {
+            if ($t['s'] === $openCh) $depth++;
+            elseif ($t['s'] === $closeCh) { $depth--; if ($depth === 0) return $k; }
+        }
+    }
+    return -1;
+}
+
+/** Primeiro/último índice não-trivial num intervalo, ou null. */
+function sigRange(array $toks, int $from, int $to): ?array {
+    $f = null; $l = null;
+    for ($k = $from; $k <= $to && $k < count($toks); $k++) {
+        if (isTrivia($toks[$k])) continue;
+        if ($f === null) $f = $k;
+        $l = $k;
+    }
+    return $f === null ? null : [$f, $l];
+}
+
+/**
+ * Argumentos de uma chamada cujo '(' está em `open`: lista de
+ * {from,to} separados por vírgula em profundidade 1.
+ */
+function callArgs(array $toks, int $open): array {
+    $close = matchDelim($toks, $open);
+    if ($close < 0) return [];
+    $args = [];
+    $depth = 0;
+    $start = $open + 1;
+    for ($k = $open; $k <= $close; $k++) {
+        $t = $toks[$k];
+        if (is_string($t['t'])) {
+            if ($t['s'] === '(' || $t['s'] === '[' || $t['s'] === '{') { $depth++; continue; }
+            if ($t['s'] === ')' || $t['s'] === ']' || $t['s'] === '}') { $depth--; }
+            if ($t['s'] === ',' && $depth === 1) {
+                $args[] = ['from' => $start, 'to' => $k - 1];
+                $start = $k + 1;
+            }
+        }
+    }
+    if ($start <= $close - 1) $args[] = ['from' => $start, 'to' => $close - 1];
+    return array_values(array_filter($args, fn($a) => sigRange($toks, $a['from'], $a['to']) !== null));
+}
+
+/** Strings literais de um intervalo. */
+function stringLiterals(array $toks, int $from, int $to): array {
+    $out = [];
+    for ($k = $from; $k <= $to && $k < count($toks); $k++) {
+        $t = $toks[$k];
+        if (is_int($t['t']) && $t['t'] === T_CONSTANT_ENCAPSED_STRING) {
+            $out[] = trim($t['s'], "'\"");
+        }
+    }
+    return $out;
+}
+
+function firstString(array $toks, int $from, int $to): string {
+    $s = stringLiterals($toks, $from, $to);
+    return $s[0] ?? '';
+}
+
+function nameOf(array $toks, int $k): ?string {
+    if ($k < 0 || $k >= count($toks)) return null;
+    $t = $toks[$k];
+    if (is_int($t['t']) && ($t['t'] === T_STRING || $t['t'] === T_NAME_QUALIFIED || $t['t'] === T_NAME_FULLY_QUALIFIED)) {
+        return $t['s'];
+    }
+    return null;
+}
+
+function shortName(string $fqcn): string {
+    $parts = explode('\\', $fqcn);
+    return $parts[count($parts) - 1];
+}
+
+/** Índice do próximo char `ch` a partir da posição de sig `fromSig`. */
+function findNextSig(array $toks, array $sig, int $fromSig, string $ch): int {
+    for ($q = $fromSig; $q < count($sig); $q++) {
+        $k = $sig[$q];
+        if (is_string($toks[$k]['t']) && $toks[$k]['s'] === $ch) return $k;
+    }
+    return -1;
+}
+
+// ---------------------------------------------------------------------------
+// Classificação de arquivo (heurística de caminho — spec §2.3)
+// ---------------------------------------------------------------------------
+
+function classify(string $rel): string {
+    $p = strtolower($rel);
+    if (preg_match('#(^|/)routes/#', $p)) return 'routes';
+    if (preg_match('#controllers?/#', $p) || preg_match('#controller\.php$#', $p)) return 'controller';
+    if (preg_match('#requests?/#', $p) || preg_match('#request\.php$#', $p)) return 'formrequest';
+    if (preg_match('#(^|/)tests?/#', $p) || preg_match('#test\.php$#', $p) || preg_match('#_test\.php$#', $p)) return 'test';
+    if (preg_match('#models?/#', $p) || preg_match('#model\.php$#', $p)) return 'model';
+    return 'other';
+}
+
+// ---------------------------------------------------------------------------
+// Imports (arestas p/ oracle-isolation)
+// ---------------------------------------------------------------------------
+
+function extractImports(array $toks): array {
+    $imports = [];
+    $sig = significant($toks);
+    $count = count($sig);
+    $firstClass = null;
+    foreach ($sig as $p => $k) {
+        if ($toks[$k]['t'] === T_CLASS) { $firstClass = $p; break; }
+    }
+    for ($p = 0; $p < $count; $p++) {
+        $k = $sig[$p];
+        if ($toks[$k]['t'] !== T_USE) continue;
+        $next = $sig[$p + 1] ?? null;
+        if ($next !== null && is_string($toks[$next]['t']) && $toks[$next]['s'] === '(') continue; // closure use
+        $isTopLevel = ($firstClass === null) || ($p < $firstClass);
+        $q = $p + 1;
+        $cur = '';
+        while ($q < $count) {
+            $kk = $sig[$q];
+            $t = $toks[$kk];
+            if (is_string($t['t']) && $t['s'] === ';') break;
+            if (is_string($t['t']) && $t['s'] === ',') {
+                if ($cur !== '') $imports[] = ['fqcn' => ltrim($cur, '\\'), 'line' => $toks[$k]['l'], 'use' => true];
+                $cur = ''; $q++; continue;
+            }
+            if (is_int($t['t']) && $t['t'] === T_AS) break;
+            $nm = nameOf($toks, $kk);
+            if ($nm !== null) $cur .= $nm;
+            $q++;
+        }
+        if ($cur !== '') {
+            $qualified = strpos($cur, '\\') !== false;
+            if ($isTopLevel || $qualified) {
+                $imports[] = ['fqcn' => ltrim($cur, '\\'), 'line' => $toks[$k]['l'], 'use' => true];
+            }
+        }
+    }
+    return $imports;
+}
+
+// ---------------------------------------------------------------------------
+// Rotas (com resolução obrigatória de groupMiddleware — R1.7)
+// ---------------------------------------------------------------------------
+
+const ROUTE_HTTP = ['get' => 'GET', 'post' => 'POST', 'put' => 'PUT', 'patch' => 'PATCH', 'delete' => 'DELETE', 'options' => 'OPTIONS'];
+
+function extractRoutes(array $toks): array {
+    $routes = [];
+    $sig = significant($toks);
+    $count = count($sig);
+
+    $groupStack = [];        // [['mw'=>[], 'depth'=>int]]
+    $braceDepth = 0;
+    $pendingGroupMw = null;  // middleware aguardando o '{' do closure de grupo
+
+    for ($p = 0; $p < $count; $p++) {
+        $k = $sig[$p];
+        $t = $toks[$k];
+
+        if (is_string($t['t']) && $t['s'] === '{') {
+            $braceDepth++;
+            if ($pendingGroupMw !== null) {
+                $groupStack[] = ['mw' => $pendingGroupMw, 'depth' => $braceDepth];
+                $pendingGroupMw = null;
+            }
+            continue;
+        }
+        if (is_string($t['t']) && $t['s'] === '}') {
+            if ($groupStack && $groupStack[count($groupStack) - 1]['depth'] === $braceDepth) {
+                array_pop($groupStack);
+            }
+            $braceDepth--;
+            continue;
+        }
+
+        if (!isDoubleColon($t)) continue;
+        $prevName = nameOf($toks, $sig[$p - 1] ?? -1);
+        if ($prevName !== 'Route') continue;
+        $mName = nameOf($toks, $sig[$p + 1] ?? -1);
+        if ($mName === null) continue;
+        $paren = $sig[$p + 2] ?? null;
+        if ($paren === null || !is_string($toks[$paren]['t']) || $toks[$paren]['s'] !== '(') continue;
+
+        if ($mName === 'middleware') {
+            $captured = [];
+            foreach (callArgs($toks, $paren) as $a) {
+                $captured = array_merge($captured, stringLiterals($toks, $a['from'], $a['to']));
+            }
+            $pendingGroupMw = array_merge($pendingGroupMw ?? [], $captured);
+            continue;
+        }
+        if ($mName === 'group') {
+            $mw = callArgs($toks, $paren);
+            $captured = $mw ? stringLiterals($toks, $mw[0]['from'], $mw[0]['to']) : [];
+            $pendingGroupMw = array_merge($pendingGroupMw ?? [], $captured);
+            continue;
+        }
+        if ($mName === 'prefix' || $mName === 'name' || $mName === 'domain' || $mName === 'scopeBindings') {
+            continue;
+        }
+
+        if (isset(ROUTE_HTTP[$mName])) {
+            $args = callArgs($toks, $paren);
+            $path = $args ? firstString($toks, $args[0]['from'], $args[0]['to']) : '';
+            [$handler, $controller, $handlerMethod] = $args && count($args) >= 2
+                ? parseHandler($toks, $args[1]['from'], $args[1]['to'])
+                : ['Closure', null, null];
+            $routeMw = collectChainMiddleware($toks, $sig, $p);
+            $groupMw = [];
+            foreach ($groupStack as $g) $groupMw = array_merge($groupMw, $g['mw']);
+            $routes[] = [
+                'method' => ROUTE_HTTP[$mName],
+                'path' => '/' . ltrim($path, '/'),
+                'handler' => $handler,
+                'controller' => $controller,
+                'handlerMethod' => $handlerMethod,
+                'routeMiddleware' => array_values(array_unique($routeMw)),
+                'groupMiddleware' => array_values(array_unique($groupMw)),
+                'line' => $toks[$k]['l'],
+            ];
+            continue;
+        }
+
+        if ($mName === 'apiResource' || $mName === 'resource' || $mName === 'apiResources' || $mName === 'resources') {
+            $args = callArgs($toks, $paren);
+            $path = $args ? firstString($toks, $args[0]['from'], $args[0]['to']) : '';
+            $controller = null;
+            if ($args && count($args) >= 2) { [, $controller, ] = parseHandler($toks, $args[1]['from'], $args[1]['to']); }
+            $routeMw = collectChainMiddleware($toks, $sig, $p);
+            $groupMw = [];
+            foreach ($groupStack as $g) $groupMw = array_merge($groupMw, $g['mw']);
+            $base = '/' . trim($path, '/');
+            $expansion = [
+                ['GET', $base, 'index'],
+                ['POST', $base, 'store'],
+                ['GET', $base . '/{id}', 'show'],
+                ['PUT', $base . '/{id}', 'update'],
+                ['PATCH', $base . '/{id}', 'update'],
+                ['DELETE', $base . '/{id}', 'destroy'],
+            ];
+            foreach ($expansion as [$m, $pth, $hm]) {
+                $routes[] = [
+                    'method' => $m,
+                    'path' => $pth,
+                    'handler' => $controller ? ($controller . '@' . $hm) : 'Closure',
+                    'controller' => $controller,
+                    'handlerMethod' => $hm,
+                    'routeMiddleware' => array_values(array_unique($routeMw)),
+                    'groupMiddleware' => array_values(array_unique($groupMw)),
+                    'line' => $toks[$k]['l'],
+                ];
+            }
+            continue;
+        }
+    }
+    return $routes;
+}
+
+/** Handler: [Class::class,'m'] | 'Class@m' | 'Class' | closure. */
+function parseHandler(array $toks, int $from, int $to): array {
+    $range = sigRange($toks, $from, $to);
+    if ($range === null) return ['Closure', null, null];
+    [$f, $l] = $range;
+    // closure
+    if (is_int($toks[$f]['t']) && ($toks[$f]['t'] === T_FUNCTION || $toks[$f]['t'] === T_FN)) {
+        return ['Closure', null, null];
+    }
+    // array [Class::class, 'm'] — o primeiro token é '['
+    if (is_string($toks[$f]['t']) && $toks[$f]['s'] === '[') {
+        $names = []; $method = null;
+        for ($k = $f; $k <= $l; $k++) {
+            $t = $toks[$k];
+            if (is_int($t['t']) && $t['t'] === T_STRING) $names[] = $t['s'];
+            if (is_int($t['t']) && $t['t'] === T_CONSTANT_ENCAPSED_STRING) $method = trim($t['s'], "'\"");
+        }
+        $class = null;
+        for ($j = 0; $j < count($names); $j++) {
+            if ($names[$j] === 'class') { $class = $names[$j - 1] ?? null; break; }
+        }
+        if ($class === null && $names) $class = $names[0];
+        $class = $class ? shortName($class) : null;
+        $handler = $class ? ($class . '@' . ($method ?? '')) : 'Closure';
+        return [$handler, $class, $method];
+    }
+    // Class::class (resource/invokable) — T_STRING seguido de ::class.
+    // Com TOKEN_PARSE o `class` mágico chega como T_STRING, não T_CLASS.
+    if (is_int($toks[$f]['t']) && ($toks[$f]['t'] === T_STRING || $toks[$f]['t'] === T_NAME_QUALIFIED || $toks[$f]['t'] === T_NAME_FULLY_QUALIFIED)) {
+        $n1 = $f + 1; while ($n1 <= $l && isTrivia($toks[$n1])) $n1++;
+        $n2 = $n1 + 1; while ($n2 <= $l && isTrivia($toks[$n2])) $n2++;
+        if ($n1 <= $l && isDoubleColon($toks[$n1]) && $n2 <= $l && is_int($toks[$n2]['t'])
+            && ($toks[$n2]['t'] === T_CLASS || ($toks[$n2]['t'] === T_STRING && $toks[$n2]['s'] === 'class'))) {
+            $class = shortName($toks[$f]['s']);
+            return [$class, $class, null];
+        }
+    }
+    // string 'Class@m' | 'Class'
+    $strs = stringLiterals($toks, $from, $to);
+    if ($strs) {
+        $s = $strs[0];
+        if (strpos($s, '@') !== false) {
+            [$c, $m] = explode('@', $s, 2);
+            return [$s, shortName($c), $m];
+        }
+        return [$s, shortName($s), null];
+    }
+    return ['Closure', null, null];
+}
+
+/** `->middleware(...)` encadeados na statement de rota corrente. */
+function collectChainMiddleware(array $toks, array $sig, int $pSig): array {
+    $out = [];
+    $count = count($sig);
+    $parenDepth = 0; $braceDepth = 0;
+    for ($q = $pSig; $q < $count; $q++) {
+        $k = $sig[$q];
+        $t = $toks[$k];
+        if (is_string($t['t'])) {
+            if ($t['s'] === '(') $parenDepth++;
+            elseif ($t['s'] === ')') $parenDepth--;
+            elseif ($t['s'] === '{') $braceDepth++;
+            elseif ($t['s'] === '}') $braceDepth--;
+            elseif ($t['s'] === ';' && $parenDepth <= 0 && $braceDepth <= 0) break;
+        }
+        // nova statement Route:: encerra a chain
+        if (isDoubleColon($t) && nameOf($toks, $sig[$q - 1] ?? -1) === 'Route' && $q !== $pSig) break;
+        // ->middleware(
+        if (isArrow($t) && nameOf($toks, $sig[$q + 1] ?? -1) === 'middleware') {
+            $paren = $sig[$q + 2] ?? null;
+            if ($paren !== null && is_string($toks[$paren]['t']) && $toks[$paren]['s'] === '(') {
+                foreach (callArgs($toks, $paren) as $a) {
+                    $out = array_merge($out, stringLiterals($toks, $a['from'], $a['to']));
+                }
+            }
+        }
+    }
+    return $out;
+}
+
+// ---------------------------------------------------------------------------
+// Controllers (middleware + métodos) — R1.8 (3 estilos)
+// ---------------------------------------------------------------------------
+
+/** Nome da classe que `class X extends Y` estende (ou null). */
+function extendsOf(array $toks, array $sig, int $classSig): ?string {
+    for ($q = $classSig; $q < count($sig); $q++) {
+        $k = $sig[$q];
+        if ($toks[$k]['t'] === T_EXTENDS) {
+            return nameOf($toks, $sig[$q + 1] ?? -1);
+        }
+        if ($toks[$k]['t'] === T_CLASS) continue;
+        if (is_string($toks[$k]['t']) && $toks[$k]['s'] === '{') break;
+    }
+    return null;
+}
+
+function isControllerClass(array $toks, array $sig, int $classSig, string $class): bool {
+    if (substr($class, -10) === 'Controller') return true;
+    $ext = extendsOf($toks, $sig, $classSig);
+    return $ext !== null && substr($ext, -10) === 'Controller';
+}
+
+function extractControllers(array $toks): array {
+    $controllers = [];
+    $sig = significant($toks);
+    $count = count($sig);
+    for ($p = 0; $p < $count; $p++) {
+        $k = $sig[$p];
+        if ($toks[$k]['t'] !== T_CLASS) continue;
+        $class = nameOf($toks, $sig[$p + 1] ?? -1);
+        if ($class === null) continue;
+        if (!isControllerClass($toks, $sig, $p, $class)) continue;
+        $bodyOpen = findNextSig($toks, $sig, $p, '{');
+        if ($bodyOpen < 0) continue;
+        $bodyClose = matchDelim($toks, $bodyOpen);
+        if ($bodyClose < 0) continue;
+
+        $middleware = [];
+        $middleware = array_merge($middleware, propertyArray($toks, $sig, $bodyOpen, $bodyClose, 'middleware'));
+        $middleware = array_merge($middleware, constructMiddleware($toks, $sig, $bodyOpen, $bodyClose));
+        $middleware = array_merge($middleware, staticMiddleware($toks, $sig, $bodyOpen, $bodyClose));
+
+        $methods = [];
+        for ($q = $p; $q < $count; $q++) {
+            $mk = $sig[$q];
+            if ($toks[$mk]['t'] !== T_FUNCTION) continue;
+            if ($mk < $bodyOpen || $mk > $bodyClose) continue;
+            $mname = nameOf($toks, $sig[$q + 1] ?? -1);
+            if ($mname === null || $mname === '__construct') continue;
+            $mOpen = findNextSig($toks, $sig, $q, '{');
+            if ($mOpen < 0 || $mOpen > $bodyClose) continue;
+            $mClose = matchDelim($toks, $mOpen);
+            if ($mClose < 0) continue;
+
+            $requestParam = requestParamType($toks, $sig, $q);
+            $varName = requestVarName($toks, $sig, $q);
+            $rawPayload = rawPayloadCalls($toks, $sig, $mOpen, $mClose, $varName);
+            $validatesInline = bodyHasCall($toks, $sig, $mOpen, $mClose, 'validate')
+                || bodyHasCall($toks, $sig, $mOpen, $mClose, 'validated')
+                || bodyHasCall($toks, $sig, $mOpen, $mClose, 'safe');
+            $unguard = bodyHasCall($toks, $sig, $mOpen, $mClose, 'unguard');
+
+            $methods[] = [
+                'name' => $mname,
+                'line' => $toks[$mk]['l'],
+                'requestParam' => $requestParam,
+                'rawPayloadCalls' => $rawPayload,
+                'validatesInline' => $validatesInline,
+                'unguard' => $unguard,
+            ];
+        }
+
+        $controllers[] = [
+            'class' => $class,
+            'middleware' => array_values(array_unique($middleware)),
+            'methods' => $methods,
+        ];
+    }
+    return $controllers;
+}
+
+function propertyArray(array $toks, array $sig, int $bodyOpen, int $bodyClose, string $prop): array {
+    $out = [];
+    for ($q = 0; $q < count($sig); $q++) {
+        $k = $sig[$q];
+        if ($k <= $bodyOpen || $k >= $bodyClose) continue;
+        if (is_int($toks[$k]['t']) && $toks[$k]['t'] === T_VARIABLE && $toks[$k]['s'] === '$' . $prop) {
+            $eq = $sig[$q + 1] ?? null;
+            if ($eq === null || !is_string($toks[$eq]['t']) || $toks[$eq]['s'] !== '=') continue;
+            $arr = $sig[$q + 2] ?? null;
+            if ($arr === null || !is_string($toks[$arr]['t']) || $toks[$arr]['s'] !== '[') continue;
+            $close = matchDelim($toks, $arr);
+            if ($close < 0) continue;
+            $out = array_merge($out, stringLiterals($toks, $arr, $close));
+        }
+    }
+    return $out;
+}
+
+function constructMiddleware(array $toks, array $sig, int $bodyOpen, int $bodyClose): array {
+    $out = [];
+    for ($q = 0; $q < count($sig); $q++) {
+        $k = $sig[$q];
+        if ($k <= $bodyOpen || $k >= $bodyClose) continue;
+        if ($toks[$k]['t'] === T_FUNCTION && nameOf($toks, $sig[$q + 1] ?? -1) === '__construct') {
+            $cOpen = findNextSig($toks, $sig, $q, '{');
+            if ($cOpen < 0) continue;
+            $cClose = matchDelim($toks, $cOpen);
+            if ($cClose < 0) continue;
+            for ($r = 0; $r < count($sig); $r++) {
+                $rk = $sig[$r];
+                if ($rk <= $cOpen || $rk >= $cClose) continue;
+                if (isArrow($toks[$rk]) && nameOf($toks, $sig[$r + 1] ?? -1) === 'middleware') {
+                    $paren = $sig[$r + 2] ?? null;
+                    if ($paren !== null && is_string($toks[$paren]['t']) && $toks[$paren]['s'] === '(') {
+                        foreach (callArgs($toks, $paren) as $a) {
+                            $out = array_merge($out, stringLiterals($toks, $a['from'], $a['to']));
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return $out;
+}
+
+function staticMiddleware(array $toks, array $sig, int $bodyOpen, int $bodyClose): array {
+    $out = [];
+    for ($q = 0; $q < count($sig); $q++) {
+        $k = $sig[$q];
+        if ($k <= $bodyOpen || $k >= $bodyClose) continue;
+        if ($toks[$k]['t'] === T_FUNCTION && nameOf($toks, $sig[$q + 1] ?? -1) === 'middleware') {
+            $mOpen = findNextSig($toks, $sig, $q, '{');
+            if ($mOpen < 0) continue;
+            $mClose = matchDelim($toks, $mOpen);
+            if ($mClose < 0) continue;
+            $out = array_merge($out, stringLiterals($toks, $mOpen, $mClose));
+        }
+    }
+    return $out;
+}
+
+function requestParamType(array $toks, array $sig, int $fnSig): ?string {
+    $paren = findNextSig($toks, $sig, $fnSig, '(');
+    if ($paren < 0) return null;
+    $close = matchDelim($toks, $paren);
+    if ($close < 0) return null;
+    for ($k = $paren + 1; $k < $close; $k++) {
+        $t = $toks[$k];
+        if (is_int($t['t']) && ($t['t'] === T_STRING || $t['t'] === T_NAME_QUALIFIED)) {
+            $nm = $t['s'];
+            if (substr($nm, -7) === 'Request') return shortName($nm);
+        }
+    }
+    return null;
+}
+
+function requestVarName(array $toks, array $sig, int $fnSig): ?string {
+    $paren = findNextSig($toks, $sig, $fnSig, '(');
+    if ($paren < 0) return null;
+    $close = matchDelim($toks, $paren);
+    if ($close < 0) return null;
+    $lastType = null;
+    for ($k = $paren + 1; $k < $close; $k++) {
+        $t = $toks[$k];
+        if (is_int($t['t']) && ($t['t'] === T_STRING || $t['t'] === T_NAME_QUALIFIED)) $lastType = $t['s'];
+        if (is_int($t['t']) && $t['t'] === T_VARIABLE && $lastType !== null && substr($lastType, -7) === 'Request') {
+            return $t['s'];
+        }
+    }
+    return null;
+}
+
+/** Chamadas `$<var>->all|input|json(` no corpo. */
+function rawPayloadCalls(array $toks, array $sig, int $open, int $close, ?string $varName): array {
+    $out = [];
+    $targets = ['all', 'input', 'json'];
+    for ($q = 0; $q < count($sig); $q++) {
+        $k = $sig[$q];
+        if ($k <= $open || $k >= $close) continue;
+        if (isArrow($toks[$k])) {
+            $method = nameOf($toks, $sig[$q + 1] ?? -1);
+            if ($method !== null && in_array($method, $targets, true)) {
+                $prev = $sig[$q - 1] ?? null;
+                if ($prev !== null && is_int($toks[$prev]['t']) && $toks[$prev]['t'] === T_VARIABLE) {
+                    if ($varName === null || $toks[$prev]['s'] === $varName) $out[] = $method;
+                }
+            }
+        }
+    }
+    return array_values(array_unique($out));
+}
+
+/** Corpo contém `-><name>(` ou `<Class>::<name>(`? */
+function bodyHasCall(array $toks, array $sig, int $open, int $close, string $name): bool {
+    for ($q = 0; $q < count($sig); $q++) {
+        $k = $sig[$q];
+        if ($k <= $open || $k >= $close) continue;
+        if (isMemberOp($toks[$k])) {
+            $n = nameOf($toks, $sig[$q + 1] ?? -1);
+            if ($n === $name) {
+                $paren = $sig[$q + 2] ?? null;
+                if ($paren !== null && is_string($toks[$paren]['t']) && $toks[$paren]['s'] === '(') return true;
+            }
+        }
+    }
+    return false;
+}
+
+// ---------------------------------------------------------------------------
+// FormRequests
+// ---------------------------------------------------------------------------
+
+function isFormRequestClass(array $toks, array $sig, int $classSig, string $class): bool {
+    $ext = extendsOf($toks, $sig, $classSig);
+    if ($ext !== null && (substr($ext, -7) === 'Request' || $ext === 'FormRequest')) return true;
+    if (substr($class, -7) === 'Request') return true;
+    return false;
+}
+
+function extractFormRequests(array $toks): array {
+    $out = [];
+    $sig = significant($toks);
+    $count = count($sig);
+    for ($p = 0; $p < $count; $p++) {
+        $k = $sig[$p];
+        if ($toks[$k]['t'] !== T_CLASS) continue;
+        $class = nameOf($toks, $sig[$p + 1] ?? -1);
+        if ($class === null) continue;
+        if (!isFormRequestClass($toks, $sig, $p, $class)) continue;
+        $bodyOpen = findNextSig($toks, $sig, $p, '{');
+        if ($bodyOpen < 0) continue;
+        $bodyClose = matchDelim($toks, $bodyOpen);
+        if ($bodyClose < 0) continue;
+
+        $authorize = false; $authorizeRaw = ''; $hasRules = false;
+
+        for ($q = $p; $q < $count; $q++) {
+            $mk = $sig[$q];
+            if ($toks[$mk]['t'] !== T_FUNCTION) continue;
+            if ($mk < $bodyOpen || $mk > $bodyClose) continue;
+            $mname = nameOf($toks, $sig[$q + 1] ?? -1);
+            $mOpen = findNextSig($toks, $sig, $q, '{');
+            if ($mOpen < 0 || $mOpen > $bodyClose) continue;
+            $mClose = matchDelim($toks, $mOpen);
+            if ($mClose < 0) continue;
+            if ($mname === 'authorize') {
+                $authorizeRaw = trim(rawText($toks, $mOpen + 1, $mClose - 1));
+                $authorize = (bool) preg_match('/return\s+true\b/', $authorizeRaw);
+            } elseif ($mname === 'rules' || $mname === 'rulesArray') {
+                $hasRules = $hasRules || rulesBodyNonEmpty($toks, $mOpen, $mClose);
+            }
+        }
+
+        $out[] = [
+            'class' => $class,
+            'authorize' => $authorize,
+            'authorizeRaw' => $authorizeRaw,
+            'hasRules' => $hasRules,
+            'line' => $toks[$k]['l'],
+        ];
+    }
+    return $out;
+}
+
+function rulesBodyNonEmpty(array $toks, int $open, int $close): bool {
+    for ($q = $open; $q <= $close; $q++) {
+        if (is_string($toks[$q]['t']) && $toks[$q]['s'] === '[') {
+            $c = matchDelim($toks, $q);
+            if ($c < 0) continue;
+            if (stringLiterals($toks, $q, $c)) return true;
+        }
+    }
+    return false;
+}
+
+// ---------------------------------------------------------------------------
+// Raw queries (tripwire no-raw-queries — R2.9/R2.10/R2.11)
+// ---------------------------------------------------------------------------
+
+const RAW_STATIC = ['raw', 'select', 'statement', 'insert', 'update', 'delete'];
+const RAW_CHAIN = ['whereRaw', 'orWhereRaw', 'havingRaw', 'selectRaw', 'orderByRaw', 'whereSelect'];
+
+function extractRawQueries(array $toks): array {
+    $out = [];
+    $sig = significant($toks);
+    $count = count($sig);
+    for ($q = 0; $q < $count; $q++) {
+        $k = $sig[$q];
+        $t = $toks[$k];
+
+        if (isDoubleColon($t)) {
+            $recv = nameOf($toks, $sig[$q - 1] ?? -1);
+            $mname = nameOf($toks, $sig[$q + 1] ?? -1);
+            if ($recv === 'DB' && $mname !== null && in_array($mname, RAW_STATIC, true)) {
+                $paren = $sig[$q + 2] ?? null;
+                if ($paren !== null && is_string($toks[$paren]['t']) && $toks[$paren]['s'] === '(') {
+                    $out[] = rawQueryEntry($toks, $paren, 'DB::' . $mname, $toks[$k]['l']);
+                }
+            }
+            continue;
+        }
+        if (isArrow($t)) {
+            $mname = nameOf($toks, $sig[$q + 1] ?? -1);
+            if ($mname !== null && in_array($mname, RAW_CHAIN, true)) {
+                $paren = $sig[$q + 2] ?? null;
+                if ($paren !== null && is_string($toks[$paren]['t']) && $toks[$paren]['s'] === '(') {
+                    $out[] = rawQueryEntry($toks, $paren, $mname, $toks[$k]['l']);
+                }
+            }
+        }
+    }
+    return $out;
+}
+
+function rawQueryEntry(array $toks, int $paren, string $call, int $line): array {
+    $args = callArgs($toks, $paren);
+    $interpolated = false; $hasBindings = false;
+    if ($args) {
+        $sqlRange = sigRange($toks, $args[0]['from'], $args[0]['to']);
+        if ($sqlRange) {
+            [$f, $l] = $sqlRange;
+            for ($k = $f; $k <= $l; $k++) {
+                if (is_int($toks[$k]['t']) && $toks[$k]['t'] === T_VARIABLE) { $interpolated = true; break; }
+            }
+            $sqlText = rawText($toks, $f, $l);
+            if (strpos($sqlText, '?') !== false || preg_match('/:[a-zA-Z_][a-zA-Z0-9_]*/', $sqlText)) {
+                $hasBindings = true;
+            }
+        }
+        if (count($args) >= 2) {
+            $b = sigRange($toks, $args[1]['from'], $args[1]['to']);
+            if ($b && is_string($toks[$b[0]]['t']) && $toks[$b[0]]['s'] === '[') $hasBindings = true;
+        }
+    }
+    return ['call' => $call, 'interpolated' => $interpolated, 'hasBindings' => $hasBindings, 'line' => $line];
+}
+
+// ---------------------------------------------------------------------------
+// Service-locator (anti-burla R3.3 — spec §6.4 / card F1)
+//
+// `app(FQCN::class)`, `resolve(FQCN::class)`, `make(FQCN::class)` e
+// `Container::make|get(FQCN::class)` são IMPORT DINÂMICO: o teste que não
+// escreveu `use App\...` ainda assim alcança a unidade que deveria fiscalizar
+// de fora. Sem esta aresta, o service-locator é a burla que vira a lei de
+// cabeça para baixo (spec §8: "Burla via app(Service::class) no oráculo").
+// Só resolve para FQCN explícito (`X::class`); string dinâmica não resolvida
+// não entra (heurística conservadora, calibrada por fixture).
+// ---------------------------------------------------------------------------
+
+const LOCATOR_FUNCS = ['app', 'resolve', 'make'];
+
+/**
+ * FQCN de um intervalo `FQCN::class` (com barra inicial), ou null.
+ * Atenção: `from`/`to` vêm de `callArgs` e são índices do array BRUTO de
+ * tokens — o avanço aqui pula trivia em índice bruto (não em `sig`).
+ */
+function classConstFqcn(array $toks, int $from, int $to): ?string {
+    $range = sigRange($toks, $from, $to);
+    if ($range === null) return null;
+    [$f, $l] = $range;
+    $name = nameOf($toks, $f);
+    if ($name === null) return null;
+    $n1 = $f + 1; while ($n1 <= $l && isTrivia($toks[$n1])) $n1++;
+    if ($n1 > $l || !isDoubleColon($toks[$n1])) return null;
+    $n2 = $n1 + 1; while ($n2 <= $l && isTrivia($toks[$n2])) $n2++;
+    if ($n2 > $l || !is_int($toks[$n2]['t'])) return null;
+    // Com TOKEN_PARSE o `class` de `X::class` chega como T_STRING (não
+    // T_CLASS); o texto é o discriminador — `Foo::bar` não vira aresta.
+    if ($toks[$n2]['s'] !== 'class') return null;
+    if ($toks[$n2]['t'] !== T_CLASS && $toks[$n2]['t'] !== T_STRING) return null;
+    return ltrim($name, chr(92));
+}
+
+/**
+ * Chamadas de service-locator num intervalo. Retorna lista de
+ * { fqcn, line } com o FQCN resolvido do argumento `FQCN::class`.
+ */
+function serviceLocatorCalls(array $toks, array $sig, int $open, int $close): array {
+    $out = [];
+    $count = count($sig);
+    for ($q = 0; $q < $count; $q++) {
+        $k = $sig[$q];
+        if ($k < $open || $k > $close) continue;
+        $t = $toks[$k];
+
+        $fqcn = null;
+        if (is_int($t['t']) && $t['t'] === T_STRING && in_array($t['s'], LOCATOR_FUNCS, true)) {
+            // app()/resolve()/make() globais — não pode ser método ($this->app(), Route::make()...)
+            $prev = $sig[$q - 1] ?? null;
+            if ($prev !== null && isMemberOp($toks[$prev])) continue;
+            $paren = $sig[$q + 1] ?? null;
+            if ($paren === null || !is_string($toks[$paren]['t']) || $toks[$paren]['s'] !== '(') continue;
+            $args = callArgs($toks, $paren);
+            if ($args) $fqcn = classConstFqcn($toks, $args[0]['from'], $args[0]['to']);
+        } elseif (isDoubleColon($t)) {
+            // Container::make|get(FQCN::class) — receiver pode ser FQCN
+            // (\Illuminate\Support\Facades\Container::make).
+            $recv = nameOf($toks, $sig[$q - 1] ?? -1);
+            $mname = nameOf($toks, $sig[$q + 1] ?? -1);
+            if ($recv === null || shortName($recv) !== 'Container' || ($mname !== 'make' && $mname !== 'get')) continue;
+            $paren = $sig[$q + 2] ?? null;
+            if ($paren === null || !is_string($toks[$paren]['t']) || $toks[$paren]['s'] !== '(') continue;
+            $args = callArgs($toks, $paren);
+            if ($args) $fqcn = classConstFqcn($toks, $args[0]['from'], $args[0]['to']);
+        } elseif (isArrow($t)) {
+            // ->make(FQCN::class) / ->resolve(FQCN::class) em qualquer receptor
+            // ($this->app->make(), app()->make(), $container->make()): é a
+            // mesma resolução dinâmica com FQCN explícito — anti-burla.
+            $mname = nameOf($toks, $sig[$q + 1] ?? -1);
+            if ($mname !== 'make' && $mname !== 'resolve') continue;
+            $paren = $sig[$q + 2] ?? null;
+            if ($paren === null || !is_string($toks[$paren]['t']) || $toks[$paren]['s'] !== '(') continue;
+            $args = callArgs($toks, $paren);
+            if ($args) $fqcn = classConstFqcn($toks, $args[0]['from'], $args[0]['to']);
+        }
+        if ($fqcn !== null && $fqcn !== '') {
+            $out[] = ['fqcn' => $fqcn, 'line' => $toks[$k]['l']];
+        }
+    }
+    return $out;
+}
+
+// ---------------------------------------------------------------------------
+// Tests (PHPUnit + Pest) — regras de oráculo
+// ---------------------------------------------------------------------------
+
+/**
+ * Extrai classes de teste + service-locators do arquivo inteiro.
+ * @return array{0: array, 1: array} [tests, serviceLocator]
+ */
+function extractTests(array $toks): array {
+    $out = [];
+    $sig = significant($toks);
+    $count = count($sig);
+    // Anti-burla (spec §6.4): service-locator no arquivo inteiro — vale também
+    // fora de método de teste (setUp, helpers de topo, Pest de topo).
+    $locator = $count > 0 ? serviceLocatorCalls($toks, $sig, $sig[0], $sig[$count - 1]) : [];
+    $appImports = [];
+    foreach (extractImports($toks) as $im) {
+        if (preg_match('#^App\\\\#', $im['fqcn'])) $appImports[] = $im['fqcn'];
+    }
+
+    for ($p = 0; $p < $count; $p++) {
+        $k = $sig[$p];
+        if ($toks[$k]['t'] !== T_CLASS) continue;
+        $class = nameOf($toks, $sig[$p + 1] ?? -1);
+        if ($class === null) continue;
+        $bodyOpen = findNextSig($toks, $sig, $p, '{');
+        if ($bodyOpen < 0) continue;
+        $bodyClose = matchDelim($toks, $bodyOpen);
+        if ($bodyClose < 0) continue;
+
+        $traits = classTraits($toks, $sig, $bodyOpen, $bodyClose);
+        $methods = [];
+        for ($q = $p; $q < $count; $q++) {
+            $mk = $sig[$q];
+            if ($toks[$mk]['t'] !== T_FUNCTION) continue;
+            if ($mk < $bodyOpen || $mk > $bodyClose) continue;
+            $mname = nameOf($toks, $sig[$q + 1] ?? -1);
+            if ($mname === null) continue;
+            if (strpos($mname, 'test') !== 0 && !hasTestAnnotation($toks, $mk)) continue;
+            $mOpen = findNextSig($toks, $sig, $q, '{');
+            if ($mOpen < 0 || $mOpen > $bodyClose) continue;
+            $mClose = matchDelim($toks, $mOpen);
+            if ($mClose < 0) continue;
+
+            $methods[] = [
+                'name' => $mname,
+                'line' => $toks[$mk]['l'],
+                'withoutMiddleware' => bodyHasCall($toks, $sig, $mOpen, $mClose, 'withoutMiddleware'),
+                'actingAs' => bodyHasCall($toks, $sig, $mOpen, $mClose, 'actingAs'),
+                'containerFakes' => containerFakes($toks, $sig, $mOpen, $mClose),
+                'mockOnly' => isMockOnly($toks, $sig, $mOpen, $mClose),
+                'importsApp' => $appImports,
+                'serviceLocator' => serviceLocatorCalls($toks, $sig, $mOpen, $mClose),
+            ];
+        }
+        if ($methods) $out[] = ['class' => $class, 'traits' => $traits, 'methods' => $methods];
+    }
+
+    foreach (pestTests($toks, $sig, $appImports) as $pt) $out[] = $pt;
+    return [$out, $locator];
+}
+
+function hasTestAnnotation(array $toks, int $fnK): bool {
+    for ($k = $fnK - 1; $k >= 0; $k--) {
+        $t = $toks[$k];
+        if (is_int($t['t']) && $t['t'] === T_DOC_COMMENT) return (bool) preg_match('/@test\b/', $t['s']);
+        if (is_int($t['t']) && $t['t'] !== T_WHITESPACE && $t['t'] !== T_COMMENT) break;
+    }
+    return false;
+}
+
+function classTraits(array $toks, array $sig, int $bodyOpen, int $bodyClose): array {
+    $traits = [];
+    for ($q = 0; $q < count($sig); $q++) {
+        $k = $sig[$q];
+        if ($k <= $bodyOpen || $k >= $bodyClose) continue;
+        if ($toks[$k]['t'] === T_USE) {
+            $r = $q + 1;
+            while ($r < count($sig)) {
+                $rk = $sig[$r];
+                if (is_string($toks[$rk]['t']) && $toks[$rk]['s'] === ';') break;
+                $nm = nameOf($toks, $rk);
+                if ($nm !== null) $traits[] = shortName($nm);
+                $r++;
+            }
+        }
+    }
+    return array_values(array_unique($traits));
+}
+
+function containerFakes(array $toks, array $sig, int $open, int $close): array {
+    $found = [];
+    $names = ['mock', 'partialMock', 'swap', 'fake'];
+    for ($q = 0; $q < count($sig); $q++) {
+        $k = $sig[$q];
+        if ($k <= $open || $k >= $close) continue;
+        if (isMemberOp($toks[$k])) {
+            $m = nameOf($toks, $sig[$q + 1] ?? -1);
+            if ($m !== null && in_array($m, $names, true)) {
+                $paren = $sig[$q + 2] ?? null;
+                if ($paren !== null && is_string($toks[$paren]['t']) && $toks[$paren]['s'] === '(') $found[] = $m;
+            }
+        }
+        if (isDoubleColon($toks[$k]) && nameOf($toks, $sig[$q - 1] ?? -1) === 'Container' && nameOf($toks, $sig[$q + 1] ?? -1) === 'set') {
+            $found[] = 'set';
+        }
+    }
+    return array_values(array_unique($found));
+}
+
+function isMockOnly(array $toks, array $sig, int $open, int $close): bool {
+    $hasMock = false; $hasDomain = false;
+    $mockNames = ['expects', 'shouldReceive', 'mock', 'partialMock'];
+    $domainAssert = ['assertSame', 'assertEquals', 'assertDatabaseHas', 'assertDatabaseMissing', 'assertJsonPath', 'assertJson', 'assertExactJson', 'assertTrue', 'assertFalse', 'assertNull', 'assertNotNull', 'assertCount', 'assertGreaterThan', 'assertLessThan'];
+    for ($q = 0; $q < count($sig); $q++) {
+        $k = $sig[$q];
+        if ($k <= $open || $k >= $close) continue;
+        if (isMemberOp($toks[$k])) {
+            $m = nameOf($toks, $sig[$q + 1] ?? -1);
+            if ($m === null) continue;
+            if (in_array($m, $mockNames, true)) $hasMock = true;
+            if (preg_match('/assert\w*Called$/', $m)) $hasMock = true;
+            if (in_array($m, $domainAssert, true)) $hasDomain = true;
+            if (preg_match('/assert(Status|JsonStructure|Header|Cookie)/', $m)) $hasDomain = true;
+        }
+    }
+    return $hasMock && !$hasDomain;
+}
+
+function pestTests(array $toks, array $sig, array $appImports): array {
+    $methods = [];
+    $count = count($sig);
+    for ($q = 0; $q < $count; $q++) {
+        $k = $sig[$q];
+        if (!is_int($toks[$k]['t']) || $toks[$k]['t'] !== T_STRING) continue;
+        $fn = $toks[$k]['s'];
+        if (!in_array($fn, ['test', 'it', 'describe'], true)) continue;
+        $prev = $sig[$q - 1] ?? null;
+        if ($prev !== null && isMemberOp($toks[$prev])) continue; // não é chamada de topo
+        $paren = $sig[$q + 1] ?? null;
+        if ($paren === null || !is_string($toks[$paren]['t']) || $toks[$paren]['s'] !== '(') continue;
+        $args = callArgs($toks, $paren);
+        if (!$args) continue;
+        $name = firstString($toks, $args[0]['from'], $args[0]['to']);
+        if ($name === '') continue;
+        $body = $args[count($args) - 1];
+        $methods[] = [
+            'name' => $name,
+            'line' => $toks[$k]['l'],
+            'withoutMiddleware' => bodyHasCall($toks, $sig, $body['from'], $body['to'], 'withoutMiddleware'),
+            'actingAs' => bodyHasCall($toks, $sig, $body['from'], $body['to'], 'actingAs'),
+            'containerFakes' => containerFakes($toks, $sig, $body['from'], $body['to']),
+            'mockOnly' => isMockOnly($toks, $sig, $body['from'], $body['to']),
+            'importsApp' => $appImports,
+            'serviceLocator' => serviceLocatorCalls($toks, $sig, $body['from'], $body['to']),
+        ];
+    }
+    if (!$methods) return [];
+    return [['class' => '(Pest)', 'traits' => [], 'methods' => $methods]];
+}
+
+// ---------------------------------------------------------------------------
+// Driver
+// ---------------------------------------------------------------------------
+
+$root = null;
+$files = [];
+$argvv = $_SERVER['argv'] ?? [];
+$n = count($argvv);
+$i = 1;
+while ($i < $n) {
+    $a = $argvv[$i];
+    if ($a === '--root') { $i++; if ($i < $n) $root = $argvv[$i]; }
+    elseif ($a === '--files') { $i++; while ($i < $n) { $files[] = $argvv[$i]; $i++; } break; }
+    $i++;
+}
+if ($root === null) {
+    fwrite(STDERR, "uso: ast_extractor.php --root <raiz> --files <...>\n");
+    echo json_encode(['version' => 1, 'files' => []]), "\n";
+    exit(0);
+}
+$root = rtrim($root, '/');
+
+$blocked = ['#(^|/)vendor/#', '#(^|/)node_modules/#', '#(^|/)storage/#'];
+$resultFiles = [];
+
+foreach ($files as $rel) {
+    $rel = str_replace('\\', '/', $rel);
+    $skip = false;
+    foreach ($blocked as $b) { if (preg_match($b, $rel)) { $skip = true; break; } }
+    if ($skip) continue;
+    $abs = $root . '/' . ltrim($rel, '/');
+    if (!is_file($abs)) { $resultFiles[] = ['path' => $rel, 'error' => 'missing']; continue; }
+    $src = @file_get_contents($abs);
+    if ($src === false) { $resultFiles[] = ['path' => $rel, 'error' => 'unreadable']; continue; }
+    $toks = tokenize($src);
+    if ($toks === null) { $resultFiles[] = ['path' => $rel, 'error' => 'syntax']; continue; }
+    [$tests, $locator] = extractTests($toks);
+    $resultFiles[] = [
+        'path' => $rel,
+        'kind' => classify($rel),
+        'imports' => extractImports($toks),
+        'routes' => extractRoutes($toks),
+        'controllers' => extractControllers($toks),
+        'formRequests' => extractFormRequests($toks),
+        'rawQueries' => extractRawQueries($toks),
+        'tests' => $tests,
+        'serviceLocator' => $locator,
+    ];
+}
+
+echo json_encode(['version' => 1, 'files' => $resultFiles], JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE), "\n";
+exit(0);