Strangler-fig: progressively tighten Ruff complexity thresholds

[sergio-sisternes-epam]

Strangler-fig: progressively tighten Ruff complexity thresholds

Labels: tracking, code-quality

---

Overview

PR #999 introduced Ruff code quality guardrails with complexity thresholds set just above current codebase maximums (strangler-fig pattern). This tracking issue coordinates the progressive tightening of those thresholds through dedicated refactoring PRs.

Current thresholds (baseline from #999)

Metric	Threshold	Current max	Worst offender
max-statements	275	269	mcp_integrator.py::install
max-branches	115	108	mcp_integrator.py::install
max-complexity	100	97	mcp_integrator.py::install
max-args	18	18	commands/install.py
max-returns	18	16	marketplace/publisher.py
file-length (CI)	2400	2316	github_downloader.py

Strangler-fig roadmap

Metric	Current	Stage 1	Stage 2	Stage 3	Target
max-statements	275	200	120	80	50
max-branches	115	60	40	25	15
max-complexity	100	50	35	20	10
max-args	18	15	12	8	5
max-returns	18	12	8	6	6
file-length	2400	1400	800	500	400

Approach

Each stage is a separate sub-issue. A stage PR must:

1. Refactor the functions that exceed the new threshold
2. Update the thresholds in pyproject.toml
3. Pass uv run ruff check src/ tests/ with the tightened values
4. Not change functional behaviour (refactor only)

Sub-issues

• Stage 1: Tame the worst outliers (~5 files)
• Stage 2: Second-tier tightening (~15 files)
• Stage 3: Broad refactoring pass (~35 files)
• Stage 4: Reach target thresholds (~80 files)

References

• PR feat: add Ruff code quality guardrails (replaces black + isort) #999: Ruff guardrails (merged)
• chore: audit F401 noqa suppressions -- genuine re-exports vs dead code #1003: Audit F401 noqa suppressions
• refactor: Stage 1 strangler-fig -- extract mcp_integrator.py::install #1004: Stage 1 draft (superseded by this roadmap)
• chore: enable RUF002/RUF003 (ambiguous Unicode characters) #1005: Enable RUF002/RUF003

[github-actions]

Triage decision

accept

Proposed labels

theme/portability
area/ci-cd
area/cli
type/refactor
status/accepted

Milestone

null -- this tracking issue spans multiple releases; milestone assignment belongs on each stage sub-issue.

Suggested next action

Open a PR for Stage 1 (#1077) targeting mcp_integrator.py::install using the extract-phases decomposition (_validate, _resolve, _deploy, _hooks) and update pyproject.toml thresholds to Stage 1 values.

Suggested issue comment

Thanks for putting this together -- the strangler-fig framing is exactly
the right approach here. Setting thresholds just above the current
maximum avoids CI disruption while creating a directed, measurable
improvement path.

The panel reviewed the roadmap and has a few notes for the implementing
PRs:

- **Stage 1 (#1077):** The extract-phases decomposition for
  `mcp_integrator.py::install` (`_validate`, `_resolve`, `_deploy`,
  `_hooks`) aligns well with the existing `install/phases/` module
  pattern. This is the highest-leverage starting point.
- **High-arg-count functions (Stages 2-3):** Context dataclasses are
  the right tool (matches the `BaseIntegrator`/dataclass patterns
  already in the codebase). Parameter objects will also help
  `install/services.py` and `mcp/command.py`.
- **Stage 4 `max-args=5`:** The issue already flags this as potentially
  aggressive for a CLI tool. Recommend treating it as a target to
  re-evaluate after Stage 3 data is in -- 6-7 may be the pragmatic
  ceiling for CLI-layer functions with many options.
- **Functional equivalence:** Each stage PR should explicitly run the
  full test suite as evidence of no behavioral delta (not just a Ruff
  pass).

The sub-issue structure (#1077 - #1080) makes this contributor-friendly.
Stage 1 is already tagged `good first issue`, which is the right signal
for community engagement at the right entry point.

Accepted and labelled. Stage 1 is the natural next step.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

No CLI surface impact. The initiative is entirely internal (Ruff thresholds in pyproject.toml, refactoring of CLI-layer internals). The benefit to DevX is indirect: lower complexity reduces bugs and lowers the contributor onboarding barrier. The staged structure with sub-issues and verification scripts (uv run ruff check src/ tests/ + wc -l checks) is a clear, contributor-friendly guide. No UX concerns.

Supply Chain Security Expert -- Risk-Surface Reviewer

No risk-surface implication. This issue modifies Ruff linter thresholds and targets code complexity reduction in mcp_integrator.py, install/validation.py, commands/install.py, and github_downloader.py. None of these changes alter dependency resolution, lockfile integrity, authentication flows, path security guards, or package download paths. Complexity reduction in security-adjacent modules (install pipeline, MCP integrator) is a net positive for auditability. No theme/security or theme/governance label required.

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- author is sergio-sisternes-epam with author_association: COLLABORATOR; established contributor with no first-timer tone-tuning required.

Python Architect -- Architecture Reviewer

Architecturally sound roadmap. The strangler-fig pattern (threshold at current max + 1, progressive tightening) is the correct approach to avoid big-bang refactor risk. Stage 1 extract-phases decomposition for mcp_integrator.py::install aligns with the existing install/phases/ module pattern. Context dataclasses for high-arg-count functions (install/services.py, mcp/command.py) match APM's BaseIntegrator/dataclass conventions. No cross-cutting design decision (new interface, new primitive, schema change) blocks Stages 1-3 from proceeding. Stage 4's max-args=5 target is flagged as potentially aggressive -- the issue itself acknowledges this and calls for re-evaluation after Stage 3, which is the right governance hook. Each stage PR must assert test-suite green as functional equivalence proof.

Doc Writer -- Documentation Reviewer

Not activated -- no user-facing documentation surface implied. This is purely internal code quality work (Ruff threshold configuration and refactoring). No new CLI flags, primitives, or authoring concepts introduced. The implementing PRs do not require changes to docs/src/content/docs/.

APM CEO -- Triage Arbiter

Clean accept. The strangler-fig approach avoids the big-bang refactor anti-pattern and creates a staged, measurable improvement path that is contributor-friendly at every level. The sub-issue breakdown (#1077-#1080 with good first issue on Stage 1) is the right community engagement structure. No strategic positioning risk; no breaking changes; no user-facing surface. Milestone assignment is correctly deferred to the stage sub-issues since this parent tracking issue spans multiple releases. theme/portability captures the code quality / maintainability angle; area/ci-cd captures the Ruff gate dimension; area/cli captures the CLI-layer files being refactored.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": "theme/portability",
  "areas": ["area/ci-cd", "area/cli"],
  "type": "type/refactor",
  "status": "status/accepted",
  "priority": null,
  "preserved_labels": [],
  "milestone": null,
  "next_action": "Open a PR for Stage 1 (#1077) targeting mcp_integrator.py::install using the extract-phases decomposition and update pyproject.toml thresholds to Stage 1 values.",
  "comment_markdown": "Thanks for putting this together -- the strangler-fig framing is exactly the right approach here. Setting thresholds just above the current maximum avoids CI disruption while creating a directed, measurable improvement path.\n\nThe panel reviewed the roadmap and has a few notes for the implementing PRs:\n\n- **Stage 1 (#1077):** The extract-phases decomposition for `mcp_integrator.py::install` (`_validate`, `_resolve`, `_deploy`, `_hooks`) aligns well with the existing `install/phases/` module pattern. This is the highest-leverage starting point.\n- **High-arg-count functions (Stages 2-3):** Context dataclasses are the right tool (matches the `BaseIntegrator`/dataclass patterns already in the codebase). Parameter objects will also help `install/services.py` and `mcp/command.py`.\n- **Stage 4 `max-args=5`:** The issue already flags this as potentially aggressive for a CLI tool. Recommend treating it as a target to re-evaluate after Stage 3 data is in -- 6-7 may be the pragmatic ceiling for CLI-layer functions with many options.\n- **Functional equivalence:** Each stage PR should explicitly run the full test suite as evidence of no behavioral delta (not just a Ruff pass).\n\nThe sub-issue structure (#1077 - #1080) makes this contributor-friendly. Stage 1 is already tagged `good first issue`, which is the right signal for community engagement at the right entry point.\n\nAccepted and labelled. Stage 1 is the natural next step."
}

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Note

🔒 Integrity filter blocked 1 item

The following item was blocked because it doesn't meet the GitHub integrity level.

• [BUG] apm install --update fails for GHES/generic hosts due to pipeline probe blocking credential helpers #1082 list_issues: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".

To allow these resources, lower min-integrity in your GitHub frontmatter:

tools:
  github:
    min-integrity: approved  # merged | approved | unapproved | none

Generated by Triage Panel for issue #1076 · ● 566.9K · ◷