Repository navigation
refactor: split source-provider handler into responsibility owners - #14543
Conversation
The 7,925-line dashboard/handlers/source_providers.py held URL validation, the provider-CLI runner, three providers' reads, the ADF converter, two caches, the chip refresh loop and every write. Each now has one owner module under dashboard/source_providers/, moved verbatim. The handler keeps the /api/source/* routes, their audit and error mapping, and the dashboard owner gate. Every other name it defined still resolves there. Reads come from the owner and writes are forwarded to it, reusing the security package's re-export pattern (#13933), so existing imports and patches still reach the running code. Owners reach each other as modules and import only earlier owners, so the owners form no cycle. The owners that redact provider data join security_posture's non-egress allowlist in place of the handler. The spawn-audit tripwire now names runner._run_provider, the function that actually spawns. The dashboard spec records the owner map.
Design Review (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS Verify CI green on the full 2,251-file related set the local gate could not run — local runs covered only the owned and adjacent suites. [DESIGN-REVIEWED] 84ffe73 |
First Principles Review (Fable 5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Verify CI's full related-test set is green on this head: the author locally ran only the owned and adjacent suites, deferring the 2,251-file set to CI. Not justified as shipped
What this change shipsInventory (10 items) — 9 justifiedIntent: split the 7,925-line source-provider handler into per-responsibility modules with zero caller-visible change — a refactor (ADDITION of structure, not a FIX).
The forwarding class is the repo's established per-package pattern (8th instance; 7 exist in [FIRST-PRINCIPLES-REVIEWED] 84ffe73 |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
|
Cross-Platform Portability — disposition for the three flagged added lines ( The gate reads added lines. All three are verbatim moves out of
The gate documents the label as the escape hatch for exactly this case. Rewording the lines only to dodge the regex would be the spelling-chase AGENTS.md rejects, so the code stays as it was. |
|
Opus 5 Review — ✅ no blocking findingsReviewed Review detailsNon-blocking: the relocated GitLab merge-state re-read omits FINDING — src/kiro_crew/dashboard/source_providers/gitlab.py:135 — [OPUS-REVIEWED] 84ffe73 Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
|
|
self-added: yes
This PR merged before its review repairs were pushed. They land in #14603, together with the coordinator's facade-hygiene requirements. Open items on this PR and where each went:
|
The source-provider split merged before its review repairs were pushed. This lands them, together with the facade hygiene the campaign asks every re-export facade to hold. The handler facade keeps forwarding both writes and deletes to the owner module, the canonical re-export pattern, so monkeypatch and mock.patch restore exactly in any nesting order. mock.patch with create=True skips the write-back that restore relies on and would leave the owner without the name, so a guard test refuses any patch in the test trees that may create a forwarded name. It resolves each call from the syntax tree: the patch callable under any alias, and targets through aliases, module-name constants, f-strings and concatenation. A target it cannot resolve fails the guard rather than passing it. The forwarding __getattr__ is hidden from type checkers, and the facade binds every public name it always bound, so a star import sees what it saw before the split. Two tests regain their teeth: the plugin spelling-cap check asks the collector's own module, and the facade write test patches in a private MonkeyPatch instead of undoing the shared fixture mid-test. The spec bullet drops an overclaim and fixes its verb agreement.
The source-provider split merged before its review repairs were pushed. This lands them, together with the facade hygiene the campaign asks every re-export facade to hold. The handler facade keeps forwarding both writes and deletes to the owner module, the canonical re-export pattern, so monkeypatch and mock.patch restore exactly in any nesting order. mock.patch with create=True skips the write-back that restore relies on and would leave the owner without the name, so a guard test refuses any patch in the test trees that may create a forwarded name. It resolves each call from the syntax tree: the patch callable under any alias, and targets through aliases, module-name constants, f-strings and concatenation, reading every test file that names the handler. A target it cannot resolve, a helper call's result included, fails the guard rather than passing it. The forwarding __getattr__ is hidden from type checkers, and the facade binds every public name it always bound, so a star import sees what it saw before the split. Two tests regain their teeth: the plugin spelling-cap check asks the collector's own module, and the facade write test patches in a private MonkeyPatch instead of undoing the shared fixture mid-test. The spec bullet drops an overclaim and fixes its verb agreement.
The source-provider split merged before its review repairs were pushed. This lands them, together with the facade hygiene the campaign asks every re-export facade to hold. The handler facade keeps forwarding both writes and deletes to the owner module, the canonical re-export pattern, so monkeypatch and mock.patch restore exactly in any nesting order. mock.patch with create=True skips the write-back that restore relies on and would leave the owner without the name, so a guard test refuses any patch in the test trees that may create a forwarded name. It resolves each call from the syntax tree: the patch callable under any alias, and targets through aliases, module-name constants, f-strings and concatenation, reading every test file that names the handler. A target it cannot resolve, a helper call's result included, fails the guard rather than passing it. The forwarding __getattr__ is hidden from type checkers, and the facade binds every public name it always bound, so a star import sees what it saw before the split. Two tests regain their teeth: the plugin spelling-cap check asks the collector's own module, and the facade write test patches in a private MonkeyPatch instead of undoing the shared fixture mid-test. The spec bullet drops an overclaim and fixes its verb agreement.
Problem / Motivation
Goal: Maintainers can read and change one part of the pull-request / issue source panel's backend without working through a 7,925-line file, and every caller, patch and HTTP response behaves exactly as before.
src/kiro_crew/dashboard/handlers/source_providers.pyheld everything behind the Changes and Issues panels in one module:gh/glabrunnerIt is one of the most-patched files in the test suite. A change to any one of these parts meant reading all of them, and every open PR in this area collided on the same file.
Why it matters
Every source-provider change pays for the size today: review cost, merge conflicts across the many PRs that touch this file, and the risk of editing a security-relevant rule (redaction, host pinning, the owner gate) without seeing where else it applies. This split is also the first step of the dashboard spec chain B01 → B11 → B12. The Cron and AutoNudge refactors start from a base that contains it.
Not a goal
What changed (motivation → approach → change)
The source panel's backend is now sixteen modules, each named for the one thing it owns, so changing one part means reading only that part. Users and callers see no difference. Each responsibility has one owner module under
src/kiro_crew/dashboard/source_providers/, and the code moved there verbatim: an AST comparison against the base shows every moved definition is identical once sibling qualification is ignored. The handler file keeps the/api/source/*routes, their audit and error mapping, and the dashboard owner gate.contractSourceProviderPlugin, errorssanitizehostspluginslinksrunnergh/glabrunprojectiongithub,gitlab,jiraadfchip_statuscachechip_refreshmutations,reviewCallers and tests patch these names through the handler, so the handler reuses the security package's re-export pattern (#13933).
_OWNED_NAMES/_EXPORTSmap each moved name to the module that holds it. A read resolves the owner fromsys.moduleson each access, and_ReExportModuleforwards a write or delete to that owner. A patch through the handler therefore reaches every caller. For that to hold, owners reach a sibling as a module (runner._run_json(...)) and copy only types. Owners import only owners earlier in the table order, so the owners form no import cycle.Two shared entries follow the move, as granted by the campaign coordinator.
NON_EGRESS_REDACTION_MODULESinsrc/kiro_crew/security_posture.pylists the five owners that call a redactor (adf,cache,chip_refresh,review,sanitize) in place of the handler, which no longer calls one.test_spawn_audit's agent-influenced key now namesdashboard/source_providers/runner.py::_run_provider, the function that spawns the child. The old…::_run_jsonkey named a function with no spawn in it, so that check could not fail.The
learn-cron-dashboard.mdbullet now carries the owner map.Backwards compatibility
Compatible. Every one of the 417 names the handler exposed still resolves at
kiro_crew.dashboard.handlers.source_providers, with the same object. Writes and deletes through it reach the owning module. Every HTTP route, status, body and error code is unchanged. The only intentional differences:jsonandtimeare plain imports on the handler rather than forwarded, because several owners import their own.Tests
test_source_providers_refactor_handlers.py,..._visibility.pyand..._jira.pyare new characterization tests. They pin every handler's status/body/code/audit mapping, the public-repo visibility gate, and the Jira failure messages and request shape. All of them passed against the unsplit base before the move.test_source_providers_refactor_facade.pypins the surface and the protocol:Each check was shown to fail when its property is broken: an export was dropped, forwarding was removed,
githubwas made to copy_run_json, and a handler was made to read a name bare.Two existing owned tests read the module that holds the code they check, since the handler no longer holds it:
test_source_providers.py: the ADF chokepoint scan reads the converter's module.test_source_provider_plugin.py: the check that the transcript-search collector keeps no spelling cap of its own asks the collector's module as well as the handler. Adding that constant topluginsturns it red.Existing: the 707 owned tests and 69 files of adjacent tests (source links, session cards, the owner gate, security posture, error codes, spawn audit, mirrored-owner storage) pass. The only edits to them are the two above and the one-key
test_spawn_auditchange.On Python 3.12 (CI's version):
mypy src/kiro_crew/: clean, and the adjacent and guard files: 5,517 passed, 16 skipped, on production code identical to this head.scripts/local-gate.py --base f57c1dee --dry-runselects 2,251 backend and 1,175 frontend related files, because more than 100 test files import or patch this handler. That is beyond this host's shared test budget, so, with the campaign coordinator's approval, the suites above ran locally and CI owns the full related set. The diff touches nowebsite/**path.Manual verification
Built the wheel and installed it into a separate target. The handler and all 16 owners imported from the installed package, and
dashboard.routes.chatimported against it. Importing each owner module first in a fresh interpreter also works. There is no UI change.Related Issues
no linked issue: campaign scope B01 (source-provider core refactor).
These unclaimed files cite code that moved. They still resolve through the handler, and the campaign coordinator logs them as follow-ups for their owners:
docs/architecture/resource-protection.md:88,:419→source_providers/runner.pydocs/system-specs/modules/security.md:1960(_run_json()audit) →source_providers/runner.py; the owner gate stays in the handlersrc/kiro_crew/hooks.py:4411,src/kiro_crew/sandbox.py:13930→source_providers/runner.pysrc/kiro_crew/history_search.py:543(provider registry) →source_providers/plugins.pytest/fixtures/adf_markdown_safety.json_commentandwebsite/src/test/MarkdownRenderer.adfSafety.test.tsx:18(escape set) →source_providers/adf.pywebsite/docs/extension-seams.md:537,:557→source_providers/plugins.py,source_providers/contract.pyChecklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)