@blast-shield/parser/README.md

Parser utility for blast-shield

# 📋 @blast-shield/parser

> Parser utility for Blast Shield. Provides file parsing, comment extraction, language detection, and language config helpers with no technical debt logic.

<!-- Package Info -->
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![npm version](https://img.shields.io/npm/v/%40blast-shield%2Fparser)](https://www.npmjs.com/package/@blast-shield/parser)

<!-- Tech Stack -->
[![ESM Ready](https://img.shields.io/badge/ESM-Ready-green)]()
[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)


## Features
- Parse files for comments and language
- Extract comments from code in multiple languages
- Find files respecting .gitignore and custom ignore patterns
- Unified language config for both regex and string-based comment detection
- Language config helpers for heuristics, UI, and fallback logic

## Usage

```ts
import {
  parseFileForComments,
  findFilesWithGitignore,
  extractComments,
  getLanguageFromFilePath,
  LANGUAGE_CONFIGS,
  getLanguageConfigForFile,
  isComment,
  isBlockCommentStart,
  isBlockCommentEnd,
  isInBlockComment
} from '@blast-shield/parser';

// Find files
const files = await findFilesWithGitignore(['src/**/*.ts'], { rootDir: process.cwd(), additionalIgnores: ['dist/**'] });

// Parse a file for comments
const result = await parseFileForComments(files[0]);
console.log(result.comments, result.language, result.linesOfCode);

// Use language config helpers
const langConfig = getLanguageConfigForFile('foo.ts');
if (langConfig) {
  console.log(isComment('// TODO: refactor', langConfig)); // true
}
```

## API

### parseFileForComments(filePath: string)
Returns `{ filePath, comments, language, linesOfCode }` for a given file.

### findFilesWithGitignore(patterns, options)
Find files matching glob patterns, respecting .gitignore and additional ignore patterns.
- `patterns`: string or string[]
- `options`: `{ rootDir?: string, additionalIgnores?: string[] }`

### extractComments(code: string, language: string)
Extracts all comments from code for a given language (using regex-based config).

### getLanguageFromFilePath(filePath: string)
Detects the language from a file path.

### LANGUAGE_CONFIGS
Unified array of language configs, each with:
- `name`: string
- `extensions`: string[]
- `lineComments`: `{ regex: RegExp, marker: string }[]`
- `blockComments`: `{ start: { regex, marker }, end: { regex, marker } }[]`

### getLanguageConfigForFile(filePath: string)
Returns the language config for a file, or null if unsupported.

### isComment(line: string, config: LanguageConfig)
Returns true if the line is a comment (single-line or block) for the given language config.

### isBlockCommentStart(line: string, config: LanguageConfig)
Returns true if the line starts a block comment.

### isBlockCommentEnd(line: string, config: LanguageConfig)
Returns true if the line ends a block comment.

### isInBlockComment(line: string, config: LanguageConfig)
Returns true if the line is inside a block comment.

## Logging
Uses the `logger` package for warnings and errors.

## Development

```sh
pnpm build       # Build the package
pnpm test        # Run tests
pnpm lint        # Run Biome linter
```

## License
MIT