codasaurus-toml.md

.codasaurus.toml schema

Place .codasaurus.toml at the repo root (or set CODASAURUS_CONFIG). Dashboard DB settings overlay this file for detector toggles and policy. Per-repo config_json from the UI can further override.

Full example

[checks]
hallucinated_imports = true
phantom_deps = true
lockfile_drift = true
license_drift = true
vulnerabilities = true
secrets = true
over_engineering = true
boilerplate = true
stale_api = true
risky_patterns = true
todo_leaks = true
guidelines = true
graph = true
iac = true
exclude_patterns = ["vendor/", "dist/", "*.lock", "node_modules/"]

[behavior]
# CLI: non-zero exit on findings. Also maps to review_strictness=strict when unset.
strict = false
# Review personality: lenient | balanced | strict | nitpick
review_strictness = "balanced"

[registry]
cache_ttl_secs = 3600

[guidelines]
# Optional path relative to repo root (else auto-discovers CONTRIBUTING.md / AGENTS.md / …)
# contributing_guidelines = "docs/CONTRIBUTING.md"

[pre_merge]
# Both emit a blocking `policy` finding on the review when violated.
require_description = false          # PR body must not be empty
require_title_convention = false     # PR title must be `type(scope): subject`
max_blocking = 0
max_warnings = 20

# Optional natural-language pre-merge checks. Each runs the LLM against the
# PR diff. mode: off | warning | error (error + failed blocks merge).
# scope: optional glob filter over changed paths (tests/** or *.rs).
# Requires an LLM; disabled when offline_mode is on.
# [[pre_merge.checks]]
# name = "No secrets in tests"
# mode = "error"
# scope = "tests/**"
# instructions = "Fail if any test file contains hardcoded credentials or API keys."

[quality_gate]
name = "codasaurus way"
block_on_fail = true

[[quality_gate.conditions]]
metric = "new_blocker_issues"
op = "gt"
threshold = 0.0

[[quality_gate.conditions]]
metric = "new_high_issues"
op = "gt"
threshold = 0.0

[[quality_gate.conditions]]
metric = "new_medium_issues"
op = "gt"
threshold = 5.0

[confidence]
judge_tier1 = false
drop_ungrounded = false

[index]
languages = ["rust", "go", "python", "javascript", "typescript"]
max_files = 50000
# Semantic (pgvector) grounding. Every accepted neighbour costs prompt tokens.
# Out-of-range values are clamped rather than rejected, so a typo degrades
# the feature instead of breaking the review.
semantic_distance_threshold = 0.5   # max cosine distance; lower = stricter (clamped to 0.0-2.0)
semantic_max_query_symbols = 100    # cap on changed symbols embedded per query (clamped to 1-1000)
embedding_batch_size = 100          # symbols per embedding request (clamped to 1-2048)

[reachability]
enabled = true

[readiness]
enabled = true
require_approvals = 1
block_on_blockers = true

[learning]
# Dismissals mine candidate rules; approve them with @codasaurus approve-rule <id>.
auto_approve_rules = false
# Distinct PRs, within the same repo, that must dismiss a detector before its
# rule auto-promotes. Floored at 1: a 0 would promote every first dismissal.
min_dismissals_for_rule = 3
# Extra detectors treated as security-class, on top of the built-in set.
# Additive only: config can harden the default, never weaken it.
security_detectors = []
# Comment phrases mined from PR review. Empty uses the built-in sets.
false_positive_hints = []
pushback_hints = []

Sections

Section	Purpose
[checks]	Enable/disable Tier-1 detectors; exclude_patterns globs
[behavior]	strict, review_strictness
[registry]	Package registry / OSV cache TTL
[guidelines]	Contribution guideline path override
[pre_merge]	Soft caps used as defaults before DB policy overlay
[quality_gate]	Sonar-style gate on new findings; failed gate blocks the check run when block_on_fail
[confidence]	Per-finding confidence 0-5: optional LLM judge + grounding filter
[index]	Whole-repo symbol index: enabled, languages, max_files; semantic-grounding distance/batch limits
[reachability]	OSV reachability: upgrade import-hit vulns to OSV severity, tag manifest-only as info
[readiness]	Merge-readiness score 0-5: hard blockers zero it, soft signals weight it
[learning]	Dismissal → rule mining: approval gate, threshold, security-detector floor, mined comment phrases

review_strictness

Value	Effect
lenient	Raise floor toward warning; hide info; fewer warnings surfaced
balanced	Use default_severity + default signal budgets
strict	Surface more warnings; thorough LLM tone
nitpick	Force info floor; wider info/warning budgets; nitpick LLM tone

Dashboard Settings → Review → Tone & thresholds overrides TOML when set. Repo config_json.policy.review_strictness overrides both.

quality_gate

Sonar-style gate evaluated against findings on new code lines. Any failed condition fails the gate; when block_on_fail = true the Codasaurus check run concludes action_required. Findings on pre-existing lines are baseline-suppressed (recorded once, then hidden) and do not count toward the gate.

Metric	Counts
new_issues	All new-code findings
new_blocker_issues	Severity blocking
new_high_issues	Severity blocking (taxonomy has no high; maps to blocking)
new_medium_issues	Severity warning
new_warning_issues	Severity warning
new_info_issues	Severity info

Operators: gt, gte, lt, lte, eq, ne.

confidence

Every finding carries a confidence score 0-5. Tier-1 detectors (registry, manifest, secrets, IaC) get a base 5; heuristic detectors (style, stale APIs, guidelines, graph) get a base 3; LLM-authored prose findings default to 4.

Key	Default	Effect
judge_tier1	false	Also run the LLM judge on deterministic tier-1 findings
drop_ungrounded	false	Drop findings with confidence <= 1 (after judge)

When a BYOK LLM is configured and enabled for the repo, the judge scores heuristic findings and stores confidence + judge_rationale. The judge is best-effort: LLM failure keeps base confidence and never fails the review.

Repo config_json (dashboard)

{
    "detectors": { "secrets": true, "graph": false },
    "llm_enabled": true,
    "auto_describe": true,
    "auto_review_diff": false,
    "allow_auto_fix": false,
    "pr_title_fix": "off",
    "exclude_patterns": ["vendor/"],
    "policy": {
        "min_severity": "warning",
        "max_warnings": 20,
        "max_blocking": 0,
        "forbidden_paths": ["secrets/"],
        "request_reviewers": true,
        "create_check_run": true,
        "review_strictness": "strict"
    },
    "quality_gate": {
        "name": "release",
        "block_on_fail": true,
        "conditions": [
            { "metric": "new_blocker_issues", "op": "gt", "threshold": 0 },
            { "metric": "new_medium_issues", "op": "gt", "threshold": 2 }
        ]
    }
}

See also: configuration.md, commands.md.