uppaal-to-tchecker/README.md

JavaScript implementation of Uppaal to TChecker translator - convert Uppaal timed automata models to TChecker format

# uppaal-to-tchecker (JavaScript)

[![npm version](https://badge.fury.io/js/uppaal-to-tchecker.svg)](https://badge.fury.io/js/uppaal-to-tchecker)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

JavaScript implementation of the Uppaal to TChecker translator. This tool converts Uppaal timed automata models to the TChecker model-checker format.

## Overview

`uppaal-to-tchecker` (or `utot` for short) is a JavaScript port of the original C++ tool that translates files produced by [Uppaal](http://www.uppaal.org) to the [TChecker](http://github.com/ticktac-project/tchecker) model-checker format. This JavaScript version provides the same core functionality with the convenience of npm packaging and Node.js integration.

## Installation

### Global Installation (CLI usage)

```bash
npm install -g uppaal-to-tchecker
```

### Local Installation (Library usage)

```bash
npm install uppaal-to-tchecker
```

## Usage

### Command Line Interface

The CLI interface is compatible with the original C++ version:

```bash
# Basic usage
utot input.xta output.tck

# Read from stdin, write to stdout
utot < input.xta > output.tck

# With options
utot --verbose --sysname MySystem input.xta output.tck

# Force specific format
utot --xml input.xml output.tck
utot --xta input.ta output.tck
```

### CLI Options

- `-d, --debug`: Enable debug traces
- `-e, --erase`: Erase output file if it exists  
- `-V, --verbose`: Increase verbosity level (can be used multiple times)
- `-h, --help`: Display help message
- `-v, --version`: Display version number
- `--xml`: Enforce XML as input format
- `--xta`: Enforce XTA as input language
- `--ta`: Enforce TA as input language
- `--sysname <id>`: Specify the system name

### Programmatic Usage

```javascript
const UppaalToTChecker = require('uppaal-to-tchecker');

const translator = new UppaalToTChecker();

// Translate from string
const xtaModel = `
clock x;
int n;

process P() {
    state s0, s1;
    init s0;
    trans s0 -> s1 { guard x > 0; assign x = 0, n = 1; };
}

system P;
`;

const result = await translator.translate(xtaModel, {
    format: 'xta',
    language: 'xta', 
    systemName: 'MySystem',
    verbose: 1
});

console.log(result);

// Translate from file
const result2 = await translator.translateFile('input.xta', 'output.tck', {
    systemName: 'FileSystem',
    verbose: 1
});
```

## Comparison: Original C++ vs JavaScript Version

### Original C++ Usage

```bash
# C++ version
mkdir build && cd build
cmake -DCMAKE_INSTALL_PREFIX=/usr/local ..
make -j && make install

# Usage
utot [options] [input-file] [output-file]
utot --verbose --sysname System input.xta output.tck
```

### JavaScript Version Usage

```bash
# JavaScript version
npm install -g uppaal-to-tchecker

# Usage (same interface)
utot [options] [input-file] [output-file]  
utot --verbose --sysname System input.xta output.tck

# Plus programmatic API
node -e "
const UppaalToTChecker = require('uppaal-to-tchecker');
const translator = new UppaalToTChecker();
translator.translateFile('input.xta', 'output.tck').then(console.log);
"
```

## Supported Features

The JavaScript version supports the same Uppaal language subset as the original:

### ✅ Supported
- Basic types (int, bool, clock, scalar)
- Arrays (flattened when necessary)
- Process templates and instantiation
- Channel synchronization (CCS-like and broadcast)
- Guards, invariants, and assignments
- Urgent and committed locations
- Select statements (enumerated)

### ❌ Not Supported
- Uppaal query language
- Urgent channels
- C-like functions
- Process priorities
- Complex data structures

## Examples

### Simple Process Communication

Input (XTA):
```
chan a;

process Sender() {
    state s0, s1;
    init s0;
    trans s0 -> s1 { sync a!; };
}

process Receiver() {
    state r0, r1;
    init r0;
    trans r0 -> r1 { sync a?; };
}

system Sender, Receiver;
```

Output (TChecker):
```
system:System

process:Sender
location:Sender:s0{initial:}
location:Sender:s1{}
event:a_emit
edge:Sender:s0:s1:a_emit{}

process:Receiver
location:Receiver:r0{initial:}
location:Receiver:r1{}
event:a_recv
edge:Receiver:r0:r1:a_recv{}

sync:Sender@a_emit:Receiver@a_recv
```

### Broadcast Communication

Input:
```
broadcast chan alarm;

process Sensor() {
    state idle, alert;
    init idle;
    trans idle -> alert { sync alarm!; };
}

process Device() {
    state normal, emergency;
    init normal;
    trans normal -> emergency { sync alarm?; };
}

system Sensor, Device;
```

The JavaScript version generates the same TChecker output as the C++ version, with proper broadcast synchronization vectors.

## API Reference

### UppaalToTChecker Class

#### Methods

- `translate(content, options)`: Translate Uppaal content string
- `translateFile(inputFile, outputFile, options)`: Translate from/to files
- `detectFormat(content)`: Auto-detect input format
- `setVerbose(level)`: Set verbosity level
- `setDebug(enabled)`: Enable/disable debug mode

#### Options Object

```javascript
{
    format: 'auto' | 'xml' | 'xta',
    language: 'xta' | 'ta',
    systemName: string,
    verbose: number,
    debug: boolean
}
```

## Development

### Setup

```bash
git clone <repository>
cd uppaal-to-tchecker-js
npm install
```

### Testing

```bash
npm test                # Run all tests
npm run test:watch     # Watch mode
npm run test:coverage  # With coverage
```

### Building

```bash
npm run build          # Production build
npm run dev           # Development build
```

## Architecture

The JavaScript version maintains the same modular architecture as the C++ original:

- **UppaalParser**: Parses XTA and XML input formats
- **Translator**: Core translation logic and orchestration
- **ExpressionTranslator**: Handles expression translation and evaluation
- **DeclarationTranslator**: Processes variable and type declarations
- **TCheckerOutputter**: Generates TChecker format output
- **ContextPrefix**: Manages variable scoping and naming

## Compatibility

- **Node.js**: >= 14.0.0
- **Input formats**: XTA, XML (same as C++ version)
- **Output format**: TChecker (identical to C++ version)
- **Command line**: Full compatibility with original utot CLI

## Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Related Projects

- [TChecker](http://github.com/ticktac-project/tchecker) - Target model checker
- [Uppaal](http://www.uppaal.org) - Source modeling tool
- [Original C++ uppaal-to-tchecker](https://github.com/ticktac-project/uppaal-to-tchecker) - Reference implementation

## Support

- **Issues**: GitHub Issues
- **Documentation**: This README and inline code documentation
- **Examples**: See `examples/` directory