開発

ActQLのチェックアウトを用意し、ビルドし、変更に関係するテストを動かすまでの手順と、変更が従う決まりごとです。エンジン、Host、Connector、仕様を変更する人のためのページです。プログラムを書くだけなら、ここに書いてあることは不要です。インストールを参照してください。

v0.1の間のコントリビューションのしかたCopy Anchor Link

ActQLはオープンソースで、v0.1の間、メンテナーはCoreの安定化に集中しています。issueは開いています。不具合、仕様の読み取りに迷った箇所、Connectorが扱うシステムの事実関係の報告が、今いちばん助かるコントリビューションです。このリポジトリへのプルリクエストは、v0.1の間は受け付けません。v0.1のあとはメンテナーが少数の変更を取り込むことがありますが、Core（言語の意味、契約、Host）はメンテナー主導のまま進めます。周辺のエコシステム（Connector、SDK、テンプレート、ツール）は、広くコントリビューションを受け入れていきます。このページの残りは、メンテナーと、このリポジトリで変更を作るAgentのための作業リファレンスです。

リポジトリの構成Copy Anchor Link

共通の実行コードが src/connectors/ 配下のパッケージに依存することはありません。Connectorが共通ライブラリに依存するのであって、その逆はありません。この境界はリポジトリのゲートで強制されています。

前提Copy Anchor Link

• Node.js 22以降とnpm（ツール、Nodeパッケージ、ドキュメントのチェックに使う）。
• Python 3.11以降、Cコンパイラ、make。
• Git、curl、tar。
• リポジトリが固定しているMoonBitツールチェーン。インストール方法は後述。開発に対応しているプラットフォームは、Apple SiliconのmacOSとx86-64のLinuxです。

npm ci

MoonBitCopy Anchor Link

ActQLのCoreはMoonBitで書かれています。リポジトリが固定しているバージョンのツールチェーンをそのままインストールしてください。グローバルなインストールは使いません。

node scripts/setup-moonbit.mjs
export MOON_HOME="$PWD/.toolchains/moonbit-$(node -p "require('./toolchain.json').version")"
export PATH="$MOON_HOME/bin:$PATH"
moon version --all

セットアップはアーカイブのチェックサムを検証し、無視対象の .toolchains/ ディレクトリの下にだけインストールし、シェルの設定には触れません。同じ2つの変数をエディターの環境にも設定してください。ツールチェーンを更新するときは toolchain.json を変えてセットアップをやり直します。インストールの中で moon upgrade を実行してはいけません。

ルートの moon.mod が、唯一のモジュール actql/actql を定義しています。日々の作業ではJavaScriptが既定のビルドターゲットです。共通のCoreはWasmとネイティブにもビルドでき、CIは3つすべてを検証します。

ビルドとテストCopy Anchor Link

変更に対する既定の検証は、影響を受けるMoonBitパッケージをJavaScriptバックエンドでテストすることと、触ったSDK、アダプター、スクリプトのNodeテストです。この2つは別の層です。JavaScriptにコンパイルしたMoonBitのテストは、公開されたNode APIのテストの代わりにはなりませんし、その逆もそうです。

node scripts/local-checks.mjs changed は、ツールが「この変更に関係する」と判断したテストを列挙します。パスに基づく助言であって、依存関係の閉包ではありません。変更したものの呼び出し元を見て、そのテストも加えてください。

選んだテストは、有界のラッパーを通して実行します。このラッパーは、実際に何も実行されなかった場合に失敗します。

node scripts/local-checks.mjs test node -- --test-name-pattern 'selected name' scripts/example.test.mjs
node scripts/local-checks.mjs test moon -- --target js src/query_integration --filter '*selected name*'

実行のあいだ、インクリメンタルビルド用の _build/ ディレクトリは残しておきます。同じチェックアウトに対して2つの検証ゲートを同時に走らせてはいけません。ネイティブ限定やFFIの変更には、明示的に選んだネイティブの診断が必要です。Core全体、全ターゲット、証明、性能の各スイートは、既定では動かさず、意図して実行します。

変更を報告するときは、どのチェックをいくつ実行したかと、実行しなかったカバレッジを書いてください。プルリクエストのチェックが立証するのは、実際に実行したものだけです。

パッケージCopy Anchor Link

パックされたクライアントパッケージ（actql、@actql/node、@actql/sdk）は、scripts/ のスクリプトでチェックアウトから作ります。正確なコマンドと成果物の規則は、ソースからビルドするを参照してください。リリースのインストール方法はインストールにあります。

仕様を変更するCopy Anchor Link

docs/spec/ の文書は規範です。各要件には識別子（requirement-block）が付き、spec/ の機械向けの契約は内容の識別子で固定されています。

• 規範のテキストを編集するときは、要件の識別子を保つか、明示的に割り当ててください。
• npm run check:metadata で、編集によってどの義務と文書のインポートが変わったかを確認し、npm run update:metadata でレビュー済みの更新を適用します。変わった義務は、実行の証拠がない状態から始まります。
• コミットする前に npm run check:spec を実行してください。
• 変更した契約の本体に古い内容の識別子を残してはいけません。期待するフィクスチャを実装自身の出力から計算してもいけません。

契約のバージョン文字列（actql/0.1 と /0.1 の契約識別子）はパッケージのバージョンとは独立しており、通常の変更の一部として上げることはありません。

issueと決まりごとCopy Anchor Link

• 不具合、仕様の読み取りに迷った箇所、Connectorが扱うシステムの事実関係は、issueにしてください。言語の意味、ワイヤー形式、契約を変えることになるものは、コードを書く前にissueで互換性への影響を合意します。新しい演算がどう評価されるかは拡張を提案するに書いています。
• リポジトリの中はすべて英語で書きます。コードのコメント、ドキュメント、コミットメッセージ、issue、プルリクエストが対象です。
• コミットメッセージとプルリクエストのタイトルにはConventional Commitsを使います。<type>[optional scope][!]: <description> の形です。
• プルリクエストはテンプレートに従います。何をなぜ変えたか、範囲と互換性、何を検証したか（ソースのリビジョンとともに）、何を実行しなかったか、です。v0.1の間、プルリクエストを開くのはメンテナーだけです。

リポジトリの中でConnectorを作る手順には専用のページがあります。Connectorの作成を参照してください。Coreを実装する人はActQLを実装するを読んでください。