Repository navigation
refactor(validation): split validation.py into validation_parts owners - #21524
Conversation
UX Review (Opus 5.5) — ✅ PASSUX-level review of UX-Verdict: PASS Nothing to check. [UX-REVIEWED] cf6a937 Description read[DESCRIPTION-READ] b20e93326ae1f81deca7296edf72ce6998e1275b35622a6b0764554d05e8c588 That sha256 names everything this verdict read: the PR description, plus the 3 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Before merge, check that [DESIGN-REVIEWED] cf6a937 Description read[DESCRIPTION-READ] 42608e7a61d555bad3ce34c442c2df490e362c5b68d2e5fce936407804f9ef93 That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Make sure the disclosed non-move edits (the hard-coded logger name, What this change shipsInventory (8 items) — 8 justifiedIntent: move
[FIRST-PRINCIPLES-REVIEWED] cf6a937 Description read[DESCRIPTION-READ] 610f24db53f2589557533b9c0855b118d3992900e4d795de6d53c38e1fe536f4 That sha256 names the PR description this verdict read. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 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: |
|
Disposition on the Design punchline (
|
|
Disposition on the First Principles punchline (only seven AST-changed units): confirmed, with evidence.
|
validation.py held every MCP tool schema, the FieldSpec engine, the inputSchema validator, the sanitizers and the wire envelopes in one 5,533-line file, far over the 2,000-line cap and edited by most feature PRs. It is now a kiro_crew._facade_mirror facade (559 lines) over 16 owner modules in src/kiro_crew/validation_parts/, each holding one area: input bounds, the text sanitizer, the FieldSpec engine, the inputSchema validator, wire envelopes, and the tool schemas by server and domain. Every unit moved whole; kiro_crew.validation stays the only import path and serves every name as its owner's object, and a patch through it reaches every owner that holds the name. The facade keeps its BASE import header bound (setup.cfg F401 row, guarded by a frozen import inventory test). Non-move edits: the truncation warning keeps the kiro_crew.validation logger name; ValidationError and JsonRpcEnvelopeError keep their kiro_crew.validation __module__; four owner constants carry explicit types so mypy can read them before it has inferred them; a git-ref split is spelled split(sep="/"); two comments and one docstring are reworded for the comment-history and brand gates. Part of #20192
ff519d6 to
cf6a937
Compare
|
Disposition on the Design punchline (
|
|
Disposition on the First Principles punchline (the disclosed non-move edits are the only hunks that differ from a pure move): confirmed, with evidence.
|
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
Approved on behalf of the maintainer: code-move refactor or test split held by the cron on the file cap, the Opus size warning or a path rule alone. Every review lane on the current head is clean (only size notes); the lanes found no behavior change.
Problem / Motivation
Goal:
src/kiro_crew/validation.pydrops from 5,551 lines to a 560-line facade, with every definition in a named owner module, so validation work stops landing in one file far over the 2,000-line cap.validation.pyholds every MCP tool schema, theFieldSpecengine, the inputSchema validator, the sanitizers and the wire envelopes in one 5,551-line file that changes about 30 times a week. AGENTS.md caps a hand-written file at 2,000 lines, and this file is listed in.github/file-line-cap-baseline.txt.Why it matters
Every feature that adds or changes a tool schema edits this one file, so it keeps growing past the cap and every PR that touches it conflicts with every other. A reader has to scroll thousands of lines to find the schema for one server.
Not a goal
kiro_crew.validation.What changed (motivation → approach → change)
validation.pystays the only import path and becomes akiro_crew._facade_mirrorfacade, the shape the earlier splits ofconfig/sections.py,mcp_core.pyandcrew_log/projection.pyuse. The mirror matters here:test_validation.pypatchesvalidation.strip_hidden_unicodeand checks thatsanitize_stringsees the patch, and the mirror writes that patch into the owner that reads it.src/kiro_crew/validation_parts/)input_boundstext_sanitizerfield_engineValidationError,FieldSpec,ToolSchema,validate_tool_argsjson_schema_argsvalidate_mcp_tool_argumentswire_envelopesbuild_tool_response, API bodiescore_agent_schemas,core_turn_schemas,ask_question_cardkirocrew-coretool schemasartifact_schemas,app_schemas,messaging_session_schemas,dashboard_route_schemascron_schemas,computer_use_schemas,opt_in_server_schemas,server_registriesEvery unit moved whole (98.1% of non-import lines unchanged by AST). The facade keeps BASE's import header byte-identical, so names other modules read from it stay bound;
setup.cfggets avalidation.py: F401row for that header, and a frozen import inventory test stands in for F401. The owner list, the new-module rule and the patch reach are recorded indocs/system-specs/modules/security.md.Move audit
Non-move edits, each disclosed:
sanitize_response:logging.getLogger(__name__)->logging.getLogger("kiro_crew.validation"), so the truncation warning keeps its BASE logger name (L25).is_valid_followup_branch:branch.split("/")->branch.split(sep="/"). A git ref split, not a filesystem path; identical call; it avoids the Cross-Platform rule-4 path-separator heuristic, which scans package files.ARTIFACT_SLUG_REandCRON_SESSION_RE: "Used to validate" -> "It validates" / "Validates" (comment-history gate; comment text only, AST unchanged).infer_use_casedocstring: "KiroCrew" -> "Kiro Crew" (brand gate).mypy src/kiro_crew. The facade reaches its owners only through itsTYPE_CHECKINGmanifest, which mypy orders last inside the package-wide import cycle, so a consumer could be checked before the owner it reads and see an untyped call result:_AGENT_NAME_RE: re.Pattern[str]fixessubagent.py: Cannot determine type of "_AGENT_NAME_RE" [has-type];QUALIFIED_MODEL_PATTERN: strfixesdashboard/handlers/core.py: Cannot determine type of "QUALIFIED_MODEL_PATTERN" [has-type];MODEL_ID_RE: re.Pattern[str]fixes the deferral behindacp/runtime_start.py: Cannot determine type of "_dead"andacp/runtime.py: Item "None" ... [union-attr];WORK_LEDGER_RECORD_SCHEMA: ToolSchemafixes 20[arg-type] "str | None"errors indashboard/handlers/work_ledger.py, where the deferred route lost itskeynarrowing inside a nested closure.ValidationError.__module__andJsonRpcEnvelopeError.__module__are set to"kiro_crew.validation"right after each class, so tracebacks and logs keep the dotted name callers import (campaign exception-class rule).FieldSpec,ToolSchemaandMcpTextContentkeep their owner module; nothing reads it.Upstream ports (L16): while this was in review, #20790 rewrote one comment inside
DASHBOARD_PREVIEW_SCHEMA, #20974 and #21296 gaveDASHBOARD_APPLY_SCHEMAan optionaltemplate_idfield and its comment, and #21346 addedCHAT_SESSION_PIN_MOVE_SCHEMAwith itsMCP_DASHBOARD_SCHEMASrow; the recipe re-ran on main, so each unit carries the upstream text byte for byte into its owner (opt_in_server_schemas.py,artifact_schemas.pybesideCHAT_SESSION_PIN_SCHEMA,server_registries.py).Diff alignment (L36):
git diffandgit diff --minimaladd the same lines in every file (validation.py+467/-5458 both ways). Diff size 607 KB.Backwards compatibility
Compatible: every top-level name
validation.pydefined or imported at BASE still resolves onkiro_crew.validationas the same object (pinned bytest_validation_parts_facade.pyandcampaign_facade_inventories/kiro_crew.validation.json); a patch through the facade reaches every owner that holds the name.Reader: src/kiro_crew/session_allocation.py:bounded_session_id -- chat -- imports it from kiro_crew.validation, which serves validation_parts/input_bounds.py's own function (test_validation_parts_facade)
Reader: src/kiro_crew/cli_commands.py:normalize_lesson_category -- release -- imports it from kiro_crew.validation, which serves validation_parts/input_bounds.py's own function (test_validation_parts_facade)
Reader: src/kiro_crew/dashboard/handlers/cron.py:clamp_query_offset -- cron -- imports it from kiro_crew.validation, which serves validation_parts/input_bounds.py's own function (test_validation_parts_facade)
Reader: src/kiro_crew/acp/skill_projection.py:is_registered_agent_name -- subagent -- imports it from kiro_crew.validation, which serves validation_parts/input_bounds.py's own function (test_validation_parts_facade)
Reader: src/kiro_crew/dashboard/chat_handlers.py:normalize_theme_consent_sha -- chat -- imports it from kiro_crew.validation, which serves validation_parts/input_bounds.py's own function (test_validation_parts_facade)
Reader: src/kiro_crew/dashboard/handlers/artifacts.py:infer_use_case -- crew page -- imports it from kiro_crew.validation, which serves validation_parts/input_bounds.py's own function (test_validation_parts_facade)
Reader: src/kiro_crew/mcp_work.py:clamp_report -- subagent -- imports it from kiro_crew.validation, which serves validation_parts/field_engine.py's own function (test_validation_parts_facade)
Reader: src/kiro_crew/computer_use/tools.py:coerce_mcp_tool_args -- chat -- imports it from kiro_crew.validation, which serves validation_parts/field_engine.py's own function (test_validation_parts_facade)
Reader: src/kiro_crew/apps/builtins/mochi/mcp_server.py:coerce_mcp_tool_args_json_schema -- app -- imports it from kiro_crew.validation, which serves validation_parts/field_engine.py's own function (test_validation_parts_facade)
Reader: src/kiro_crew/cloud/ec2.py:validate_field -- crew page -- imports it from kiro_crew.validation, which serves validation_parts/field_engine.py's own function (test_validation_parts_facade)
Reader: src/kiro_crew/computer_use/tools.py:validate_tool_args -- chat -- imports it from kiro_crew.validation, which serves validation_parts/field_engine.py's own function (test_validation_parts_facade)
Reader: src/kiro_crew/apps/builtins/auto_improvement/backend/mcp_server.py:validate_mcp_tool_arguments -- app -- imports it from kiro_crew.validation, which serves validation_parts/json_schema_args.py's own function (test_validation_parts_facade)
Reader: src/kiro_crew/dashboard/handlers/files.py:strip_hidden_unicode -- crew page -- imports it from kiro_crew.validation, which serves validation_parts/text_sanitizer.py's own function (test_validation_parts_facade)
Reader: src/kiro_crew/members.py:normalize_unicode -- crew page -- imports it from kiro_crew.validation, which serves validation_parts/text_sanitizer.py's own function (test_validation_parts_facade)
Reader: src/kiro_crew/acp/kas_wire.py:sanitize_string -- chat -- imports it from kiro_crew.validation, which serves validation_parts/text_sanitizer.py's own function (test_validation_parts_facade)
Reader: src/kiro_crew/mcp_tools/apps.py:sanitize_json_values -- app -- imports it from kiro_crew.validation, which serves validation_parts/text_sanitizer.py's own function (test_validation_parts_facade)
Reader: src/kiro_crew/diagnostics.py:sanitize_response -- release -- imports it from kiro_crew.validation, which serves validation_parts/text_sanitizer.py's own function (test_validation_parts_facade)
Reader: src/kiro_crew/mcp_shared.py:validate_jsonrpc_request -- chat -- imports it from kiro_crew.validation, which serves validation_parts/wire_envelopes.py's own function (test_validation_parts_facade)
Reader: src/kiro_crew/autonudge.py:judge_is_off -- chat -- imports it from kiro_crew.validation, which serves validation_parts/core_agent_schemas.py's own function (test_validation_parts_facade)
Reader: src/kiro_crew/dashboard/handlers/autonudge.py:validate_judge_spec -- chat -- imports it from kiro_crew.validation, which serves validation_parts/core_agent_schemas.py's own function (test_validation_parts_facade)
Reader: src/kiro_crew/dashboard/handlers/ask_question.py:format_ask_answers -- chat -- imports it from kiro_crew.validation, which serves validation_parts/ask_question_card.py's own function (test_validation_parts_facade)
Reader: src/kiro_crew/dashboard/handlers/worktree.py:is_valid_followup_branch -- chat -- imports it from kiro_crew.validation, which serves validation_parts/core_turn_schemas.py's own function (test_validation_parts_facade)
Reader: src/kiro_crew/computer_use/capture_macos.py:build_tool_response -- chat -- imports it from kiro_crew.validation, which serves validation_parts/wire_envelopes.py's own function (test_validation_parts_facade)
Reader: src/kiro_crew/mcp_shared.py:validate_jsonrpc_response -- chat -- imports it from kiro_crew.validation, which serves validation_parts/wire_envelopes.py's own function (test_validation_parts_facade)
Reader: src/kiro_crew/dashboard/handlers/cron.py:validate_string_field -- cron -- imports it from kiro_crew.validation, which serves validation_parts/wire_envelopes.py's own function (test_validation_parts_facade)
Reader: src/kiro_crew/dashboard/chat_runner.py:validate_ask_user_question -- chat -- imports it from kiro_crew.validation, which serves validation_parts/ask_question_card.py's own function (test_validation_parts_facade)
Reader: src/kiro_crew/validation_parts/field_engine.py:clamp_to_max_len -- chat -- validate_field calls it in the same owner; kiro_crew.validation.clamp_to_max_len still resolves to it (test_directive_refusal_not_lost_marker_8635)
Reader: test/test_validation.py:validate_api_body -- release -- kiro_crew.validation.validate_api_body still resolves to validation_parts/wire_envelopes.py's function (test_validation)
Tests
test/test_validation_parts_facade.py: every BASE name resolves as its one owner's object and is listed bydir(); every BASE import stays bound as its home module's object; the owners are exactly the package's modules, lowest layer first, each importing only earlier owners; a fresh interpreter loads every owner from oneimport kiro_crew.validation; the facade imports nothing beyond its frozen inventory (with a planted-import self-test); the two exceptions keep the facade's dotted name in a traceback; the truncation warning logs underkiro_crew.validation;is_valid_followup_branchstill checks each ref component. Each check was mutation-tested: the matching mutation turns it red.test/campaign_facade_inventories/kiro_crew.validation.json(291 BASE public names, 29 rebound to their home modules).test/test_spawn_audit.pyBENIGN_SPAWNS key ->validation_parts/json_schema_args.py::_bounded_pattern_search: the samesubprocess.runmoved byte-for-byte, so its existing entry moves with it (no new exemption);test_benign_allowlist_has_no_stale_entriesis what refuses the old key;test/test_cli_doctor_refactor_facade.pyorigin row foris_registered_agent_name->func:kiro_crew.validation_parts.input_bounds;website/src/test/askQuestionTool.test.tsreads the_ASK_*bounds fromvalidation_parts/ask_question_card.py, and its comment and title name that file. This is a cross-surface parity read of a Python file; no UI changes.setup.cfg: only thesrc/kiro_crew/validation.py: F401per-file row (with its reason comment), after theconfig/sections.pyrow. Touchingsetup.cfgalso starts the desktop, Windows-installer and crew-image build lanes..github/file-line-cap-baseline.txt: thevalidation.pyrow is deleted (the facade is 560 lines; every owner is at most 695).validation.pyas the home of a moved construct now name its owner (path only):ops_mission_control/tests/test_agent_api_tool.py,design_tweak/tests/test_agent_api_tool.py,aws_control/.../common/config.py,artifact_store/rules.py,crew_log/entry_types_ledgers.py,cron_service/fields.py,goal-conductor/scripts/patrol_budget.py,apps/builtins/issue_radar/backend/crew_ledger_spec.md:795.kiro_crew.validation(plus the facade, mirror, inventory, spawn-audit, line-cap, flake-ratchet, posture and import-budget guards),-n 3: 20,478 passed, 41 skipped, 1 failed —test_pytest_asyncio_scan_gate.py, from a local venv carrying pytest-asyncio 0.20.3 instead of the pinned 0.21.2; with the pin it passes (11 passed). Coldmypy src/kiro_crew: no issues in 2,698 files. Per-owner line coverage from that floor plus the cron, panel, work-ledger and turn-metric suites: every owner at 89% or more.test_validation_parts_facade.pypassed 5 runs at-n0and two at-n 3;test_flake_pattern_ratchet.pypasses. Semgrep 1.78 with the CI config on every changed file: 0 findings, no parse errors. Installed wheel from agit archiveexport: every owner imports under an isolated HOME.scripts/local-gate.py --dry-runselects 3,419 backend and 960 frontend test files, past the campaign's local cap, so the floor above ran instead and CI owns the broad matrix.Manual verification
N/A — a structural move with no runtime behaviour change; the unit floor, the facade contract tests and the installed-wheel import smoke cover it.
CI path references
None: no workflow path filter or explicit file list names
validation.py.References not edited (cost)
website/src/utils/askQuestionTool.ts:24,35citevalidation.pyfor_ASK_PAIR_SEPARATOR/_ASK_MAX_ANSWER_LEN; the new home issrc/kiro_crew/validation_parts/ask_question_card.py(left for the batched docs PR under L50, which keeps comment-only website cites out of backend splits).Related Issues
Part of #20192
Follow-up: #21320 (comment cites of
validation.pyinwebsite/src/utils/askQuestionTool.ts, not edited here)Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
Contributions are accepted under the project's Apache-2.0 license.