theirongolddev/gitlore
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: Remove redundant doc comments throughout codebase

Browse Source 
Removes module-level doc comments (//! lines) and excessive inline doc
comments that were duplicating information already evident from:
- Function/struct names (self-documenting code)
- Type signatures (the what is clear from types)
- Implementation context (the how is clear from code)

Affected modules:
- cli/* - Removed command descriptions duplicating clap help text
- core/* - Removed module headers and obvious function docs
- documents/* - Removed extractor/regenerator/truncation docs
- embedding/* - Removed pipeline and chunking docs
- gitlab/* - Removed client and transformer docs (kept type definitions)
- ingestion/* - Removed orchestrator and ingestion docs
- search/* - Removed FTS and vector search docs

Philosophy: Code should be self-documenting. Comments should explain
"why" (business decisions, non-obvious constraints) not "what" (which
the code itself shows). This change reduces noise and maintenance burden
while keeping the codebase just as understandable.

Retains comments for:
- Non-obvious business logic
- Important safety invariants
- Complex algorithm explanations
- Public API boundaries where generated docs matter

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Taylor Eernisse
2026-02-05 00:04:32 -05:00
parent 976ad92ef0
commit 65583ed5d6
57 changed files with 143 additions and 1693 deletions
Download Patch File Download Diff File Expand all files Collapse all files

114
src/cli/mod.rs
View File

@@ -1,41 +1,31 @@
//! CLI module with clap command definitions.
pub mod commands;
pub mod progress;
use clap::{Parser, Subcommand};
use std::io::IsTerminal;
/// Gitlore - Local GitLab data management with semantic search
#[derive(Parser)]
#[command(name = "lore")]
#[command(version, about, long_about = None)]
pub struct Cli {
/// Path to config file
#[arg(short = 'c', long, global = true)]
pub config: Option<String>,
/// Machine-readable JSON output (auto-enabled when piped)
#[arg(long, global = true, env = "LORE_ROBOT")]
pub robot: bool,
/// JSON output (global shorthand)
#[arg(short = 'J', long = "json", global = true)]
pub json: bool,
/// Color output: auto (default), always, or never
#[arg(long, global = true, value_parser = ["auto", "always", "never"], default_value = "auto")]
pub color: String,
/// Suppress non-essential output
#[arg(short = 'q', long, global = true)]
pub quiet: bool,
/// Increase log verbosity (-v, -vv, -vvv)
#[arg(short = 'v', long = "verbose", action = clap::ArgAction::Count, global = true)]
pub verbose: u8,
/// Log format for stderr output: text (default) or json
#[arg(long = "log-format", global = true, value_parser = ["text", "json"], default_value = "text")]
pub log_format: String,
@@ -44,7 +34,6 @@ pub struct Cli {
}
impl Cli {
/// Check if robot mode is active (explicit flag, env var, or non-TTY stdout)
pub fn is_robot_mode(&self) -> bool {
self.robot || self.json || !std::io::stdout().is_terminal()
}
@@ -53,104 +42,74 @@ impl Cli {
#[derive(Subcommand)]
#[allow(clippy::large_enum_variant)]
pub enum Commands {
/// List or show issues
Issues(IssuesArgs),
/// List or show merge requests
Mrs(MrsArgs),
/// Ingest data from GitLab
Ingest(IngestArgs),
/// Count entities in local database
Count(CountArgs),
/// Show sync state
Status,
/// Verify GitLab authentication
Auth,
/// Check environment health
Doctor,
/// Show version information
Version,
/// Initialize configuration and database
Init {
/// Skip overwrite confirmation
#[arg(short = 'f', long)]
force: bool,
/// Fail if prompts would be shown
#[arg(long)]
non_interactive: bool,
/// GitLab base URL (required in robot mode)
#[arg(long)]
gitlab_url: Option<String>,
/// Environment variable name holding GitLab token (required in robot mode)
#[arg(long)]
token_env_var: Option<String>,
/// Comma-separated project paths (required in robot mode)
#[arg(long)]
projects: Option<String>,
},
/// Create timestamped database backup
#[command(hide = true)]
Backup,
/// Delete database and reset all state
#[command(hide = true)]
Reset {
/// Skip confirmation prompt
#[arg(short = 'y', long)]
yes: bool,
},
/// Search indexed documents
Search(SearchArgs),
/// Show document and index statistics
Stats(StatsArgs),
/// Generate searchable documents from ingested data
#[command(name = "generate-docs")]
GenerateDocs(GenerateDocsArgs),
/// Generate vector embeddings for documents via Ollama
Embed(EmbedArgs),
/// Run full sync pipeline: ingest -> generate-docs -> embed
Sync(SyncArgs),
/// Run pending database migrations
Migrate,
/// Quick health check: config, database, schema version
Health,
/// Machine-readable command manifest for agent self-discovery
#[command(name = "robot-docs")]
RobotDocs,
/// Generate shell completions
#[command(hide = true)]
Completions {
/// Shell to generate completions for
#[arg(value_parser = ["bash", "zsh", "fish", "powershell"])]
shell: String,
},
// --- Hidden backward-compat aliases ---
/// List issues or MRs (deprecated: use 'lore issues' or 'lore mrs')
#[command(hide = true)]
List {
/// Entity type to list
#[arg(value_parser = ["issues", "mrs"])]
entity: String,
@@ -192,36 +151,28 @@ pub enum Commands {
source_branch: Option<String>,
},
/// Show detailed entity information (deprecated: use 'lore issues <IID>' or 'lore mrs <IID>')
#[command(hide = true)]
Show {
/// Entity type to show
#[arg(value_parser = ["issue", "mr"])]
entity: String,
/// Entity IID
iid: i64,
#[arg(long)]
project: Option<String>,
},
/// Verify GitLab authentication (deprecated: use 'lore auth')
#[command(hide = true, name = "auth-test")]
AuthTest,
/// Show sync state (deprecated: use 'lore status')
#[command(hide = true, name = "sync-status")]
SyncStatus,
}
/// Arguments for `lore issues [IID]`
#[derive(Parser)]
pub struct IssuesArgs {
/// Issue IID (omit to list, provide to show details)
pub iid: Option<i64>,
/// Maximum results
#[arg(
short = 'n',
long = "limit",
@@ -230,39 +181,30 @@ pub struct IssuesArgs {
)]
pub limit: usize,
/// Filter by state (opened, closed, all)
#[arg(short = 's', long, help_heading = "Filters")]
pub state: Option<String>,
/// Filter by project path
#[arg(short = 'p', long, help_heading = "Filters")]
pub project: Option<String>,
/// Filter by author username
#[arg(short = 'a', long, help_heading = "Filters")]
pub author: Option<String>,
/// Filter by assignee username
#[arg(short = 'A', long, help_heading = "Filters")]
pub assignee: Option<String>,
/// Filter by label (repeatable, AND logic)
#[arg(short = 'l', long, help_heading = "Filters")]
pub label: Option<Vec<String>>,
/// Filter by milestone title
#[arg(short = 'm', long, help_heading = "Filters")]
pub milestone: Option<String>,
/// Filter by time (7d, 2w, 1m, or YYYY-MM-DD)
#[arg(long, help_heading = "Filters")]
pub since: Option<String>,
/// Filter by due date (before this date, YYYY-MM-DD)
#[arg(long = "due-before", help_heading = "Filters")]
pub due_before: Option<String>,
/// Show only issues with a due date
#[arg(
long = "has-due",
help_heading = "Filters",
@@ -273,18 +215,15 @@ pub struct IssuesArgs {
#[arg(long = "no-has-due", hide = true, overrides_with = "has_due")]
pub no_has_due: bool,
/// Sort field (updated, created, iid)
#[arg(long, value_parser = ["updated", "created", "iid"], default_value = "updated", help_heading = "Sorting")]
pub sort: String,
/// Sort ascending (default: descending)
#[arg(long, help_heading = "Sorting", overrides_with = "no_asc")]
pub asc: bool,
#[arg(long = "no-asc", hide = true, overrides_with = "asc")]
pub no_asc: bool,
/// Open first matching item in browser
#[arg(
short = 'o',
long,
@@ -297,13 +236,10 @@ pub struct IssuesArgs {
pub no_open: bool,
}
/// Arguments for `lore mrs [IID]`
#[derive(Parser)]
pub struct MrsArgs {
/// MR IID (omit to list, provide to show details)
pub iid: Option<i64>,
/// Maximum results
#[arg(
short = 'n',
long = "limit",
@@ -312,35 +248,27 @@ pub struct MrsArgs {
)]
pub limit: usize,
/// Filter by state (opened, merged, closed, locked, all)
#[arg(short = 's', long, help_heading = "Filters")]
pub state: Option<String>,
/// Filter by project path
#[arg(short = 'p', long, help_heading = "Filters")]
pub project: Option<String>,
/// Filter by author username
#[arg(short = 'a', long, help_heading = "Filters")]
pub author: Option<String>,
/// Filter by assignee username
#[arg(short = 'A', long, help_heading = "Filters")]
pub assignee: Option<String>,
/// Filter by reviewer username
#[arg(short = 'r', long, help_heading = "Filters")]
pub reviewer: Option<String>,
/// Filter by label (repeatable, AND logic)
#[arg(short = 'l', long, help_heading = "Filters")]
pub label: Option<Vec<String>>,
/// Filter by time (7d, 2w, 1m, or YYYY-MM-DD)
#[arg(long, help_heading = "Filters")]
pub since: Option<String>,
/// Show only draft MRs
#[arg(
short = 'd',
long,
@@ -349,7 +277,6 @@ pub struct MrsArgs {
)]
pub draft: bool,
/// Exclude draft MRs
#[arg(
short = 'D',
long = "no-draft",
@@ -358,26 +285,21 @@ pub struct MrsArgs {
)]
pub no_draft: bool,
/// Filter by target branch
#[arg(long, help_heading = "Filters")]
pub target: Option<String>,
/// Filter by source branch
#[arg(long, help_heading = "Filters")]
pub source: Option<String>,
/// Sort field (updated, created, iid)
#[arg(long, value_parser = ["updated", "created", "iid"], default_value = "updated", help_heading = "Sorting")]
pub sort: String,
/// Sort ascending (default: descending)
#[arg(long, help_heading = "Sorting", overrides_with = "no_asc")]
pub asc: bool,
#[arg(long = "no-asc", hide = true, overrides_with = "asc")]
pub no_asc: bool,
/// Open first matching item in browser
#[arg(
short = 'o',
long,
@@ -390,25 +312,20 @@ pub struct MrsArgs {
pub no_open: bool,
}
/// Arguments for `lore ingest [ENTITY]`
#[derive(Parser)]
pub struct IngestArgs {
/// Entity to ingest (issues, mrs). Omit to ingest everything.
#[arg(value_parser = ["issues", "mrs"])]
pub entity: Option<String>,
/// Filter to single project
#[arg(short = 'p', long)]
pub project: Option<String>,
/// Override stale sync lock
#[arg(short = 'f', long, overrides_with = "no_force")]
pub force: bool,
#[arg(long = "no-force", hide = true, overrides_with = "force")]
pub no_force: bool,
/// Full re-sync: reset cursors and fetch all data from scratch
#[arg(long, overrides_with = "no_full")]
pub full: bool,
@@ -416,60 +333,46 @@ pub struct IngestArgs {
pub no_full: bool,
}
/// Arguments for `lore stats`
#[derive(Parser)]
pub struct StatsArgs {
/// Run integrity checks
#[arg(long, overrides_with = "no_check")]
pub check: bool,
#[arg(long = "no-check", hide = true, overrides_with = "check")]
pub no_check: bool,
/// Repair integrity issues (auto-enables --check)
#[arg(long)]
pub repair: bool,
}
/// Arguments for `lore search <QUERY>`
#[derive(Parser)]
pub struct SearchArgs {
/// Search query string
pub query: String,
/// Search mode (lexical, hybrid, semantic)
#[arg(long, default_value = "hybrid", value_parser = ["lexical", "hybrid", "semantic"], help_heading = "Output")]
pub mode: String,
/// Filter by source type (issue, mr, discussion)
#[arg(long = "type", value_name = "TYPE", value_parser = ["issue", "mr", "discussion"], help_heading = "Filters")]
pub source_type: Option<String>,
/// Filter by author username
#[arg(long, help_heading = "Filters")]
pub author: Option<String>,
/// Filter by project path
#[arg(short = 'p', long, help_heading = "Filters")]
pub project: Option<String>,
/// Filter by label (repeatable, AND logic)
#[arg(long, action = clap::ArgAction::Append, help_heading = "Filters")]
pub label: Vec<String>,
/// Filter by file path (trailing / for prefix match)
#[arg(long, help_heading = "Filters")]
pub path: Option<String>,
/// Filter by created after (7d, 2w, or YYYY-MM-DD)
#[arg(long, help_heading = "Filters")]
pub after: Option<String>,
/// Filter by updated after (7d, 2w, or YYYY-MM-DD)
#[arg(long = "updated-after", help_heading = "Filters")]
pub updated_after: Option<String>,
/// Maximum results (default 20, max 100)
#[arg(
short = 'n',
long = "limit",
@@ -478,71 +381,57 @@ pub struct SearchArgs {
)]
pub limit: usize,
/// Show ranking explanation per result
#[arg(long, help_heading = "Output", overrides_with = "no_explain")]
pub explain: bool,
#[arg(long = "no-explain", hide = true, overrides_with = "explain")]
pub no_explain: bool,
/// FTS query mode: safe (default) or raw
#[arg(long = "fts-mode", default_value = "safe", value_parser = ["safe", "raw"], help_heading = "Output")]
pub fts_mode: String,
}
/// Arguments for `lore generate-docs`
#[derive(Parser)]
pub struct GenerateDocsArgs {
/// Full rebuild: seed all entities into dirty queue, then drain
#[arg(long)]
pub full: bool,
/// Filter to single project
#[arg(short = 'p', long)]
pub project: Option<String>,
}
/// Arguments for `lore sync`
#[derive(Parser)]
pub struct SyncArgs {
/// Reset cursors, fetch everything
#[arg(long, overrides_with = "no_full")]
pub full: bool,
#[arg(long = "no-full", hide = true, overrides_with = "full")]
pub no_full: bool,
/// Override stale lock
#[arg(long, overrides_with = "no_force")]
pub force: bool,
#[arg(long = "no-force", hide = true, overrides_with = "force")]
pub no_force: bool,
/// Skip embedding step
#[arg(long)]
pub no_embed: bool,
/// Skip document regeneration
#[arg(long)]
pub no_docs: bool,
/// Skip resource event fetching (overrides config)
#[arg(long = "no-events")]
pub no_events: bool,
}
/// Arguments for `lore embed`
#[derive(Parser)]
pub struct EmbedArgs {
/// Re-embed all documents (clears existing embeddings first)
#[arg(long, overrides_with = "no_full")]
pub full: bool,
#[arg(long = "no-full", hide = true, overrides_with = "full")]
pub no_full: bool,
/// Retry previously failed embeddings
#[arg(long, overrides_with = "no_retry_failed")]
pub retry_failed: bool,
@@ -550,14 +439,11 @@ pub struct EmbedArgs {
pub no_retry_failed: bool,
}
/// Arguments for `lore count <ENTITY>`
#[derive(Parser)]
pub struct CountArgs {
/// Entity type to count (issues, mrs, discussions, notes, events)
#[arg(value_parser = ["issues", "mrs", "discussions", "notes", "events"])]
pub entity: String,
/// Parent type filter: issue or mr (for discussions/notes)
#[arg(short = 'f', long = "for", value_parser = ["issue", "mr"])]
pub for_entity: Option<String>,
}