infornoid 0.2.0

data/README.md

@@ -0,0 +1,248 @@
+# Infornoid Compiler
+
+> 混合架构智能编译器 — 确定性前端 + LLM 顾问优化 + 确定性代码生成
+
+Infornoid 是一个采用**混合架构**设计的智能编译器：确定性编译器保证安全性与可预测性，LLM 作为**顾问**提供优化建议，不直接生成可执行代码。
+
+**零第三方依赖，纯 Ruby 标准库实现。**
+
+---
+
+## 特性
+
+- **确定性前端**：手写词法分析器 + 递归下降语法分析器
+- **规则引擎语义**：符号表 + 作用域 + 类型推导
+- **LLM 顾问优化**（可选）：通过 [Ollama](https://ollama.com/) 本地调用大模型提供优化建议
+- **确定性代码生成**：模板驱动的目标代码输出（JavaScript / Python）
+- **优雅降级**：Ollama 不可用时自动回退到纯确定性编译
+
+---
+
+## 快速开始
+
+### 环境要求
+
+- **Ruby 2.5+**（仅使用标准库，无需安装 gem）
+- **可选**：本地 Ollama 服务（用于 `--llm` 顾问功能）
+
+### 安装
+
+```bash
+gem build infornoid.gemspec
+gem install infornoid-0.1.0.gem
+```
+
+安装后可直接使用 `infornoid` 命令：
+
+```bash
+infornoid examples/hello.inf                 # 编译为 JavaScript
+infornoid compile examples/hello.inf -o out.js
+infornoid examples/hello.inf --target py -o out.py
+```
+
+### 本地开发（无需安装）
+
+```bash
+# 编译为 JavaScript (默认子命令为 compile)
+ruby lib/infornoid.rb examples/hello.inf
+
+# 指定输出文件
+ruby lib/infornoid.rb examples/hello.inf -o out.js
+
+# 编译为 Python
+ruby lib/infornoid.rb examples/hello.inf --target py -o out.py
+```
+
+### 命令行工具 (本地开发)
+
+将 `bin/`（Unix/macOS）或仓库根目录（Windows）加入 `PATH` 后，即可直接使用 `infornoid` 命令：
+
+```bash
+# Windows: infornoid.cmd
+# Unix/macOS: bin/infornoid (chmod +x bin/infornoid)
+
+infornoid examples/hello.inf                 # 编译为 JavaScript
+infornoid compile examples/hello.inf -o out.js
+infornoid examples/hello.inf --target py -o out.py
+```
+
+### 子命令风格（类似 gcc/clang 分阶段调用）
+
+```bash
+infornoid lex examples/hello.inf           # 输出 Token 列表
+infornoid parse examples/hello.inf --json  # 输出 AST JSON
+infornoid semantic examples/hello.inf      # 输出符号表 / 类型 / 错误
+infornoid optimize examples/hello.inf      # 输出优化后 AST
+infornoid codegen examples/hello.inf --target py   # 仅生成代码
+infornoid check examples/hello.inf         # 语法检查 (不输出代码)
+```
+
+> 兼容旧用法：`--tokens` 等同 `lex`，`--ast` 等同 `parse`，无子命令时默认 `compile`。
+
+---
+
+## 语言示例
+
+```inf
+// 函数声明
+fn add(a: Number, b: Number) -> Number {
+  return a + b;
+}
+
+// 变量声明 + 类型推断
+let x = 1 + 2 * 3;
+let y = add(x, 10);
+
+// 条件分支
+if (x > 5) {
+  let z = x + y;
+} else {
+  let z = x - y;
+}
+
+// 循环
+let i = 0;
+while (i < 10) {
+  i = i + 1;
+}
+```
+
+---
+
+## 架构
+
+```
+源码 (.inf)
+    ↓
+[Lexer]  → Token
+    ↓
+[Parser] → AST
+    ↓
+[Semantic] → 类型检查、符号表验证
+    ↓
+[Optimizer] → 常量折叠、死代码消除、LLM 建议
+    ↓
+[Codegen] → 目标代码（JavaScript / Python）
+```
+
+| 模块 | 功能 |
+|------|------|
+| `lib/infornoid.rb` | 主驱动，CLI 参数解析与阶段编排 |
+| `lib/lexer.rb` | 词法分析器 |
+| `lib/parser.rb` | 递归下降语法分析器 |
+| `lib/semantic.rb` | 语义分析：符号表 + 类型检查 |
+| `lib/optimizer.rb` | 优化器：常量折叠、死代码消除 |
+| `lib/codegen.rb` | 代码生成器 |
+| `lib/advisor.rb` | LLM 顾问层：Ollama 集成 + 优雅降级 |
+
+---
+
+## 项目结构
+
+```
+infornoid/
+├── bin/
+│   └── infornoid         # Unix/macOS 命令入口
+├── infornoid.cmd         # Windows 命令入口
+├── infornoid.gemspec     # gem 构建文件
+├── lib/
+│   ├── infornoid.rb      # 主入口（子命令风格 CLI）
+│   ├── lexer.rb          # 词法分析器
+│   ├── parser.rb         # 语法分析器
+│   ├── semantic.rb       # 语义分析器
+│   ├── optimizer.rb      # 优化器
+│   ├── codegen.rb        # 代码生成器
+│   └── advisor.rb        # LLM 顾问层
+├── spec/
+│   ├── base_spec.rb      # 测试套件
+│   └── spec_helper.rb    # 测试辅助
+├── examples/
+│   ├── hello.inf         # 示例源文件
+│   └── hello.js          # 编译输出示例
+├── documents/            # 调研文档与方案设计
+│   ├── 01_GitHub项目调研/
+│   ├── 02_大模型构建编译器方案/
+│   ├── 03_相关SKILL分析/
+│   └── 04_下一步计划/
+├── README.md             # 本文件
+└── index.html            # 交互式演示页面
+```
+
+---
+
+## 测试
+
+```bash
+bundle exec rspec spec/base_spec.rb
+```
+
+测试覆盖：Lexer、Parser、Semantic、Optimizer、Codegen、端到端。
+
+---
+
+## CLI 选项
+
+| 选项 | 说明 |
+|------|------|
+| `-o <file>` | 指定输出文件路径 |
+| `--target <lang>` | 目标语言：`js`（默认）、`py` |
+| `--json` | 以 JSON 输出调试信息（`lex` / `parse` / `semantic` / `optimize`） |
+| `--ast` | 输出 AST JSON（等同 `parse`） |
+| `--tokens` | 输出 Token 列表（等同 `lex`） |
+| `--no-opt` | 跳过优化阶段 |
+| `--llm` | 启用 LLM 顾问（需要 Ollama） |
+| `--help`, `-h` | 显示帮助 |
+| `--version`, `-v` | 显示版本 |
+
+## CLI 子命令
+
+| 子命令 | 说明 |
+|--------|------|
+| `compile`（默认） | 完整流水线：词法 → 语法 → 语义 → 优化 → 代码生成 |
+| `lex` | 仅词法分析，输出 Token 列表（`--json` 输出 JSON） |
+| `parse` | 仅语法分析，输出 AST |
+| `semantic` | 语义分析，输出符号表 / 类型 / 错误 |
+| `optimize` | 优化阶段，输出优化后 AST |
+| `codegen` | 仅代码生成（默认目标 JS，可用 `--target` 切换） |
+| `check` | 语法检查，通过时退出码 0，出错时退出码 1 |
+
+---
+
+## 语言规范速查
+
+### 数据类型
+
+`Number` · `String` · `Boolean` · `Void`
+
+### 关键字
+
+```
+let  fn  if  else  while  return  true  false
+```
+
+### 运算符优先级
+
+1. `=` 赋值
+2. `||` 逻辑或
+3. `&&` 逻辑与
+4. `==` `!=` 等于/不等于
+5. `<` `>` `<=` `>=` 比较
+6. `+` `-` 加减
+7. `*` `/` `%` 乘除模
+8. `!` `-`（一元）逻辑非、取负
+
+---
+
+## 设计文档
+
+本项目的设计与调研文档位于 `documents/` 目录，涵盖：
+
+- **GitHub 项目调研**：AI 优化传统编译器、深度学习专用编译器
+- **三条技术路线**：LLM 作编码助手 / LLM 充当编译器 / 混合架构 AgentCompile
+- **推荐路线**：混合架构（路线三）— LLM 顾问 + 确定性编译器
+
+---
+
+## 许可证
+
+AGPL-3.0

data/bin/infornoid

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+#coding:utf-8
+# infornoid — 命令行入口
+# 安装为 gem 后: infornoid examples/hello.inf
+# 本地开发:     ruby bin/infornoid examples/hello.inf
+
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__)) unless $LOADED_FEATURES.any?{|f| f.end_with?('infornoid.rb')}
+require 'infornoid'
+
+exit(Infor::Compiler.main(ARGV) || 0)

data/lib/advisor.rb

@@ -0,0 +1,151 @@
+#coding:utf-8
+# infornoid LLM 顾问层 — Ollama 本地集成 + 优雅降级
+# 零第三方依赖, 通过 net/http 调用本地 Ollama API
+# 设计哲学: LLM 只输出建议性元数据, 不直接生成可执行代码
+# CALL: Advisor.suggest(ast, phase) → suggestions Hash
+# RETN: {ok:true/false, suggestions:[...], source:"llm"/"fallback"}
+
+require 'net/http'
+require 'json'
+
+module Infor
+  module Advisor
+    module_function
+
+    # ☆ Ollama 默认配置, 可通过环境变量覆盖
+    DEF_HOST = ENV['OLLAMA_HOST'] || '127.0.0.1'
+    DEF_PORT = (ENV['OLLAMA_PORT'] || 11434).to_i
+    DEF_MODEL = ENV['INFORNOID_MODEL'] || 'qwen2.5-coder:7b'
+
+    #### 探活 ####
+
+    # 检查 Ollama 是否可用
+    def alive? host = DEF_HOST, port = DEF_PORT
+      s = TCPSocket.new(host, port)
+      s.close
+      true
+    rescue
+      false
+    end
+
+    #### 核心调用 ####
+
+    # 向 Ollama 发送 prompt, 返回文本响应
+    # CALL: ask(prompt) → String
+    def ask prompt, model = DEF_MODEL, host = DEF_HOST, port = DEF_PORT
+      return '' unless alive?(host, port)
+      uri = URI("http://#{host}:#{port}/api/generate")
+      req = Net::HTTP::Post.new(uri, 'Content-Type'=>'application/json')
+      req.body = JSON.generate({
+        model: model,
+        prompt: prompt,
+        stream: false,
+        options: { temperature: 0, seed: 42 }
+      })
+      http = Net::HTTP.new(host, port)
+      http.read_timeout = 60
+      res = http.request(req)
+      return '' unless res.is_a? Net::HTTPSuccess
+      data = JSON.parse(res.body)
+      data['response'] || ''
+    rescue => e
+      $stderr.puts "[advisor] LLM 调用失败: #{e.message}"
+      ''
+    end
+
+    #### 语义分析顾问 ####
+
+    # 让 LLM 对 AST 做类型推断建议
+    # RETN: {ok, suggestions, source}
+    def typecheck_advice ast
+      prompt = <<-PROMPT
+你是类型推断顾问, 分析以下 AST, 对需要推断类型的节点给出建议.
+只输出 JSON, 格式: {"suggestions":[{"node_path":"...","type":"Number|String|Boolean|Void","confidence":0.0-1.0,"reason":"..."}]}
+
+AST(JSON):
+#{JSON.pretty_generate(ast)}
+PROMPT
+      raw = ask(prompt)
+      return fallback_typecheck(ast) if raw.empty?
+      parse_suggestions(raw, :typecheck)
+    end
+
+    #### 优化顾问 ####
+
+    # 让 LLM 分析 AST/IR 输出优化建议
+    # RETN: {ok, suggestions, source}
+    def optimize_advice ast
+      prompt = <<-PROMPT
+你是编译优化顾问, 分析以下 AST, 列出优化建议.
+可用 Pass: constant_folding, dead_code_elimination, inline_call, loop_unroll, strength_reduction
+只输出 JSON, 格式: {"suggestions":[{"pass":"...","target":"...","params":{},"expected_gain":"...","reason":"..."}]}
+
+AST(JSON):
+#{JSON.pretty_generate(ast)}
+PROMPT
+      raw = ask(prompt)
+      return fallback_optimize(ast) if raw.empty?
+      parse_suggestions(raw, :optimize)
+    end
+
+    #### 代码生成顾问 ####
+
+    # 让 LLM 建议代码模板
+    # RETN: {ok, suggestions, source}
+    def codegen_advice node, target = 'JavaScript'
+      prompt = <<-PROMPT
+你是代码生成顾问, 为以下 AST 节点建议 #{target} 代码模板.
+只输出 JSON, 格式: {"templates":[{"node_type":"...","template":"..."}]}
+
+AST 节点(JSON):
+#{JSON.pretty_generate(node)}
+PROMPT
+      raw = ask(prompt)
+      return fallback_codegen(node) if raw.empty?
+      parse_suggestions(raw, :codegen)
+    end
+
+    #### JSON 解析 ####
+
+    # 尝试从 LLM 响应中提取 JSON
+    def parse_suggestions raw, phase
+      # 尝试直接解析
+      begin
+        data = JSON.parse(raw)
+        return { ok:true, suggestions:data['suggestions'] || data['templates'] || [data], source:'llm' }
+      rescue
+      end
+      # 尝试提取 JSON 块
+      if raw =~ /\{[\s\S]*\}/m
+        begin
+          data = JSON.parse($&)
+          return { ok:true, suggestions:data['suggestions'] || data['templates'] || [data], source:'llm' }
+        rescue
+        end
+      end
+      # 降级
+      case phase
+      when :typecheck then fallback_typecheck(nil)
+      when :optimize  then fallback_optimize(nil)
+      when :codegen   then fallback_codegen(nil)
+      end
+    end
+
+    #### 降级策略 — 零 LLM 时的确定性兜底 ####
+
+    def fallback_typecheck ast
+      { ok:false, suggestions:[], source:'fallback', reason:'LLM 不可用, 使用规则引擎兜底' }
+    end
+
+    def fallback_optimize ast
+      { ok:false, suggestions:[
+        { pass:'constant_folding', target:'all', params:{}, expected_gain:'+5%', reason:'确定性常量折叠, 无需 LLM' }
+      ], source:'fallback' }
+    end
+
+    def fallback_codegen node
+      { ok:false, suggestions:[], source:'fallback', reason:'LLM 不可用, 使用默认模板兜底' }
+    end
+
+  end
+end

data/lib/codegen.rb

@@ -0,0 +1,109 @@
+#coding:utf-8
+# infornoid 代码生成器 — LLM 建议模板 + 确定性填充
+# 默认目标: JavaScript
+# 确定性模板优先, LLM 模板仅在编译验证通过时采纳
+# CALL: Codegen.gen(ast, target, use_llm) → String (目标代码)
+
+module Infor
+  module Codegen
+    module_function
+
+    # ☆ 确定性默认模板
+    TMPL = {
+      'LetDecl'    => 'let %s = %s;',
+      'FnDecl'     => "function %s(%s) {\n%s\n}",
+      'IfStmt'     => "if (%s) {\n%s\n} else {\n%s\n}",
+      'WhileStmt'  => "while (%s) {\n%s\n}",
+      'ReturnStmt' => 'return %s;',
+      'ExprStmt'   => '%s;',
+      'Assign'     => '%s = %s',
+      'Binary'     => '(%s %s %s)',
+      'Unary'      => '%s%s',
+      'NumLit'     => '%s',
+      'StrLit'     => '"%s"',
+      'BoolLit'    => '%s',
+      'Ident'      => '%s',
+      'Call'       => '%s(%s)',
+    }
+
+    @ind = 0  #缩进层级
+
+    def gen ast, target = 'JavaScript', use_llm = false
+      @ind = 0
+      @log = []
+      code = gen_node(ast)
+      { code:code, log:@log }
+    end
+
+    #### 递归生成 ####
+
+    def gen_node node
+      return '' unless node
+      case node[:type]
+      when 'Program'
+        node[:body].map{|s| gen_node(s) }.join("\n\n")
+      when 'Block'
+        node[:body].map{|s| gen_node(s) }.join("\n")
+      when 'LetDecl'
+        pad TMPL['LetDecl'] % [node[:name], gen_node(node[:value])]
+      when 'FnDecl'
+        params = node[:params].map{|p| p[:name] }.join(', ')
+        body = indent { gen_node(node[:body]) }
+        pad TMPL['FnDecl'] % [node[:name], params, body]
+      when 'IfStmt'
+        cond = gen_node(node[:cond])
+        then_b = indent { gen_node(node[:then]) }
+        if node[:els]
+          els_b = indent { gen_node(node[:els]) }
+          pad TMPL['IfStmt'] % [cond, then_b, els_b]
+        else
+          pad "if (%s) {\n%s\n}" % [cond, then_b]
+        end
+      when 'WhileStmt'
+        cond = gen_node(node[:cond])
+        body = indent { gen_node(node[:body]) }
+        pad TMPL['WhileStmt'] % [cond, body]
+      when 'ReturnStmt'
+        val = node[:value] ? gen_node(node[:value]) : ''
+        pad TMPL['ReturnStmt'] % val
+      when 'ExprStmt'
+        pad TMPL['ExprStmt'] % gen_node(node[:expr])
+      when 'Assign'
+        pad TMPL['Assign'] % [gen_node(node[:target]), gen_node(node[:value])]
+      when 'Binary'
+        TMPL['Binary'] % [gen_node(node[:left]), node[:op], gen_node(node[:right])]
+      when 'Unary'
+        TMPL['Unary'] % [node[:op], gen_node(node[:operand])]
+      when 'NumLit'
+        node[:value]
+      when 'StrLit'
+        '"%s"' % node[:value].gsub('"', '\\"')
+      when 'BoolLit'
+        node[:value] ? 'true' : 'false'
+      when 'Ident'
+        node[:name]
+      when 'Call'
+        args = node[:args].map{|a| gen_node(a) }.join(', ')
+        TMPL['Call'] % [node[:name], args]
+      when 'Error'
+        '/* ERROR */'
+      else
+        "/* unknown: #{node[:type]} */"
+      end
+    end
+
+    #### 缩进辅助 ####
+
+    def pad str
+      '  ' * @ind + str
+    end
+
+    def indent
+      @ind += 1
+      r = yield
+      @ind -= 1
+      r
+    end
+
+  end
+end