synta 0.1.3

# Troubleshooting Guide

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*

- [Installation Issues](#installation-issues)
  - [Problem: `cargo install synta-codegen` fails](#problem-cargo-install-synta-codegen-fails)
- [Parsing Errors](#parsing-errors)
  - [Problem: "Expected identifier, got Symbol"](#problem-expected-identifier-got-symbol)
  - [Problem: "Unexpected token" in constraints](#problem-unexpected-token-in-constraints)
  - [Problem: "Unknown type" errors](#problem-unknown-type-errors)
- [Code Generation Issues](#code-generation-issues)
  - [Problem: Generated code has naming conflicts](#problem-generated-code-has-naming-conflicts)
  - [Problem: Field names become invalid Rust identifiers](#problem-field-names-become-invalid-rust-identifiers)
  - [Problem: SEQUENCE OF generates Vec instead of array](#problem-sequence-of-generates-vec-instead-of-array)
- [Compilation Errors](#compilation-errors)
  - [Problem: "cannot find type `Integer` in this scope"](#problem-cannot-find-type-integer-in-this-scope)
  - [Problem: "trait `Encode` is not implemented"](#problem-trait-encode-is-not-implemented)
  - [Problem: "use of undeclared type" for imported types](#problem-use-of-undeclared-type-for-imported-types)
- [Runtime Issues](#runtime-issues)
  - [Problem: Constraint validation fails unexpectedly](#problem-constraint-validation-fails-unexpectedly)
  - [Problem: PATTERN validation not working](#problem-pattern-validation-not-working)
  - [Problem: CONTAINING validation not working](#problem-containing-validation-not-working)
  - [Problem: Decoding fails with "unexpected tag"](#problem-decoding-fails-with-unexpected-tag)
- [Performance Issues](#performance-issues)
  - [Problem: Code generation is slow](#problem-code-generation-is-slow)
  - [Problem: Generated code compiles slowly](#problem-generated-code-compiles-slowly)
  - [Problem: Runtime validation is slow](#problem-runtime-validation-is-slow)
- [Getting Help](#getting-help)
- [Quick Reference: Common Error Patterns](#quick-reference-common-error-patterns)
- [Debug Mode](#debug-mode)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

Common issues and solutions when using synta-codegen.

## Table of Contents

- [Installation Issues](#installation-issues)
- [Parsing Errors](#parsing-errors)
- [Code Generation Issues](#code-generation-issues)
- [Compilation Errors](#compilation-errors)
- [Runtime Issues](#runtime-issues)
- [Performance Issues](#performance-issues)

---

## Installation Issues

### Problem: `cargo install synta-codegen` fails

**Symptoms:**
```
error: failed to compile synta-codegen
```

**Solutions:**

1. **Update Rust toolchain:**
   ```bash
   rustup update stable
   ```

2. **Check Rust version:**
   ```bash
   rustc --version  # Should be 1.70+ for edition 2021
   ```

3. **Install from source:**
   ```bash
   git clone https://codeberg.org/abbra/synta
   cd synta/synta-codegen
   cargo install --path .
   ```

---

## Parsing Errors

### Problem: "Expected identifier, got Symbol"

**Example:**
```
ParseError { message: "Expected identifier, got Symbol(\"{\")", line: 5, column: 20 }
```

**Common Causes:**

1. **Missing type name before definition:**
   ```asn1
   -- Wrong:
   ::= SEQUENCE { ... }
   
   -- Right:
   MyType ::= SEQUENCE { ... }
   ```

2. **Reserved keyword as identifier:**
   ```asn1
   -- Wrong:
   type ::= INTEGER
   
   -- Right:
   typeValue ::= INTEGER
   ```

**Solution:** Check the line and column number in the error message, verify syntax.

### Problem: "Unexpected token" in constraints

**Example:**
```asn1
MyString ::= IA5String (SIZE(1..10))  -- Missing space
```

**Solution:** Add proper spacing:
```asn1
MyString ::= IA5String (SIZE (1..10))  -- Correct
```

### Problem: "Unknown type" errors

**Example:**
```
ParseError: Unknown type 'Foo'
```

**Common Causes:**

1. **Type not defined:**
   ```asn1
   User ::= SEQUENCE {
       status  UserStatus  -- UserStatus not defined
   }
   ```

2. **Type not imported:**
   ```asn1
   MyModule DEFINITIONS ::= BEGIN
       -- Missing: IMPORTS UserStatus FROM OtherModule;
       User ::= SEQUENCE {
           status  UserStatus
       }
   END
   ```

**Solution:** Define or import the type:
```asn1
MyModule DEFINITIONS ::= BEGIN
    IMPORTS UserStatus FROM OtherModule;
    
    User ::= SEQUENCE {
        status  UserStatus
    }
END
```

---

## Code Generation Issues

### Problem: Generated code has naming conflicts

**Symptoms:**
```rust
error[E0428]: the name `MyType` is defined multiple times
```

**Cause:** Same type name in multiple modules without proper namespacing.

**Solution:** Use module prefixes when generating:
```bash
synta-codegen module1.asn1 --crate-imports -o src/module1.rs
synta-codegen module2.asn1 --crate-imports -o src/module2.rs
```

### Problem: Field names become invalid Rust identifiers

**Symptoms:**
```rust
pub struct MyStruct {
    pub type: Integer,  // 'type' is a keyword!
}
```

**Cause:** ASN.1 allows identifiers that are Rust keywords.

**Generated Code:** synta-codegen automatically escapes:
```rust
pub struct MyStruct {
    pub r#type: Integer,  // Escaped with r#
}
```

**Usage:**
```rust
let s = MyStruct {
    r#type: Integer::from(1),
};
```

### Problem: SEQUENCE OF generates Vec instead of array

**Expected:**
```rust
pub fixed: [Integer; 10]
```

**Generated:**
```rust
pub items: Vec<Integer>
```

**Explanation:** ASN.1 SEQUENCE OF is variable-length by default. Use SIZE constraint for documentation:
```asn1
FixedArray ::= SEQUENCE (SIZE (10)) OF INTEGER
```

Note: This still generates `Vec<Integer>`, but validates at runtime.

---

## Compilation Errors

### Problem: "cannot find type `Integer` in this scope"

**Symptoms:**
```
error[E0412]: cannot find type `Integer` in this scope
```

**Solution:** Add synta dependency to Cargo.toml:
```toml
[dependencies]
synta = "0.1"
```

### Problem: "trait `Encode` is not implemented"

**Symptoms:**
```
error[E0277]: the trait `Encode` is not implemented for `MyType`
```

**Causes:**

1. **Missing derive attribute:**
   ```rust
   // Add #[cfg_attr(feature = "derive", derive(Asn1Sequence))]
   ```

2. **Missing synta import:**
   ```rust
   use synta::{Encode, Decode};
   ```

3. **Custom type without Encode implementation:**
   ```rust
   // You need to manually implement Encode for custom types
   impl Encode for MyCustomType { ... }
   ```

### Problem: "use of undeclared type" for imported types

**Symptoms:**
```
error[E0412]: cannot find type `ImportedType` in this scope
```

**Cause:** Missing module import in Rust code.

**Solution:** Check generated imports at top of file:
```rust
use crate::other_module::ImportedType;
```

If missing, regenerate with `--crate-imports`:
```bash
synta-codegen schema.asn1 --crate-imports -o output.rs
```

---

## Runtime Issues

### Problem: Constraint validation fails unexpectedly

**Symptoms:**
```rust
let port = HttpPort::new(Integer::from(80))?;  // Error!
```

**Debugging:**

1. **Check constraint definition:**
   ```asn1
   HttpPort ::= INTEGER (80 | 443 | 8080)
   ```

2. **Verify value is in allowed set:**
   ```rust
   // Valid values: 80, 443, 8080
   let port = HttpPort::new(Integer::from(80))?;  // OK
   let port = HttpPort::new(Integer::from(8000))?;  // Error!
   ```

3. **Use unchecked constructor for testing:**
   ```rust
   let port = HttpPort::new_unchecked(Integer::from(8000));  // Bypasses validation
   ```

### Problem: PATTERN validation not working

**Symptoms:**
```rust
let email = Email::new(IA5String::from("invalid"))?;  // Should fail but doesn't
```

**Cause:** PATTERN validation requires `regex` feature.

**Solution:** Enable feature in Cargo.toml:
```toml
[dependencies]
synta = { version = "0.1", features = ["regex"] }
regex = "1.10"
once_cell = "1.19"
```

### Problem: CONTAINING validation not working

**Cause:** CONTAINING validation requires `validate_containing` feature.

**Solution:**
```toml
[dependencies]
synta = { version = "0.1", features = ["validate_containing"] }
```

### Problem: Decoding fails with "unexpected tag"

**Symptoms:**
```
Error: DecodeError { message: "unexpected tag" }
```

**Common Causes:**

1. **Wrong encoding format:**
   ```rust
   // Data is BER, but decoding as DER
   let result = synta::decode_der(&ber_data)?;  // Error!
   
   // Solution: Use correct decoder
   let result = synta::decode_ber(&ber_data)?;  // OK
   ```

2. **Wrong type:**
   ```rust
   let result: WrongType = synta::decode_der(&data)?;  // Error if data is DifferentType
   ```

3. **Corrupted data:**
   ```rust
   // Verify data integrity first
   ```

---

## Performance Issues

### Problem: Code generation is slow

**Symptoms:** Large schemas take minutes to generate.

**Solutions:**

1. **Split large schemas into modules:**
   ```bash
   # Instead of one 10,000 line schema
   synta-codegen huge-schema.asn1
   
   # Split into smaller modules
   synta-codegen base-types.asn1 -o base.rs
   synta-codegen extensions.asn1 -o ext.rs
   ```

2. **Use parallel generation for multiple files:**
   ```bash
   ls schemas/*.asn1 | xargs -P 4 -I {} synta-codegen {} -o generated/{}.rs
   ```

### Problem: Generated code compiles slowly

**Cause:** Very large generated files.

**Solutions:**

1. **Enable incremental compilation:**
   ```toml
   [profile.dev]
   incremental = true
   ```

2. **Split into multiple modules**

3. **Use `--release` for final builds:**
   ```bash
   cargo build --release
   ```

### Problem: Runtime validation is slow

**Cause:** Complex constraints with many unions/intersections.

**Solutions:**

1. **Use `new_unchecked()` for trusted data:**
   ```rust
   // For data from trusted sources
   let port = HttpPort::new_unchecked(value);
   ```

2. **Simplify constraints if possible:**
   ```asn1
   -- Instead of: INTEGER (1|2|3|4|5|6|7|8|9|10|...)
   -- Use: INTEGER (1..100)
   ```

3. **Cache validated values:**
   ```rust
   // Validate once, reuse many times
   let validated = MyType::new(value)?;
   ```

---

## Getting Help

If your issue isn't covered here:

1. **Check documentation:**
   - [ASN.1 Support](asn1-support.md)
   - [Limitations](limitations.md)
   - [Tutorial](tutorial.md)

2. **Verify your ASN.1 syntax:**
   - Check against ITU-T X.680 specification
   - Try a simpler version to isolate the problem

3. **Create minimal reproduction:**
   ```asn1
   TestModule DEFINITIONS ::= BEGIN
       SimpleType ::= INTEGER  -- Simplest possible case
   END
   ```

4. **Report issues:**
   - GitHub: https://codeberg.org/abbra/synta/issues
   - Include: ASN.1 input, command used, error message, Rust version

---

## Quick Reference: Common Error Patterns

| Error Message | Likely Cause | Quick Fix |
|---------------|--------------|-----------|
| "Expected identifier" | Syntax error | Check ASN.1 syntax |
| "Unknown type" | Missing import/definition | Add IMPORTS or define type |
| "cannot find type `Integer`" | Missing synta dependency | Add to Cargo.toml |
| "unexpected tag" | Wrong decoder or corrupted data | Use correct decode_* function |
| "constraint validation failed" | Value out of range | Check constraint definition |
| "PATTERN validation disabled" | Missing regex feature | Enable `regex` feature |

---

## Debug Mode

For detailed debugging, set environment variable:

```bash
RUST_LOG=debug synta-codegen schema.asn1 -o output.rs
```

This provides verbose output during parsing and generation.