設定
Veritas が設定を読む場所、すべての設定の既定値と使える値、結果のキャッシュの仕組みをまとめます。
設定例
.veritas/config.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)。プロジェクトの外を指すシンボリックリンクの設定ファイルは読み込みません。
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
| Setting | Type | Default | Allowed values |
|---|---|---|---|
$schema | string | unset | |
schemaVersion | string | "1.0.0" | only "1.0.0" (fixed) |
project
| Setting | Type | Default | Allowed values |
|---|---|---|---|
project.packageManager | string | "unknown" | pnpm, npm, yarn, bun, unknown |
project.tsconfig | string or null | null |
sources
| Setting | Type | Default | Allowed values |
|---|---|---|---|
sources.local | boolean | true | |
sources.github.enabled | boolean | false | |
sources.github.repo | string | unset | matches ^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})\/(?!\.\.?$)[A-Za-z0-9._-]{1,100}$ |
sources.web.enabled | boolean | false | |
sources.web.allowDomains | array of string | [] | items match ^[a-z0-9.-]+$ |
sources.web.maxPages | integer | 30 | > 0, <= 1000 |
sources.web.maxDepth | integer | 1 | >= 0, <= 5 |
sources.web.maxChars | integer | 200000 | > 0 |
sources.web.timeoutMs | integer | 30000 | > 0 |
sources.web.maxDurationMs | integer | 120000 | > 0 |
sources.sendFullTextToLlm | boolean | false |
analysis
| Setting | Type | Default | Allowed values |
|---|---|---|---|
analysis.include | array of string (at least 1) | ["src/**/*.{ts,tsx,js,mjs}"] | |
analysis.exclude | array of string | ["**/*.generated.*","**/node_modules/**","**/dist/**"] | |
analysis.testInclude | array of string | ["**/*.{test,spec}.{ts,tsx,js,mjs}"] | |
analysis.testFramework | string | "vitest" | only "vitest" (fixed) |
analysis.inferSpecsFromCode | boolean | true | |
analysis.requireApprovalForNormativeClaims | boolean | true | only true (fixed) |
mutation
| Setting | Type | Default | Allowed values |
|---|---|---|---|
mutation.backend | string | "mizchi" | only "mizchi" (fixed) |
mutation.mode | string | "diff" | diff, full |
mutation.timeoutMs | integer | 120000 | > 0 |
pbt
| Setting | Type | Default | Allowed values |
|---|---|---|---|
pbt.numRuns | integer | 1000 | > 0, <= 1000000 |
pbt.seed | integer | unset |
formal
| Setting | Type | Default | Allowed values |
|---|---|---|---|
formal.backend | string | "z3" | z3, lean |
formal.integerDomain.min | string | "-10000" | matches ^-?\d+$ |
formal.integerDomain.max | string | "10000" | matches ^-?\d+$ |
formal.maxSolverMs | integer | 30000 | > 0 |
formal.maxArrayLength | integer | 3 | >= 1, <= 8 |
formal.rejectUnsupportedSemantics | boolean | true | only true (fixed) |
llm
| Setting | Type | Default | Allowed values |
|---|---|---|---|
llm.provider | string | "none" | none, claude, claude-code, openai, codex |
llm.model | string | unset | |
llm.maxTokensPerRun | integer | 200000 | >= 0 |
llm.allowCodexFileReads | boolean | false |
improvement
| Setting | Type | Default | Allowed values |
|---|---|---|---|
improvement.autoApply | boolean | false | only false (fixed) |
improvement.testFilesOnly | boolean | true | only true (fixed) |
improvement.maxIterations | integer | 3 | > 0, <= 20 |
improvement.maxPatchFiles | integer | 5 | > 0, <= 50 |
reports
| Setting | Type | Default | Allowed values |
|---|---|---|---|
reports.formats | array of string | ["json","markdown","html","sarif"] | text, json, markdown, html, sarif |
policy
| Setting | Type | Default | Allowed values |
|---|---|---|---|
policy.confirmedViolation | string | "fail" | fail, warn |
policy.inconclusiveBehavior | string | "warn" | fail, warn, ignore |
policy.maxNewSurvivors | integer | unset | >= 0 |
policy.minPropertyCoverage | number | unset | >= 0, <= 1 |
sandbox
| Setting | Type | Default | Allowed values |
|---|---|---|---|
sandbox.allowNetworkWithoutIsolation | boolean | false |
storage
| Setting | Type | Default | Allowed values |
|---|---|---|---|
storage.retainRuns | integer | 20 | > 0 |
storage.storePrompts | boolean | false | only false (fixed) |
cache
| Setting | Type | Default | Allowed values |
|---|---|---|---|
cache.enabled | boolean | true |
limits
| Setting | Type | Default | Allowed values |
|---|---|---|---|
limits.memoryMb | integer | 2048 | >= 256, <= 65536 |
主な設定の働き
| 設定 | 既定値 | 働き |
|---|---|---|
sources.web.enabled、sources.github.enabled | false | Web や GitHub から根拠を集めます。Web には allowDomains も必要です。GitHub は sources.github.repo(owner/name)を読みます。どちらも --offline では使いません |
sources.web.maxPages、maxDepth、maxChars、timeoutMs、maxDurationMs | 30、1、200000、30000、120000 | Web の収集の上限です。ページ数、リンクの深さ、残す文字数、1 ページの時間、全体の時間を指定します。時間内に取得できなかったページは skipped として報告します |
analysis.inferSpecsFromCode | true | コードから推測した Property の候補を提案します。false にすると、ドキュメントなどの出典だけから Property を作ります |
mutation.mode | diff | diff は --since を付けて使う前提のモードで、--since がなければ範囲内のすべての mutant を実行し、そのことをステージのメッセージに書きます。full はすべての mutant をメッセージなしで実行します。どちらのモードでも、--since を付ければ変更されたコードに絞ります |
formal.integerDomain | -10000 から 10000 | 形式検証で使う整数の範囲です。安全な整数の範囲内で指定します |
formal.maxSolverMs | 30000 | クエリ 1 件あたりのソルバーの制限時間です |
formal.maxArrayLength | 3 | 形式検証で扱う配列の最大の長さ(1〜8)です。これより長い配列は検証しません |
pbt.numRuns、pbt.seed | 1000、Property ごと | property-based テストの実行回数と seed です。seed を指定しなければ、Property の ID から決まる固定の seed を使うので、結果を再現できます |
llm.provider | none | 自由記述の文を読むのに使う LLM です。LLM プロバイダーを参照してください。llm.maxTokensPerRun は 1 回の実行で使うトークンの上限です |
policy.confirmedViolation | fail | fail では、確定した違反で終了コード 1 になります。warn では警告として報告します |
policy.inconclusiveBehavior | warn | fail では、判定できない結果で終了コード 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.allowNetworkWithoutIsolation | false | ネットワークを遮断できる Node.js 25 以上がなくても、プロジェクトのコードを実行します。指定しなければ、その結果は判定できないままです |
storage.retainRuns | 20 | .veritas/runs/ に残す、終わった実行の数です(今回の実行を含みます)。実行が終わるたびに、それより古い実行を削除します。実行中のものは削除しません |
cache.enabled | true | .veritas/cache/ の結果を再利用します(キャッシュを参照) |
limits.memoryMb | 2048 | プロジェクトのコード、プロジェクトのテスト、mutator、Z3 を実行するプロセスのメモリの上限(MiB、256 以上)です。Lean には上限をかけません。メモリが足りなくなると error になります |
判定できない結果とは、unknown、timeout、unsupported、semantic_mismatch、error の主張と、partial、skipped、unsupported、timeout、cancelled のステージのことです。
値が 1 つしかない設定
次の設定は規則を明示するためのもので、受け付ける値は 1 つだけです。ほかの値を書くと、不正な設定になります。
| 設定 | 受け付ける値 | 規則 |
|---|---|---|
analysis.requireApprovalForNormativeClaims | true | Property が accepted になるのは、判断を記録したときだけ |
improvement.testFilesOnly | true | improve はテストファイルを追加するだけで、本番のコードは編集しない |
improvement.autoApply | false | 計画の適用には --apply、計画 ID、承認トークンが必要 |
storage.storePrompts | false | LLM に送ったプロンプトは保存しない |
formal.rejectUnsupportedSemantics | true | 形式検証の対象外のコードは unsupported とし、近似では扱わない |
analysis.testFramework | vitest | 対応するテストランナーは Vitest |
mutation.backend | mizchi | mutation 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 にしてください(セキュリティモデルを参照)。