feat: append new HTTP method handlers to existing route files

[Copilot]

Summary

When a new HTTP method is added to an existing path in the OpenAPI spec, regeneration previously skipped updating existing route files, so new handler stubs were missing. This change keeps existing route code intact while appending only missing handler exports (and required type imports).
It also incorporates PR feedback by ensuring import insertion safely falls back to prepending at file start when no existing import position can be determined, and fixes TypeScript typing issues in the append logic.

Original Prompt

When the OpenAPI spec is updated to add a new request method to an existing route, the type for that request method is generated. However, the handler under routes is not generated, due to the rule that existing files under routes should not be overwritten.

In this case, it's okay to APPEND a new export to the file under routes as long as none of the existing code has been changed.

Manual acceptance tests

• Generate routes from a spec with GET /pet — verify routes/pet.ts is created with only a GET export.
• Add POST /pet to the spec and regenerate — verify GET is unchanged and a new POST stub is appended at the bottom of the file.
• Manually edit the GET handler before regenerating with POST — verify the custom edit survives and POST is still appended.
• Remove import lines from an existing routes/pet.ts, then regenerate after adding a new method — verify missing import type lines are prepended at the top of the file.
• Regenerate with no spec changes — verify no existing route file is modified.

Tasks

• Added Repository.appendNewHandlers(fullPath, generatedContent) to:
  • Detect missing export const METHOD handlers in existing route files.
  • Extract matching import type lines and handler export blocks from generated content.
  • Insert missing imports after the last import when present, or prepend at position 0 when not.
  • Append only missing handler export blocks without modifying existing handler code.
• Updated Repository.writeFiles() to use append behavior for existing route files instead of unconditionally skipping them.
• Fixed TypeScript safety issues in append logic by narrowing regex capture values before use.
• Added/updated repository tests for:
  • Appending newly added methods,
  • Preserving user edits,
  • No-op regeneration with unchanged specs,
  • Import-prepend fallback when existing route files have no import section.
• Updated docs/faq.md to document append-on-update route behavior.

[pmcelhaney]

@copilot CI is failing on lint rules

[pmcelhaney]

@copilot if you can't find an existing import then default to position 0. In other words, preprend the import to the beginning of the file. That should always be safe.

[Copilot]

Implemented in 42663de. In appendNewHandlers, when import insertion cannot determine a valid existing import index, it now falls back to insert position 0 (prepend). I also added a regression test that strips imports from an existing route file and verifies the new import is prepended when appending a new method handler.

[Copilot]

@copilot CI is failing on lint rules

Fixed in 42663de. I investigated the failing CI run and the failure was in TypeScript checks (not eslint): nullable regex captures in repository.ts. The commit adds proper type narrowing and CI now passes locally with yarn lint, yarn build, and yarn test.