[design] 現状の設計

[opaopa6969]

親issue: opaopa6969/issue-hub#49

現状の設計（深度調査結果）

コアパイプライン

Source（式文字列）
  → FormulaInfoParser（メタデータ解析 + ExecutionBackend 選択）
  → CalculatorCreatorRegistry.forBackend(backend)
  → Calculator（backend 実装）
  → calculator.apply(CalculationContext)
  → Object（評価結果）

AST 設計

• 手書き AST（レガシー経路）: OperatorOperandTreeCreator → JavaCodeCalculatorV3
  • トークン列から直接 Java コードを生成し javac でコンパイル・実行
• 生成 AST（P4/DSL 経路）: UBNF → unlaxer-dsl codegen → Parser + Mapper + Evaluator
  • 生成物は target/generated-sources/tinyexpression-p4/runtime/ 以下
  • pom.xml の exec-maven-plugin で generate-sources フェーズに自動実行
  • 生成クラス例: BinaryExpr、IfExpr、MatchExpr、MethodInvocationExpr、ExternalXxxInvocationExpr、StringConcatExpr、InTimeRangeExpr 等
• 型付き AST（P4 経路）: P4TypedAstEvaluator — sealed switch による型安全な AST 走査（PRIMARY）

Parser 設計

• 手書き Combinator パーサー (src/main/java/org/unlaxer/tinyexpression/parser/):
  • 各演算子・構文要素ごとに独立した Parser クラス（例: BooleanAndExpressionParser、TernaryOperatorParser 等）
  • unlaxer-common の combinator 基盤上に構築
  • TinyExpressionParserCapabilities：delimiter/head 判定を parser 所有に集約（evaluator 側の drift 防止）
  • TinyExpressionKeywords：if/match/call/external/var/variable キーワードを共有定数化
• 生成パーサー (target/generated-sources/.../runtime/): UBNF から自動生成

Evaluator の分離

Evaluator	場所	役割
JavaCodeCalculatorV3	evaluator/javacode/	本番 JavaCode 生成・実行
LegacyAstCreatorJavaCodeCalculator	evaluator/javacode/legacy/	旧 OOTC 経路（凍結）
AstEvaluatorCalculator	evaluator/ast/	AST 走査実行（generated→token→javacode fallback chain）
DslJavaCodeCalculator	evaluator/javacode/	DSL JavaCode シーム（native + legacy bridge）
P4AstEvaluatorCalculator	evaluator/p4/	P4 生成パーサー + AST 評価
P4DslJavaCodeCalculator	evaluator/p4/	P4 生成パーサー + DSL Java 生成
P4TypedAstEvaluator	evaluator/p4/	PRIMARY sealed switch 型安全評価

主要 API

• CalculationContext（変数・オブジェクト・concurrent context）
• PreConstructedCalculator / JavaCodeCalculatorV3
• TinyExpressionsExecutor：複数式を依存関係付きでまとめて実行
• FileBaseTinyExpressionInstancesCache：テナントごとに formulaInfo.txt を読込・キャッシュ
• FormulaInfoAdditionalFields：グローバル既定 backend を外出し
• ResultConsumer：結果を context 書き戻し / ドメイン反映へ委譲

Backend 解決順序

1. FormulaInfoAdditionalFields.executionBackend（グローバル既定値、初期値 JAVA_CODE）
2. 式ごとの executionBackend / backend キー（FormulaInfo メタデータ）
3. CalculatorCreatorRegistry.forBackend(...) でディスパッチ

型システム

• ExpressionTypes enum: _byte/_short/_int/_float/_double/_long/bigDecimal/bigInteger/number/string/_boolean/object/timestamp/_void
• number は float の別名（Float.class にマッピング）
• 算術演算の型昇格: double > float > long > int
• SpecifiedExpressionTypes：式の評価型と結果型を明示的に指定
• Tag ベースで型情報が parser からパーサー間で伝搬

拡張ポイント

1. 新 backend 追加: ExecutionBackend enum + CalculatorCreatorRegistry に登録（将来的には SPI ServiceLoader 化を計画 — TINYEXPRESSION-MULTIPROJECT-PLAN.md）
2. 文法拡張: tools/tinyexpression-p4-lsp-vscode/grammar/tinyexpression-p4.ubnf を編集 → mvn compile で再生成
3. 外部関数追加: import Class#method returning TYPE as alias; 構文
4. カタログ拡張: CatalogProvider 実装（FileBase / InMemory / Composite）
5. LSP/DAP 拡張: unlaxer-dsl の @catalog / @declares / @quickFix / @quickFixHook アノテーション（設計中）

FormulaInfo 記法（実装確認済み）

calculatorName: myFormula
dependsOn: otherFormula
resultType: float
numberType: float
executionBackend: p4-ast
tags: FA
formula:
  var $amount as number set if not exists 100 description='amount';
  call compute($amount)
  float compute($x as number){
    $x * 1.1
  }
---END_OF_PART---

• 主要キー: calculatorName / dependsOn / resultType / numberType / formula / executionBackend(backend) / tags / description / var / field / checkKind

3層アーキテクチャ計画（TINYEXPRESSION-MULTIPROJECT-PLAN.md）

• Layer 1 tinyexpression-api: Calculator、ExecutionBackend、FormulaInfo、Source（pure API）
• Layer 2 tinyexpression-evaluators-*: JAVA_CODE / AST_EVALUATOR / DSL_JAVA_CODE
• Layer 3 tinyexpression-p4 + tinyexpression-tooling: UBNF 生成バックエンド + LSP/DAP/CLI
• SPI ServiceLoader で backend を動的登録（循環依存排除）