docs: impact depth guidance + full docs-vs-code audit fixes - #517
Merged
Conversation
* feat: self-update command + background update notification (#508) Add command for self-updating the binary: - — check + interactive [y/N] prompt - — auto-confirm (CI/automation) - — check only, no download Background startup notification: - Non-blocking check on every command run (cached 24h) - Cache stored at ~/.codecora/cora-code/update-cache.json - Disable via config: update_check: false - Disable via env: CORA_NO_UPDATE_CHECK=1 Implementation: - GitHub 302 redirect parsing (no API rate limit) - SHA256 checksum verification - Binary smoke-test post-download - Atomic rename for safe replacement - Version normalization (strip 'v' prefix) Closes #508 * style: cargo fmt --------- Co-authored-by: ajianaz <ajianaz@users.noreply.github.com>
- Add context line filter: drop Minor/Info findings on unchanged diff lines (pre-existing code flagged as new issue) - Enhanced system prompt: in-place mutation awareness (Vec::retain etc.) and error path vs happy path distinction - Import Severity type for filter comparison Co-authored-by: ajianaz <ajianaz@users.noreply.github.com>
… (#512) - cora_dir() now returns ~/.codecora/cora-code/ (was ~/.cora/) - cache_dir() now returns ~/.codecora/cora-code/cache/reviews/ (was ~/.cache/cora/reviews/) - Auto-migration from legacy paths on first run (config.yaml, auth.toml, cache files) - Migration is idempotent (.migrated-to-codecora marker) - Old files preserved (copy, not move) for user safety - Updated all user-facing strings and doc comments Co-authored-by: ajianaz <ajianaz@users.noreply.github.com>
- Replace MIT with Apache-2.0 (patent grant + retaliation clause) - Add CLA_INDIVIDUAL.md and CLA_CORPORATE.md (v1.1) - Update CONTRIBUTING.md with Contribution Terms callout at top - Update README badge MIT to Apache-2.0 - Update AGENT.md license references - Add [Unreleased] entry to CHANGELOG.md CLA v1.1 key provisions: - Contributor retains copyright, grants license (not assignment) - CodeCoraDev may sublicense under proprietary/commercial terms - SIAC arbitration (Singapore seat), Indonesian substantive law - CodeCoraDev definition covers successors/assigns/affiliates - Signed-off-by required on all commits Signed-off-by: ajianaz <ajianaz@users.noreply.github.com> Co-authored-by: ajianaz <ajianaz@users.noreply.github.com>
* ci(cla): add CLA check workflow Calls org-level reusable workflow from codecoradev/.github. Every PR will now be checked for CLA signature. Signed-off-by: ajianaz <ajianaz@users.noreply.github.com> * ci: re-trigger CLA check (org workflow now merged) Signed-off-by: ajianaz <ajianaz@users.noreply.github.com> * fix(ci): add permissions to CLA check caller workflow Reusable workflow needs explicit permissions grant from caller. Without it, GitHub Actions silently fails (0s, no log). Signed-off-by: ajianaz <ajianaz@users.noreply.github.com> * fix(ci): inline CLA check workflow (drop reusable dependency) Reusable workflow path with .github repo caused YAML validation failure (0s, no jobs). Switching to self-contained inline workflow that fetches signatures.json from org repo via raw.githubusercontent. Signed-off-by: ajianaz <ajianaz@users.noreply.github.com> * ci: re-trigger CLA check (CDN cache cleared) Signed-off-by: ajianaz <ajianaz@users.noreply.github.com> * fix(ci): use GitHub API for signatures (raw CDN unreliable) raw.githubusercontent.com returns HTTP 200 with '404: Not Found' body instead of proper HTTP 404, breaking curl -f flag. Switching to gh api which properly resolves content via GitHub REST API. Signed-off-by: ajianaz <ajianaz@users.noreply.github.com> * fix(ci): use public REST API for signatures fetch GITHUB_TOKEN is repo-scoped — cannot access codecoradev/.github. Switching to unauthenticated public REST API endpoint (60 req/hr limit is fine for PR-triggered workflow). Signed-off-by: ajianaz <ajianaz@users.noreply.github.com> * fix(ci): use actions/checkout for signatures fetch All CDN/API approaches failed for cross-repo access: - raw.githubusercontent: CDN cache returns 404 body with HTTP 200 - api.github.com: rate limited unauthenticated, GITHUB_TOKEN 404 cross-repo - jsdelivr: too slow for freshly pushed content actions/checkout with sparse-checkout is bulletproof: uses git protocol to clone .cla/ folder from codecoradev/.github directly. Signed-off-by: ajianaz <ajianaz@users.noreply.github.com> * fix(ci): use unauthenticated git clone for signatures GITHUB_TOKEN cannot access codecoradev/.github (repo-scoped). Switching to plain git clone over HTTPS — repo is public, no auth needed. Signed-off-by: ajianaz <ajianaz@users.noreply.github.com> * fix(ci): wget+curl fallback for signatures fetch .github repo was private — now public. CDN may still cache 404. Using wget (primary) → curl (fallback) → empty JSON (last resort). Signed-off-by: ajianaz <ajianaz@users.noreply.github.com> * ci: re-trigger CLA check (.github now public + CDN refreshed) Signed-off-by: ajianaz <ajianaz@users.noreply.github.com> --------- Signed-off-by: ajianaz <ajianaz@users.noreply.github.com> Co-authored-by: ajianaz <ajianaz@users.noreply.github.com>
## What - configuration.md: new 'Impact Depth Guidance' section — per-depth cost profile (1/2/3/4+), why unlimited depth is counterproductive, and how to choose per codebase shape. impact_depth table row now links to it. - code-intelligence.md: new 'Call Graph Semantics & Limitations' section — multi-level BFS traversal with cycle protection, cross-project caller fallback, and static-analysis blind spots (dynamic dispatch, callbacks, reflection). ## Why These behaviors were only documented in source doc-comments (engine/context/types.rs, index/graph.rs). Users configuring impact_depth or trusting cora impact on dynamic-dispatch-heavy code had no way to know the trade-offs or limits. ## Changes - docs/configuration.md - docs/code-intelligence.md ## Testing - Markdown-only change; verified internal anchor link (#impact-depth-guidance) matches new heading.
## What Add note: impact_depth only governs automatic review-context blast radius; interactive cora impact / cora trace default to --depth 3 and are unaffected by the config. ## Why Code audit found CLI default depth = 3 (main.rs Impact/Trace clap default_value) while review context default = 2. Docs previously implied one setting covered both. ## Changes - docs/configuration.md (Impact Depth Guidance note) ## Testing Verified against src/main.rs clap defaults; markdown-only change.
## What - code-intelligence.md: fix invalid flag --incoming -> --direction incoming; graph.db -> cora.db (Multi-Project section); regex languages 15 -> 18; tree-sitter is DEFAULT-enabled (Cargo.toml default features), not opt-in — updated all three mentions; fix sidecar filenames (cora_index.keys; lock is held on .usearch file itself, no .lock file). - configuration.md: bundling section marked deprecated (cora scan does not read it — batching is --batch-files + internal 60k char budget); fix invalid example values (strategy: directory -> smart, severity: warning -> minor); correct include_callers bounds — <=3 call-sites only applies to regex fallback, index path uses up to 20. - cli-reference.md: document scan behaviors found in code but not in docs (index-based deterministic findings, brain context enrichment, cora.db persistence + auto-resolve, exit code 2 for hook block). ## Why Full docs-vs-code audit (3 parallel reviewers) of code-intelligence, review engine, and scan engine. All discrepancies patched; everything else verified accurate (CLI flags, defaults, RRF k=60, quality gate, debt tracking, embedding backends). ## Changes - docs/code-intelligence.md - docs/configuration.md - docs/cli-reference.md ## Testing Markdown-only; verified each fix against cited source lines (main.rs, scan.rs, resolver.rs, vector.rs, data_dir.rs, Cargo.toml).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
impact_depthonly governs review context — interactivecora impact/cora tracedefault--depth 3.--incoming→--direction incoming; tree-sitter is default-enabled (not opt-in);graph.db→cora.db; 15 → 18 regex languages; sidecar filenames corrected; bundling section marked deprecated (dead config — scan does not read it); invalid example values fixed (strategy: directory,severity: warning);include_callersbounds clarified (≤3 only in regex fallback, index path = 20); scan behaviors documented (index findings, brain context, cora.db persistence, exit code 2).Why
These behaviors were only in source doc-comments or plain wrong. Users configuring
impact_depthor trustingcora impacton dynamic-dispatch-heavy code had no way to know the trade-offs. Audit done by 3 parallel reviewers against main.rs, engine/, index/, config/.Changes
Testing
Markdown-only. Every fix verified against cited source lines (main.rs, types.rs, graph.rs, resolver.rs, vector.rs, scan.rs, data_dir.rs, Cargo.toml). Pre-commit cora review passed on all commits.