[Feature]: Add @internal tags to 10 borderline test-facing exports

[sjnims]

Feature Type

Pipeline architecture

Problem or Need

10 exported functions have enough internal complexity to justify direct unit testing, but are not part of the public API. They lack any annotation distinguishing them from genuinely public exports. The existing knip config already excludes @internal-tagged items via tags: ["-internal"], but these functions don't have the tag.

Proposed Solution

Add /** @internal */ JSDoc tags to 10 exports. No code or test changes needed — just documentation.

Utils (4 exports):

Export	File	Line
writeYaml	src/utils/file-io.ts	99
writeText	src/utils/file-io.ts	121
table	src/utils/logging.ts	281
callLLMForText	src/utils/llm.ts	56

Stage 3 — Execution (5 exports):

Export	File	Line
createToolCaptureCollector	src/stages/3-execution/hook-capture.ts	72
analyzeCaptures	src/stages/3-execution/hook-capture.ts	306
collectQueryMessages	src/stages/3-execution/sdk-client.ts	430
extractMetrics	src/stages/3-execution/transcript-builder.ts	198
areMcpServersHealthy	src/stages/3-execution/plugin-loader.ts	572

Stage 4 — Evaluation (1 export):

Export	File	Line
getConflictSummary	src/stages/4-evaluation/conflict-tracker.ts	244

Also add @internal to SanitizationConfig type export in src/utils/sanitizer.ts:89 (type-only, borderline).

Steps:

1. Add /** @internal */ JSDoc tag above each function/type definition
2. Verify: npm run build && npm run typecheck && npm run knip

Pipeline Stage Affected

General / Multiple stages

Component Type (if applicable)

Not component-specific

Alternatives Considered

• Removing the exports entirely — rejected because these have enough logic to warrant direct testing; forcing integration-style tests would lose edge-case coverage
• Leaving them undocumented — rejected because it makes the public API boundary unclear

How important is this feature to you?

Low - Just a suggestion

Additional Context

Identified during comprehensive dead code analysis (2026-01-31). Related: #371 (dead types), #372 (stdlib wrappers), #373 (export removal). The existing 7 @internal tags on CLI helpers set good precedent for this pattern.

---

🤖 Created with Claude Code

[claude]

Analysis: Add @internal tags to 10 borderline test-facing exports

1. Problem Assessment

Clearly defined? Yes — the issue is well-scoped with exact file paths, line numbers, and a clear rationale. All 11 exports (10 functions + 1 type) were verified to exist at the specified locations with accurate line numbers.

Root cause: The project has a clear public API surface defined in src/index.ts (stage runners + config), but many internal helper functions are exported solely to enable direct unit testing. Without @internal tags, there's no machine-readable distinction between public API and test-facing exports. The knip configuration already supports this via tags: ["-internal"] (knip.json:8), and 7 existing @internal tags on CLI helpers (src/cli/commands/resume.ts, src/cli/styles.ts) establish the pattern.

Pipeline stages affected: General — this is a documentation/API-hygiene change spanning utils, Stage 3 (Execution), and Stage 4 (Evaluation).

Key finding on internal usage: Several of these exports have nuanced usage profiles worth noting:

• callLLMForText (src/utils/llm.ts:56) — Production code only uses callLLMForTextWithCost, never callLLMForText directly. This is a genuine test-only export.
• table (src/utils/logging.ts:281) — Re-exported from src/utils/index.ts:36 but never called anywhere in production src/ code. Test-only.
• writeYaml and writeText (src/utils/file-io.ts:99,121) — Re-exported from src/utils/index.ts:48-50 but no production imports found. Test-only.
• Stage 3 exports (createToolCaptureCollector, analyzeCaptures, collectQueryMessages, extractMetrics, areMcpServersHealthy) — None are re-exported from src/stages/3-execution/index.ts or src/index.ts. They live in internal module files and are only imported by tests.
• getConflictSummary (src/stages/4-evaluation/conflict-tracker.ts:244) — Same pattern: not re-exported through the stage barrel.
• SanitizationConfig (src/utils/sanitizer.ts:89) — Type-only export, used internally within the same file at the createSanitizerFromOutputConfig parameter signature.

2. Proposed Solution Evaluation

The issue proposes adding /** @internal */ JSDoc tags with no code changes. This is the right approach:

Tradeoffs:

• Pro: Zero-risk change — no runtime behavior affected, no test changes, no build changes
• Pro: Leverages existing infrastructure (knip.json tags: ["-internal"] already configured)
• Pro: Consistent with established pattern (7 existing @internal tags in CLI code)
• Pro: Improves public API documentation accuracy in docs/public-api.md
• Con (minor): @internal doesn't enforce anything at compile time — consumers could still import these. But this is documentation-level intent, which is appropriate.

Risks: Effectively none. This is a JSDoc-only change.

Edge cases:

• 4 of the utils exports (writeYaml, writeText, table, callLLMForText) are re-exported from src/utils/index.ts. Adding @internal to the source definition is correct, but the barrel re-export in src/utils/index.ts will still expose them. This is fine — the tag documents intent, and knip already understands the tag semantics.
• collectQueryMessages, extractMetrics, and areMcpServersHealthy don't appear to have test imports currently (based on search). They may be truly unused exports rather than "test-facing" ones. Worth confirming whether these should be in scope for [Feature]: Remove export from 19 internal implementation details #373 (export removal) instead.

3. Alternative Approaches

Approach	Pros	Cons
A. @internal JSDoc tags (proposed)	Zero risk, leverages knip, follows precedent	Doesn't enforce at compile time
B. Remove exports, use module-internal tests	Stronger encapsulation	Requires test restructuring, loses edge-case coverage — explicitly rejected in issue
C. Move to __internal barrel export	Explicit separation	Over-engineered for 11 items, non-standard pattern
D. Use TypeScript @internal + API Extractor	Compile-time enforcement	Requires adding api-extractor dependency, significant setup overhead for a dev tool

Recommendation: Approach A — the proposed solution is the right one. The other approaches add complexity without proportional benefit for a developer tool.

4. Implementation Considerations

Files affected (11 edits across 7 files):

• src/utils/file-io.ts — 2 tags (lines ~99, ~121)
• src/utils/logging.ts — 1 tag (line ~281)
• src/utils/llm.ts — 1 tag (line ~56)
• src/stages/3-execution/hook-capture.ts — 2 tags (lines ~72, ~306)
• src/stages/3-execution/sdk-client.ts — 1 tag (line ~430)
• src/stages/3-execution/transcript-builder.ts — 1 tag (line ~198)
• src/stages/3-execution/plugin-loader.ts — 1 tag (line ~572)
• src/stages/4-evaluation/conflict-tracker.ts — 1 tag (line ~244)
• src/utils/sanitizer.ts — 1 tag (line ~89)

Breaking changes: None. JSDoc-only change.

Migration concerns: None.

Testing: Run npm run build && npm run typecheck && npm run knip to verify. No test changes needed. Tests will continue to import these exports normally — @internal is metadata, not access control.

State/resume impact: None.

Consideration: The docs/public-api.md file may benefit from a corresponding update noting which utility exports are @internal / test-facing, but this could be a follow-up.

5. Recommendation

Approve the proposed solution as-is. This is a low-risk, well-defined documentation improvement.

Suggested implementation steps:

1. Add /** @internal */ JSDoc comment above each of the 11 export definitions, using the same format as existing tags: /** @internal CLI helper - not part of public API */ (adjusted to remove "CLI" since these aren't CLI-specific — e.g., /** @internal Test-facing export - not part of public API */)
2. Run verification: npm run build && npm run typecheck && npm run knip
3. Optionally update docs/public-api.md to note the @internal convention extends beyond CLI helpers

Open question: 3 of the Stage 3 exports (collectQueryMessages, extractMetrics, areMcpServersHealthy) don't appear to have test imports. If they're truly unused (not test-facing, not production-facing), they may be better candidates for #373 (export removal) rather than @internal tagging. Worth a quick verification before implementation.

No follow-up issues needed — this is self-contained and the related issues (#371, #372, #373) already cover adjacent concerns.