phpstan-mcp-mx 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Martijn Schimmel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,147 @@
+# phpstan-mcp-mx
+
+Een MCP-server die [PHPStan](https://phpstan.org) ontsluit als tools voor Claude. Eén server
+bedient meerdere PHP-projecten tegelijk; welke dat zijn, leg je zelf vast.
+
+## Installatie
+
+```bash
+claude mcp add phpstan \
+  --env PHPSTAN_MCP_ROOTS=/pad/naar/projecten \
+  -- npx -y phpstan-mcp-mx
+```
+
+Of, als je de repo lokaal hebt staan:
+
+```bash
+npm install && npm run build
+claude mcp add phpstan \
+  --env PHPSTAN_MCP_ROOTS=/pad/naar/projecten \
+  -- node /pad/naar/phpstan-mcp-mx/dist/index.js
+```
+
+Voor Claude Desktop komt hetzelfde in `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "phpstan": {
+      "command": "npx",
+      "args": ["-y", "phpstan-mcp-mx"],
+      "env": { "PHPSTAN_MCP_ROOTS": "/pad/naar/projecten" }
+    }
+  }
+}
+```
+
+## Configuratie
+
+`PHPSTAN_MCP_ROOTS` is verplicht: een lijst absolute paden, gescheiden door een dubbele punt
+(een puntkomma op Windows). Alles daaronder mag geanalyseerd worden, alles daarbuiten niet.
+
+```
+PHPSTAN_MCP_ROOTS=/Users/jij/projecten:/Users/jij/werk/klant-x
+```
+
+Een root hoeft niet zelf een project te zijn. De server zoekt tot vier niveaus diep naar
+mappen met een `composer.json`, stopt zodra hij er een vindt, en slaat `vendor/`,
+`node_modules/` en verborgen mappen over. Een indeling als `~/projecten/<klant>/<project>`
+werkt dus met `~/projecten` als enige root.
+
+### Waarom die lijst verplicht is
+
+PHPStan is geen passieve parser. Het laadt de autoloader van het project, voert
+`bootstrapFiles` uit de configuratie uit en laadt extensies als PHP-code. "Analyseer map X"
+betekent daarmee "voer de PHP-code uit die in X's configuratie staat" — en het pad komt van
+een taalmodel. De lijst met roots maakt expliciet en menselijk vastgesteld wat binnen bereik
+ligt.
+
+## Tools
+
+Elke tool verwacht een expliciet `project`-pad. De server heeft geen "huidig project": dat
+zou toestand zijn die het model niet in zijn context ziet staan, met stilzwijgend het
+verkeerde project als gevolg.
+
+### `list_projects`
+
+Somt de projecten op die binnen bereik liggen, met per project of PHPStan geïnstalleerd is
+en welk configbestand er ligt. Begin hier — het `path` uit het resultaat is wat de andere
+tools als `project` verwachten.
+
+### `analyse_project`
+
+| Argument | Verplicht | Betekenis |
+| --- | --- | --- |
+| `project` | ja | absoluut pad naar de projectroot |
+| `paths` | nee | paden binnen het project; leeg betekent: volg `phpstan.neon` |
+| `level` | nee | level-override, `0` t/m `10` of `max` |
+| `memoryLimit` | nee | bijv. `1G`, als PHPStan op de PHP-geheugenlimiet klapt |
+| `timeoutSeconds` | nee | standaard 300 |
+| `offset` / `limit` | nee | welk deel van de bevindingen je terugkrijgt |
+
+### `analyse_file`
+
+Zelfde argumenten, plus een verplichte `path` — één bestand of map binnen het project. Het
+pad mag relatief aan de projectroot zijn of absoluut, maar moet er wel binnen liggen.
+
+### `baseline_summary`
+
+Leest de `phpstan-baseline*.neon` van een project en telt wat er genegeerd wordt, per
+identifier en per bestand. Draait geen analyse, dus het antwoord is er meteen.
+
+Let op het onderscheid: wat hier in staat is precies wat `analyse_project` *niet* meldt. Een
+project dat zijn baseline includet, rapporteert alleen de fouten die er nieuw bij komen —
+die vergelijking maakt PHPStan zelf al.
+
+## Wat je terugkrijgt
+
+Een analyse levert eerst tellingen over álle bevindingen en daarna één pagina met de
+bevindingen zelf (standaard 50, hoogstens 500):
+
+```
+25 bevinding(en) in 11 bestand(en).
+
+Meest voorkomend:
+    13  argument.type
+     6  return.type
+
+Zwaarst getroffen bestanden:
+     6  src/Support/Filters/DealFilters.php
+
+Bevindingen 1-50 van 25:
+
+src/Support/Filters/DealFilters.php
+  42  argument.type  Parameter #1 $id expects int, string given.
+```
+
+Bij meer resultaten eindigt de tekst met de letterlijke vervolgaanroep (`offset=50`).
+
+## Vereisten
+
+- Node 20 of nieuwer
+- PHPStan geïnstalleerd in het project zelf (`vendor/bin/phpstan`); de server brengt geen
+  eigen PHPStan mee, want de versie en de extensies horen bij het project
+
+## Bekende scherpe randen
+
+- **De PHP-geheugenlimiet.** PHPStan klapt daar met een groot project makkelijk overheen;
+  `memoryLimit: "1G"` lost dat meestal op. De crash komt terug als een gewone fout, met
+  PHPStans eigen uitleg erbij.
+- **Larastan start je Laravel-applicatie.** Lukt dat niet — ontbrekende `.env`, database niet
+  bereikbaar — dan faalt de analyse met de uitleg van Larastan zelf.
+- **Analyses in hetzelfde project draaien na elkaar,** omdat PHPStans resultcache in het
+  project ligt. Verschillende projecten draaien wel tegelijk.
+
+## Ontwikkelen
+
+```bash
+npm run build        # tsc → dist/
+npm run typecheck    # inclusief de tests
+npm run lint
+npm test
+npm run inspect      # MCP Inspector tegen de gebouwde server
+```
+
+## Licentie
+
+MIT

package/dist/baseline.d.ts

@@ -0,0 +1,52 @@
+import type { ResolvedProject } from './project.js';
+/** Eén genegeerde fout uit een baseline-bestand. */
+export interface BaselineEntry {
+    readonly identifier: string;
+    readonly path: string;
+    /** Hoe vaak deze fout in dat bestand genegeerd wordt. */
+    readonly count: number;
+}
+/** Wat er in de baselines van één project staat. */
+export interface BaselineSummary {
+    readonly project: string;
+    /** De gevonden baseline-bestanden, met per bestand de aantallen. */
+    readonly files: readonly {
+        file: string;
+        entries: number;
+        errors: number;
+    }[];
+    readonly totals: {
+        readonly entries: number;
+        readonly errors: number;
+    };
+    readonly byIdentifier: readonly {
+        identifier: string;
+        count: number;
+    }[];
+    readonly byPath: readonly {
+        path: string;
+        count: number;
+    }[];
+}
+/** Fout die als bruikbare melding naar het model teruggaat, niet als crash. */
+export declare class BaselineError extends Error {
+}
+/**
+ * Zoekt de baseline-bestanden in de projectroot. Alleen daar en niet dieper: een
+ * baseline hoort naast phpstan.neon te staan, en dieper zoeken zou de baselines
+ * van pakketten in vendor/ oppikken.
+ */
+export declare function findBaselineFiles(project: ResolvedProject): string[];
+/**
+ * Leest een baseline-bestand uit.
+ *
+ * Bewust een regelgerichte parser en geen NEON-bibliotheek: er is geen fatsoenlijke
+ * NEON-parser voor JavaScript, en dit bestand wordt door PHPStan zelf gegenereerd —
+ * de vorm ligt vast. Alleen de velden die we tellen worden gelezen; de
+ * message-regex laten we links liggen, want daar doen we niets mee.
+ */
+export declare function parseBaseline(content: string): BaselineEntry[];
+/** Telt de baselines van één project bij elkaar op. */
+export declare function summariseBaseline(project: ResolvedProject): BaselineSummary;
+/** Schrijft een baseline-samenvatting uit als tekst voor het model. */
+export declare function renderBaseline(summary: BaselineSummary): string;

package/dist/baseline.js

@@ -0,0 +1,145 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+/** Hoeveel regels de samenvattingslijsten hoogstens tonen. */
+const SUMMARY_ROWS = 15;
+/** Fout die als bruikbare melding naar het model teruggaat, niet als crash. */
+export class BaselineError extends Error {
+}
+/**
+ * Zoekt de baseline-bestanden in de projectroot. Alleen daar en niet dieper: een
+ * baseline hoort naast phpstan.neon te staan, en dieper zoeken zou de baselines
+ * van pakketten in vendor/ oppikken.
+ */
+export function findBaselineFiles(project) {
+    try {
+        return readdirSync(project.path, { withFileTypes: true })
+            .filter((entry) => entry.isFile() && /^phpstan-baseline.*\.neon$/.test(entry.name))
+            .map((entry) => entry.name)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Leest een baseline-bestand uit.
+ *
+ * Bewust een regelgerichte parser en geen NEON-bibliotheek: er is geen fatsoenlijke
+ * NEON-parser voor JavaScript, en dit bestand wordt door PHPStan zelf gegenereerd —
+ * de vorm ligt vast. Alleen de velden die we tellen worden gelezen; de
+ * message-regex laten we links liggen, want daar doen we niets mee.
+ */
+export function parseBaseline(content) {
+    const entries = [];
+    let current = null;
+    const flush = () => {
+        if (current === null)
+            return;
+        // Een blok zonder path is geen bruikbare entry; identifier ontbreekt bij
+        // baselines van vóór PHPStan 1.11 en heet dan expliciet onbekend.
+        if (current.path !== undefined) {
+            entries.push({
+                identifier: current.identifier ?? '(zonder identifier)',
+                path: current.path,
+                count: current.count ?? 1,
+            });
+        }
+        current = null;
+    };
+    for (const line of content.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed === '-') {
+            flush();
+            current = {};
+            continue;
+        }
+        if (current === null)
+            continue;
+        const match = /^(identifier|path|count):\s*(.*)$/.exec(trimmed);
+        if (match === null)
+            continue;
+        const [, key, raw] = match;
+        const value = (raw ?? '').trim();
+        if (key === 'identifier')
+            current.identifier = unquote(value);
+        else if (key === 'path')
+            current.path = unquote(value);
+        else if (key === 'count')
+            current.count = Number.parseInt(value, 10) || 1;
+    }
+    flush();
+    return entries;
+}
+/** Telt de baselines van één project bij elkaar op. */
+export function summariseBaseline(project) {
+    const files = findBaselineFiles(project);
+    if (files.length === 0) {
+        throw new BaselineError(`${project.path} heeft geen baseline (geen phpstan-baseline*.neon in de projectmap).`);
+    }
+    const perFile = [];
+    const all = [];
+    for (const file of files) {
+        const content = readFileSync(join(project.path, file), 'utf8');
+        const entries = parseBaseline(content);
+        // Een leeg resultaat uit een bestand dat wél ignoreErrors noemt betekent dat
+        // de vorm afwijkt van wat we aankunnen. Dat is iets anders dan "nul fouten".
+        if (entries.length === 0 && content.includes('ignoreErrors')) {
+            throw new BaselineError(`${file} bevat ignoreErrors maar er is geen enkele entry uit te lezen. ` +
+                'Waarschijnlijk een vorm die deze server niet kent.');
+        }
+        perFile.push({
+            file,
+            entries: entries.length,
+            errors: entries.reduce((sum, entry) => sum + entry.count, 0),
+        });
+        all.push(...entries);
+    }
+    return {
+        project: project.path,
+        files: perFile,
+        totals: {
+            entries: all.length,
+            errors: all.reduce((sum, entry) => sum + entry.count, 0),
+        },
+        byIdentifier: tally(all, (entry) => entry.identifier).map(([identifier, count]) => ({
+            identifier,
+            count,
+        })),
+        byPath: tally(all, (entry) => entry.path).map(([path, count]) => ({ path, count })),
+    };
+}
+/** Schrijft een baseline-samenvatting uit als tekst voor het model. */
+export function renderBaseline(summary) {
+    const lines = [];
+    if (summary.totals.entries === 0) {
+        lines.push('De baseline is leeg.');
+        return lines.join('\n');
+    }
+    lines.push(`${summary.totals.errors} genegeerde fout(en) in ${summary.totals.entries} baseline-regel(s).`);
+    if (summary.files.length > 1) {
+        lines.push('', 'Per bestand:');
+        for (const file of summary.files)
+            lines.push(`  ${pad(file.errors)}  ${file.file}`);
+    }
+    lines.push('', 'Meest genegeerd:', ...summary.byIdentifier.map((row) => `  ${pad(row.count)}  ${row.identifier}`), '', 'Zwaarst belaste bestanden:', ...summary.byPath.map((row) => `  ${pad(row.count)}  ${row.path}`), '', 'Dit is wat PHPStan bewust negeert. Wat analyse_project meldt staat hier juist níét in:', 'een project dat zijn baseline includet, rapporteert alleen wat er nieuw bij komt.');
+    return lines.join('\n');
+}
+/** De drukste regels eerst, bij gelijk aantal alfabetisch zodat de volgorde vastligt. */
+function tally(entries, key) {
+    const counts = new Map();
+    for (const entry of entries) {
+        const name = key(entry);
+        counts.set(name, (counts.get(name) ?? 0) + entry.count);
+    }
+    return [...counts.entries()]
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+        .slice(0, SUMMARY_ROWS);
+}
+function unquote(value) {
+    const match = /^'(.*)'$/.exec(value) ?? /^"(.*)"$/.exec(value);
+    return match?.[1] ?? value;
+}
+function pad(count) {
+    return String(count).padStart(5);
+}
+//# sourceMappingURL=baseline.js.map

package/dist/baseline.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { loadRoots } from './roots.js';
+import { VERSION, createServer } from './server.js';
+async function main() {
+    const roots = loadRoots();
+    const server = createServer(roots);
+    // stdio: het protocol zelf loopt over stdout. Alles wat deze server logt moet
+    // daarom naar stderr — één console.log breekt de JSON-RPC-stroom.
+    await server.connect(new StdioServerTransport());
+    console.error(`phpstan-mcp ${VERSION} luistert op stdio, ${roots.length} root(s) geconfigureerd`);
+}
+main().catch((error) => {
+    console.error('phpstan-mcp kon niet starten:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEpD,KAAK,UAAU,IAAI;IACjB,MAAM,KAAK,GAAG,SAAS,EAAE,CAAC;IAC1B,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IAEnC,8EAA8E;IAC9E,kEAAkE;IAClE,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAC;IAEjD,OAAO,CAAC,KAAK,CAAC,eAAe,OAAO,uBAAuB,KAAK,CAAC,MAAM,yBAAyB,CAAC,CAAC;AACpG,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC9B,OAAO,CAAC,KAAK,CAAC,+BAA+B,EAAE,KAAK,CAAC,CAAC;IACtD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/phpstan.d.ts

@@ -0,0 +1,45 @@
+import type { ResolvedProject } from './project.js';
+/** Standaardtijd waarna een analyse wordt afgebroken. */
+export declare const DEFAULT_TIMEOUT_MS = 300000;
+/** Eén bevinding van PHPStan, gekoppeld aan een bestand. */
+export interface Finding {
+    /** Absoluut pad zoals PHPStan het rapporteert. */
+    readonly file: string;
+    readonly line: number | null;
+    readonly message: string;
+    /** Bijv. "argument.type"; ontbreekt bij oudere PHPStan-versies. */
+    readonly identifier: string | null;
+    /** PHPStans eigen hint bij deze fout, als die er is. */
+    readonly tip: string | null;
+}
+/** Uitkomst van een geslaagde analyse — ook als er fouten gevonden zijn. */
+export interface AnalysisResult {
+    readonly project: string;
+    readonly findings: readonly Finding[];
+    /** Fouten die niet aan een bestand hangen, zoals configuratieproblemen. */
+    readonly generalErrors: readonly string[];
+    readonly totals: {
+        readonly fileErrors: number;
+        readonly generalErrors: number;
+    };
+}
+/** Opties per aanroep; alles optioneel, want het project bepaalt de standaard. */
+export interface AnalyseOptions {
+    /** Paden binnen het project. Leeg betekent: gebruik wat in de config staat. */
+    readonly paths?: readonly string[];
+    /** Level-override, 0 t/m 10 of "max". */
+    readonly level?: string;
+    readonly memoryLimit?: string;
+    readonly timeoutMs?: number;
+}
+/** Fout die als bruikbare melding naar het model teruggaat, niet als crash. */
+export declare class PhpstanError extends Error {
+}
+/**
+ * Draait PHPStan in één project en levert de bevindingen.
+ *
+ * Aanroepen op hetzelfde project worden op volgorde afgehandeld: PHPStans
+ * resultcache ligt ín het project, en twee gelijktijdige runs schrijven daar
+ * overheen. Verschillende projecten draaien wél parallel.
+ */
+export declare function analyse(project: ResolvedProject, options?: AnalyseOptions): Promise<AnalysisResult>;

package/dist/phpstan.js

@@ -0,0 +1,208 @@
+import { spawn } from 'node:child_process';
+import { z } from 'zod';
+/** Standaardtijd waarna een analyse wordt afgebroken. */
+export const DEFAULT_TIMEOUT_MS = 300_000;
+/** Fout die als bruikbare melding naar het model teruggaat, niet als crash. */
+export class PhpstanError extends Error {
+}
+/**
+ * Draait PHPStan in één project en levert de bevindingen.
+ *
+ * Aanroepen op hetzelfde project worden op volgorde afgehandeld: PHPStans
+ * resultcache ligt ín het project, en twee gelijktijdige runs schrijven daar
+ * overheen. Verschillende projecten draaien wél parallel.
+ */
+export async function analyse(project, options = {}) {
+    if (project.binary === null) {
+        throw new PhpstanError(`PHPStan is niet geïnstalleerd in ${project.path} (vendor/bin/phpstan ontbreekt). ` +
+            'Draai daar eerst `composer install`.');
+    }
+    // Na de null-check is binary een string; dit maakt dat expliciet zodat run()
+    // er geen cast voor nodig heeft.
+    const installed = { ...project, binary: project.binary };
+    return enqueue(installed.path, () => run(installed, options));
+}
+async function run(project, options) {
+    const args = buildArgs(project, options);
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const execution = await execute(project.binary, args, project.path, timeoutMs);
+    if (execution.spawnError !== null) {
+        throw new PhpstanError(`PHPStan kon niet gestart worden in ${project.path}: ${execution.spawnError.message}`);
+    }
+    if (execution.signal !== null) {
+        throw new PhpstanError(`De analyse van ${project.path} is na ${Math.round(timeoutMs / 1000)}s afgebroken ` +
+            `(signaal ${execution.signal}). Analyseer een kleiner deel van het project, of verhoog timeoutMs.`);
+    }
+    // Eerst proberen te parsen, pas daarna naar de exit code kijken: PHPStan geeft
+    // ook exit code 1 als het gewoon fouten gevonden heeft, en meldt configuratie-
+    // problemen ín de JSON. De exit code alleen is dus geen betrouwbaar signaal.
+    const parsed = tryParse(execution.stdout);
+    if (parsed !== null)
+        return toResult(project.path, parsed);
+    throw new PhpstanError(describeFailure(project, execution));
+}
+function buildArgs(project, options) {
+    const args = ['analyse', '--error-format=json', '--no-progress', '--no-interaction', '--no-ansi'];
+    if (options.level !== undefined)
+        args.push(`--level=${options.level}`);
+    if (options.memoryLimit !== undefined)
+        args.push(`--memory-limit=${options.memoryLimit}`);
+    // Zonder config én zonder paden weet PHPStan niet wat het moet doen; dan is een
+    // duidelijke melding beter dan PHPStans eigen usage-tekst.
+    const paths = options.paths ?? [];
+    if (paths.length === 0 && project.config === null) {
+        throw new PhpstanError(`${project.path} heeft geen phpstan.neon(.dist). Geef expliciet paths mee, of maak een config aan.`);
+    }
+    args.push(...paths);
+    return args;
+}
+/** Hoe lang een gedode procesgroep de tijd krijgt voordat SIGKILL volgt. */
+const KILL_GRACE_MS = 5_000;
+/**
+ * Start PHPStan zonder shell. Bewust spawn en niet execFile: die laatste kapt de
+ * output af op maxBuffer (1 MB), en de JSON van een groot project gaat daar
+ * ruim overheen.
+ *
+ * `detached: true` maakt het proces leider van een eigen procesgroep, zodat een
+ * timeout de héle groep kan doden. Zonder dat blijven PHPStans parallelle workers
+ * na een timeout gewoon doorrekenen.
+ */
+function execute(binary, args, cwd, timeoutMs) {
+    return new Promise((resolve) => {
+        // Geen `timeout`-optie van spawn: die doodt alleen het proces zelf.
+        const child = spawn(binary, args, { cwd, shell: false, detached: true });
+        const stdout = [];
+        const stderr = [];
+        let spawnError = null;
+        child.stdout.on('data', (chunk) => stdout.push(chunk));
+        child.stderr.on('data', (chunk) => stderr.push(chunk));
+        child.on('error', (error) => {
+            spawnError = error;
+        });
+        const timers = [];
+        const stopTimers = () => timers.forEach((timer) => { clearTimeout(timer); });
+        timers.push(setTimeout(() => {
+            killGroup(child.pid, 'SIGTERM');
+            // Wie op SIGTERM niet reageert, krijgt alsnog SIGKILL.
+            timers.push(setTimeout(() => { killGroup(child.pid, 'SIGKILL'); }, KILL_GRACE_MS));
+        }, timeoutMs));
+        let settled = false;
+        const finish = (code, signal) => {
+            if (settled)
+                return;
+            settled = true;
+            stopTimers();
+            resolve({
+                code,
+                signal,
+                stdout: Buffer.concat(stdout).toString('utf8'),
+                stderr: Buffer.concat(stderr).toString('utf8'),
+                spawnError,
+            });
+        };
+        // Normaal wachten we op 'close': dan is alle output binnen.
+        child.on('close', finish);
+        // Maar bij een timeout wordt alleen het proces zelf gedood, terwijl zijn
+        // kleinkinderen — PHPStan draait parallelle workers — de pipes openhouden.
+        // 'close' komt dan pas als die klaar zijn, en dan is de timeout geen timeout
+        // meer. Zodra het proces zelf door een signaal is gestopt, heeft wachten op
+        // meer output geen zin.
+        child.on('exit', (code, signal) => {
+            if (signal !== null)
+                finish(code, signal);
+        });
+    });
+}
+/**
+ * Doodt de hele procesgroep van `pid`. Het minteken maakt van het pid een
+ * groeps-id; dat werkt alleen omdat het proces met `detached` is gestart.
+ */
+function killGroup(pid, signal) {
+    if (pid === undefined)
+        return;
+    try {
+        process.kill(-pid, signal);
+    }
+    catch {
+        // De groep kan al verdwenen zijn tussen de timer en deze aanroep; dat is
+        // precies de gewenste uitkomst, geen fout.
+    }
+}
+const findingSchema = z.object({
+    message: z.string(),
+    line: z.number().nullable().optional(),
+    identifier: z.string().nullable().optional(),
+    tip: z.string().nullable().optional(),
+});
+const outputSchema = z.object({
+    totals: z.object({ errors: z.number(), file_errors: z.number() }),
+    files: z.record(z.string(), z.object({ messages: z.array(findingSchema) })),
+    errors: z.array(z.string()),
+});
+function tryParse(stdout) {
+    if (stdout.trim() === '')
+        return null;
+    let raw;
+    try {
+        raw = JSON.parse(stdout);
+    }
+    catch {
+        return null;
+    }
+    // PHP codeert een lege associatieve array als [], niet als {}. Een project
+    // zonder bevindingen levert dus "files": [] op, wat het schema anders afkeurt.
+    if (typeof raw === 'object' && raw !== null && Array.isArray(raw.files)) {
+        raw.files = {};
+    }
+    const parsed = outputSchema.safeParse(raw);
+    return parsed.success ? parsed.data : null;
+}
+function toResult(project, output) {
+    const findings = [];
+    for (const [file, entry] of Object.entries(output.files)) {
+        for (const message of entry.messages) {
+            findings.push({
+                file,
+                line: message.line ?? null,
+                message: message.message,
+                identifier: message.identifier ?? null,
+                tip: message.tip ?? null,
+            });
+        }
+    }
+    return {
+        project,
+        findings,
+        generalErrors: output.errors,
+        totals: { fileErrors: output.totals.file_errors, generalErrors: output.totals.errors },
+    };
+}
+/** Vertaalt een run die geen bruikbare JSON opleverde naar iets waar je wat mee kunt. */
+function describeFailure(project, execution) {
+    const details = (execution.stderr.trim() || execution.stdout.trim()).slice(0, 2000);
+    // PHPStan meldt dit op twee manieren: PHP's eigen "Allowed memory size ...
+    // exhausted", en PHPStans eigen "reached configured PHP memory limit: 128M".
+    if (/allowed memory size|memory[_ ]limit/i.test(details)) {
+        return (`PHPStan liep in ${project.path} tegen de PHP-geheugenlimiet aan. ` +
+            'Geef memoryLimit mee (bijv. "1G") of analyseer een kleiner deel.\n\n' +
+            details);
+    }
+    return (`PHPStan gaf geen bruikbare JSON terug in ${project.path} (exit code ${execution.code ?? '?'}).\n\n` +
+        (details === '' ? 'Geen output op stdout of stderr.' : details));
+}
+/** Lopende analyses per projectpad, zodat aanroepen per project op volgorde gaan. */
+const queues = new Map();
+function enqueue(key, task) {
+    const previous = queues.get(key) ?? Promise.resolve();
+    // .catch vóór .then: een mislukte vorige analyse mag de volgende niet blokkeren.
+    const result = previous.then(task, task);
+    const tail = result.catch(() => undefined);
+    queues.set(key, tail);
+    void tail.then(() => {
+        // Alleen opruimen als er ondertussen niets nieuws achteraan is gezet.
+        if (queues.get(key) === tail)
+            queues.delete(key);
+    });
+    return result;
+}
+//# sourceMappingURL=phpstan.js.map