chore: define and document public API exports

[sjnims]

Summary

• Define explicit public API via package.json exports field
• Re-export stage runners and config loader from main entry
• Add @internal JSDoc tags to CLI-only helpers
• Add Programmatic Usage documentation to README.md and CLAUDE.md

Problem

Fixes #228

Dead code analysis flagged 180+ re-exports as "unused" because they're not consumed internally. However, many of these are intentional public API exports meant for external consumption. This PR clarifies the distinction.

Solution

Implemented a minimal public API strategy as recommended in the issue analysis:

1. package.json exports field - Explicitly defines two subpaths:

   • . (main) - Stage runners + config loader
   • ./types - Type definitions (zero runtime cost)

2. Public API Exports - Re-exports from src/index.ts:

   • runAnalysis, runGeneration, runExecution, runEvaluation
   • loadConfigWithOverrides, consoleProgress
   • CLIOptions type

3. Internal Markers - Added @internal JSDoc tags to:

   • Resume handlers (resumeFrom*)
   • CLI option extractors (extractCLIOptions, etc.)
   • Output formatters (outputCLISummary, etc.)
   • Internal types (ResumeHandler, EvaluationFile)

4. Documentation - Added:

   • Programmatic Usage section to README.md with examples
   • Public API section to CLAUDE.md with entry points and exports table

Alternatives Considered

• Full export strategy: Would expose too much internal surface area
• Tiered exports: More complex than needed at this stage
• knip ignore only: Would silence the tool without adding value

Changes

• package.json: Add exports field with main and types subpaths
• src/index.ts: Add public API exports section, reorganize imports, add @internal tags
• README.md: Add Programmatic Usage section after CLI Reference
• CLAUDE.md: Add Public API section with exports table

Testing

• Linting passes (npm run lint)
• Type checking passes (npm run typecheck)
• All tests pass (npm test)
• Formatting applied (npm run format)

---

🤖 Generated with Claude Code

[claude]

Claude finished @sjnims's task in 4m 0s —— View job

---

PR Review Complete ✅

• Run quality checks (typecheck, lint, format)
• Review the diff
• Analyze changed files
• Check for specific issues
• Provide feedback

---

Verdict: ✅ Looks good

This PR successfully defines a clean, minimal public API for cc-plugin-eval with excellent documentation and zero technical issues.

Quality Checks

All checks pass without issues:

• ✅ TypeScript - No type errors
• ✅ Linting - No ESLint issues
• ✅ Formatting - All files properly formatted
• ✅ Tests - 1340 passed, 5 skipped (unrelated to this PR)

What's Good

1. Excellent API Design

• Minimal surface area with only the essentials exported
• Clear separation via @internal JSDoc tags for CLI-only helpers
• Proper use of package.json exports field with typed subpaths
• Zero runtime cost for ./types subpath (types-only)

2. Documentation Quality

• Comprehensive usage examples in both README and CLAUDE.md
• Accurate function signatures and return types
• Clear distinction between public API and internal CLI helpers
• Well-organized tables showing all exports

3. Code Quality

• All ESM imports use .js extensions (ESM requirement ✓)
• No any types introduced
• Proper TypeScript strictness maintained
• Good use of JSDoc for public API documentation

4. Architecture Compliance

• Follows established patterns (stage runners, config loader)
• Doesn't expose internal state management
• Maintains backward compatibility for CLI usage
• Re-exports are clean and well-organized

5. Testing

• All existing tests pass
• No regression introduced
• Public API functions already well-tested through existing integration tests

Suggestions

1. Consider Adding a Basic Integration Test

While the public API functions are well-tested individually, consider adding a simple integration test that exercises the documented usage pattern:

// tests/integration/public-api.test.ts
import { describe, it, expect } from 'vitest';
import {
  runAnalysis,
  runGeneration,
  loadConfigWithOverrides,
  consoleProgress,
} from '../../src/index.js';

describe('Public API Integration', () => {
  it('should support the documented usage pattern', async () => {
    const config = loadConfigWithOverrides('tests/fixtures/valid-plugin/config.yaml', {
      plugin: 'tests/fixtures/valid-plugin',
    });
    
    const analysis = await runAnalysis(config);
    expect(analysis).toBeDefined();
    expect(analysis.plugin_name).toBeDefined();
    
    // Verify consoleProgress is exported and callable
    expect(typeof consoleProgress.onStageStart).toBe('function');
  });
});

This would:

• Validate the documented API works end-to-end
• Catch any future breaking changes to the public API
• Serve as executable documentation

2. Future Enhancement: Add TypeScript Type Tests

For the next iteration, consider adding type-level tests using @ts-expect-error to ensure the public API types remain stable:

// tests/types/public-api.test-d.ts
import type { EvalConfig, AnalysisOutput } from '../../src/types/index.js';
import { runAnalysis } from '../../src/index.js';

// Valid usage
const config: EvalConfig = {} as EvalConfig;
const result: Promise<AnalysisOutput> = runAnalysis(config);

// @ts-expect-error - should not accept wrong types
runAnalysis("invalid");

This helps prevent accidental breaking changes to the public API surface.

3. Minor: Consider a CHANGELOG Entry

For semantic versioning awareness, consider adding a CHANGELOG.md entry noting the new programmatic API for the next release (likely 0.3.0 as a minor feature addition).

Summary

This is a well-executed PR that:

• ✅ Solves the issue chore: audit and document public API exports #228 dead code analysis problem
• ✅ Adds genuine value with a clean programmatic API
• ✅ Maintains excellent code quality and documentation
• ✅ Introduces zero breaking changes
• ✅ Follows all project conventions

The suggestions above are optional enhancements for future iterations, not blockers. This PR is ready to merge.

---