Problem

When kubechecks produces a report that exceeds the VCS comment size limit (GitHub: 64 KB, GitLab: 1 MB), the comment is truncated.

This results in incomplete reports and effectively renders kubechecks unusable for pull requests that touch numerous apps or resources with sizeable diffs (e.g., CRDs, bulk app removals). Several users and organisations have flagged this as a blocking issue, with some resorting to maintaining custom builds to work around it.

This has been a long-standing feature request with multiple community contributions (#299, #301, #421, #436) - all of which were eventually closed by the stale bot without being merged. Similar tools (e.g., Atlantis) already handle this gracefully.

It would be lovely to finally get this sorted.

I can work on this as a matter of priority if you like, so let's try to get all the requirements together.

Proposed Scope

Configuration

Comment Splitting Logic

Structural splitting:

• Split at app-level boundaries (<details> blocks), keeping each app's section intact within a single comment wherever possible.
• If a single app's output exceeds the VCS limit on its own, fall back to byte-level splitting within that app's section.

Byte-level fallback:

• Close any open markdown constructs (code blocks, <details> tags) at the end of each chunk.
• Re-open them at the start of the next chunk.
• Each chunk must be valid, renderable markdown in its own right.

Chunk decoration:

• Every chunk carries the header: # Kubechecks {identifier} Report (Part N of M). The identifier MUST be present in all chunks so that multi-instance deployments sharing the same token correctly prune or hide only their own comments (per the review on #301 and Allow multiple kubechecks instances with the same token #370).
• Non-first chunks include: Continued from previous comment.
• Non-last chunks include: Continued in next comment.
• The footer (commit SHA, duration, pod info) appears only on the final chunk.

VCS Client Changes

• UpdateMessage signature: Accept []string (chunks) rather than a single string. The first chunk edits the existing comment; subsequent chunks are posted as new comments.
• PostMessage: BuildComment returns []string and PostMessage posts them sequentially.
• Backoff and retry: Exponential backoff on VCS API calls during multi-comment posting to respect rate limits.
• GitHub and GitLab: The splitting logic itself is VCS-agnostic. Only MaxCommentLength and the underlying API calls differ per provider.

Clean Up the "kubechecks running" Placeholder

When posting the final report:

• Find and delete the :hourglass: kubechecks running ... placeholder comment rather than editing it in place.
• Post the report as fresh comment(s).

This sidesteps the rather awkward in-place edit of a placeholder and simplifies the split-comment flow.

TidyOutdatedComments

pruneOldComments and hideOutdatedMessages must account for multi-comment runs:

• Identify all comments belonging to the same kubechecks instance and check run via the identifier in the header.
• Prune or hide the entire group together.

Memory Considerations

A prior attempt (#436) surfaced excessive memory usage during splitting. The implementation should:

• Avoid materialising the entire split output in memory at once where feasible.
• Favour strings.Builder for chunk assembly.
• Profile memory usage with large reports (100 KB+) as part of testing.

Testing

• Unit tests for the splitting function covering both structural and byte-level paths.
• Unit tests for chunk decoration (identifier, part numbering, markdown validity).
• Manual verification for both GitHub and GitLab (Not sure if integration tests are feasible).
• Edge cases: single app exceeding the limit, report landing exactly at the limit, empty report, single-app report, and the max-comments cap being reached.

Out of Scope

• Offloading full output to external storage (S3, etc.).
• Per-resource-level splitting (GitHub's 64 KB limit means single-resource diffs can span multiple comments regardless).

References

• Multiple comments instead of trimming comment size #299, feat: Split Github comments instead of trimming #301, Kubechecks comments can get cut off if the comment length is too long #421, feat: Split comments if too long #436 -- prior issues and community attempts.
• Allow multiple kubechecks instances with the same token #370 -- identifier feature (merged). Identifier must appear in all split chunks.
• Review comment on #301 requiring the identifier in continued messages.

Cc: @MeNsaaH, @Greyeye, @djeebus