Skip to content

fix: regenerate invalidated modules in whole-repository-mode --update runs - #100

Open
kiboook wants to merge 1 commit into
FSoft-AI4Code:mainfrom
kiboook:fix/incremental-update-whole-repo-mode
Open

fix: regenerate invalidated modules in whole-repository-mode --update runs#100
kiboook wants to merge 1 commit into
FSoft-AI4Code:mainfrom
kiboook:fix/incremental-update-whole-repo-mode

Conversation

@kiboook

@kiboook kiboook commented Aug 31, 2026

Copy link
Copy Markdown

Fixes #99

Problem

--update --compare-to <commit> never regenerates an invalidated module
when the repo went through whole-repository documentation mode (module
clustering skipped because the repo fits in one context window). It
correctly deletes the affected module's .md, then fails every time with
IncompleteGenerationError. See #99 for the full trace of why.

Root cause

generate_module_documentation() computed the processing order only from
first_module_tree.json, which stays {} forever for whole-repo-mode
repos (only the LLM clustering path writes it) — even though
module_tree.json can have real sub-modules a prior whole-repo agent run
inserted. So the regeneration loop had nothing to iterate over for an
invalidated module.

Fix

Extracted the processing-order lookup into
DocumentationGenerator.resolve_processing_order(), which falls back to
module_tree only when first_module_tree produces an empty order. The
normal clustered-repo path is unaffected, since first_module_tree is
non-empty there and the fallback never triggers.

Testing

  • Added tests/test_processing_order_fallback.py (4 unit tests, no LLM/
    network needed) covering: fallback when first_module_tree is empty,
    first_module_tree still wins when non-empty (regression safety for
    the normal path), both-empty doesn't crash, and nested children are
    still walked leaf-first through the fallback.
  • Ran the new tests plus the existing tests/test_overview_structure.py
    against this change — all pass.
  • End-to-end verified against the minimal repro from --update --compare-to never regenerates invalidated modules in whole-repository documentation mode (always ends in IncompleteGenerationError) #99 (tiny
    auth/payment/notification TypeScript fixture, 2 commits): before the
    fix, the run reproducibly failed with IncompleteGenerationError;
    after the fix, generate --update --compare-to <sha> succeeds, the
    changed module regenerates, the two unaffected modules are correctly
    skipped ("✓ Module docs already exists"), and the overview is rebuilt
    referencing all three.

… runs

first_module_tree.json is only ever written by the LLM clustering path,
so it stays {} for any repo small enough to skip clustering
("whole-repository documentation mode"). generate_module_documentation()
computed the processing order exclusively from that file, so once
--update/--compare-to invalidated (deleted) an affected sub-module's .md
via module_tree.json, the regeneration loop had nothing to iterate and
the run always ended in IncompleteGenerationError.

Fall back to module_tree for the processing order only when
first_module_tree is empty. The normal clustered-repo path is untouched,
since first_module_tree is non-empty there and the fallback never
triggers.

Fixes FSoft-AI4Code#99
@kiboook
kiboook force-pushed the fix/incremental-update-whole-repo-mode branch from 54615ec to e27accc Compare August 31, 2026 08:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

--update --compare-to never regenerates invalidated modules in whole-repository documentation mode (always ends in IncompleteGenerationError)

1 participant