Struct Options 

pub struct Options {

    pub repo_path: PathBuf,
    pub after: Option<Date>,
    pub before: Option<Date>,
    pub group_file: Option<PathBuf>,
    pub team_map_file: Option<PathBuf>,
    pub min_revs: u32,
    pub min_shared_revs: u32,
    pub min_coupling_pct: u8,
    pub max_coupling_pct: u8,
    pub max_changeset_size: u32,
    pub fisher_significance: f64,
    pub message_regex: Option<String>,
    pub age_time_now: Option<Date>,
    pub rows_limit: Option<u32>,
    pub include_merges: bool,
    pub strict_grouping: bool,
    pub complexity_sample: ComplexitySample,
    pub explain: bool,
    pub use_canonical_lineage: bool,
    pub min_clone_node_count: u32,
    pub exclude_patterns: Vec<String>,
    pub include_ignored: bool,
    pub departed_threshold_days: u32,
    pub min_clone_shared_revs: u32,
    pub clone_similarity_floor: f64,
    pub clone_skip_same_dir: bool,
    pub min_soc: Option<u32>,
    pub time_bucket: Option<TimeBucket>,
    pub code_maat_compat: bool,
    pub fdr_correction: bool,
    pub window_days: u32,
    pub knowledge_model: String,
    pub rework_window_days: u32,
    pub release_tag_glob: String,
    pub target: Option<String>,
    pub calibration: Option<PathBuf>,
    pub defect_calibration: Option<PathBuf>,
    pub allow_foreign_calibration: bool,
    pub head_only_ingest: bool,
    pub temp_dir: Option<PathBuf>,
}

Fields

repo_path: PathBuf

after: Option<Date>

before: Option<Date>

group_file: Option<PathBuf>

team_map_file: Option<PathBuf>

min_revs: u32

min_shared_revs: u32

min_coupling_pct: u8

max_coupling_pct: u8

max_changeset_size: u32

fisher_significance: f64

message_regex: Option<String>

age_time_now: Option<Date>

rows_limit: Option<u32>

include_merges: bool

strict_grouping: bool

complexity_sample: ComplexitySample

explain: bool

Print the DuckDB query plan + raw SQL to stderr before running the analysis. Set via --explain. Cosmetic — not part of the canonical cache key.

use_canonical_lineage: bool

When true (default), aggregations follow file renames through changes.rename_from. A file’s pre-rename history is merged onto its current canonical path. When false, every commit’s path is treated literally — matches code-maat’s historic behaviour (it uses --no-renames). --code-maat-compat implies use_canonical_lineage = false for bit-for-bit parity.

min_clone_node_count: u32

exclude_patterns: Vec<String>

include_ignored: bool

When false (default), paths_filter::PathsFilter auto-respects .gitignore, .git/info/exclude, and .codeloreignore at the repo root so vendored deps (node_modules), build outputs (target, dist), lockfiles, locales, etc. don’t show up in hotspots or skew Kamei features. Set to true (via --include-ignored) to analyse everything regardless of those files.

departed_threshold_days: u32

Knowledge-islands: an author is considered “departed” if their most recent commit anywhere in the repo is older than this many days at the anchor moment. Default 90. See constants::DEFAULT_DEPARTED_THRESHOLD_DAYS for the rationale on this default.

min_clone_shared_revs: u32

Minimum shared_revs for a clone pair to count as “live”. Below this floor the Fisher test is unreliable (small contingency-table cells). Default 3.

clone_similarity_floor: f64

Minimum similarity for a clone pair to enter the coupling intersection. SourcererCC’s BCB benchmark found precision/recall optimum at 0.70. Default 0.70. Type 1 + Type 2 always = 1.0 today; this matters once Type 3 (MinHash) lands.

clone_skip_same_dir: bool

Skip clone pairs whose two files share the same parent directory (intentional structural mirroring like foo_test.rs ↔ foo.rs). Default true.

min_soc: Option<u32>

SoC threshold for the soc analysis. None = drop solo commits (default 1). Modern replacement for code-maat’s overloaded use of --min-revs to mean “minimum SoC sum” in this one analysis.

time_bucket: Option<TimeBucket>

Time-bucket granularity for coupling-family analyses. None = raw commit grain (no bucketing). When set, coupling and friends aggregate changes by the bucket-truncated date.

code_maat_compat: bool

Migration-helper flag. When true, flips internal defaults to match legacy code-maat output bit-for-bit (lying column headers, arbitrary tiebreaks, etc.). Off by default — the modern surface is the recommendation; this flag exists so users with dashboards parsing code-maat CSV verbatim aren’t broken on day one of migration.

fdr_correction: bool

Apply a Benjamini-Hochberg false-discovery-rate correction across the whole family of Fisher-tested coupling pairs instead of the per-pair fisher_p < fisher_significance gate. Off by default — the per-test gate is unchanged. --code-maat-compat still bypasses both gates.

window_days: u32

Trailing window in days for activity-scoped analyses. Anchored to the repo’s last commit date (not wall-clock time) so results are reproducible on old or archived repos. Valid range: 1–3650. Default: 90. Set via --window-days.

knowledge_model: String

Knowledge model for bus-factor. Valid values: "commits" (default, Filatov 2010 — greedy coverage of ≥80% of commits) or "doe" (Cury & Avelino SBES’24 truck-factor procedure — greedy removal of the author with the most expert files until >50% of files lack an expert). Set via --knowledge-model.

rework_window_days: u32

Hunk-overlap window for rework detection in delivery-metrics. Pairs of hunks touching the same path where the second commit’s author-date falls within this many days of the first are counted as rework candidates. Valid range: 1–365. Default: 21. Set via --rework-window-days.

release_tag_glob: String

Glob pattern for filtering release tags in release-cadence. Only tags whose short name matches this glob are included. Must be non-empty. Default: "v*". Set via --release-tag-glob.

target: Option<String>

Target file path for analyses that operate on a single file. Currently used only by function-xray. Set via --target. Validation that the value is present when required lives in the dispatch arm, not Options::validate, to avoid cross-analysis coupling.

calibration: Option<PathBuf>

Corpus-calibration artifact for the code-health corpus-percentile lens. Some(path) overrides the embedded world artifact with a hand-built or org-specific one; None falls back to the embedded artifact (or no lens when that is a placeholder). A per-invocation selector that never affects ingest, so canonical_json drops it from the cache key and instead hashes its content into calibration_digest for provenance. Set via --calibration.

defect_calibration: Option<PathBuf>

Own-repo defect-calibration artifact (defects.calib.json, built with codelore calibrate-defects) whose smell weights replace the built-in code-health defaults for this run. Like calibration, a per-invocation selector that never affects ingest: canonical_json drops the path and hashes the file content into defect_calibration_digest. Set via --defect-calibration.

allow_foreign_calibration: bool

Skip the repo-identity guard when deliberately applying a defect-calibration artifact whose root-commit identity does not match this repository — e.g. reusing one repository’s calibration on a genuinely different repo, or a shallow / non-git checkout whose root commit is unreachable (so the identity falls back to the path and no longer matches). Set via --allow-foreign-calibration.

head_only_ingest: bool

Internal ingest mode used by codelore calibrate: populate only the HEAD-time complexity and import facts (entities, complexity_metrics, imports) and leave every history table (commits, changes, hunks, …) empty. The full commit-history walk — and the kamei/clones passes it feeds — is skipped entirely; this also lets calibrate ingest shallow (depth-1) checkouts, which the commit walker cannot traverse. Not exposed as a CLI flag. Serialized like every other field, so canonical_json keys head-only cache entries apart from full ones.

temp_dir: Option<PathBuf>

Override the DuckDB spill directory (the temp_directory PRAGMA target used once a query exceeds the internal memory ceiling — see constants::DEFAULT_DUCKDB_MEMORY_LIMIT). When None, facts::FactsDb defaults to a subdirectory of the cache root, or the system temp directory when there is no cache root in play (e.g. --no-cache). An environment/spill selector — it changes where DuckDB writes scratch files, never any row an analysis reads, so canonical_json drops it from the cache key like target and rows_limit. Set via --temp-dir; validated as an existing writable directory in Options::validate.

Implementations

impl Options

pub fn canonical_json(&self) -> Value

Stable JSON-serialized snapshot of the full struct, used for cache keying and provenance manifest recording.

Adding a new field to Options automatically propagates to BOTH the cache key and the provenance manifest with zero per-field maintenance — fixes a historical drift where new fields silently weren’t hashed.

Normalizations applied to keep the canonical form stable:

• exclude_patterns is sorted (insertion order from CLI flags vs. .codeloreignore parsing doesn’t perturb the form).
• rows_limit is dropped (cosmetic — affects only output truncation, not the underlying data; setting --rows 10 on a cached analysis should still hit the cache).

Panics

Panics only if Options ever gains a field whose type does not implement Serialize. Caught at compile time via the derive on the struct; this panic is unreachable in well-formed code.

pub fn with_no_row_limit(&self) -> Self

Clone with rows_limit = None. Use this WHENEVER a composite analysis invokes another analysis as an internal step (e.g. code-health and clone-coupling both invoke run_coupling to materialize the global coupling graph). Without this wrapper, --rows 10 flows into the inner SQL’s LIMIT ?, the inner result truncates to the top 10 pairs, and the composite result is computed over that arbitrary subset — e.g. coupling-centrality scores end up counting partners from a 10-pair sliver of the full graph. Worse: canonical_json deliberately drops rows_limit from the cache key (because the user-visible row-cap is cosmetic), so the corrupted result gets cached under the no-row-limit cache key and poisons subsequent runs.

pub fn for_clone_coupling_inner_coupling(&self) -> Self

Like with_no_row_limit, but also lowers min_shared_revs to at most min_clone_shared_revs. Used by clone-coupling’s internal call to run_coupling.

Without this override, the inner coupling call applies the default min_shared_revs = 5 even though clone-coupling’s own floor is min_clone_shared_revs = 3. Clone pairs that co-changed exactly 3 or 4 times were silently dropped by the inner call — clone-coupling then filtered the (already trimmed) result by min_clone_shared_revs, but the missing pairs were already gone.

The min-of-both semantics is the safer choice: if a user explicitly LOWERED --min-shared-revs below min-clone-shared-revs, honour that; if they didn’t, drop the floor to the clone-coupling threshold so we don’t lose anything.

pub fn validate(&self) -> Result<()>

Check cross-field invariants. Caller (typically the CLI boundary) runs this once after constructing Options so pathological flag combinations fail loudly instead of silently producing empty output. Each invariant catches a real footgun from the CLI surface.

Errors

Returns crate::CodeLoreError::InvalidOptions (exit-2 configuration-error category) with a message naming the offending field pair.

Trait Implementations

impl Clone for Options

fn clone(&self) -> Options

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Options

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Options

fn default() -> Self

Returns the “default value” for a type.

impl Serialize for Options

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.