theirongolddev/gitlore
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
fe7d2109885a2c4fbccfacdbcdbd57eea4a35ae2
gitlore/docs/command-surface-analysis/09-appendices.md
teernisse 3f38b3fda7 docs: add comprehensive command surface analysis 
Deep analysis of the full `lore` CLI command surface (34 commands across
6 categories) covering command inventory, data flow, overlap analysis,
and optimization proposals.

Document structure:
- Main consolidated doc: docs/command-surface-analysis.md (1251 lines)
- Split sections in docs/command-surface-analysis/ for navigation:
  00-overview.md      - Summary, inventory, priorities
  01-entity-commands.md   - issues, mrs, notes, search, count
  02-intelligence-commands.md - who, timeline, me, file-history, trace, related, drift
  03-pipeline-and-infra.md    - sync, ingest, generate-docs, embed, diagnostics
  04-data-flow.md     - Shared data source map, command network graph
  05-overlap-analysis.md  - Quantified overlap percentages for every command pair
  06-agent-workflows.md   - Common agent flows, round-trip costs, token profiles
  07-consolidation-proposals.md  - 5 proposals to reduce 34 commands to 29
  08-robot-optimization-proposals.md - 6 proposals for --include, --batch, --depth
  09-appendices.md    - Robot output envelope, field presets, exit codes

Key findings:
- High overlap pairs: who-workload/me (~85%), health/doctor (~90%)
- 5 consolidation proposals to reduce command count by 15%
- 6 robot-mode optimization proposals targeting agent round-trip reduction
- Full DB table mapping and data flow documentation

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-28 00:08:31 -05:00

182 lines
6.2 KiB
Markdown
Raw Blame History

# Appendices
---
## A. Robot Output Envelope
All robot-mode responses follow this structure:
```json
{
"ok": true,
"data": { /* command-specific */ },
"meta": { "elapsed_ms": 42 }
}
```
Errors (to stderr):
```json
{
"error": {
"code": "CONFIG_NOT_FOUND",
"message": "Configuration file not found",
"suggestion": "Run 'lore init'",
"actions": ["lore init"]
}
}
```
The `actions` array contains copy-paste shell commands for automated recovery. Omitted when empty.
---
## B. Exit Codes
| Code | Meaning | Retryable |
|---|---|---|
| 0 | Success | N/A |
| 1 | Internal error / not implemented | Maybe |
| 2 | Usage error (invalid flags or arguments) | No (fix syntax) |
| 3 | Config invalid | No (fix config) |
| 4 | Token not set | No (set token) |
| 5 | GitLab auth failed | Maybe (token expired?) |
| 6 | Resource not found (HTTP 404) | No |
| 7 | Rate limited | Yes (wait) |
| 8 | Network error | Yes (retry) |
| 9 | Database locked | Yes (wait) |
| 10 | Database error | Maybe |
| 11 | Migration failed | No (investigate) |
| 12 | I/O error | Maybe |
| 13 | Transform error | No (bug) |
| 14 | Ollama unavailable | Yes (start Ollama) |
| 15 | Ollama model not found | No (pull model) |
| 16 | Embedding failed | Yes (retry) |
| 17 | Not found (entity does not exist) | No |
| 18 | Ambiguous match (use `-p` to specify project) | No (be specific) |
| 19 | Health check failed | Yes (fix issues first) |
| 20 | Config not found | No (run init) |
---
## C. Field Selection Presets
The `--fields` flag supports both presets and custom field lists:
```bash
lore -J issues --fields minimal # Preset
lore -J mrs --fields iid,title,state,draft # Custom comma-separated
```
| Command | Minimal Preset Fields |
|---|---|
| `issues` (list) | `iid`, `title`, `state`, `updated_at_iso` |
| `mrs` (list) | `iid`, `title`, `state`, `updated_at_iso` |
| `notes` (list) | `id`, `author_username`, `body`, `created_at_iso` |
| `search` | `document_id`, `title`, `source_type`, `score` |
| `timeline` | `timestamp`, `type`, `entity_iid`, `detail` |
| `who expert` | `username`, `score` |
| `who workload` | `iid`, `title`, `state` |
| `who reviews` | `name`, `count`, `percentage` |
| `who active` | `entity_type`, `iid`, `title`, `participants` |
| `who overlap` | `username`, `touch_count` |
| `me` (items) | `iid`, `title`, `attention_state`, `updated_at_iso` |
| `me` (activity) | `timestamp_iso`, `event_type`, `entity_iid`, `actor` |
---
## D. Configuration Precedence
1. CLI flags (highest priority)
2. Environment variables (`LORE_ROBOT`, `GITLAB_TOKEN`, `LORE_CONFIG_PATH`)
3. Config file (`~/.config/lore/config.json`)
4. Built-in defaults (lowest priority)
---
## E. Time Parsing
All commands accepting `--since`, `--until`, `--as-of` support:
| Format | Example | Meaning |
|---|---|---|
| Relative days | `7d` | 7 days ago |
| Relative weeks | `2w` | 2 weeks ago |
| Relative months | `1m`, `6m` | 1/6 months ago |
| Absolute date | `2026-01-15` | Specific date |
Internally converted to Unix milliseconds for DB queries.
---
## F. Database Schema (28 migrations)
### Primary Entity Tables
| Table | Key Columns | Notes |
|---|---|---|
| `projects` | `gitlab_project_id`, `path_with_namespace`, `web_url` | No `name` or `last_seen_at` |
| `issues` | `iid`, `title`, `state`, `author_username`, 5 status columns | Status columns nullable (migration 021) |
| `merge_requests` | `iid`, `title`, `state`, `draft`, `source_branch`, `target_branch` | `last_seen_at INTEGER NOT NULL` |
| `discussions` | `gitlab_discussion_id` (text), `issue_id`/`merge_request_id` | One FK must be set |
| `notes` | `gitlab_id`, `author_username`, `body`, DiffNote position columns | `type` column for DiffNote/DiscussionNote |
### Relationship Tables
| Table | Purpose |
|---|---|
| `issue_labels`, `mr_labels` | Label junction (DELETE+INSERT for stale removal) |
| `issue_assignees`, `mr_assignees` | Assignee junction |
| `mr_reviewers` | Reviewer junction |
| `entity_references` | Cross-refs: closes, mentioned, related (with `source_method`) |
| `mr_file_changes` | File diffs: old_path, new_path, change_type |
### Event Tables
| Table | Constraint |
|---|---|
| `resource_state_events` | CHECK: exactly one of issue_id/merge_request_id NOT NULL |
| `resource_label_events` | Same CHECK constraint; `label_name` nullable (migration 012) |
| `resource_milestone_events` | Same CHECK constraint; `milestone_title` nullable |
### Document/Search Pipeline
| Table | Purpose |
|---|---|
| `documents` | Unified searchable content (source_type: issue/merge_request/discussion) |
| `documents_fts` | FTS5 virtual table for text search |
| `documents_fts_docsize` | FTS5 shadow B-tree (19x faster for COUNT) |
| `document_labels` | Fast label filtering (indexed exact-match) |
| `document_paths` | File path association for DiffNote filtering |
| `embeddings` | vec0 virtual table; rowid = document_id * 1000 + chunk_index |
| `embedding_metadata` | Chunk provenance + staleness tracking (document_hash) |
| `dirty_sources` | Documents needing regeneration (with backoff via next_attempt_at) |
### Infrastructure
| Table | Purpose |
|---|---|
| `sync_runs` | Sync history with metrics |
| `sync_cursors` | Per-resource sync position (updated_at cursor + tie_breaker_id) |
| `app_locks` | Crash-safe single-flight lock |
| `raw_payloads` | Raw JSON storage for debugging |
| `pending_discussion_fetches` | Dependent discussion fetch queue |
| `pending_dependent_fetches` | Job queue for resource_events, mr_closes, mr_diffs |
| `schema_version` | Migration tracking |
---
## G. Glossary
| Term | Definition |
|---|---|
| **IID** | Issue/MR number within a project (not globally unique) |
| **FTS5** | SQLite full-text search extension (BM25 ranking) |
| **vec0** | SQLite extension for vector similarity search |
| **RRF** | Reciprocal Rank Fusion — combines FTS and vector rankings |
| **DiffNote** | Comment attached to a specific line in a merge request diff |
| **Entity reference** | Cross-reference between issues/MRs (closes, mentioned, related) |
| **Rename chain** | BFS traversal of mr_file_changes to follow file renames |
| **Attention state** | Computed field on `me` items: needs_attention, not_started, stale, etc. |
| **Surgical sync** | Fetching specific entities by IID instead of full incremental sync |
Reference in New Issue View Git Blame Copy Permalink