defmodule CMDCTest do
  @moduledoc """
  CMDC Test — 集成方 / 第三方 plugin 作者 / cmdc 子库测试 helpers 一站式包。

  cmdc 主库自身的 `test/support/` 目录在 hex 发布时不会打包，导致 Studio /
  Hive 等集成方写 contract test 时各自重写 mock provider / plugin runner /
  事件断言族。本子库把这些常见测试基础设施统一发布到 hex.pm：

  | 模块 | 用途 |
  |---|---|
  | `CMDCTest.MockProvider` | Builder 式 mock LLM provider，配合 `CMDC.Config.provider_fn` 注入 |
  | `CMDCTest.Plugin` | `run_hook/4` 单元测 Plugin；`with_mock_plugin/3` macro 集成路径测试 |
  | `CMDCTest.EventCapture` | EventBus 订阅 + 收集 |
  | `CMDCTest.Assertions` | `assert_event_emitted` / `assert_event_count` / `refute_event_emitted` |
  | `CMDCTest.RAG.Fixtures` | RAG / GraphRAG tool JSON、plugin event、evidence 与状态 fixture |
  | `CMDCTest.RAG.MockBackend` | shape-compatible fake Arcana search/answer backend |
  | `CMDCTest.RAG.MockGraphBackend` | fake GraphStore backend，用于 preflight/status/evidence |
  | `CMDCTest.RAG.MockMaintenanceBackend` | fake graph/reembed maintenance backend |
  | `CMDCTest.RAG.MockPipelineRunner` | fake pipeline runner，返回 grounding 与 run summary |
  | `CMDCTest.RAG.MockStatusBackend` | fake knowledge index status backend |
  | `CMDCTest.RAG.Policy` | 一行生成 collection ACL / pipeline / graph profile 测试 user_data |
  | `CMDCTest.RAG.Assertions` | citation、grounding、pipeline summary、graph evidence 与 raw text 泄漏断言 |
  | `CMDCTest.Workflow.Fixtures` | WorkflowSpec / Run / NodeRun / RunEvent / Gateway 事件 fixture |
  | `CMDCTest.Workflow.FakeRunStore` | shape-compatible fake `CMDCOrchestrator.RunStore` |
  | `CMDCTest.Workflow.Assertions` | workflow completed、signal path、human_task、幂等与 Gateway event 断言 |
  | `CMDCTest.Reasoning.Fixtures` | reasoning 事件与 Runner payload fixture |
  | `CMDCTest.Reasoning.MockProvider` | prompt-routed mock provider，用于并行/递归推理分支测试 |
  | `CMDCTest.Reasoning.Assertions` | reasoning done、strategy、progress、branch、score 断言 |

  ## Quick Start

      # mix.exs
      defp deps do
        [
          {:cmdc, "~> 0.6"},
          {:cmdc_test, "~> 0.3", only: :test}
        ]
      end

      # test/my_agent_test.exs
      defmodule MyAgentTest do
        use ExUnit.Case, async: true
        import CMDCTest.Assertions

        test "Agent 调用 shell 工具触发 SecurityGuard block_tool" do
          provider =
            CMDCTest.MockProvider.new()
            |> CMDCTest.MockProvider.respond_tool_call("shell", %{"cmd" => "rm -rf /"})

          {:ok, session} =
            CMDC.create_agent(
              model: "mock:test",
              config: %{provider_fn: CMDCTest.MockProvider.to_provider_fn(provider)},
              plugins: [CMDC.Plugin.Builtin.SecurityGuard]
            )

          CMDCTest.EventCapture.start_capture(session)
          CMDC.prompt(session, "请删根目录")

          assert_event_emitted(session, :block_tool, timeout: 500)
        end
      end

  详见各子模块 moduledoc。
  """

  @doc "返回 cmdc_test 当前版本号。"
  @spec version() :: String.t()
  def version, do: Mix.Project.config()[:version] || "0.3.1"
end