phpstan-error-parser

A JavaScript/TypeScript parser that converts PHPStan error messages into a structured format for easier programmatic processing and analysis.

Overview

This is a JavaScript/TypeScript library that parses PHPStan error messages and extracts key components like function names, method names, variables, and doc tags into a structured data format. It uses Chevrotain for lexical analysis and parsing.

Features

- Parse PHPStan error messages into structured tokens
- Extract and identify:
- Function names (including namespaced functions)
- Method names (both static and instance methods)
- Variable names
- PHPDoc tags
- Common words
- Get location information (start/end columns) for each token
- Built with TypeScript for type safety

Tasks

- [x] comma
- [ ] -> ("Using nullsafe method call on non-nullable type Exception. Use -> instead.")
- [ ] number as a word (-123, 8.5)
- [ ] number as a type (array{1, 3})
- [ ] error including parameter number(#1, #2, ...)
- [ ] static keyword(static::)
- [ ] types
- [ ] array types (int[], string[][])
- [ ] array shapes (array{key: value, ...}, array{0}, array{})
- [ ] generic types (Path\SomeClass, array)
- [ ] Union type
- [ ] Intersection type

- [] more...

Installation

``bash
npm install phpstan-error-parser
`

Usage

`typescript
import { parse } from 'phpstan-error-parser';

const errorMessage = "Function format not found.";
const words = parse(errorMessage);

console.log(words);
// Output:
// [
// { type: 'common_word', value: 'Function', location: { startColumn: 0, endColumn: 8 } },
// { type: 'function_name', value: 'format', location: { startColumn: 9, endColumn: 15 } },
// { type: 'common_word', value: 'not', location: { startColumn: 16, endColumn: 19 } },
// { type: 'common_word', value: 'found', location: { startColumn: 20, endColumn: 25 } },
// { type: 'period', value: '.', location: { startColumn: 25, endColumn: 26 } }
// ]
`

API

$3

Parses a PHPStan error message and returns an array of structured word tokens.

Parameters:
- errorMessage: The PHPStan error message string to parse

Returns:
- An array of Word objects

$3

`typescript
type Word = {
type: "function_name" | "method_name" | "variable_name" | "doc_tag" | "common_word" | "period";
value: string;
location: {
startColumn: number;
endColumn: number;
};
};
`

Supported Patterns

The parser can identify:

- Function names: Function format, Function abc\format (with namespaces)
- Method names: Method formatString(), method getData
- Variables: $variable, $user_name
- Doc tags: @param, @return, @var
- Common words: Regular words in the error message
- Punctuation: Periods marking sentence endings

Development

$3

`bash
git clone
cd phpstan-error-parser
npm install
`

$3

`bash
npm test
`

$3

View the parser diagram visualization like Chevrotain Playground:

`bash
npm run diagram
`

$3

A development tool to calculate word offsets for testing purposes:

`bash


Link the package globally (run once)


npm link
`

`bash


Use the CLI from anywhere

calc-offset "Function format not found."

|0 |9 |16 |20
Function format not found.
|8 |15 |19 |26
`

`bash


Unlink when done


npm unlink -g phpstan-error-parser
`

Project Structure

`
├── src/
│ ├── parser.ts # Lexer and parser definitions
│ ├── format.ts # CST to structured format converter
│ └── index.ts # Main export
├── test/
│ ├── parser.spec.ts
│ └── format.spec.ts
└── package.json
`

Examples

$3

`typescript
const errorMessage = "Method formatString() not found in class MyClass.";
const words = parse(errorMessage);
// Extracts 'formatString()' as a method_name token
`

$3

`typescript
const errorMessage = "Variable $userName is not defined.";
const words = parse(errorMessage);
// Extracts '$userName' as a variable_name token
`

$3

`typescript
const errorMessage = "Invalid @param tag in docblock.";
const words = parse(errorMessage);
// Extracts '@param' as a doc_tag token
``

License

MIT

Credit

- Inspired by pretty-ts-error

Keywords

- PHPStan
- parser
- static analysis
- error parsing