feat: index storage backend (cache default, PR opt-in) by Benkapner · Pull Request #71 · redhat-community-ai-tools/code-to-docs

Benkapner · 2026-08-17T05:52:08Z

Summary

Changes how semantic indexes are persisted. The current default (opening a PR against main) is intrusive. New index-storage input with three options:

cache (new default): saves indexes to a well-known path for Actions cache. Same performance benefit, no unsolicited PR.
pr: current behavior, unchanged. For users who want indexes committed to the repo.
none: skip persistence entirely.

Behavior change: default flips from pr to cache. Existing users who rely on the index PR should set index-storage: pr explicitly.

Test plan

uv run pytest -v passes (417 tests)
Lint clean
Default run does not open an index PR
index-storage: pr reproduces old behavior

Opening a PR against the user's main branch as a side effect of running a docs review is intrusive and surprises people the first time. Add an index-storage input with three options: "cache" (saves indexes to a well-known path for Actions cache restore), "pr" (current behavior), and "none" (skip persistence). Default to "cache" so new adopters get the performance benefit without an unsolicited PR. Setting index-storage to "pr" reproduces the old behavior exactly.

fullsend-ai-review · 2026-08-17T05:53:11Z

🤖 Finished Review · ✅ Success · Started 5:53 AM UTC · Completed 6:12 AM UTC

Commit: e6a4f24 · View workflow run →

fullsend-ai-review · 2026-08-17T06:12:38Z

Review

Findings

Medium

[default-value-mismatch] src/doc_index.py:864 — Python fallback default for INDEX_STORAGE is "pr" (os.environ.get("INDEX_STORAGE", "pr")), but action.yml declares the default as "cache". Outside the GitHub Action context (local dev, direct script execution), the Python default silently uses PR-based storage, contradicting the documented default and potentially creating unwanted PRs.
Remediation: Change to os.environ.get("INDEX_STORAGE", "cache").
[logic-error] src/doc_index.py:1295 — fetch_indexes_from_main() unconditionally calls restore_indexes_from_cache() regardless of the INDEX_STORAGE setting. When set to "pr" or "none", stale cache data from /tmp/code-to-docs-index-cache is loaded if the path exists, skipping the git-based fetch entirely.
Remediation: Guard with if os.environ.get("INDEX_STORAGE", "cache").lower() == "cache".
[backward-incompatible] action.yml:77 — Default value for index-storage changes from implicit "pr" to explicit "cache". Existing consumers relying on the index PR workflow will experience a silent behavior change.
Remediation: Keep default as "pr" for backward compatibility, or document the migration path in README/CHANGELOG.
[config-centralization] src/doc_index.py:864 — INDEX_STORAGE is accessed directly via os.environ.get() instead of through a config.py getter, breaking the codebase's established pattern for testable configuration access.
Remediation: Add get_index_storage() to config.py.
[undocumented-cache-contract] src/doc_index.py:817 — The cache backend saves to /tmp/code-to-docs-index-cache but no documentation shows consumers how to configure the required GitHub Actions cache steps for this path.
Remediation: Expose the cache path via action.yml outputs, or document the cache workflow configuration in README.
[stale-doc] CLAUDE.md:56 — Environment variables table is missing the new INDEX_STORAGE variable.
[stale-doc] CLAUDE.md:111 — Function descriptions for commit_indexes_to_repo() and fetch_indexes_from_main() are outdated — both now have conditional behavior based on INDEX_STORAGE.
[missing-doc] README.md:193 — Optional Action Inputs section is missing the new index-storage input.
[stale-doc] README.md:271 — Performance Optimization section describes PR-based index persistence as the default, but the default is now cache-based.

Low

[missing-validation] src/doc_index.py:864 — No validation of INDEX_STORAGE value; unrecognized values silently fall through to the PR-creation path.
[test-inadequate] src/doc_index.py — No tests for save_indexes_to_cache(), restore_indexes_from_cache(), or the modified dispatch logic.
[missing-authorization] — No linked issue for a non-trivial feature PR. The PR body documents the rationale, but a separate issue would provide clearer authorization.
[architecture-coherence-gap] CLAUDE.md — Index system section doesn't reflect the new multi-backend architecture.
[scope-expansion] src/doc_index.py:849 — commit_indexes_to_repo() now handles both storage routing and PR-based persistence; consider extracting backends.

Labels: PR adds a new index-storage feature, modifying both Python source and GitHub Action configuration.

Next steps:

/fs-fix — agent addresses review findings automatically
/fs-fix <your instruction> — agent fixes with your specific guidance
Push commits directly — review re-runs automatically on push
/fs-fix-stop — disable automatic fix runs for this PR

fullsend-ai-review

See the review comment for full details.

fullsend-ai-review · 2026-08-17T06:12:39Z

-        bool: True if content was committed and PR created/updated, False otherwise
+        bool: True if content was persisted, False otherwise
    """
+    storage = os.environ.get("INDEX_STORAGE", "pr").lower()


[medium] default-value-mismatch

Python fallback default for INDEX_STORAGE is 'pr' (os.environ.get('INDEX_STORAGE', 'pr')), but action.yml declares the default as 'cache'. Outside the GitHub Action context (local dev, direct script execution), the Python default silently uses PR-based storage, contradicting the documented default.

Suggested fix: Change to os.environ.get('INDEX_STORAGE', 'cache').

fullsend-ai-review · 2026-08-17T06:12:40Z

    Returns:
        bool: True if indexes/summaries were fetched, False otherwise
    """
+    if restore_indexes_from_cache():


[medium] logic-error

fetch_indexes_from_main() unconditionally calls restore_indexes_from_cache() regardless of the INDEX_STORAGE setting. When INDEX_STORAGE is 'pr' or 'none', stale cache data from /tmp/code-to-docs-index-cache is loaded if the path exists, skipping the git-based fetch entirely.

Suggested fix: Guard with: if os.environ.get('INDEX_STORAGE', 'cache').lower() == 'cache'.

fullsend-ai-review · 2026-08-17T06:12:40Z

    required: false
    default: ''
+  index-storage:
+    description: 'How to persist semantic indexes: "cache" (Actions cache, default), "pr" (open a PR to main), or "none" (no persistence)'


[medium] backward-incompatible

Default value for index-storage changes from implicit 'pr' to explicit 'cache'. Existing consumers relying on the index PR workflow will experience a silent behavior change.

Suggested fix: Keep default as 'pr' for backward compatibility, or document the migration path in README/CHANGELOG.

fullsend-ai-review · 2026-08-17T06:12:40Z

-        bool: True if content was committed and PR created/updated, False otherwise
+        bool: True if content was persisted, False otherwise
    """
+    storage = os.environ.get("INDEX_STORAGE", "pr").lower()


[medium] config-centralization

INDEX_STORAGE is accessed directly via os.environ.get() instead of through a config.py getter, breaking the codebase's established pattern for testable configuration access.

Suggested fix: Add get_index_storage() to config.py.

fullsend-ai-review · 2026-08-17T06:12:40Z

    return updated_folders


+_CACHE_MANIFEST_PATH = "/tmp/code-to-docs-index-cache"


[medium] undocumented-cache-contract

The cache backend saves to /tmp/code-to-docs-index-cache but no documentation shows consumers how to configure the required GitHub Actions cache steps for this path.

Suggested fix: Expose the cache path via action.yml outputs, or document the cache workflow configuration in README.

fullsend-ai-review · 2026-08-17T06:12:40Z

-        bool: True if content was committed and PR created/updated, False otherwise
+        bool: True if content was persisted, False otherwise
    """
+    storage = os.environ.get("INDEX_STORAGE", "pr").lower()


[low] missing-validation

No validation of INDEX_STORAGE value. An unrecognized value silently falls through to the PR-creation path.

fullsend-ai-review · 2026-08-17T06:12:40Z

+    return True
+
+
 def commit_indexes_to_repo(content_type="indexes"):


[low] scope-expansion

commit_indexes_to_repo() now handles both storage routing and PR-based persistence. Consider extracting backends into separate functions.

Benkapner requested a review from csoceanu August 17, 2026 05:53

Benkapner self-assigned this Aug 17, 2026

fullsend-ai-review Bot suggested changes Aug 17, 2026

View reviewed changes

fullsend-ai-review Bot added feature python Pull requests that update python code github_actions Pull requests that update GitHub Actions code labels Aug 17, 2026

Navigation Menu

Uh oh!

feat: index storage backend (cache default, PR opt-in) - #71

feat: index storage backend (cache default, PR opt-in)#71
Benkapner wants to merge 1 commit into
mainfrom
feat/index-storage

Benkapner commented Aug 17, 2026

Uh oh!

fullsend-ai-review Bot commented Aug 17, 2026 •

edited

Loading

Uh oh!

fullsend-ai-review Bot commented Aug 17, 2026

Uh oh!

fullsend-ai-review Bot left a comment

Uh oh!

fullsend-ai-review Bot Aug 17, 2026

Uh oh!

fullsend-ai-review Bot Aug 17, 2026

Uh oh!

fullsend-ai-review Bot Aug 17, 2026

Uh oh!

fullsend-ai-review Bot Aug 17, 2026

Uh oh!

fullsend-ai-review Bot Aug 17, 2026

Uh oh!

fullsend-ai-review Bot Aug 17, 2026

Uh oh!

fullsend-ai-review Bot Aug 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

		return updated_folders


		_CACHE_MANIFEST_PATH = "/tmp/code-to-docs-index-cache"

		return True


		def commit_indexes_to_repo(content_type="indexes"):

Uh oh!

Conversation

Benkapner commented Aug 17, 2026

Summary

Test plan

Uh oh!

fullsend-ai-review Bot commented Aug 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fullsend-ai-review Bot commented Aug 17, 2026

Review

Findings

Medium

Low

Uh oh!

fullsend-ai-review Bot left a comment

Choose a reason for hiding this comment

Uh oh!

fullsend-ai-review Bot Aug 17, 2026

Choose a reason for hiding this comment

Uh oh!

fullsend-ai-review Bot Aug 17, 2026

Choose a reason for hiding this comment

Uh oh!

fullsend-ai-review Bot Aug 17, 2026

Choose a reason for hiding this comment

Uh oh!

fullsend-ai-review Bot Aug 17, 2026

Choose a reason for hiding this comment

Uh oh!

fullsend-ai-review Bot Aug 17, 2026

Choose a reason for hiding this comment

Uh oh!

fullsend-ai-review Bot Aug 17, 2026

Choose a reason for hiding this comment

Uh oh!

fullsend-ai-review Bot Aug 17, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

fullsend-ai-review Bot commented Aug 17, 2026 •

edited

Loading