MoonChunk

A compact DSL and runtime for generating static HTML from .mncnk source files.

Overview

Complete Documentation (in Polish): MoonChunk_Complete_Docs_Polish.pdf

MoonChunk is an open-source language runtime focused on:

• describing page generation in a concise DSL (*.mncnk)
• parsing with ANTLR4TS
• executing language constructs (imports, scopes, loops, functions, recursion)
• generating formatted HTML output

Features

• Modular chunks with import / @include
• Explicit entrypoint execution via moon(...)
• Local and global variable model (let, const, env { global ... })
• Type-aware expressions (int, float, double, bool, string, number, array, object, unknown, any)
• Control flow: if, for, while, break, continue
• Functions (including recursive calls)
• Arrays and objects with path/index access (obj.a, arr[0])
• Scope-aware access to parent scopes via parent::name
• Casts with both styles: value as int and (int)value
• Builtins like data(...) and print(...)
• Internal base layout + metadata defined directly in .mncnk
• Friendly error diagnostics with line/column information

Requirements

• Node.js >=18
• Yarn Classic (1.x) recommended

Installation

yarn install

Quick Start

yarn build
yarn start examples/scenarios/18-recursive-function/site.mncnk

Build & Run

# Full build (ANTLR generation + TypeScript compilation)
yarn build

# Start runtime
yarn start <path/to/file.mncnk>

# Debug mode
yarn start:debug <path/to/file.mncnk>

# Type checks / validation script
yarn run check

# Lint checks
yarn lint

# Auto-fix lint issues
yarn lint:fix

Git Hooks (Husky)

Husky is configured for local quality gates:

• pre-commit -> yarn lint + yarn run check
• pre-push -> yarn build

After pulling changes, run:

yarn install

(prepare script will initialize Husky hooks automatically.)

Quality Checks

Recommended local verification before opening a PR:

yarn lint
yarn run check
yarn build

Checks overview:

• yarn lint -> ESLint for TypeScript and scripts
• yarn run check -> MoonChunk self-check (build + runtime sanity check)
• yarn build -> grammar generation + TypeScript compilation

Programmatic API

import { executeMoonChunk, executeMoonChunkFile } from "moonchunk";

const fromFile = executeMoonChunkFile(
  "examples/scenarios/17-print-builtin/site.mncnk",
);
console.log(fromFile.ok, fromFile.generatedFiles);

const fromSource = executeMoonChunk(
  'chunk "Main" { output: "./dist"; }; moon(Main);',
);
console.log(fromSource.ok, fromSource.diagnostics);

Project Layout

moonchunk/
├── MoonChunkLexer.g4
├── MoonChunkParser.g4
├── moonchunk/
│   ├── api.ts
│   ├── parser/
│   ├── runtime/
│   └── base.tpl
├── scripts/
└── examples/scenarios/

Examples

• examples/scenarios/16-metadata-common
• examples/scenarios/17-print-builtin
• examples/scenarios/18-recursive-function
• examples/scenarios/26-final-mandatory
• examples/scenarios/27-inc-and-parent-depth

Run any example:

yarn start examples/scenarios/17-print-builtin/site.mncnk

Ecosystem

• VS Code syntax highlight extension: moonchunk-highlight-vscode-extension

Status

MoonChunk is under active development.
The language is intentionally evolving and new tokens/runtime capabilities are being added incrementally.

Contributing

Issues and pull requests are welcome.

Suggested flow:

1. Fork the repository.
2. Create a feature branch.
3. Add/update scenario examples when adding language behavior.
4. Run yarn build and yarn run check.
5. Open a pull request with a short change summary.

License

MIT