NAAb — The Programming Language with Built-in AI Governance

Govern AI-generated code at the language level. NAAb is a polyglot programming language that applies code quality, security, and correctness policies at runtime — catching mistakes before they execute. A single govern.json controls what executes across 12 languages in one file.

// govern.json — catches AI hallucinations before they execute
{
  "version": "3.0",
  "mode": "enforce",
  "code_quality": {
    "no_hallucinated_apis": { "level": "hard" },
    "no_oversimplification": { "level": "hard" },
    "no_incomplete_logic": { "level": "soft" }
  }
}

$ naab-lang app.naab

Error: Hallucinated API in python block:
  ".push()" is not valid Python                        [HARD]

  Rule: code_quality.no_hallucinated_apis

  Help:
  .push() is JavaScript — in Python, use .append()

  ✗ Wrong: my_list.push(item)
  ✓ Right: my_list.append(item)

---

See It In Action

Scene	AI Mistake	Governance Response
1	.push() in Python	Blocked — use .append()
2	import fake_ai_toolkit	Blocked — unknown module
3	fn validate() { return true }	Blocked — stub function
4	Hardcoded sk-proj-... API key	Blocked — secret detected
5	Empty catch (e) { }	Blocked — incomplete logic
6	env.get() → shell unsanitized	Blocked — taint violation
7	All issues fixed	Passes clean

Run it yourself: bash demo/governance_demo.sh | Record: bash demo/governance_demo.sh --record

---

The Problem: AI Code Drift

AI models generate code that looks right but isn't. Every session starts fresh — no memory of your security rules, naming conventions, or architecture decisions:

• Hallucinated APIs — .push() in Python, print() in JavaScript, json.stringify() instead of json.dumps()
• Stubs shipped as "complete" — def validate(): return True, functions with only pass or NotImplementedError
• Security patterns bypassed — hardcoded secrets, SQL injection, except: pass swallowing errors
• Language misuse — Python for heavy computation, JavaScript for file operations, Shell for complex logic

Prompts are suggestions. govern.json is policy. NAAb checks every polyglot block against your policies before execution — where it can't be bypassed.

---

At a Glance

Capability	Details
Governance Engine	50+ checks, 3-tier policy engine (hard / soft / advisory), govern.json config
Polyglot Execution	12 languages in one file — Python, JavaScript, Rust, C++, Go, C#, Ruby, PHP, Shell, Nim, Zig, Julia
Smart Error Messages	"Did you mean?" suggestions via Levenshtein distance, detailed fixes with examples
Standard Library	14 modules — array, string, math, json, http, file, path, time, debug, env, csv, regex, crypto, bolo
Language Features	Generators/yield, interfaces, pattern matching with guards, f-strings, async/await, lambdas, closures, pipeline, destructuring
CI/CD Integration	SARIF (GitHub Code Scanning), JUnit XML (Jenkins/GitLab), JSON reports
Project Context	Auto-reads CLAUDE.md, .editorconfig, .eslintrc, package.json to supplement governance
Developer Tools	Interactive REPL, URL imports, LLM-friendly syntax (keyword aliases, optional semicolons), 204 error messages

---

Quick Start

# Clone and build
git clone --recursive https://github.com/b-macker/NAAb.git
cd NAAb
mkdir build && cd build
cmake .. -G Ninja
ninja naab-lang -j$(nproc)

# Run a file
./naab-lang hello.naab

# Start interactive REPL
./naab-lang

Hello World

main {
    let name = "World"
    print("Hello, " + name + "!")
}

---

Governance Engine

NAAb's governance engine is what sets it apart. Drop a govern.json in your project root and every polyglot block is checked before execution.

What It Catches

Category	Examples	Patterns
Hallucinated APIs	.push() in Python, print() in JS, len() in JS	86+ cross-language patterns
Oversimplification	def validate(): return True, pass-only bodies, identity functions	35+ stub patterns
Incomplete Logic	except: pass, bare raises, "something went wrong" messages	40+ patterns
Security	SQL injection, path traversal, shell injection, hardcoded secrets	Entropy-based detection
Code Quality	TODO/FIXME, debug artifacts, mock data, hardcoded URLs/IPs	Dead code detection
Taint Tracking	Untrusted data (env.get, polyglot output) reaching sinks (shell, env)	Source/sink/sanitizer with prefix matching
PII Exposure	SSN patterns, credit card numbers, API keys in strings	Regex + entropy

Three Policy Levels

• HARD — Block execution. Code does not run. No override.
• SOFT — Block execution. Code does not run unless --governance-override is passed.
• ADVISORY — Warn and continue. Logged in audit trail.

govern.json Example

{
  "version": "3.0",
  "mode": "enforce",

  "languages": {
    "allowed": ["python", "javascript", "go"],
    "blocked": ["php"]
  },

  "code_quality": {
    "no_secrets": { "level": "hard" },
    "no_sql_injection": { "level": "hard" },
    "no_oversimplification": { "level": "hard" },
    "no_incomplete_logic": { "level": "soft" },
    "no_hallucinated_apis": { "level": "soft" }
  },

  "restrictions": {
    "no_eval": { "level": "hard" },
    "no_shell_injection": { "level": "hard" }
  },

  "limits": {
    "max_lines_per_block": 200,
    "timeout_seconds": 30
  }
}

Project Context Awareness

NAAb can read your existing project configuration files and supplement governance rules — without overriding govern.json:

• Layer 1: LLM instruction files — CLAUDE.md, .cursorrules, AGENTS.md
• Layer 2: Linter configs — .eslintrc, .flake8, pyproject.toml
• Layer 3: Project manifests — package.json, Cargo.toml, go.mod

Each layer is opt-in and toggleable.

Custom Rules

Define your own regex-based governance rules:

{
  "custom_rules": [
    {
      "name": "no_print_debugging",
      "pattern": "console\\.log|print\\(.*debug",
      "message": "Remove debug print statements before committing",
      "level": "soft"
    }
  ]
}

CI/CD Integration

# GitHub Code Scanning (SARIF)
naab-lang app.naab --governance-report sarif > results.sarif

# Jenkins / GitLab CI (JUnit XML)
naab-lang app.naab --governance-report junit > results.xml

# Custom tooling (JSON)
naab-lang app.naab --governance-report json > results.json

Build your govern.json interactively | Full governance reference (Chapter 21)

Security model & threat assumptions

---

Polyglot Execution

Use each language where it shines — Python for data science, Rust for performance, JavaScript for web, Go for concurrency, Shell for file ops. Variables flow between languages automatically. No FFI, no serialization, no microservices.

Supported languages: Python · JavaScript · Rust · C++ · Go · C# · Ruby · PHP · Shell · Nim · Zig · Julia

main {
    let numbers = [10, 20, 30, 40, 50]

    // Python: statistical analysis
    let stats = <<python[numbers]
import statistics
result = {
    "mean": statistics.mean(numbers),
    "stdev": statistics.stdev(numbers)
}
str(result)
>>

    // JavaScript: format as HTML
    let html = <<javascript
const data = "Stats: mean=30, stdev=15.81";
`<div class="result">${data}</div>`;
>>

    print(stats)
    print(html)
}

Key Polyglot Features

• Variable binding — Pass NAAb variables into polyglot blocks with <<python[x, y]
• Parallel execution — Independent blocks run concurrently with automatic dependency analysis
• Persistent runtimes — Keep interpreter state across multiple calls with the runtime keyword
• JSON sovereign pipe — Return structured data from any language with naab_return() or -> JSON header
• Error mapping — Polyglot errors map back to NAAb source locations and flow into try/catch
• Block-header awareness — Go gets package main, PHP gets <?php automatically

---

Language Features

Pattern Matching

main {
    let status = 404

    let message = match status {
        200 => "OK"
        404 => "Not Found"
        n if n >= 500 => f"Server Error ({n})"  // guard clause
        _ => "Unknown"
    }

    print(message)  // "Not Found"

    // Array destructuring in match
    let point = [3, 4]
    let label = match point {
        [0, 0] => "origin"
        [x, 0] => f"on x-axis at {x}"
        [0, y] => f"on y-axis at {y}"
        [x, y] => f"point ({x}, {y})"
    }
    print(label)  // "point (3, 4)"
}

Async/Await

main {
    async fn fetch_data() {
        return "data loaded"
    }

    async fn process() {
        return "processed"
    }

    let data = await fetch_data()
    let result = await process()
    print(data + " -> " + result)
}

Lambdas & Closures

main {
    let multiplier = 3
    let scale = fn(x) { return x * multiplier }

    print(scale(10))  // 30

    // Closures capture their environment
    function make_counter() {
        let count = 0
        return fn() {
            count = count + 1
            return count
        }
    }

    let counter = make_counter()
    print(counter())  // 1
    print(counter())  // 2
}

Pipeline Operator

main {
    let result = "hello world"
        |> string.upper()
        |> string.split(" ")

    print(result)  // ["HELLO", "WORLD"]
}

If Expressions

main {
    let score = 85
    let grade = if score >= 90 { "A" } else if score >= 80 { "B" } else { "C" }
    print(grade)  // "B"
}

Error Handling

main {
    try {
        let result = <<python
raise ValueError("something broke")
>>
    } catch (e) {
        print("Caught from Python: " + e)
    }
}

Generators

fn fibonacci(limit) {
    let a = 0
    let b = 1
    while a < limit {
        yield a
        let temp = a + b
        a = b
        b = temp
    }
}

main {
    for n in fibonacci(100) {
        print(n)  // 0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89
    }
}

Interfaces

interface Printable {
    fn to_string() -> string
}

struct Point implements Printable {
    x: int
    y: int
}

fn Point.to_string(p) -> string {
    return f"({p.x}, {p.y})"
}

main {
    let p = new Point { x: 3, y: 4 }
    print(Point.to_string(p))  // "(3, 4)"
}

F-Strings

main {
    let name = "World"
    let count = 42
    print(f"Hello {name}, you have {count} items")
    print(f"Total: {count * 2}")  // expressions work too
}

More Language Features

• Optional chaining (user?.name), null coalescing (x ?? "default", x ??= fallback)
• Destructuring (let [a, b] = arr, let {x, y} = dict)
• Spread/rest ([...arr1, ...arr2], fn(...args))
• in / not in operators, array slicing (arr[1:3])
• Structs, enums, module system with imports/exports/URL imports
• For loops with destructuring, while loops, break/continue
• Dictionaries and arrays with dot-notation methods

---

Standard Library

14 modules with 204 error messages, "Did you mean?" suggestions, and detailed documentation.

main {
    // JSON
    let data = json.parse('{"name": "NAAb", "version": "0.2.0"}')
    print(data["name"])

    // HTTP
    let response = http.get("https://api.github.com/repos/b-macker/NAAb")
    print(json.parse(response)["stargazers_count"])

    // File I/O
    file.write("output.txt", "Hello from NAAb!")

    // Math
    print(math.sqrt(144))  // 12

    // String operations
    let words = string.split("hello world", " ")
    print(string.upper(words[0]))  // "HELLO"
}

Module	Functions
array	push, pop, shift, unshift, map_fn, filter_fn, reduce_fn, sort, slice_arr, find, reverse, length, contains, first, last, join
string	split, join, upper, lower, trim, replace, reverse, contains, starts_with, ends_with, length, char_at, index_of, substring, repeat, pad_left, pad_right
math	sqrt, pow, abs, floor, ceil, round, min, max, sin, cos, random, PI, E
json	parse, stringify
http	get, post, put, delete, head, patch (with headers, body, timeout)
file	read, write, append, exists, delete, list_dir, create_dir, is_file, is_dir, read_lines, write_lines, copy, move, size, basename, dirname, extension
path	join, dirname, basename, extension, resolve, is_absolute, normalize, exists
time	now, now_millis, sleep, format_timestamp, parse_datetime, year, month, day, hour, minute, second, weekday
debug	inspect, type, trace, watch, snapshot, diff, keys, values, log, timer, compare, stack, env
env	get, set_var, list
csv	parse, stringify
regex	search, matches, find, find_all, replace, replace_first, split, groups, find_groups, escape, is_valid
crypto	hash, sha256, sha512, md5, sha1, random_bytes, random_string, random_int, base64_encode, base64_decode, hex_encode, hex_decode, compare_digest, generate_token, hash_password
bolo	scan, report (governance integration)

---

Developer Experience

Smart Error Messages

NAAb doesn't just tell you what's wrong — it tells you how to fix it:

Error: Unknown function "array.pussh"

  Did you mean: array.push ?

  Help:
  - array.push(arr, value) adds an element to the end of an array

  Example:
    ✗ Wrong: array.pussh(my_list, 42)
    ✓ Right: array.push(my_list, 42)

Common Mistake Detection

NAAb detects ~35 patterns where developers (and AI) use the wrong language's idioms:

• array.append() → "That's Python. In NAAb, use array.push()"
• console.log() → "That's JavaScript. In NAAb, use print()"
• str.upper() → "Use string.upper(str) or str.upper() (dot-notation)"

LLM-Friendly Syntax

NAAb accepts multiple keyword styles so AI-generated code works without manual edits:

• function / func / fn / def — all valid
• let / const — mutable and immutable bindings
• Semicolons — optional (accepted but not required)
• return — optional in single-expression functions

---

NAAb Ecosystem

Three tools built with NAAb — code governance, performance optimization, and data security:

Project	Purpose	Key Features
NAAb BOLO	Code governance & validation	50+ checks, SARIF reports, AI drift detection
NAAb Pivot	Code evolution & optimization	3-60x speedups, proven correctness, 8 languages
NAAb Passage	Data gateway & PII protection	Zero leakage, sovereign architecture, HIPAA/GDPR

NAAb BOLO — Code Governance & Validation

NAAb BOLO ("Be On the Lookout") catches oversimplified stubs, hallucinated APIs, and incomplete logic in AI-generated code.

# Scan for governance violations
naab-lang bolo.naab scan ./src --profile enterprise

# Generate SARIF report for CI
naab-lang bolo.naab report ./src --format sarif --output results.sarif

# AI governance validation
naab-lang bolo.naab ai-check ./ml-models

50+ checks · 4 languages · 339 regression tests → Get started

NAAb Pivot — Code Evolution & Optimization

NAAb Pivot rewrites slow code in faster languages with mathematical proof of correctness.

# Analyze hotspots (Python → Rust candidates)
naab-lang pivot.naab analyze app.py

# Rewrite with proof
naab-lang pivot.naab rewrite app.py:expensive_loop --target rust --prove

# Result: 45x faster, semantically identical

3-60x speedups · 8 source languages · Proven correct → Get started

NAAb Passage — Data Gateway & PII Protection

NAAb Passage ensures zero PII leakage to LLMs, APIs, or untrusted systems with sovereign architecture.

# Start secure gateway
naab-lang main.naab

# All requests validated, PII blocked
curl -X POST http://localhost:8091/ -d '{"prompt": "SSN: 123-45-6789"}'
# → {"error": "POLICY_VIOLATION"}

Zero leakage · Self-synthesizing · HIPAA/GDPR compliant → Get started

---

Architecture

Source Code (.naab)
    |
  Lexer ──> Tokens
    |
  Parser ──> AST (recursive descent)
    |
  Governance Engine ──> Policy checks (govern.json)
    |
  Interpreter (visitor pattern)
    |
  ├── Native execution (NAAb code)
  ├── Python executor (C API)
  ├── JavaScript executor (QuickJS)
  ├── Go/Rust/C++/C#/Nim/Zig/Julia executors (compile & run)
  ├── Ruby/PHP executors (interpreted)
  └── Shell executor (subprocess)

• 82,000+ lines of C++17
• 360 regression tests, 340 mono test assertions
• 14 standard library modules with 204 error messages
• Built with Abseil, fmt, spdlog, nlohmann/json, QuickJS

---

Contributing

Contributions are welcome! See CONTRIBUTING.md for build instructions and guidelines.

Areas for Contribution

• Performance optimizations
• New standard library modules
• Documentation and tutorials
• IDE integrations (Vim, Emacs, IntelliJ, VS Code)
• Package registry (centralized module hosting)

---

License

MIT License - see LICENSE for details.

Brandon Mackert - @b-macker

---

NAAb — Polyglot without the trip.