@manifesto-ai/compiler 1.0.0 → 1.4.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Manifesto AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,310 +1,112 @@
 # @manifesto-ai/compiler
 
-> **Compiler** compiles natural language specifications into Manifesto DomainSchemas using LLM-powered pipelines.
+> **Status:** Deprecated (v2 focuses on Core/Host/World/App). This package is legacy and may be removed.
 
----
 
-## What is Compiler?
+> **Compiler** translates MEL (Manifesto Expression Language) into DomainSchema for Manifesto Core.
 
-Compiler takes natural language descriptions and produces valid DomainSchemas. It uses LLM adapters for parsing and proposal, then validates the output using Builder.
+---
 
-Importantly, Compiler is itself a Manifesto application (dogfooding).
+## What is the Compiler?
 
-In the Manifesto architecture:
+The compiler is the MEL frontend for Manifesto. It tokenizes, parses, validates, and lowers MEL source into a DomainSchema that Core can evaluate deterministically.
 
 ```
-Natural Language ──→ COMPILER ──→ DomainSchema
-                        │
-    LLM-powered pipeline (segment → normalize → propose)
-    Builder validation as authority
+MEL source -> Compiler -> DomainSchema -> Core
 ```
 
 ---
 
-## What Compiler Does
+## What the Compiler Does
 
 | Responsibility | Description |
-|----------------|-------------|
-| Parse natural language | Segment text into semantic units |
-| Normalize intents | Convert segments to structured requirements |
-| Propose schema | Generate DomainSchema draft via LLM |
-| Validate output | Use Builder to validate generated schema |
-| Handle ambiguity | Request user resolution for unclear requirements |
+| --- | --- |
+| Parse MEL | Tokenize and parse MEL into an AST |
+| Validate | Scope and semantic checks aligned to MEL v0.3.3 |
+| Generate IR | Produce DomainSchema for Core |
+| Lower system values | Optional lowering of $system.* into explicit effects |
 
 ---
 
-## What Compiler Does NOT Do
+## What the Compiler Does NOT Do
 
 | NOT Responsible For | Who Is |
-|--------------------|--------|
-| Execute domains | Host |
-| Provide LLM infrastructure | Your LLM provider (Anthropic, OpenAI, etc.) |
-| Run the domain | Host, World, Bridge |
+| --- | --- |
+| Execute effects | Host |
+| Apply patches | Core |
+| Govern authority | World |
+| Bind UI | Bridge / React |
 
 ---
 
 ## Installation
 
 ```bash
-npm install @manifesto-ai/compiler @manifesto-ai/builder
+npm install -D @manifesto-ai/compiler
 # or
-pnpm add @manifesto-ai/compiler @manifesto-ai/builder
-```
-
-### LLM Provider (choose one)
-
-```bash
-npm install @anthropic-ai/sdk  # For Anthropic
-# or
-npm install openai             # For OpenAI
+pnpm add -D @manifesto-ai/compiler
 ```
 
 ---
 
-## Quick Example
-
-### Using Anthropic (Built-in)
-
-```typescript
-import { createCompiler } from "@manifesto-ai/compiler";
-
-const compiler = createCompiler({
-  anthropic: { apiKey: process.env.ANTHROPIC_API_KEY },
-});
-
-// Subscribe to state changes
-compiler.subscribe((state) => {
-  console.log("Status:", state.status);
-
-  if (state.status === "success") {
-    console.log("Generated schema:", state.result);
-  }
-
-  if (state.status === "discarded") {
-    console.log("Discarded:", state.discardReason);
-  }
-});
-
-// Start compilation
-await compiler.start({
-  text: `
-    Track a list of todos with title and completion status.
-    Users can add new todos, toggle completion, and delete todos.
-    Show a count of remaining incomplete todos.
-  `,
-  context: {
-    domainName: "todo",
-  },
-});
-```
-
-### Using OpenAI
-
-```typescript
-import { createCompiler, createOpenAIAdapter } from "@manifesto-ai/compiler";
-import OpenAI from "openai";
-
-const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
-const adapter = createOpenAIAdapter({ client: openai, model: "gpt-4" });
-
-const compiler = createCompiler({
-  llmAdapter: adapter,
-});
-
-await compiler.start({ text: "Track user profiles with name and email..." });
-```
-
-> See [GUIDE.md](../../docs/packages/compiler/GUIDE.md) for the full tutorial.
-
----
-
 ## CLI Usage
 
-The compiler includes an interactive CLI tool:
-
 ```bash
-# Direct input
-manifesto-compile "Track user name and email"
-
-# From file
-manifesto-compile --file requirements.txt
-
-# Output to file
-manifesto-compile "Track todos" -o schema.json
-
-# Use Anthropic provider
-manifesto-compile --provider anthropic "Create a counter"
-
-# Show progress
-manifesto-compile --verbose "Complex requirements..."
+pnpm exec mel check path/to/domain.mel
+pnpm exec mel compile path/to/domain.mel --pretty
+pnpm exec mel compile path/to/domain.mel --stdout
+pnpm exec mel parse path/to/domain.mel
+pnpm exec mel tokens path/to/domain.mel
 ```
 
-### CLI Options
-
-| Option | Description |
-|--------|-------------|
-| `--provider` | LLM provider: `openai` (default) or `anthropic` |
-| `--model` | Model name |
-| `--file` | Read input from file |
-| `--stdin` | Read input from stdin |
-| `-o, --output` | Write result to file |
-| `--verbose` | Show phase progress |
-| `--full` | Show full metrics |
-
-> See [GUIDE.md](../../docs/packages/compiler/GUIDE.md#cli-usage) for detailed CLI documentation.
-
 ---
 
-## Compiler API
-
-### Main Exports
+## Node API
 
 ```typescript
-// Factory
-function createCompiler(options: CompilerOptions): Compiler;
-
-// Compiler interface
-interface Compiler {
-  start(input: CompileInput): Promise<void>;
-  subscribe(callback: (state: CompilerState) => void): Unsubscribe;
-  requestResolution(optionId: string): Promise<void>;
-  getState(): CompilerState;
-}
+import { compile, check } from "@manifesto-ai/compiler";
 
-// LLM Adapters
-function createAnthropicAdapter(options: AnthropicAdapterOptions): LLMAdapter;
-function createOpenAIAdapter(options: OpenAIAdapterOptions): LLMAdapter;
-
-// Types
-type CompilerStatus =
-  | "idle"
-  | "segmenting"
-  | "normalizing"
-  | "proposing"
-  | "validating"
-  | "awaiting_resolution"
-  | "success"
-  | "discarded";
-
-type CompilerState = {
-  status: CompilerStatus;
-  segments?: string[];
-  intents?: NormalizedIntent[];
-  draft?: DomainSchema;
-  result?: DomainSchema;
-  diagnostics?: CompilerDiagnostics;
-  resolutionOptions?: ResolutionOption[];
-  discardReason?: DiscardReason;
-};
-
-interface LLMAdapter {
-  segment(input: SegmentInput): Promise<LLMResult<SegmentResult>>;
-  normalize(input: NormalizeInput): Promise<LLMResult<NormalizeResult>>;
-  propose(input: ProposeInput): Promise<LLMResult<ProposeResult>>;
+const source = `
+domain Counter {
+  state { count: number = 0 }
+  action increment() {
+    when true { patch count = add(count, 1) }
+  }
 }
-```
-
-> See [SPEC.md](../../docs/packages/compiler/SPEC.md) for complete API reference.
-
----
-
-## Core Concepts
-
-### Pipeline Stages
-
-```
-idle → segmenting → normalizing → proposing → validating → success
-                                      ↓              ↓
-                              awaiting_resolution  discarded
-```
+`;
 
-1. **Segmenting**: Parse NL text into semantic segments
-2. **Normalizing**: Convert segments to structured NormalizedIntents
-3. **Proposing**: Generate DomainSchema draft via LLM
-4. **Validating**: Validate draft using Builder (the "judge")
-5. **Resolution**: Handle ambiguities (user choice or auto-discard)
-6. **Success/Discarded**: Terminal states
+const result = compile(source, { lowerSystemValues: true });
 
-### LLM as Untrusted Proposer
-
-The LLM generates schema proposals, but Builder validates them. This ensures type safety and structural correctness regardless of LLM output quality.
+if (!result.success) {
+  console.error(result.errors);
+} else {
+  console.log(result.schema);
+}
 
+const errors = check(source);
 ```
-LLM (untrusted proposer) → Draft Schema
-                              ↓
-                    Builder (judge) → Validation
-                              ↓
-                    Valid? → Success
-                    Invalid? → Retry or Discard
-```
-
-### Custom LLM Adapters
 
-Implement `LLMAdapter` interface for any LLM provider:
+### Compile Options
 
 ```typescript
-const myAdapter: LLMAdapter = {
-  async segment({ text }) {
-    // Call your LLM
-    return { ok: true, data: { segments: [...] } };
-  },
-  async normalize({ segments, schema, context }) {
-    return { ok: true, data: { intents: [...] } };
-  },
-  async propose({ schema, intents, history, context }) {
-    return { ok: true, data: { draft: {...} } };
-  },
+type CompileOptions = {
+  skipSemanticAnalysis?: boolean;
+  lowerSystemValues?: boolean;
 };
 ```
 
 ---
 
-## Relationship with Other Packages
-
-```
-┌─────────────┐
-│    Your     │ ← Uses Compiler for NL→Schema
-│    Tool     │
-└──────┬──────┘
-       │
-       ▼
-┌─────────────┐
-│  COMPILER   │
-└──────┬──────┘
-       │
-       ▼
-┌─────────────┐
-│   Builder   │ ← Validates generated schemas
-└─────────────┘
-```
-
-| Relationship | Package | How |
-|--------------|---------|-----|
-| Depends on | `@manifesto-ai/builder` | Validates generated schemas |
-| Depends on | `@manifesto-ai/core` | Uses Core types |
-| Used by | Developer tools | For AI-assisted domain creation |
-
----
-
-## When to Use Compiler
-
-Use Compiler when:
-- Building AI-assisted domain definition tools
-- Creating no-code/low-code domain builders
-- Prototyping domains from natural language specs
-- Building developer productivity tools
-
-For manual domain definition, use [`@manifesto-ai/builder`](../builder/) directly.
-
----
-
 ## Documentation
 
 | Document | Purpose |
-|----------|---------|
-| [GUIDE.md](../../docs/packages/compiler/GUIDE.md) | Step-by-step usage guide |
-| [SPEC.md](../../docs/packages/compiler/SPEC.md) | Complete specification |
-| [FDR.md](../../docs/packages/compiler/FDR.md) | Design rationale |
+| --- | --- |
+| [MEL Overview](../../docs/mel/) | What MEL is and how to use it |
+| [MEL Syntax](../../docs/mel/SYNTAX.md) | Grammar and syntax |
+| [MEL Examples](../../docs/mel/EXAMPLES.md) | Example library |
+| [MEL Error Guide](../../docs/mel/ERROR-GUIDE.md) | Error codes and fixes |
+| [Compiler Spec](docs/SPEC.md) | Full compiler and MEL spec |
+| [Compiler FDR](docs/FDR-0.3.3v.md) | Design rationale |
 
 ---
 

package/dist/analyzer/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Analyzer Module - Semantic analysis for MEL
+ */
+export * from "./scope.js";
+export * from "./validator.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/analyzer/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/analyzer/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC"}

package/dist/analyzer/index.js

@@ -0,0 +1,6 @@
+/**
+ * Analyzer Module - Semantic analysis for MEL
+ */
+export * from "./scope.js";
+export * from "./validator.js";
+//# sourceMappingURL=index.js.map

package/dist/analyzer/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/analyzer/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC"}

package/dist/analyzer/scope.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Scope Analysis for MEL
+ * Tracks variable scopes and resolves identifiers
+ * Based on MEL SPEC v0.3.1 Section 4.10
+ */
+import type { ProgramNode } from "../parser/ast.js";
+import type { Diagnostic } from "../diagnostics/types.js";
+import type { SourceLocation } from "../lexer/source-location.js";
+/**
+ * Symbol kinds
+ */
+export type SymbolKind = "state" | "computed" | "param" | "action" | "iteration";
+/**
+ * Symbol information
+ */
+export interface Symbol {
+    name: string;
+    kind: SymbolKind;
+    location: SourceLocation;
+    type?: string;
+}
+/**
+ * Scope represents a lexical scope
+ */
+export declare class Scope {
+    readonly parent: Scope | null;
+    readonly symbols: Map<string, Symbol>;
+    readonly kind: "domain" | "action" | "guard";
+    constructor(kind: "domain" | "action" | "guard", parent?: Scope | null);
+    /**
+     * Define a new symbol in this scope
+     */
+    define(symbol: Symbol): void;
+    /**
+     * Look up a symbol, searching parent scopes if not found
+     */
+    lookup(name: string): Symbol | undefined;
+    /**
+     * Check if a symbol is defined in this scope (not parent scopes)
+     */
+    isDefined(name: string): boolean;
+}
+/**
+ * Result of scope analysis
+ */
+export interface ScopeAnalysisResult {
+    scopes: Map<string, Scope>;
+    diagnostics: Diagnostic[];
+}
+/**
+ * Scope Analyzer - builds scope tree and checks for errors
+ */
+export declare class ScopeAnalyzer {
+    private diagnostics;
+    private scopes;
+    private currentScope;
+    private domainScope;
+    /**
+     * Analyze a MEL program
+     */
+    analyze(program: ProgramNode): ScopeAnalysisResult;
+    private analyzeDomain;
+    private analyzeComputedExpr;
+    private analyzeAction;
+    private analyzeStmt;
+    private analyzeExpr;
+    private checkIdentifier;
+    private checkSystemIdent;
+    private validatePath;
+    private defineSymbol;
+    private error;
+}
+/**
+ * Analyze a MEL program for scope issues
+ */
+export declare function analyzeScope(program: ProgramNode): ScopeAnalysisResult;
+//# sourceMappingURL=scope.d.ts.map

package/dist/analyzer/scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../src/analyzer/scope.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,WAAW,EASZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAIlE;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,UAAU,GAAG,OAAO,GAAG,QAAQ,GAAG,WAAW,CAAC;AAEjF;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE,cAAc,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,qBAAa,KAAK;IAChB,QAAQ,CAAC,MAAM,EAAE,KAAK,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAa;IAClD,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;gBAEjC,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,EAAE,MAAM,GAAE,KAAK,GAAG,IAAW;IAK5E;;OAEG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI5B;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAMxC;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;CAGjC;AAID;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC3B,WAAW,EAAE,UAAU,EAAE,CAAC;CAC3B;AAED;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,WAAW,CAAoB;IACvC,OAAO,CAAC,MAAM,CAAiC;IAC/C,OAAO,CAAC,YAAY,CAAsB;IAC1C,OAAO,CAAC,WAAW,CAAsB;IAEzC;;OAEG;IACH,OAAO,CAAC,OAAO,EAAE,WAAW,GAAG,mBAAmB;IAclD,OAAO,CAAC,aAAa;IA0CrB,OAAO,CAAC,mBAAmB;IAK3B,OAAO,CAAC,aAAa;IAuBrB,OAAO,CAAC,WAAW;IAgDnB,OAAO,CAAC,WAAW;IAgEnB,OAAO,CAAC,eAAe;IAqBvB,OAAO,CAAC,gBAAgB;IAuCxB,OAAO,CAAC,YAAY;IAiBpB,OAAO,CAAC,YAAY;IAepB,OAAO,CAAC,KAAK;CAQd;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,WAAW,GAAG,mBAAmB,CAGtE"}