Xiaoqinli (XQL) 鈥?AST-First Transpiler#

AI agents write structured .xql.json (JSON AST) directly 鈥?no parser needed, no syntax errors possible. The compiler validates types, effects, and capabilities at compile time, then emits idiomatic source code in 6 languages.

Install#

bash

# From source (requires Go 1.23+)
git clone https://github.com/Freecode100Year/xiaoqinli.git
cd xiaoqinli && go build -o xql .

# Move to PATH
# Linux/macOS: sudo mv xql /usr/local/bin/
# Windows: move xql.exe to a directory in %PATH%

Usage#

bash

# Validate AST
xql validate --file program.xql.json

# Compile to target language
xql compile --file program.xql.json --target go
xql compile --file program.xql.json --target rust --out main.rs
xql compile --file program.xql.json --target ts --out main.ts
xql compile --file program.xql.json --target kotlin --out Main.kt
xql compile --file program.xql.json --target swift --out main.swift
xql compile --file program.xql.json --target py --out main.py

.xql.json AST Format#

Every node has a "kind" field. Top-level must be "Program" with "declarations" array.

Type System#

KindGoRustTypeScriptKotlinSwiftPythonInt``int``i64``number``Long``Int``int``Float``float64``f64``number``Double``Double``float``String``string``String``string``String``String``str``Bool``bool``bool``boolean``Boolean``Bool``bool``Void(none)__(none)void``Unit(none)None``Array``[]T``Vec<T>``T[]``List<T>``[T]``list[T]``Option``*T``Option<T>``T | null``T?``T?``Optional[T]``Result``(T, error)``Result<T, E>鈥?鈥?鈥?鈥?

Node Kinds#

Declarations:

• Program 鈥?top-level, contains declarations[]
• FunctionDecl 鈥? name, params[], returnType, effects[], grant[], body[]

Statements:

• VarDecl 鈥? name, type, value
• AssignStmt 鈥? target, value
• ReturnStmt 鈥? value (optional)
• IfStmt 鈥? cond, then[], else[]
• WhileStmt 鈥? cond, body[]
• ExprStmt 鈥? expr

Expressions:

• Literal 鈥? valueType (String/Int/Float/Bool), value
• Ident 鈥? name
• BinaryExpr 鈥? op (+, -, *, /, %, ==, !=, <, >, <=, >=, &&, ||), left, right
• UnaryExpr 鈥? op (!, -), operand
• CallExpr 鈥? callee (string), args[]
• MemberExpr 鈥? object, field

Built-in Functions#

NameEffectDescriptionprintlnstatePrint with newlineprintfstateFormatted printsprintfpureFormatted string build

Safety Annotations#

• effects: ["pure"] 鈥?compiler verifies no side effects (transitive)
• effects: ["state"] / ["network"] / ["filesystem"] 鈥?declare side effects
• grant: ["io", "network"] 鈥?capability declaration; callee must be subset of caller

Example#

json

{
  "kind": "Program",
  "declarations": [
    {
      "kind": "FunctionDecl",
      "name": "greet",
      "params": [{"name": "name", "type": {"kind": "String"}}],
      "returnType": {"kind": "String"},
      "effects": ["pure"],
      "grant": [],
      "body": [{
        "kind": "ReturnStmt",
        "value": {
          "kind": "BinaryExpr", "op": "+",
          "left": {"kind": "Literal", "valueType": "String", "value": "Hello, "},
          "right": {"kind": "Ident", "name": "name"}
        }
      }]
    },
    {
      "kind": "FunctionDecl",
      "name": "main",
      "params": [],
      "returnType": {"kind": "Void"},
      "effects": ["state"],
      "grant": ["io"],
      "body": [{
        "kind": "ExprStmt",
        "expr": {
          "kind": "CallExpr", "callee": "println",
          "args": [{
            "kind": "CallExpr", "callee": "greet",
            "args": [{"kind": "Literal", "valueType": "String", "value": "World"}]
          }]
        }
      }]
    }
  ]
}

Compiles to Go:

go

package main

import "fmt"

func greet(name string) string {
    return "Hello, " + name
}

func main() {
    fmt.Println(greet("World"))
}

Three Static Checks#

CheckWhat it doesError codesType checkValidates types, function signatures, return types, argument countsXQL_E2xxEffect inferenceInfers side effects transitively through call chainsXQL_E2xxCapability checkEnforces @grant 鈥?callee capabilities must be subset of caller'sXQL_E3xx

Error Codes#

RangeCategoryXQL_E1xxParse / AST errorsXQL_E2xxType / effect errorsXQL_E3xxCapability errorsXQL_E4xxCodegen errors

Workflow#

1. Write .xql.json AST file
2. Run xql validate --file program.xql.json to check
3. Run xql compile --file program.xql.json --target go --out main.go to generate source
4. Build with target language toolchain (e.g., go build -o app.exe main.go)

Source#

https://github.com/Freecode100Year/xiaoqinli