Skip to content

設定 ​

Veritas が設定を読む場所、すべての設定の既定値と使える値、結果のキャッシュの仕組みをまとめます。

設定例 ​

.veritas/config.json には、既定値と違う設定だけを書きます。

json
{
  "$schema": "https://veritas.invalid/schemas/config.json",
  "schemaVersion": "1.0.0",
  "project": { "packageManager": "pnpm", "tsconfig": "tsconfig.json" },
  "analysis": {
    "include": ["src/**/*.ts"],
    "testInclude": ["test/**/*.test.ts"]
  },
  "formal": { "integerDomain": { "min": "-1000000", "max": "1000000" } },
  "pbt": { "numRuns": 500 },
  "policy": {
    "confirmedViolation": "fail",
    "inconclusiveBehavior": "fail",
    "maxNewSurvivors": 0
  },
  "storage": { "retainRuns": 10 }
}
  • analysis.include と analysis.testInclude で、対象にするソースとテストのファイルを選びます。veritas init が検出した値を書き込みます。
  • formal.integerDomain は、形式検証で使う整数の範囲です。境界は 10 進数の文字列で書きます。
  • policy.inconclusiveBehavior: "fail" にすると、判定できない結果があれば終了コード 4 になります。CI のゲートに向いています。
  • policy.maxNewSurvivors: 0 にすると、範囲内の mutant が 1 つでも生き残れば失敗します。
  • storage.retainRuns: 10 で、終わった実行を新しいほうから 10 個残します。実行中のものは削除しません。

設定ファイルの場所 ​

Veritas は、プロジェクトのルートにある .veritas/config.json を読みます。このファイルは veritas init で作ります。内容は schemas/config.json で検証し、未知のキーや不正な値があれば CONFIG_INVALID(終了コード 2)で失敗して、問題のあるフィールドをすべて表示します。

設定はコードでも書けます。プロジェクトのルートに veritas.config.ts、veritas.config.mjs、veritas.config.js のいずれかを置き、同じ形のオブジェクトを default export します。読み込むとプロジェクトのコードが実行されるので、グローバルオプション --allow-code-config を付けたときだけ読み込み、付けなければ CONFIG_CODE_NOT_ALLOWED で失敗します。設定ファイルは 1 つだけにしてください(複数あると CONFIG_AMBIGUOUS)。プロジェクトの外を指すシンボリックリンクの設定ファイルは読み込みません。

ts
export default {
  project: { packageManager: 'pnpm', tsconfig: 'tsconfig.json' },
  analysis: { include: ['src/**/*.ts'], testInclude: ['test/**/*.test.ts'] },
  policy: { inconclusiveBehavior: 'fail', maxNewSurvivors: 0 },
};

.veritas/config.json と .veritas/approvals.json はコミットしてください。GitHub Action は、リポジトリにある設定を使います。.veritas/runs/ と .veritas/cache/ はバージョン管理に入れないでください。

すべての設定 ​

次の表は設定のスキーマから生成しているため、英語のままです。

Every setting, with its type, default and allowed values, as validated by schemas/config.json. A setting whose allowed value is marked fixed accepts only that value. unset means the setting has no default value. Unknown keys are rejected.

Top level ​

SettingTypeDefaultAllowed values
$schemastringunset
schemaVersionstring"1.0.0"only "1.0.0" (fixed)

project ​

SettingTypeDefaultAllowed values
project.packageManagerstring"unknown"pnpm, npm, yarn, bun, unknown
project.tsconfigstring or nullnull

sources ​

SettingTypeDefaultAllowed values
sources.localbooleantrue
sources.github.enabledbooleanfalse
sources.github.repostringunsetmatches ^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})\/(?!\.\.?$)[A-Za-z0-9._-]{1,100}$
sources.web.enabledbooleanfalse
sources.web.allowDomainsarray of string[]items match ^[a-z0-9.-]+$
sources.web.maxPagesinteger30> 0, <= 1000
sources.web.maxDepthinteger1>= 0, <= 5
sources.web.maxCharsinteger200000> 0
sources.web.timeoutMsinteger30000> 0
sources.web.maxDurationMsinteger120000> 0
sources.sendFullTextToLlmbooleanfalse

analysis ​

SettingTypeDefaultAllowed values
analysis.includearray of string (at least 1)["src/**/*.{ts,tsx,js,mjs}"]
analysis.excludearray of string["**/*.generated.*","**/node_modules/**","**/dist/**"]
analysis.testIncludearray of string["**/*.{test,spec}.{ts,tsx,js,mjs}"]
analysis.testFrameworkstring"vitest"only "vitest" (fixed)
analysis.inferSpecsFromCodebooleantrue
analysis.requireApprovalForNormativeClaimsbooleantrueonly true (fixed)

mutation ​

SettingTypeDefaultAllowed values
mutation.backendstring"mizchi"only "mizchi" (fixed)
mutation.modestring"diff"diff, full
mutation.timeoutMsinteger120000> 0

pbt ​

SettingTypeDefaultAllowed values
pbt.numRunsinteger1000> 0, <= 1000000
pbt.seedintegerunset

formal ​

SettingTypeDefaultAllowed values
formal.backendstring"z3"z3, lean
formal.integerDomain.minstring"-10000"matches ^-?\d+$
formal.integerDomain.maxstring"10000"matches ^-?\d+$
formal.maxSolverMsinteger30000> 0
formal.maxArrayLengthinteger3>= 1, <= 8
formal.rejectUnsupportedSemanticsbooleantrueonly true (fixed)

llm ​

SettingTypeDefaultAllowed values
llm.providerstring"none"none, claude, claude-code, openai, codex
llm.modelstringunset
llm.maxTokensPerRuninteger200000>= 0
llm.allowCodexFileReadsbooleanfalse

improvement ​

SettingTypeDefaultAllowed values
improvement.autoApplybooleanfalseonly false (fixed)
improvement.testFilesOnlybooleantrueonly true (fixed)
improvement.maxIterationsinteger3> 0, <= 20
improvement.maxPatchFilesinteger5> 0, <= 50

reports ​

SettingTypeDefaultAllowed values
reports.formatsarray of string["json","markdown","html","sarif"]text, json, markdown, html, sarif

policy ​

SettingTypeDefaultAllowed values
policy.confirmedViolationstring"fail"fail, warn
policy.inconclusiveBehaviorstring"warn"fail, warn, ignore
policy.maxNewSurvivorsintegerunset>= 0
policy.minPropertyCoveragenumberunset>= 0, <= 1

sandbox ​

SettingTypeDefaultAllowed values
sandbox.allowNetworkWithoutIsolationbooleanfalse

storage ​

SettingTypeDefaultAllowed values
storage.retainRunsinteger20> 0
storage.storePromptsbooleanfalseonly false (fixed)

cache ​

SettingTypeDefaultAllowed values
cache.enabledbooleantrue

limits ​

SettingTypeDefaultAllowed values
limits.memoryMbinteger2048>= 256, <= 65536

主な設定の働き ​

設定既定値働き
sources.web.enabled、sources.github.enabledfalseWeb や GitHub から根拠を集めます。Web には allowDomains も必要です。GitHub は sources.github.repo(owner/name)を読みます。どちらも --offline では使いません
sources.web.maxPages、maxDepth、maxChars、timeoutMs、maxDurationMs30、1、200000、30000、120000Web の収集の上限です。ページ数、リンクの深さ、残す文字数、1 ページの時間、全体の時間を指定します。時間内に取得できなかったページは skipped として報告します
analysis.inferSpecsFromCodetrueコードから推測した Property の候補を提案します。false にすると、ドキュメントなどの出典だけから Property を作ります
mutation.modediffdiff は --since を付けて使う前提のモードで、--since がなければ範囲内のすべての mutant を実行し、そのことをステージのメッセージに書きます。full はすべての mutant をメッセージなしで実行します。どちらのモードでも、--since を付ければ変更されたコードに絞ります
formal.integerDomain-10000 から 10000形式検証で使う整数の範囲です。安全な整数の範囲内で指定します
formal.maxSolverMs30000クエリ 1 件あたりのソルバーの制限時間です
formal.maxArrayLength3形式検証で扱う配列の最大の長さ(1〜8)です。これより長い配列は検証しません
pbt.numRuns、pbt.seed1000、Property ごとproperty-based テストの実行回数と seed です。seed を指定しなければ、Property の ID から決まる固定の seed を使うので、結果を再現できます
llm.providernone自由記述の文を読むのに使う LLM です。LLM プロバイダーを参照してください。llm.maxTokensPerRun は 1 回の実行で使うトークンの上限です
policy.confirmedViolationfailfail では、確定した違反で終了コード 1 になります。warn では警告として報告します
policy.inconclusiveBehaviorwarnfail では、判定できない結果で終了コード 4 になります。warn と ignore では終了コード 0 で、verdict は pass_with_warnings になり、判定できない結果をすべて並べます
policy.maxNewSurvivorsなし実行の範囲(--since を付けたときは変更されたコード)で、生き残った mutant がこの数を超えると終了コード 1 になります。mutation の結果がなければ判定できない扱いです
policy.minPropertyCoverageなしaccepted の Property のうち、meaningful_with_evidence のテストがあるものの割合(0〜1)がこれを下回ると終了コード 1 になります。accepted の Property がないとき、または実行にテストの評価がないときは判定できない扱いです
sandbox.allowNetworkWithoutIsolationfalseネットワークを遮断できる Node.js 25 以上がなくても、プロジェクトのコードを実行します。指定しなければ、その結果は判定できないままです
storage.retainRuns20.veritas/runs/ に残す、終わった実行の数です(今回の実行を含みます)。実行が終わるたびに、それより古い実行を削除します。実行中のものは削除しません
cache.enabledtrue.veritas/cache/ の結果を再利用します(キャッシュを参照)
limits.memoryMb2048プロジェクトのコード、プロジェクトのテスト、mutator、Z3 を実行するプロセスのメモリの上限(MiB、256 以上)です。Lean には上限をかけません。メモリが足りなくなると error になります

判定できない結果とは、unknown、timeout、unsupported、semantic_mismatch、error の主張と、partial、skipped、unsupported、timeout、cancelled のステージのことです。

値が 1 つしかない設定 ​

次の設定は規則を明示するためのもので、受け付ける値は 1 つだけです。ほかの値を書くと、不正な設定になります。

設定受け付ける値規則
analysis.requireApprovalForNormativeClaimstrueProperty が accepted になるのは、判断を記録したときだけ
improvement.testFilesOnlytrueimprove はテストファイルを追加するだけで、本番のコードは編集しない
improvement.autoApplyfalse計画の適用には --apply、計画 ID、承認トークンが必要
storage.storePromptsfalseLLM に送ったプロンプトは保存しない
formal.rejectUnsupportedSemanticstrue形式検証の対象外のコードは unsupported とし、近似では扱わない
analysis.testFrameworkvitest対応するテストランナーは Vitest
mutation.backendmizchimutation testing は @mizchi/mutator で実行する

キャッシュ ​

Veritas は 3 種類の結果を .veritas/cache/ に保存し、入力が同じなら再利用します。

結果再利用の条件(次がすべて同じとき)
結論の出た Z3 の結果(sat、unsat)SMT クエリ、ソルバーのビルド、制限時間
成功した LLM の応答プロバイダー、モデル、リクエスト
完了した mutation の実行git ls-files が列挙するすべてのファイルの内容、mutator・Vitest・Node.js のバージョン、設定、--since、範囲

結論の出なかった結果や失敗した結果は再利用しません。再利用した反例も JavaScript で再生し、再利用したことはステージのメッセージに表示します。git がなければ、mutation の結果はキャッシュしません。

エントリには、プロジェクトの外に置いた鍵で署名します。鍵は ~/.cache/veritas/cache-key(Windows では %LOCALAPPDATA%\veritas\cache-key)か、VERITAS_CACHE_KEY_FILE で指定したファイルです。別の鍵で署名されたエントリ(リポジトリと一緒に持ち込まれたもの、鍵のない CI ランナーに復元したものなど)は使いません。git で管理されているキャッシュのディレクトリは、丸ごと使いません。

mutation testing で実行するプロジェクト自身のテストからは、この鍵を読めます。信頼できないコードを分析するときは cache.enabled: false にしてください(セキュリティモデルを参照)。

Apache-2.0 ライセンスで公開しています。