feat(#14): code Generation Layer module interface specification

[sugat009]

Summary

• Define the CodeGenModule plugin interface, registry, and contribution guide for the Code Generation Layer
• Implement a scaffold claude-api module as the reference example
• Address all 9 review comments from the original PR feat(#14): Implement code generation modules #69

Details

Interface (src/layers/code-gen/interface.ts)

• CodeGenModule: core contract (name, version, generate(), validate?())
• CodeGenModuleInput/Output: provider-agnostic input/output shape
• ContextFile, GeneratedFile: supporting types

Registry (src/layers/code-gen/registry.ts)

• CodeGenModuleRegistry: register, get, list, resolve aliases, get active module
• Provider resolution: explicit arg > LLM_PROVIDER env > claude-api default
• Alias support (anthropic -> claude-api, claude-cli -> claude-code-cli)

Example module (src/layers/code-gen/modules/claude-api/)

• Scaffold implementation that generates an implementation plan from ticket data
• validate() checks ANTHROPIC_API_KEY presence

Contribution guide (designs/code-gen-CONTRIBUTING.md)

• Directory layout, module contract, step-by-step guide, provider selection docs, testing guidance

Review fixes (from PR #69)

• Removed unnecessary ParsedTicket alias, use IssueTemplate directly
• Extracted duplicated readEnv() to shared src/utils/env.ts
• Moved CONTRIBUTING.md from src/ to designs/
• Moved tests to test/layers/code-gen/ matching src/ convention
• Merged duplicate imports, added 8 missing test cases
• Reverted unrelated proxyquire change in context-loader.spec.ts
• Regenerated clean package-lock.json

Test plan

• npm test passes (150 tests, 20 for code-gen layer)
• Registry resolves aliases correctly
• Registry falls back through: explicit provider > env var > default
• ClaudeApiCodeGenModule generates deterministic plan output
• Empty inputs (phases, findings, refs) handled gracefully
• Verify the interface is extensible for future modules (gemini, openai, claude-code-cli)

Fixes #14

[Hareet]

Interface and registry are clean. Tests are solid on the happy paths.

A few things to address:

1. CodeGenModuleOutput needs a partial failure channel

The output has files and explanation but no way to signal "I generated 3 of 5 files, 2 failed." When a module hits an LLM rate limit or produces invalid output mid-generation, it won't handle partial failures. Suggest adding:

export interface CodeGenModuleOutput {
  files: GeneratedFile[];
  explanation: string;
  tokensUsed?: number;
  modelUsed?: string;
  warnings?: string[];  // non-fatal issues during generation
}

2.. Silent duplicate registration

Calling registry.register() twice with the same name silently overwrites

And the examples use cht-core's project structure. Maybe in the contributing section, we want to say that will need to be changed to whatever repo you want to code-gen (cht-conf)

Quick changes and everything else looks good, thanks!

[Hareet]

Approving! I've read this in detail and re-ran the review and tests a few times.

It's not blocking, and could be a simple comment or doc fix for future agents to understand:

Revised re-review

Status of feedback items:

• ✅ warnings?: string[] added to CodeGenModuleOutput (interface.ts:29)
• ✅ Duplicate register() throws with helpful message + test (registry.ts:14-18, spec:113)
• ✅ "Note on Examples" section in CONTRIBUTING.md flags repo-specific paths

One question on the unrelated refactor (cd62a6e):
The buildScaffoldFiles rewrite changed the fallback condition. Old code fell back to ticket components when zero files were produced (i.e., even if phase components existed but all yielded null from extractModuleName).
New code falls back only when phaseComponents is empty. Trigger is rare in practice (requires trailing-slash or empty input strings), but the old comment "If no phases produced files, generate one from the first listed
component" signals the original intent was the broader fallback. Was this change intentional? If yes, fine — worth a one-line comment so the next reader understands. If no, swap the order: map+filter first, then check
empty.

Recommendation: Approve. The 3 feedback items are addressed cleanly with tests. The refactor question is worth a comment but not a gate.