luast

A Lua parser and syntax tree ecosystem for JavaScript, built on unist.

Packages

This repository contains luaparse and its ecosystem of packages for the unified / syntax-tree pipeline:

Package	Description	Status
@friday-friday/luast	Tree specification and TypeScript types	packages/luast
@friday-friday/luast-util-from-luaparse	Convert legacy luaparse AST → luast	packages/luast-util-from-luaparse
@friday-friday/luast-util-visit	Tree visitor for luast (named-field aware)	packages/luast-util-visit
@friday-friday/luast-util-scope	Scope analysis over luast trees	packages/luast-util-scope
@friday-friday/unified-lua	unified parser plugin for Lua	packages/unified-lua
@friday-friday/luaparse	Lua parser with native luast emission	v0.1.0

Documentation

• LUAST-SPEC.md — The luast tree specification. Defines every node type, the content model, the child-field registry, and the position format. This is the primary contract for the ecosystem.

• MIGRATION-PLAN.md — The phased migration plan. Covers design decisions with rationale, package architecture, the six implementation phases, risk assessment, and resolved design questions.

• PORT-ANALYSIS.md — The original gap analysis. Documents the structural differences between the current luaparse AST and what unist requires. Written before the spec and plan; superseded by them on any point of conflict.

Usage

// ESM
import luaparse from '@friday-friday/luaparse'

// Emit a luast (unist-compliant) tree
const tree = luaparse.parse('local x = 1', {ast: 'luast'})
// tree.type === 'root', tree.body[0].type === 'localStatement'

// Legacy mode (default, backwards compatible)
const legacy = luaparse.parse('local x = 1')
// legacy.type === 'Chunk', legacy.body[0].type === 'LocalStatement'

// unified pipeline
import {unified} from 'unified'
import luaParse from '@friday-friday/unified-lua'

const tree = unified().use(luaParse, {luaVersion: '5.3'}).parse('local x = 1')

Quick orientation

If you want to understand the tree format, read LUAST-SPEC.md.

If you want to understand the migration history, read MIGRATION-PLAN.md.

If you want the original gap analysis, read PORT-ANALYSIS.md.

If you want the legacy v0.x documentation, see README.legacy.md.

Design summary

luast follows the esast precedent — the only programming-language AST in the unist ecosystem. Key choices:

• Named fields, not children — condition, body, left, right etc. are the canonical structural fields. A dedicated luast-util-visit handles traversal. Generic unist-util-is and unist-util-position work unchanged.
• root as root type — not Chunk, for unist consistency.
• camelCase type names — ifStatement, binaryExpression, matching the ecosystem majority.
• Scope analysis as a separate utility — not baked into the parser.
• Comments on root only — in root.comments, following esast convention.

Ecosystem context

luast sits alongside other language-specific unist implementations:

• mdast — Markdown
• hast — HTML
• xast — XML
• nlcst — Natural language
• esast — ECMAScript

Remaining work

The following items from MIGRATION-PLAN.md are deferred:

• Phase 5: luast-util-attach-comments — comment-to-node mapping utility (optional, low priority)
• Phase 6: Drop legacy browser build — or produce it as a build artifact

Acknowledgements

This project is a rewrite and ecosystem extension of luaparse, originally created by Oskar Schöldström (oxy.fi) as part of his bachelor's thesis at Arcada University of Applied Sciences.

The core parser (luaparse.js) retains substantial portions of the original luaparse codebase. The unist-compliant luast ecosystem — the tree specification, utilities, and unified plugin — is new work by Eric Friday.

For the original luaparse documentation, see README.legacy.md.

Original acknowledgements

The original luaparse project acknowledged the following:

• Initial tests scaffolded from yueliang and manually checked for errors.
• Much of the code based on LuaMinify, the Lua source, and Esprima.
• luamin, a Lua minifier by Mathias Bynens.
• Ace, an online code editor.

License

MIT — Copyright (c) Oskar Schöldström 2012–2014 (original luaparse). Copyright (c) Eric Friday 2025 (luast ecosystem and rewrite).