code-the-jewels 0.1.0

package/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "mcp__claude_ai_Notion__notion-fetch"
+    ]
+  }
+}

package/PROMPTS/01-build-v0.1.md

@@ -0,0 +1,10 @@
+# Prompt 01: Build Code The Jewels v0.1 (Full Implementation)
+
+Source: Notion page 32f4cf98-04bf-81ac-a19d-c05270b747a6
+
+Built the complete v0.1 transpiler from scratch:
+- Lexer, Parser (recursive descent), AST, Semantic analysis, JS code generator
+- Runtime standard library: bk:text, bk:parse, atl:data, atl:flow
+- CLI with run/compile/check/repl commands
+- Pipe operator (|>) and duo blocks (mike/el dual pipelines)
+- 5 example programs, all passing acceptance criteria

package/README.md

@@ -0,0 +1,186 @@
+# Code The Jewels
+
+> :point_right:{:gem:}.rtj
+
+A programming language built the way Run The Jewels makes music. Two cities. Two voices. One compiler.
+
+## Installation
+
+```bash
+npm install -g code-the-jewels
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/everettsteele/code-the-jewels.git
+cd code-the-jewels
+npm install
+npm run build
+```
+
+## Quick Start
+
+Create `hello.rtj`:
+
+```
+talk "code the jewels"
+```
+
+Run it:
+
+```bash
+rtj run hello.rtj
+```
+
+Output: `code the jewels`
+
+A duo block:
+
+```
+feature words from "bk:parse"
+feature count from "atl:data"
+
+jewel line = "walking in the snow"
+
+jewel wordCount = duo(line) {
+  mike: words
+  el:   count
+}
+
+talk wordCount
+```
+
+Output: `4`
+
+## Keywords
+
+Every keyword traces back to RTJ.
+
+| Keyword    | Purpose                        | JS Equivalent          | Origin                                      |
+|------------|--------------------------------|------------------------|---------------------------------------------|
+| `jewel`    | Declare a variable             | `const`                | The jewel. The core unit.                   |
+| `verse`    | Declare a function             | `function`             | A verse. A block of bars.                   |
+| `send`     | Return a value                 | `return`               | Send it back.                               |
+| `talk`     | Print to console               | `console.log`          | "Talk to Me", RTJ3                          |
+| `ifwild`   | Conditional                    | `if`                   | "if wild" check before you move             |
+| `elsewild` | Else branch                    | `else`                 | The other path                              |
+| `run`      | Loop over a collection         | `for...of`             | Run it.                                     |
+| `in`       | Iterator keyword               | `of`                   | Run x in y                                  |
+| `feature`  | Import from standard library   | destructured `require` | A feature. A guest appearance.              |
+| `from`     | Import source                  | module path            | Where the feature comes from                |
+| `yank`     | Throw an error                 | `throw`                | Yank the chain. Pull the plug.              |
+| `duo`      | Dual pipeline block            | (custom)               | "yankee and the brave (ep. 4)", RTJ4        |
+| `mike`     | First pipeline in a duo block  | (custom)               | Killer Mike. Atlanta.                       |
+| `el`       | Second pipeline in a duo block | (custom)               | El-P. Brooklyn.                             |
+
+## Pipe Operator
+
+The pipe operator `|>` passes the jewel from one function to the next. Left to right. No nesting.
+
+```
+feature trim, upper from "bk:text"
+
+jewel line = "  code the jewels  "
+jewel clean = line |> trim |> upper
+
+talk clean
+// Output: CODE THE JEWELS
+```
+
+`a |> f |> g` compiles to `g(f(a))`. Each step takes the previous result as its argument.
+
+## duo()
+
+Named after "yankee and the brave (ep. 4)" from RTJ4. A duo block splits processing into two named pipelines.
+
+`mike` runs first (Atlanta). `el` responds (Brooklyn). Both branches are required. A duo without both is just a solo.
+
+```
+feature trim from "bk:text"
+feature words from "bk:parse"
+feature count from "atl:data"
+
+jewel bars = "  rtj from atlanta to brooklyn  "
+
+jewel total = duo(bars) {
+  mike: trim |> words
+  el: count
+}
+
+talk total
+// Output: 5
+```
+
+Compiles to: `el(mike(input))`. The mike pipeline feeds into the el pipeline. Two passes, one result.
+
+## Standard Library
+
+The standard library is split by city. `bk:` is Brooklyn (El-P's borough). `atl:` is Atlanta (Killer Mike's city).
+
+### bk:text
+String operations: `trim`, `upper`, `lower`, `split`, `join`
+
+### bk:parse
+Text parsing: `words`, `lines`, `chars`
+
+### atl:data
+Data operations: `count`, `countBy`, `first`, `last`
+
+### atl:flow
+Control flow: `identity`
+
+## Compiler Stages
+
+The compiler runs in stages. Each one has a name.
+
+1. **The Fist (El)** / Lexer. Breaks source into tokens.
+2. **The Hands** / Parser. Shapes tokens into an AST.
+3. **Mike Pass** / Semantic analysis. Walks the tree, checks scope, validates imports.
+4. **El Pass** / Optimization. (Reserved for v0.2.)
+5. **The Gun (Mike)** / Code generator. Fires the AST into JavaScript.
+6. **Jewel Box** / Output. The final `.js` file, ready to run.
+
+## CLI Commands
+
+```bash
+# Run a .rtj file
+rtj run <file.rtj>
+
+# Compile to JavaScript
+rtj compile <file.rtj>
+
+# Check for errors (parse + semantic only)
+rtj check <file.rtj>
+
+# Start interactive REPL
+rtj repl
+```
+
+## Version Naming
+
+Each major version is named after an RTJ album.
+
+| Version | Codename                    | Album |
+|---------|-----------------------------|-------|
+| v0.1    | RTJ0 "The Self-Titled Era"  | Run The Jewels (2013) |
+| v0.2    | RTJ2 "The Meow Era"         | Run The Jewels 2 (2014) |
+| v0.3    | RTJ3 "Talk to Me"           | Run The Jewels 3 (2016) |
+| v0.4    | RTJ4 "The Brave Era"        | RTJ4 (2020) |
+
+## Examples
+
+See the `examples/` directory:
+- `hello.rtj` - Hello world
+- `pipes.rtj` - Pipe operator
+- `duo.rtj` - Duo blocks
+- `cities.rtj` - Functions and arrays
+- `count-words.rtj` - Word frequency counting
+
+## Links
+
+[codethejewels.com](http://codethejewels.com)
+
+## License
+
+MIT. Free, like every RTJ album. Part of [Meridian](https://neverstill.llc).

package/dist/ast.d.ts

@@ -0,0 +1,143 @@
+export interface Location {
+    line: number;
+    column: number;
+}
+export type Statement = VarDecl | FunctionDecl | ReturnStmt | TalkStmt | IfStmt | LoopStmt | ImportStmt | ThrowStmt | ExpressionStmt | BlockStmt;
+export type Expression = Identifier | StringLiteral | NumberLiteral | BooleanLiteral | NullLiteral | ArrayLiteral | ObjectLiteral | BinaryExpr | UnaryExpr | CallExpr | MemberExpr | PipeExpr | DuoExpr;
+export interface Program {
+    type: 'Program';
+    body: Statement[];
+}
+export interface VarDecl {
+    type: 'VarDecl';
+    name: string;
+    init: Expression;
+    loc: Location;
+}
+export interface FunctionDecl {
+    type: 'FunctionDecl';
+    name: string;
+    params: string[];
+    body: BlockStmt;
+    loc: Location;
+}
+export interface ReturnStmt {
+    type: 'ReturnStmt';
+    value?: Expression;
+    loc: Location;
+}
+export interface TalkStmt {
+    type: 'TalkStmt';
+    value: Expression;
+    loc: Location;
+}
+export interface IfStmt {
+    type: 'IfStmt';
+    condition: Expression;
+    consequent: BlockStmt;
+    alternate?: BlockStmt;
+    loc: Location;
+}
+export interface LoopStmt {
+    type: 'LoopStmt';
+    variable: string;
+    iterable: Expression;
+    body: BlockStmt;
+    loc: Location;
+}
+export interface ImportStmt {
+    type: 'ImportStmt';
+    names: string[];
+    source: string;
+    loc: Location;
+}
+export interface ThrowStmt {
+    type: 'ThrowStmt';
+    value: Expression;
+    loc: Location;
+}
+export interface ExpressionStmt {
+    type: 'ExpressionStmt';
+    expr: Expression;
+    loc: Location;
+}
+export interface BlockStmt {
+    type: 'BlockStmt';
+    body: Statement[];
+    loc: Location;
+}
+export interface Identifier {
+    type: 'Identifier';
+    name: string;
+    loc: Location;
+}
+export interface StringLiteral {
+    type: 'StringLiteral';
+    value: string;
+    loc: Location;
+}
+export interface NumberLiteral {
+    type: 'NumberLiteral';
+    value: number;
+    loc: Location;
+}
+export interface BooleanLiteral {
+    type: 'BooleanLiteral';
+    value: boolean;
+    loc: Location;
+}
+export interface NullLiteral {
+    type: 'NullLiteral';
+    loc: Location;
+}
+export interface ArrayLiteral {
+    type: 'ArrayLiteral';
+    elements: Expression[];
+    loc: Location;
+}
+export interface ObjectLiteral {
+    type: 'ObjectLiteral';
+    pairs: {
+        key: string;
+        value: Expression;
+    }[];
+    loc: Location;
+}
+export interface BinaryExpr {
+    type: 'BinaryExpr';
+    op: string;
+    left: Expression;
+    right: Expression;
+    loc: Location;
+}
+export interface UnaryExpr {
+    type: 'UnaryExpr';
+    op: string;
+    operand: Expression;
+    loc: Location;
+}
+export interface CallExpr {
+    type: 'CallExpr';
+    callee: Expression;
+    args: Expression[];
+    loc: Location;
+}
+export interface MemberExpr {
+    type: 'MemberExpr';
+    object: Expression;
+    property: Expression;
+    computed: boolean;
+    loc: Location;
+}
+export interface PipeExpr {
+    type: 'PipeExpr';
+    steps: Expression[];
+    loc: Location;
+}
+export interface DuoExpr {
+    type: 'DuoExpr';
+    input: Expression;
+    mikePipeline: Expression[];
+    elPipeline: Expression[];
+    loc: Location;
+}

package/dist/ast.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const lexer_1 = require("./lexer");
+const parser_1 = require("./parser");
+const semantic_1 = require("./semantic");
+const generator_1 = require("./generator");
+const diagnostics_1 = require("./diagnostics");
+const repl_1 = require("./repl");
+function compile(source) {
+    const lexer = new lexer_1.Lexer(source);
+    const tokens = lexer.tokenize();
+    const parser = new parser_1.Parser(tokens);
+    const ast = parser.parse();
+    const semantic = new semantic_1.Semantic();
+    semantic.analyze(ast);
+    const gen = new generator_1.Generator();
+    return gen.generate(ast);
+}
+function resolveRuntimePath() {
+    // When running from dist/, runtime is at dist/runtime/rtj-core.js
+    // When running via ts-node, runtime is at src/runtime/rtj-core.ts
+    const distRuntime = path.join(__dirname, 'runtime', 'rtj-core');
+    return distRuntime;
+}
+function run(filePath) {
+    const absPath = path.resolve(filePath);
+    if (!fs.existsSync(absPath)) {
+        console.error(`File not found: ${absPath}`);
+        process.exit(1);
+    }
+    const source = fs.readFileSync(absPath, 'utf-8');
+    let js = compile(source);
+    // Replace the generic runtime require with the actual path
+    const runtimePath = resolveRuntimePath().replace(/\\/g, '/');
+    js = js.replace('const __rtj = require("./runtime/rtj-core");', `const __rtj = require("${runtimePath}");`);
+    // Write to temp file and execute
+    const tmpFile = path.join(os.tmpdir(), `rtj_${Date.now()}_${Math.random().toString(36).slice(2)}.js`);
+    fs.writeFileSync(tmpFile, js, 'utf-8');
+    try {
+        require(tmpFile);
+    }
+    finally {
+        fs.unlinkSync(tmpFile);
+    }
+}
+function compileToFile(filePath) {
+    const absPath = path.resolve(filePath);
+    if (!fs.existsSync(absPath)) {
+        console.error(`File not found: ${absPath}`);
+        process.exit(1);
+    }
+    const source = fs.readFileSync(absPath, 'utf-8');
+    const js = compile(source);
+    const outPath = absPath.replace(/\.rtj$/, '.js');
+    fs.writeFileSync(outPath, js, 'utf-8');
+}
+function check(filePath) {
+    const absPath = path.resolve(filePath);
+    if (!fs.existsSync(absPath)) {
+        console.error(`File not found: ${absPath}`);
+        process.exit(1);
+    }
+    const source = fs.readFileSync(absPath, 'utf-8');
+    compile(source); // throws on error
+}
+const [, , command, ...args] = process.argv;
+try {
+    switch (command) {
+        case 'run': {
+            if (!args[0]) {
+                console.error('Usage: rtj run <file.rtj>');
+                process.exit(1);
+            }
+            run(args[0]);
+            break;
+        }
+        case 'compile': {
+            if (!args[0]) {
+                console.error('Usage: rtj compile <file.rtj>');
+                process.exit(1);
+            }
+            compileToFile(args[0]);
+            break;
+        }
+        case 'check': {
+            if (!args[0]) {
+                console.error('Usage: rtj check <file.rtj>');
+                process.exit(1);
+            }
+            check(args[0]);
+            break;
+        }
+        case 'repl': {
+            (0, repl_1.startRepl)();
+            break;
+        }
+        default: {
+            console.log('Usage: rtj <run|compile|check|repl> [file]');
+        }
+    }
+}
+catch (err) {
+    if (err instanceof diagnostics_1.RTJError) {
+        console.error(err.format());
+        process.exit(1);
+    }
+    throw err;
+}

package/dist/diagnostics.d.ts

@@ -0,0 +1,7 @@
+export declare class RTJError extends Error {
+    kind: 'SyntaxError' | 'NameError' | 'ImportError' | 'DuoError' | 'RuntimeError';
+    line?: number | undefined;
+    column?: number | undefined;
+    constructor(kind: 'SyntaxError' | 'NameError' | 'ImportError' | 'DuoError' | 'RuntimeError', message: string, line?: number | undefined, column?: number | undefined);
+    format(): string;
+}

package/dist/diagnostics.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RTJError = void 0;
+class RTJError extends Error {
+    constructor(kind, message, line, column) {
+        super(message);
+        this.kind = kind;
+        this.line = line;
+        this.column = column;
+    }
+    format() {
+        const loc = this.line ? ` near line ${this.line}` : '';
+        return `${this.kind}: ${this.message}${loc}`;
+    }
+}
+exports.RTJError = RTJError;

package/dist/generator.d.ts

@@ -0,0 +1,11 @@
+import { Program } from './ast';
+export declare class Generator {
+    private indent;
+    generate(program: Program): string;
+    private pad;
+    private genStatement;
+    private genBlock;
+    private genExpression;
+    private flattenPipe;
+    private flattenPipeFromStrings;
+}

package/dist/generator.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Generator = void 0;
+class Generator {
+    constructor() {
+        this.indent = 0;
+    }
+    generate(program) {
+        const lines = [
+            '"use strict";',
+            'const __rtj = require("./runtime/rtj-core");',
+            'const __modules = __rtj.modules;',
+            '',
+        ];
+        for (const stmt of program.body) {
+            lines.push(this.genStatement(stmt));
+        }
+        return lines.join('\n') + '\n';
+    }
+    pad() {
+        return '  '.repeat(this.indent);
+    }
+    genStatement(stmt) {
+        switch (stmt.type) {
+            case 'VarDecl':
+                return `${this.pad()}const ${stmt.name} = ${this.genExpression(stmt.init)};`;
+            case 'FunctionDecl': {
+                const params = stmt.params.join(', ');
+                const body = this.genBlock(stmt.body);
+                return `${this.pad()}function ${stmt.name}(${params}) ${body}`;
+            }
+            case 'ReturnStmt':
+                return stmt.value
+                    ? `${this.pad()}return ${this.genExpression(stmt.value)};`
+                    : `${this.pad()}return;`;
+            case 'TalkStmt':
+                return `${this.pad()}__rtj.talk(${this.genExpression(stmt.value)});`;
+            case 'IfStmt': {
+                let result = `${this.pad()}if (${this.genExpression(stmt.condition)}) ${this.genBlock(stmt.consequent)}`;
+                if (stmt.alternate) {
+                    result += ` else ${this.genBlock(stmt.alternate)}`;
+                }
+                return result;
+            }
+            case 'LoopStmt':
+                return `${this.pad()}for (const ${stmt.variable} of ${this.genExpression(stmt.iterable)}) ${this.genBlock(stmt.body)}`;
+            case 'ImportStmt': {
+                const names = stmt.names.join(', ');
+                return `${this.pad()}const { ${names} } = __modules["${stmt.source}"];`;
+            }
+            case 'ThrowStmt':
+                return `${this.pad()}throw new Error(${this.genExpression(stmt.value)});`;
+            case 'ExpressionStmt':
+                return `${this.pad()}${this.genExpression(stmt.expr)};`;
+            case 'BlockStmt':
+                return this.genBlock(stmt);
+        }
+    }
+    genBlock(block) {
+        const lines = ['{'];
+        this.indent++;
+        for (const stmt of block.body) {
+            lines.push(this.genStatement(stmt));
+        }
+        this.indent--;
+        lines.push(`${this.pad()}}`);
+        return lines.join('\n');
+    }
+    genExpression(expr) {
+        switch (expr.type) {
+            case 'Identifier':
+                return expr.name;
+            case 'StringLiteral':
+                return JSON.stringify(expr.value);
+            case 'NumberLiteral':
+                return String(expr.value);
+            case 'BooleanLiteral':
+                return String(expr.value);
+            case 'NullLiteral':
+                return 'null';
+            case 'ArrayLiteral':
+                return `[${expr.elements.map(e => this.genExpression(e)).join(', ')}]`;
+            case 'ObjectLiteral': {
+                const pairs = expr.pairs.map(p => `${JSON.stringify(p.key)}: ${this.genExpression(p.value)}`);
+                return `{ ${pairs.join(', ')} }`;
+            }
+            case 'BinaryExpr':
+                return `(${this.genExpression(expr.left)} ${expr.op} ${this.genExpression(expr.right)})`;
+            case 'UnaryExpr':
+                return `(${expr.op}${this.genExpression(expr.operand)})`;
+            case 'CallExpr': {
+                const callee = this.genExpression(expr.callee);
+                const args = expr.args.map(a => this.genExpression(a)).join(', ');
+                return `${callee}(${args})`;
+            }
+            case 'MemberExpr':
+                if (expr.computed) {
+                    return `${this.genExpression(expr.object)}[${this.genExpression(expr.property)}]`;
+                }
+                return `${this.genExpression(expr.object)}.${this.genExpression(expr.property)}`;
+            case 'PipeExpr':
+                return this.flattenPipe(expr.steps);
+            case 'DuoExpr': {
+                const allSteps = [...expr.mikePipeline, ...expr.elPipeline];
+                const initial = this.genExpression(expr.input);
+                return this.flattenPipeFromStrings(initial, allSteps);
+            }
+        }
+    }
+    flattenPipe(steps) {
+        if (steps.length === 0)
+            return '';
+        if (steps.length === 1)
+            return this.genExpression(steps[0]);
+        const initial = this.genExpression(steps[0]);
+        return this.flattenPipeFromStrings(initial, steps.slice(1));
+    }
+    flattenPipeFromStrings(initial, fns) {
+        let result = initial;
+        for (const fn of fns) {
+            result = `${this.genExpression(fn)}(${result})`;
+        }
+        return result;
+    }
+}
+exports.Generator = Generator;

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { Lexer } from './lexer';
+export { Parser } from './parser';
+export { Semantic } from './semantic';
+export { Generator } from './generator';
+export { RTJError } from './diagnostics';
+export { TokenType } from './token';
+export type { Token } from './token';

package/dist/index.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenType = exports.RTJError = exports.Generator = exports.Semantic = exports.Parser = exports.Lexer = void 0;
+var lexer_1 = require("./lexer");
+Object.defineProperty(exports, "Lexer", { enumerable: true, get: function () { return lexer_1.Lexer; } });
+var parser_1 = require("./parser");
+Object.defineProperty(exports, "Parser", { enumerable: true, get: function () { return parser_1.Parser; } });
+var semantic_1 = require("./semantic");
+Object.defineProperty(exports, "Semantic", { enumerable: true, get: function () { return semantic_1.Semantic; } });
+var generator_1 = require("./generator");
+Object.defineProperty(exports, "Generator", { enumerable: true, get: function () { return generator_1.Generator; } });
+var diagnostics_1 = require("./diagnostics");
+Object.defineProperty(exports, "RTJError", { enumerable: true, get: function () { return diagnostics_1.RTJError; } });
+var token_1 = require("./token");
+Object.defineProperty(exports, "TokenType", { enumerable: true, get: function () { return token_1.TokenType; } });