Implement incremental and forced project index updates #9

New issue

Closed

opened 2026-09-03 14:22:17 +00:00 by JayKobe6k · 0 comments

JayKobe6k commented

2026-09-03 14:22:17 +00:00

Owner

Goal

Update an existing index efficiently while preserving atomic queryable revisions.

Command contract

claritree index update <project-path> [--index-path <path>] [--reindex] [project/build options]

Resolve the existing index from the cached catalog using the canonical project path. If no catalog entry exists, require --index-path to identify the existing index database. --reindex forces all translation units to be rebuilt.

Incremental behavior

Fingerprint source files, included headers, compilation commands, relevant build settings, and resolved project revision.
Detect added, changed, deleted, renamed, and no-longer-compiled translation units.
Reindex every TU affected by a changed shared header or compile command.
Remove stale TU-owned facts without deleting shared facts still referenced by unaffected TUs.
Recompute cross-TU resolution and lineage for the affected closure.
Publish a new revision atomically; retain the prior active revision if parsing, analysis, or persistence fails.
Return a deterministic no-op result when nothing changed.
Define and document revision retention/cleanup separately from correctness of publication.

Acceptance criteria

Tests cover no-op update, source edit, header edit, compile-flag change, TU addition/deletion/rename, failed parse rollback, stale-fact removal, and --reindex.
--reindex shares the same publication path as incremental updates and does not mutate the active graph in place.
Output reports old/new revision, changed and affected TUs, added/removed fact counts, diagnostics, and whether a full reindex occurred.
Query readers never observe a partially updated index.
CLI code only translates arguments/results and selects rendering.

Dependencies

Depends on #8 and the provenance/fingerprint behavior from #4, #6, and #7.

## Goal Update an existing index efficiently while preserving atomic queryable revisions. ## Command contract ```text claritree index update <project-path> [--index-path <path>] [--reindex] [project/build options] ``` Resolve the existing index from the cached catalog using the canonical project path. If no catalog entry exists, require `--index-path` to identify the existing index database. `--reindex` forces all translation units to be rebuilt. ## Incremental behavior - Fingerprint source files, included headers, compilation commands, relevant build settings, and resolved project revision. - Detect added, changed, deleted, renamed, and no-longer-compiled translation units. - Reindex every TU affected by a changed shared header or compile command. - Remove stale TU-owned facts without deleting shared facts still referenced by unaffected TUs. - Recompute cross-TU resolution and lineage for the affected closure. - Publish a new revision atomically; retain the prior active revision if parsing, analysis, or persistence fails. - Return a deterministic no-op result when nothing changed. - Define and document revision retention/cleanup separately from correctness of publication. ## Acceptance criteria - Tests cover no-op update, source edit, header edit, compile-flag change, TU addition/deletion/rename, failed parse rollback, stale-fact removal, and `--reindex`. - `--reindex` shares the same publication path as incremental updates and does not mutate the active graph in place. - Output reports old/new revision, changed and affected TUs, added/removed fact counts, diagnostics, and whether a full reindex occurred. - Query readers never observe a partially updated index. - CLI code only translates arguments/results and selects rendering. ## Dependencies Depends on #8 and the provenance/fingerprint behavior from #4, #6, and #7.

JayKobe6k added this to the CLI + Core MVP milestone

2026-09-03 14:22:17 +00:00

JayKobe6k added the

labels

2026-09-03 14:22:17 +00:00

JayKobe6k referenced this issue

2026-09-03 14:22:18 +00:00

Add end-to-end CLI workflows and user documentation #18