fix(integrations): refuse scaffold keys that shadow a module or name a keyword

[jawwad-ali]

Problem

scaffold_integration validates the key's shape (_KEY_RE, lowercase kebab-case) but never checks what the derived package name would collide with. Two ordinary keys produce broken output.

1. A key that shadows one of this package's own modules

The scaffold creates a package — integrations/<key>/__init__.py — and in Python a package shadows a same-named module in the same directory:

both 'base.py' and 'base/' present -> import demopkg.base resolves to: scaffolded package base/

Every integration in the repo does from ..base import MarkdownIntegration / SkillsIntegration, so scaffolding a key named base silently redirects all of them to the empty scaffold.

The existing guard cannot catch this — it only checks <key>/__init__.py and the test file:

existing = [path for path in (integration_file, test_file) if path.exists()]

integrations/base.py is never consulted. Currently accepted and collidable: base, catalog, manifest.

2. A key that is a reserved Python keyword

integrations/class/ cannot be named by any import statement, so the generated package is unreachable and its generated test (from specify_cli.integrations.class import ClassIntegration) is a SyntaxError. Currently accepted: class, import, return, lambda, …

Reproduction on current main (c173bf1)

Every one of these passes _clean_key:

_clean_key('base'    ) -> ACCEPTED 'base'
_clean_key('catalog' ) -> ACCEPTED 'catalog'
_clean_key('manifest') -> ACCEPTED 'manifest'
_clean_key('class'   ) -> ACCEPTED 'class'
_clean_key('import'  ) -> ACCEPTED 'import'

Fix

Refuse both up front, before anything is written:

base       -> refused (collision)
catalog    -> refused (collision)
manifest   -> refused (collision)
class      -> refused (keyword)
import     -> refused (keyword)
match      -> ACCEPTED
my-agent   -> ACCEPTED

Soft keywords are deliberately allowed

My first cut rejected soft keywords too. I checked rather than assumed, and that would have been wrong — soft keywords are contextual and import match is perfectly valid:

soft keyword 'match' -> importable? YES   iskeyword=False issoftkeyword=True
soft keyword 'case'  -> importable? YES   iskeyword=False issoftkeyword=True

So the guard uses keyword.iskeyword only, and match / case remain usable keys. (_ is not a usable key at all: _clean_key's lowercase kebab-case pattern requires a leading letter and rejects it before this guard runs.)

Verification

• Fail-before / pass-after: 7 new-vs-baseline failures with the source reverted to upstream/main → 25 passed, 1 skipped with the fix.
• The shadowing test asserts the real module is left byte-identical and that no package was created beside it — not merely that an error was raised.
• A third test pins that soft keywords and ordinary keys still scaffold successfully, so the guard cannot start refusing valid input.
• uvx ruff@0.15.0 check src tests → clean

Behaviour change, disclosed: five key values that previously scaffolded now raise. All five produced output that was broken on arrival — an unimportable package, or one that shadows a module the whole package depends on.

---

Written with assistance from Claude Code. Bug found, reproduced, and verified by me on current main.

🤖 Generated with Claude Code

[Copilot]

🟢 Approval recommended

The implementation and regression coverage are sound; only a minor documentation correction remains.

Pull request overview

Prevents integration scaffolds from creating invalid or module-shadowing Python packages.

Changes:

• Rejects Python keyword keys and module-name collisions.
• Adds regression and valid-key coverage.

File summaries

File	Description
tests/integrations/test_integration_scaffold.py	Tests rejected collisions, keywords, and accepted keys.
src/specify_cli/integration_scaffold.py	Adds keyword and module-collision validation.

Review details

• Files reviewed: 2/2 changed files
• Comments generated: 1
• Review effort level: Balanced

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[mnriem]

Please address Copilot feedback and resolve conflicts