Module first_run 

First-run auto-scan behavior for bugbot (PM-34).

When bugbot detects no prior state (.bugbot/state.db does not exist), it automatically runs a lightweight scan to establish baselines. This scan builds:

• Project call graph (cached for daemon)
• Per-file complexity and maintainability baselines
• Clone fragment index
• Temporal pattern database

Budget: <10s for a 50K LOC project (one-time cost). Runs ONCE, transparently, on first bugbot check invocation.

Baseline Policy

For files with no git history (new project, or new files in a monorepo), delta engines treat the “before” as empty:

• All current smells, clones, and complexity are “new” (reported)
• All current contracts are the baseline (no regression possible)
• Guard-removed and contract-regression produce no findings (no prior state)

Progress Indication

Prints "Building initial baselines... (one-time, ~8s)" so users understand why the first run is slow.

Structs

BaselineCallGraphMeta

Metadata for a cached baseline call graph.

BugbotState

Persisted state for bugbot across runs.

FirstRunResult

Result of a first-run baseline scan.

Enums

FirstRunStatus

Result of checking whether this is a first run.

Functions

bugbot_dir

Returns the path to the .bugbot/ directory for a given project root.

create_state_db

Create the .bugbot/ directory and write the initial state.db file.

detect_first_run

Detect whether this is a first run by checking for .bugbot/state.db.

load_cached_baseline_call_graph

Load a cached baseline call graph if the cache exists and was built from the expected commit.

resolve_git_ref

Resolve a git ref (e.g. “HEAD”, “main”, “origin/main”) to a full commit hash.

run_first_run_scan

Run the first-run baseline scan.

save_baseline_call_graph

Save a baseline call graph to .bugbot/baseline_call_graph.json.

state_db_path

Returns the path to the state database file for a given project root.