npm package: @llmignore/parser
Description: Parse and match .llmignore, .cursorignore, .aiignore, and 10+ other AI ignore file formats. Zero dependencies.
Author: rival.tips
Latest version: 0.1.1

# @llmignore/parser

Parse and match `.llmignore`, `.cursorignore`, `.aiignore`, and 10+ other AI ignore file formats. Zero dependencies.

Built by [rival.tips](https://rival.tips) — the AI model comparison platform.

## Install

```bash
npm install @llmignore/parser
```

## Usage

### Parse an ignore file

```ts
import { parse } from "@llmignore/parser";

const result = parse(`
# Secrets
.env
.env.*
**/*.pem

# Re-include example config
!.env.example
`);

console.log(result.patternCount); // 4
console.log(result.negationCount); // 1
console.log(result.patterns);
// [
//   { pattern: ".env", isNegation: false, isDirectoryOnly: false, isAnchored: false, source: 3 },
//   { pattern: ".env.*", isNegation: false, isDirectoryOnly: false, isAnchored: false, source: 4 },
//   { pattern: "**/*.pem", isNegation: false, isDirectoryOnly: false, isAnchored: false, source: 5 },
//   { pattern: ".env.example", isNegation: true, isDirectoryOnly: false, isAnchored: false, source: 8 },
// ]
```

### Match file paths

```ts
import { parse, match } from "@llmignore/parser";

const { patterns } = parse(`
*.log
!important.log
node_modules/
`);

match(patterns, "debug.log");           // true  (excluded)
match(patterns, "important.log");       // false (re-included by negation)
match(patterns, "src/app.ts");          // false (not matched)
match(patterns, "node_modules", true);  // true  (directory-only pattern, isDirectory=true)
match(patterns, "node_modules");        // false (directory-only pattern, but isDirectory defaults to false)
```

### Find all matching patterns

```ts
import { parse, matchAll } from "@llmignore/parser";

const { patterns } = parse(`
*.log
!important.log
`);

const hits = matchAll(patterns, "important.log");
// Returns both patterns that matched:
// [
//   { pattern: "*.log", isNegation: false, ... },
//   { pattern: "important.log", isNegation: true, ... }
// ]
```

### List supported formats

```ts
import { FORMATS, getFormat } from "@llmignore/parser";

console.log(FORMATS.length); // 13

const cursor = getFormat("cursorignore");
// {
//   id: "cursorignore",
//   filename: ".cursorignore",
//   tool: "Cursor",
//   description: "Blocks files from all AI features in Cursor",
//   official: true,
//   supportsNegation: true,
//   supportsCascading: false,
//   docsUrl: "https://cursor.com/docs/context/ignore-files"
// }
```

## Supported Formats

| Format | File | Tool | Official |
|--------|------|------|----------|
| llmignore | `.llmignore` | Universal | Yes |
| cursorignore | `.cursorignore` | Cursor | Yes |
| aiignore | `.aiignore` | JetBrains | Yes |
| aiexclude | `.aiexclude` | Google Gemini | Yes |
| claudeignore | `.claudeignore` | Claude Code | No |
| codeiumignore | `.codeiumignore` | Windsurf | Yes |
| geminiignore | `.geminiignore` | Gemini CLI | Yes |
| aiderignore | `.aiderignore` | Aider | Yes |
| clineignore | `.clineignore` | Cline | Yes |
| rooignore | `.rooignore` | Roo Code | Yes |
| augmentignore | `.augmentignore` | Augment | Yes |
| copilotignore | `.copilotignore` | GitHub Copilot | No |
| repomixignore | `.repomixignore` | Repomix | Yes |

## API

### `parse(content: string): ParsedIgnoreFile`

Parses raw ignore file content into structured pattern objects.

Returns a `ParsedIgnoreFile` with:
- `patterns` — Array of `Pattern` objects
- `patternCount` — Total number of patterns
- `negationCount` — Number of negation (`!`) patterns

### `match(patterns: Pattern[], filePath: string, isDirectory?: boolean): boolean`

Checks if a file path is excluded by the given patterns. Uses gitignore's "last matching rule wins" semantics. Negation patterns re-include previously excluded paths.

### `matchAll(patterns: Pattern[], filePath: string, isDirectory?: boolean): Pattern[]`

Returns all patterns that match the given path (without applying last-match-wins). Useful for debugging or building UIs that show why a file was excluded.

### `FORMATS: Format[]`

Array of all 13 supported AI ignore file format definitions.

### `getFormat(id: string): Format | undefined`

Look up a format by its id (e.g., `"cursorignore"`).

## Pattern Syntax

The parser follows `.gitignore` conventions:

| Syntax | Meaning |
|--------|---------|
| `#` | Comment line |
| `!pattern` | Negation (re-include) |
| `*` | Match anything except `/` |
| `**` | Match zero or more directories |
| `?` | Match one character except `/` |
| `[abc]` | Character class |
| `pattern/` | Match directories only |
| `/pattern` | Anchored to root |
| `dir/file` | Implicitly anchored |

## Links

- [.llmignore spec & builder](https://rival.tips/llmignore)
- [Spec repository](https://github.com/llmignore-spec/parser)
- [rival.tips](https://rival.tips) — AI model comparison

## License

MIT