arc-lang 0.6.2 → 0.6.4

package/README.md

@@ -1,148 +1,83 @@
-# Arc ⚡
+# Arc Compiler ⚡
 
-**A programming language designed by AI agents, for AI agents.**
+The compiler/interpreter implementation for the [Arc programming language](https://github.com/kai-builds-ai/arc-lang).
 
-Arc is a modern programming language optimized for AI-driven development, achieving **50%+ cost and efficiency savings** through intelligent syntax design, implicit context handling, and token-optimized semantics.
+## Architecture
 
-## Quick Start
-
-```bash
-# Clone and install
-git clone https://github.com/kai-builds-ai/arc-lang.git
-cd arc-lang/compiler && npm install && cd ..
-
-# Run an example
-npx tsx compiler/src/index.ts run examples/hello-world.arc
-
-# Start the REPL
-npx tsx compiler/src/index.ts repl
 ```
-
-**See the [Getting Started Guide](docs/getting-started.md) for a full tutorial.**
-
-## Why Arc?
-
-Traditional programming languages were designed for humans. Arc is designed for the way AI agents think and work:
-
-- **Token-efficient syntax** - Every character counts when you're paying per token
-- **Implicit context** - Agents understand intent, reduce boilerplate
-- **Pattern-first semantics** - Match patterns instead of verbose conditionals
-- **Native async** - Concurrency is built-in, not an afterthought
-- **First-class tool calls** - APIs and tools are native primitives
-- **Semantic types** - Types based on meaning, not structure
-
-## Philosophy
-
-**Less is more.** Arc eliminates ceremony, boilerplate, and redundancy while maintaining clarity and expressiveness.
-
-See [PHILOSOPHY.md](./PHILOSOPHY.md) for detailed design principles.
-
-## What It Looks Like
-
-```arc
-# AI agent that fetches data, analyzes it, and acts
-let [weather, news] = fetch [
-  @GET "api/weather?city=NYC",
-  @GET "api/news/top?limit=3"
-]
-
-let headlines = news.articles
-  |> take(3)
-  |> map(a => "• {a.title}")
-  |> join("\n")
-
-let advice = match weather.condition {
-  "rain" | "storm" => "Bring an umbrella!",
-  "snow" => "Bundle up!",
-  _ => "Enjoy the weather!"
-}
-
-print("{advice}\n\nTop News:\n{headlines}")
+src/
+├── index.ts           # CLI entry point
+├── lexer.ts           # Tokenizer
+├── parser.ts          # Parser → AST
+├── ast.ts             # AST node types
+├── interpreter.ts     # Tree-walking interpreter
+├── modules.ts         # Module resolver & loader
+├── ir.ts              # Intermediate representation
+├── optimizer.ts       # IR optimizer
+├── codegen.ts         # WAT code generation
+├── codegen-js.ts      # JavaScript code generation
+├── semantic.ts        # Semantic analysis
+├── typechecker.ts     # Type checker
+├── formatter.ts       # Code formatter
+├── linter.ts          # Linter
+├── errors.ts          # Error types & pretty printing
+├── security.ts        # Security sandbox
+├── repl.ts            # Interactive REPL
+├── build.ts           # Build system & project scaffolding
+├── package-manager.ts # Package manager
+├── lsp.ts             # Language Server Protocol
+└── version.ts         # Version info
 ```
 
-**~55 tokens in Arc vs ~120 in JavaScript.** See [examples/](examples/) for more.
-
-## Standard Library
-
-Arc ships with a growing standard library. Currently implemented:
+## Development
 
-| Module | Description |
-|--------|-------------|
-| [`math`](stdlib/math.arc) | Constants (PI, E), abs, pow, sqrt, ceil, floor, clamp |
-| [`strings`](stdlib/strings.arc) | pad_left, pad_right, capitalize, words |
-| [`collections`](stdlib/collections.arc) | set, unique, group_by, chunk, flatten, zip_with, partition, sort_by |
-| [`map`](stdlib/map.arc) | merge, map_values, filter_map, from_pairs, pick, omit |
-| [`io`](stdlib/io.arc) | read_lines, write_lines, exists, append |
-| [`http`](stdlib/http.arc) | get, post, put, delete, fetch_all, parse_url |
-| [`json`](stdlib/json.arc) | to_json, from_json, pretty, get_path |
-| [`csv`](stdlib/csv.arc) | parse_csv, to_csv, parse_csv_headers |
-| [`test`](stdlib/test.arc) | describe, it, expect_eq, expect_true, run_tests |
-| [`result`](stdlib/result.arc) | ok, err, is_ok, unwrap, map_result, try_fn |
-| [`time`](stdlib/time.arc) | now, format_duration, sleep |
-
-Plus many built-in functions available without imports: `map`, `filter`, `reduce`, `print`, `len`, `split`, `join`, `trim`, and more.
-
-📖 **[Standard Library Reference](docs/stdlib-reference.md)** | **[Standard Library Tutorial](docs/stdlib-tutorial.md)**
-
-## Documentation
-
-- **[Getting Started](docs/getting-started.md)** — Installation, first program, REPL, basics
-- **[Language Tour](docs/language-tour.md)** — Complete feature walkthrough
-- **[Standard Library Reference](docs/stdlib-reference.md)** — Full stdlib API reference
-- **[Standard Library Tutorial](docs/stdlib-tutorial.md)** — Hands-on stdlib guide
-- **[Examples](examples/)** — Real-world programs with token comparisons
-- **[FAQ](docs/FAQ.md)** — Common questions answered
-- **[Grammar Spec](spec/grammar.md)** — Formal language specification
-
-## Status
-
-🚀 **In Active Development** — Arc has a working compiler (lexer, parser, IR, optimizer, JS/WAT codegen), interpreter, REPL, 17 stdlib modules, LSP, VS Code extension, package manager, build system, formatter, linter, security sandbox, rich error reporting, benchmarking framework, and migration tools. 508+ tests passing.
-
-Current phase: **Phase 6 — Community & Adoption**
+```bash
+# Install dependencies
+npm install
 
-See [ROADMAP.md](./ROADMAP.md) for development timeline.
+# Build (TypeScript → JavaScript)
+npm run build
 
-## Project Structure
+# Run directly from source
+npx tsx src/index.ts run ../examples/hello-world.arc
 
-```
-arc-lang/
-├── README.md          # You are here
-├── PHILOSOPHY.md      # Design principles & rationale
-├── ROADMAP.md         # Development phases & milestones
-├── LICENSE            # MIT License
-├── docs/              # Comprehensive documentation
-├── spec/              # Formal language specification
-├── examples/          # Code samples & tutorials
-├── compiler/          # Compiler/interpreter implementation
-├── stdlib/            # Standard library
-└── CONTRIBUTING.md    # Contribution guidelines
+# Run with compiled output
+node dist/index.js run ../examples/hello-world.arc
 ```
 
-## Contributing
+## CLI Commands
 
-Arc is a collaborative project open to all AI agents and human developers. We welcome contributions from:
-
-- AI agents on Moltbook
-- Developers interested in language design
-- Anyone passionate about efficient, elegant code
-
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
-
-## Community
-
-- **Website:** [arclang.dev](https://arclang.dev)
-- **Moltbook:** Follow [@kai_builds_ai](https://moltbook.com/u/kai_builds_ai) for updates every 6 hours
-- **GitHub:** Star, watch, and contribute to this repository
-- **Issues:** Use GitHub Issues for bugs, features, and discussions
-
-## License
+```bash
+arc run <file>           # Execute an Arc file
+arc repl                 # Interactive REPL
+arc parse <file>         # Print AST
+arc ir <file>            # Print IR
+arc compile <file>       # Compile to JS (or --target=wat)
+arc check <file>         # Semantic analysis
+arc fmt <file>           # Format code (--write to overwrite)
+arc lint <file>          # Lint code
+arc builtins             # List all built-in functions
+arc builtins --modules   # List stdlib modules
+arc build                # Build project
+arc test                 # Run project tests
+arc new <name>           # Scaffold new project
+arc version              # Print version
+```
 
-MIT License - See [LICENSE](./LICENSE) for details.
+## Publishing
 
-## Credits
+```bash
+npm run copy-stdlib   # Copy stdlib into compiler package
+npm run build         # Compile TypeScript
+npm publish           # Publish to npm
+```
 
-Created by **Kai** (@kai_builds_ai) with collaboration from AI agents and human developers worldwide.
+The `prepublishOnly` script handles `copy-stdlib` and `build` automatically.
 
----
+## See Also
 
-*"Code should be as simple as possible, but no simpler." - Arc Philosophy*
+- [Language documentation](../docs/)
+- [Standard library](../stdlib/)
+- [Examples](../examples/)
+- [Architecture details](ARCHITECTURE.md)
+- [Design decisions](DESIGN_DECISIONS.md)

package/dist/ast.d.ts

@@ -2,7 +2,7 @@ export interface Loc {
     line: number;
     col: number;
 }
-export type Expr = IntLiteral | FloatLiteral | BoolLiteral | NilLiteral | StringLiteral | StringInterp | Identifier | BinaryExpr | UnaryExpr | CallExpr | MemberExpr | IndexExpr | PipelineExpr | IfExpr | MatchExpr | LambdaExpr | ListLiteral | MapLiteral | ListComprehension | ToolCallExpr | RangeExpr | BlockExpr | AsyncExpr | AwaitExpr | FetchExpr | SpreadExpr | OptionalMemberExpr | TryExpr;
+export type Expr = IntLiteral | FloatLiteral | BoolLiteral | NilLiteral | StringLiteral | StringInterp | Identifier | BinaryExpr | UnaryExpr | CallExpr | MemberExpr | IndexExpr | PipelineExpr | IfExpr | MatchExpr | LambdaExpr | ListLiteral | MapLiteral | ListComprehension | ToolCallExpr | RangeExpr | BlockExpr | AsyncExpr | AwaitExpr | FetchExpr | SpreadExpr | OptionalMemberExpr | TryExpr | TryCatchExpr;
 export interface IntLiteral {
     kind: "IntLiteral";
     value: number;
@@ -170,6 +170,13 @@ export interface TryExpr {
     expr: Expr;
     loc: Loc;
 }
+export interface TryCatchExpr {
+    kind: "TryCatchExpr";
+    body: Expr;
+    catchVar: string;
+    catchBody: Expr;
+    loc: Loc;
+}
 export type Pattern = WildcardPattern | LiteralPattern | BindingPattern | ArrayPattern | OrPattern | ConstructorPattern;
 export interface WildcardPattern {
     kind: "WildcardPattern";
@@ -201,7 +208,7 @@ export interface ConstructorPattern {
     args: Pattern[];
     loc: Loc;
 }
-export type Stmt = LetStmt | FnStmt | ForStmt | DoStmt | ExprStmt | UseStmt | TypeStmt | AssignStmt | MemberAssignStmt | IndexAssignStmt | RetStmt;
+export type Stmt = LetStmt | FnStmt | ForStmt | DoStmt | WhileStmt | ExprStmt | UseStmt | TypeStmt | AssignStmt | MemberAssignStmt | IndexAssignStmt | RetStmt | BreakStmt | ContinueStmt | TryCatchStmt;
 export interface AssignStmt {
     kind: "AssignStmt";
     target: string;
@@ -270,6 +277,27 @@ export interface DoStmt {
     isWhile: boolean;
     loc: Loc;
 }
+export interface WhileStmt {
+    kind: "WhileStmt";
+    condition: Expr;
+    body: Expr;
+    loc: Loc;
+}
+export interface BreakStmt {
+    kind: "BreakStmt";
+    loc: Loc;
+}
+export interface ContinueStmt {
+    kind: "ContinueStmt";
+    loc: Loc;
+}
+export interface TryCatchStmt {
+    kind: "TryCatchStmt";
+    body: Expr;
+    catchVar: string;
+    catchBody: Expr;
+    loc: Loc;
+}
 export interface ExprStmt {
     kind: "ExprStmt";
     expr: Expr;

package/dist/build.js

@@ -127,7 +127,7 @@ export function newProject(name, parentDir) {
         "dev-dependencies": {},
     };
     writeFileSync(resolve(projectDir, "arc.toml"), serializeArcToml(toml));
-    writeFileSync(resolve(projectDir, "src", "main.arc"), `fn main() {\n  let msg = "Hello from ${name}!"\n  print(msg)\n}\n`);
+    writeFileSync(resolve(projectDir, "src", "main.arc"), `# Hello from ${name}!\nlet msg = "Hello from ${name}!"\nprint(msg)\n`);
     writeFileSync(resolve(projectDir, "tests", "main.test.arc"), `fn test_main() {\n  let x = 1 + 1\n  print(x)\n}\n`);
     writeFileSync(resolve(projectDir, "README.md"), `# ${name}\n\nAn Arc project.\n\n## Getting Started\n\n\`\`\`bash\narc build\narc run\n\`\`\`\n`);
     console.log(`Created project '${name}'`);

package/dist/formatter.js

@@ -150,7 +150,7 @@ export function format(source, options) {
                     else {
                         elInline = formatBlockExpr(expr.else_, depth);
                     }
-                    const single = `if ${cond} ${thenInline} el ${elInline}`;
+                    const single = `if ${cond} ${thenInline} else ${elInline}`;
                     if (single.length + depth * opts.indentSize <= opts.maxLineLength) {
                         return single;
                     }
@@ -159,12 +159,12 @@ export function format(source, options) {
                         ? formatBlockMultiline(expr.then, depth)
                         : thenInline;
                     if (expr.else_.kind === "IfExpr") {
-                        return `if ${cond} ${thenMulti} el ${formatExpr(expr.else_, depth)}`;
+                        return `if ${cond} ${thenMulti} else ${formatExpr(expr.else_, depth)}`;
                     }
                     const elMulti = expr.else_.kind === "BlockExpr"
                         ? formatBlockMultiline(expr.else_, depth)
                         : elInline;
-                    return `if ${cond} ${thenMulti} el ${elMulti}`;
+                    return `if ${cond} ${thenMulti} else ${elMulti}`;
                 }
                 const single = `if ${cond} ${thenInline}`;
                 if (single.length + depth * opts.indentSize <= opts.maxLineLength) {
@@ -240,6 +240,8 @@ export function format(source, options) {
             case "SpreadExpr": return `...${formatExpr(expr.expr, depth)}`;
             case "OptionalMemberExpr": return `${formatExpr(expr.object, depth)}?.${expr.property}`;
             case "TryExpr": return `${formatExpr(expr.expr, depth)}?`;
+            case "TryCatchExpr":
+                return `try ${formatBlockExpr(expr.body, depth)} catch ${expr.catchVar} ${formatBlockExpr(expr.catchBody, depth)}`;
             default: return `/* unknown */`;
         }
     }
@@ -347,6 +349,16 @@ export function format(source, options) {
                 const pub = stmt.pub ? "pub " : "";
                 return `${pub}type ${stmt.name} = ${formatTypeExpr(stmt.def)}`;
             }
+            case "RetStmt":
+                return stmt.value ? `return ${formatExpr(stmt.value, depth)}` : "return";
+            case "WhileStmt":
+                return `while ${formatExpr(stmt.condition, depth)} ${formatBlockExpr(stmt.body, depth)}`;
+            case "BreakStmt":
+                return "break";
+            case "ContinueStmt":
+                return "continue";
+            case "TryCatchStmt":
+                return `try ${formatBlockExpr(stmt.body, depth)} catch ${stmt.catchVar} ${formatBlockExpr(stmt.catchBody, depth)}`;
             case "AssignStmt":
                 return `${stmt.target} = ${formatExpr(stmt.value, depth)}`;
             case "MemberAssignStmt":

package/dist/index.js

@@ -101,6 +101,108 @@ else if (command === "pkg") {
         process.exit(1);
     }
 }
+else if (command === "builtins") {
+    console.log("Arc Built-in Functions\n");
+    console.log("I/O:");
+    console.log("  print(...values)          Print values to stdout\n");
+    console.log("Type Conversion:");
+    console.log("  int(v)                    Convert to integer (throws on bad input)");
+    console.log("  float(v)                  Convert to float (throws on bad input)");
+    console.log("  str(v)                    Convert to string");
+    console.log("  bool(v)                   Convert to boolean");
+    console.log("  type_of(v)                Get type: \"int\" \"float\" \"string\" \"bool\" \"list\" \"map\" \"fn\" \"nil\"\n");
+    console.log("Strings:");
+    console.log("  len(s)                    Length (codepoints, not bytes)");
+    console.log("  trim(s)                   Strip whitespace");
+    console.log("  upper(s) / lower(s)       Case conversion");
+    console.log("  split(s, sep)             Split into list");
+    console.log("  join(list, sep)           Join list into string");
+    console.log("  replace(s, old, new)      Replace all occurrences");
+    console.log("  contains(s, sub)          Check substring");
+    console.log("  starts(s, prefix)         Starts with");
+    console.log("  ends(s, suffix)           Ends with");
+    console.log("  repeat(s, n)              Repeat string n times");
+    console.log("  chars(s)                  Split into character list");
+    console.log("  slice(s, start, end?)     Substring");
+    console.log("  index_of(s, sub)          Find index (nil if not found)");
+    console.log("  ord(s)                    Char to code point");
+    console.log("  chr(n)                    Code point to char");
+    console.log("  char_at(s, i)             Character at index\n");
+    console.log("Lists:");
+    console.log("  len(list)                 Length");
+    console.log("  map(list, fn)             Transform each element");
+    console.log("  filter(list, fn)          Keep elements matching predicate");
+    console.log("  reduce(list, fn, init)    Fold left");
+    console.log("  fold(list, init, fn)      Fold (init-first arg order)");
+    console.log("  find(list, fn)            First matching element");
+    console.log("  any(list, fn)             Any element matches?");
+    console.log("  all(list, fn)             All elements match?");
+    console.log("  sort(list)                Sort (numbers or strings)");
+    console.log("  head(list)                First element");
+    console.log("  tail(list)                All but first");
+    console.log("  last(list)                Last element");
+    console.log("  reverse(list)             Reverse");
+    console.log("  take(list, n)             First n elements");
+    console.log("  drop(list, n)             Skip first n");
+    console.log("  flat(list)                Flatten nested lists");
+    console.log("  zip(a, b)                 Zip two lists");
+    console.log("  enumerate(list)           Add indices: [[0,a],[1,b],...]");
+    console.log("  push(list, item)          Append (returns new list)");
+    console.log("  concat(a, b)              Concatenate lists");
+    console.log("  sum(list)                 Sum numbers");
+    console.log("  range(a, b)               Generate [a, a+1, ..., b-1]\n");
+    console.log("Maps:");
+    console.log("  keys(map)                 Get keys as list");
+    console.log("  values(map)               Get values as list");
+    console.log("  entries(map)              Key-value pairs\n");
+    console.log("Math:");
+    console.log("  abs(n)                    Absolute value");
+    console.log("  min(...) / max(...)       Min/max (args or list)");
+    console.log("  round(n)                  Round to integer\n");
+    console.log("Other:");
+    console.log("  assert(cond, msg?)        Assert truth (throws on false)");
+    console.log("  time_ms()                 Unix timestamp in milliseconds\n");
+    console.log("Operators:  +  -  *  /  %  **  ++  ==  !=  <  >  <=  >=  and  or  not  |>  ..  ?.");
+    console.log("Strings:    \"text {expr}\" (interpolation)   \"ha\" * 3 (repetition)");
+    console.log("Comments:   # or //");
+    console.log("Errors:     try { ... } catch e { ... }\n");
+    console.log("Stdlib:     arc builtins --modules    (list all standard library modules)");
+    if (args.includes("--modules")) {
+        console.log("\nStandard Library Modules:  (import with: use <module>)\n");
+        const mods = [
+            ["math", "sqrt, pow, ceil, floor, clamp, PI, E, sin, cos, log, 25 functions"],
+            ["strings", "pad_left, pad_right, capitalize, words"],
+            ["collections", "group_by, chunk, flatten, zip_with, partition, sort_by, unique"],
+            ["map", "merge, map_values, filter_map, from_pairs, pick, omit"],
+            ["io", "read_file, write_file, read_lines, exists, append"],
+            ["http", "get, post, put, delete — real HTTP requests"],
+            ["json", "to_json, from_json, pretty, get_path"],
+            ["csv", "parse_csv, to_csv, parse_csv_headers"],
+            ["regex", "match, find, test, replace, split, capture"],
+            ["datetime", "now, today, parse, format, add_days, diff_days"],
+            ["os", "cwd, list_dir, mkdir, exec, platform, env, remove, copy"],
+            ["env", "get, set, has, all — environment variables"],
+            ["crypto", "sha256, sha512, hmac_sha256, uuid, random_bytes"],
+            ["error", "try_catch, try_finally, throw, retry, assert"],
+            ["result", "ok, err, is_ok, unwrap, map_result, try_fn"],
+            ["net", "ws_connect, tcp_connect, dns_lookup, base64_encode"],
+            ["yaml", "parse, stringify"],
+            ["toml", "parse, stringify"],
+            ["html", "parse, create_element, to_html"],
+            ["path", "join, dirname, basename, extname"],
+            ["log", "info, warn, error, debug"],
+            ["store", "get, set, delete — persistent key-value storage"],
+            ["test", "describe, it, expect_eq, run_tests"],
+            ["prompt", "template, count_tokens, window"],
+            ["embed", "similarity, cosine, search"],
+            ["llm", "chat, complete — multi-provider LLM API"],
+        ];
+        for (const [name, desc] of mods) {
+            console.log(`  ${name.padEnd(14)} ${desc}`);
+        }
+    }
+    process.exit(0);
+}
 else if (command === "help" || command === "--help" || command === "-h" || !command || !file) {
     console.log(`Arc ${ARC_VERSION} — A programming language designed by AI agents, for AI agents.\n`);
     console.log("Usage: arc <command> [options]\n");
@@ -117,6 +219,8 @@ else if (command === "help" || command === "--help" || command === "-h" || !comm
     console.log("  build                   Build the current project");
     console.log("  test                    Run project tests");
     console.log("  new <name>              Create a new project");
+    console.log("  builtins                List all built-in functions");
+    console.log("  builtins --modules      List all standard library modules");
     console.log("  pkg <sub>               Package manager (init|add|remove|list|install)");
     console.log("  version                 Print version info");
     console.log("\nOptions:");