# cyclone-analyzer

> A static analyzer library for Cyclone specification language

Latest version **0.0.41** (published 2026-01-01) · BSD-2-Clause license · 0 weekly downloads

## Install

```sh
npm install cyclone-analyzer
pnpm add cyclone-analyzer
yarn add cyclone-analyzer
bun add cyclone-analyzer
```

## Health

**Score 50/100 (C)** — status: stable.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.0.41 |
| Published | 2026-01-01 |
| First published | 2024-01-28 |
| Weekly downloads | 0 |
| License | BSD-2-Clause |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 4.7 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | lucid-brndmg |
| Maintainers | lucid-brndmg |
| Keywords | cyclone |

## Links

- npm: https://www.npmjs.com/package/cyclone-analyzer
- Homepage: https://github.com/lucid-brndmg/cyclone-analyzer
- Issues: https://github.com/lucid-brndmg/cyclone-analyzer/issues
- npm.io page: https://npm.io/package/cyclone-analyzer

## Dependencies (1)

- [antlr4](https://npm.io/package/antlr4.md) ^4.13.1-patch-1

## Recent versions

- 0.0.41 (latest) — 2026-01-01
- 0.0.40 — 2025-07-07
- 0.0.39 — 2025-04-01
- 0.0.37 — 2024-09-06
- 0.0.35 — 2024-07-01
- 0.0.34 — 2024-06-13
- 0.0.33 — 2024-06-12
- 0.0.32 — 2024-06-11
- 0.0.31 — 2024-06-09
- 0.0.30 — 2024-06-06
- 0.0.29 — 2024-06-02
- 0.0.28 — 2024-05-31
- 0.0.27 — 2024-05-30
- 0.0.25 — 2024-05-28
- 0.0.24 — 2024-04-30
- … 22 more at https://npm.io/package/cyclone-analyzer/versions

## README

# Cyclone Analyzer

Cyclone analyzer is a static analyzer for [Cyclone Specification Language](https://classicwuhao.github.io/cyclone_tutorial/tutorial-content.html). This library powers the [cyclone online editor](https://github.com/lucid-brndmg/cyclone-online-editor) project.

The analyzer covers most of Cyclone's language features. This package also contains the language specification, an IR builder, some utility functions, a parser and a lexer based on ANTLR4 for Cyclone. This analyzer currently checks for 40+ kinds of semantic errors in a Cyclone spec, and would be helpful as a linter for Cyclone code editors. 

**Limitations:** This analyzer performs a static analysis for each Cyclone specification. The semantic errors detected by this analyzer are not comprehensive: Certain errors can not be discovered by this analyzer. If this analyzer report no error on a certain specification, it doesn't mean the specification actually has no problem at all.

*This project is a part of my final year project (CS440[A]) at Maynooth University.*

## TODO

- This document is unfinished and will be updated in the future.

## Usage

### Installation

Use npm or yarn to install:

```shell
npm install cyclone-analyzer
```

Import this library using `import` or `require`:

```javascript
// ESM
import cycloneAnalyzer from "cyclone-analyzer"

// CJS
const cycloneAnalyzer = require("cyclone-analyzer")
```

### Analyze a Cyclone Specification

Find errors in any Cyclone specification by simply using `analyzeCycloneSpec`. 

```javascript
import {analyzer} from "cyclone-analyzer"

const cycloneSpec = `
graph G {
  int i = 1;
  
  start normal node S0 {
    i ++;
  }
  
  final normal node S1 {
    i --;
  }
  
  edge {S0 -> S1}
  
  goal {
    assert i == 1 in (S1);
    check for 1
  }
}
`

const result = analyzer.analyzeCycloneSpec(cycloneSpec)

if (result.hasSyntaxError()) {
  console.log("This spec has syntax error:", result.parserErrors)
} else if (result.hasSemanticError()) {
  console.log("Semantic errors detected:", result.semanticErrors)
} else {
  console.log("This spec seems ok")
}
```

### Parsing

Use `utils.antlr.parseCycloneSyntax` to parse a Cyclone specification via ANTLR4:

```javascript
import cycloneAnalyzer from "cyclone-analyzer"
const {parseCycloneSyntax} = cycloneAnalyzer.utils.antlr

const spec = `
graph G {
  int i = 1 // syntax error: a semicolon is required here
}
`

const parsed = parseCycloneSyntax({input: spec})

if (parsed.syntaxErrorsCount > 0) {
  console.log("This spec has syntax error")
}
```

### Syntax Block Builder

There is an IR builder `blockBuilder.SyntaxBlockBuilder` for building a tree-structured context for a Cyclone spec after semantic analysis:

```javascript
import {analyzer, blockBuilder} from "cyclone-analyzer"

const cycloneSpec = `
graph G {
  start final node A {}
  edge {A -> A}
  goal { check for 1 }
}
`

const irBuilder = new blockBuilder.SyntaxBlockBuilder()
const analysisResult = analyzer.analyzeCycloneSpec(cycloneSpec, {
  analyzerExtensions: [irBuilder] // the builder is an extension of the analyzer
})

// the syntax block of the input Cyclone spec, as a tree
const program = irBuilder.getProgramBlock()

console.log(program)
```

### Analyzer Extensions

The semantic analyzer defined series of events and can be listened with `analyzer.on` method. In this way, extensions can be written by listening to analyzer events. Extensions can be objects or class instances that has an `attach` method:

```javascript
import {analyzer} from "cyclone-analyzer"

// defining an extension as class
class MyExtension {
  // the required attach method
  attach(analyzer) {
    // this.analyzer = analyzer
    analyzer.on("errors", (ctx, errors) => console.log("semantic errors discovered:", errors))
    analyzer.on("block:enter", (ctx, payload) => console.log("entering a semantic context block"))
    analyzer.on("block:exit", (ctx, payload) => console.log("exiting a semantic context block"))
    analyzer.on("identifier:register", (ctx, {text}) => console.log("registering identifier: ", text))
    analyzer.on("identifier:reference", (ctx, {references}) => console.log("referencing identifiers: ", references))
  }
}

const cycloneSpec = `
graph G {
  start final node A {}
  edge {A -> A}
  goal { check for 1 }
}
`

const ext = new MyExtension()
const analysisResult = analyzer.analyzeCycloneSpec(cycloneSpec, {
  analyzerExtensions: [ext] // attach the extension
})
```

## Modules

This package contains the following modules:

| Module         | Description                                                          | Status   |
|----------------|----------------------------------------------------------------------|----------|
| `analyzer`     | The semantic analyzer for Cyclone                                    | Stable   |
| `blockBuilder` | An IR builder based on the semantic analyzer                         | Unstable |
| `generated`    | The generated lexer and parser based on ANTLR4                       | Stable   |
| `language`     | The language's definitions in enums & specifications                 | Stable   |
| `library`      | Some libraries that has nothing to do with the language itself       | Stable   |
| `utils`        | Helper modules for analyzer and block builder to handle the language | Stable   |



### Analyzer
TODO

### Block Builder
TODO

### Generated Lexer & Parser
TODO

### Language Definitions & Specifications
TODO

### Library
TODO

### Utilities
TODO

## License

Published under the [BSD-2 license](https://www.tldrlegal.com/license/bsd-2-clause-license-freebsd)

---
_Source: https://npm.io/package/cyclone-analyzer · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._