How dullabs/bhai-lang works
Project Type and Purpose
• Bhai Lang is a toy programming language written in TypeScript, organized as a monorepo.
• It provides:
• A CLI tool (packages/cli) for running .bhai source files.
• A Parser (packages/parser) that turns source text into an AST.
• An Interpreter (packages/interpreter) that walks the AST and executes code.
• A documentation site and in-browser playground (apps/docs), built with Next.js.
• Shared configuration packages (packages/config, packages/tsconfig) and a Turborepo orchestrator (turbo.json).
File-Structure Analysis and Architectural Insights
• Top-level directories:
• packages/cli, packages/parser, packages/interpreter – core language components.
• packages/config, packages/tsconfig – shared ESLint/TS presets.
• apps/docs – Next.js documentation site and interactive playground.
• Build & CI:
• turbo.json drives build/test pipelines across packages.
• GitHub Actions workflow (.github/workflows/node.js.yml).
• Architectural patterns:
• Parser: recursive-descent with tokenExecutor, producing AST via parser/src/components.
• Interpreter: Visitor pattern traverses AST nodes in interpreter/src/components/visitor.
• CLI glues Parser → Interpreter.
• Docs site loads both Parser & Interpreter in browser (playground) and server (rendered docs).
1. Source Code (.bhai file)
2. CLI Frontend (Node.js executable in packages/cli)
3. Parser Module
• Tokenizer
• Parser logic → AST
4. AST (in-memory data structures)
5. Interpreter Module (Visitor pattern)
• Runtime scope management
• Exception handling
6. Console Output (stdout)
7. Documentation Site / Playground
• Next.js server
• Client-side code editor & runner
• Sentry integration (error logging)
8. Monorepo Orchestrator (Turbo) & Shared Configs
9. External Services
• NPM Registry (package distribution)
• GitHub Actions (CI/CD)
• Sentry (monitoring)
Interactions & Data Flow
• User runs bhailang test.bhai → CLI component
• CLI reads file → hands raw text to Parser
• Parser → Tokenizer → builds tokens → parsing logic → AST
• AST passed to Interpreter → executes statements → writes to stdout
• For the docs playground:
• Browser editor input → client-side parse & interpret → displays output
• Next.js server may pre-render docs and playground page
• Turbo coordinates build/test across packages before publishing to NPM
Architectural Patterns & Principles
• Modularization: each concern (parsing, interpreting, CLI, docs) lives in its own package.
• Visitor pattern in the interpreter simplifies AST node handling.
• Monorepo tooling (Turborepo) for fast incremental builds and tests.
• Shared configuration ensures consistent linting and TypeScript settings.
• Separation of concerns between server-side docs and client-side playground code.
Essential Elements
• Clear component labels (e.g., “Tokenizer,” “Parser,” “AST,” “Interpreter”)