meld-ast/TROUBLESHOOTING.md

AST parser for Meld

# Troubleshooting Guide

This guide helps resolve common issues when using meld-ast.

## Common Issues

### Module Resolution Errors

#### "Cannot find module 'meld-ast'"

**Symptoms:**
- Error when importing the package
- Module not found errors

**Solutions:**
1. Check your package.json has the correct dependency:
   ```json
   {
     "dependencies": {
       "meld-ast": "^1.1.0"
     }
   }
   ```

2. Verify your import statement matches your environment:
   ```typescript
   // ESM (recommended)
   import { parse } from 'meld-ast';
   
   // CommonJS
   const { parse } = require('meld-ast');
   ```

3. For TypeScript projects, ensure your tsconfig.json has correct module settings:
   ```json
   {
     "compilerOptions": {
       "module": "NodeNext",
       "moduleResolution": "NodeNext"
     }
   }
   ```

#### "SyntaxError is not defined" or "parse is not a function"

**Symptoms:**
- Runtime errors about missing exports
- Undefined parser functions

**Solutions:**
1. Update to version 1.1.0 or later which fixes export issues
2. Use the correct import syntax for your environment:
   ```typescript
   // ESM - named imports
   import { parse, SyntaxError } from 'meld-ast';
   
   // CommonJS - destructuring
   const { parse, SyntaxError } = require('meld-ast');
   ```

### Build and Development Issues

#### "Error: Cannot find grammar file"

**Symptoms:**
- Build fails with missing grammar file
- Runtime errors about missing peggy grammar

**Solutions:**
1. Check the grammar file exists:
   ```bash
   ls src/grammar/meld.pegjs
   ```

2. Run the prebuild script:
   ```bash
   npm run prebuild
   ```

3. Verify the lib/grammar directory exists and contains:
   - parser.js (ESM)
   - parser.cjs (CommonJS)
   - meld.pegjs (Grammar)

#### TypeScript Type Resolution Issues

**Symptoms:**
- TypeScript errors about missing types
- "Could not find a declaration file for module 'meld-ast'"

**Solutions:**
1. Ensure you're using TypeScript 5.3 or later

2. Check your tsconfig.json includes:
   ```json
   {
     "compilerOptions": {
       "moduleResolution": "NodeNext",
       "types": ["node"]
     }
   }
   ```

3. If using meld-spec types, add it to dependencies:
   ```json
   {
     "dependencies": {
       "meld-spec": "^0.3.11"
     }
   }
   ```

## Debugging

### Enable Debug Logging

Set the DEBUG environment variable:
```bash
# Unix/macOS
export DEBUG=meld-ast:*

# Windows
set DEBUG=meld-ast:*
```

### Debug Output Examples

```
meld-ast:parser Initializing parser...
meld-ast:parser Found pre-built parser at lib/grammar/parser.cjs
meld-ast:parser Successfully loaded CJS parser
```

### Common Debug Patterns

1. **Parser Initialization:**
   - Look for "Initializing parser" messages
   - Check which parser version is being loaded
   - Verify environment detection is correct

2. **Grammar Loading:**
   - Watch for grammar file path resolution
   - Check for fallback attempts
   - Verify final parser source

3. **Module Resolution:**
   - Monitor import/require attempts
   - Check package root detection
   - Verify final module path

## Getting Help

If you're still having issues:

1. Enable debug logging as shown above
2. Create a minimal reproduction of the issue
3. Open an issue on GitHub with:
   - Debug output
   - Environment details (Node.js version, TypeScript version)
   - Steps to reproduce
   - Expected vs actual behavior