chore: audit F401 noqa suppressions -- genuine re-exports vs dead code

[sergio-sisternes-epam]

Context

PR #999 added # noqa: F401 directives to preserve existing import patterns when enabling Ruff's F401 (unused import) rule. Many of these are intentional re-exports (e.g., __init__.py barrels), but some may be genuinely dead code.

Scope

# Current count
grep -r "# noqa: F401" src/ | wc -l    # ~388 suppressions

Task

1. Audit each # noqa: F401 in src/ to classify as:
   • Re-export (intentional): keep the # noqa: F401 or convert to __all__ declaration
   • Dead import (unused): remove the import and the noqa directive
2. For genuine re-exports, consider using Ruff's [tool.ruff.lint.isort] known-first-party or __all__ patterns to make intent explicit
3. Test files (tests/) can be audited separately -- most F401 there are fixture imports or mock targets

References

• Parent PR: feat: add Ruff code quality guardrails (replaces black + isort) #999

[github-actions]

Triage decision

accept

Proposed labels

area/cli
type/refactor
status/accepted
priority/low

Note: No theme/* label applied -- this is pure infra (only area/cli applies, no product surface implication). See label construction rules.

Milestone

0.10.1

Suggested next action

Identify the 5-10 files with the highest concentration of F401 suppressions (e.g. __init__.py barrels) and open a draft PR with the audit classification table to invite early feedback before doing the full sweep.

Suggested issue comment

Thanks for filing this, @sergio-sisternes-epam -- and for the clear scope and reference to #999.

Auditing the ~388 `# noqa: F401` suppressions is a solid code hygiene win. The two-bucket approach (re-export vs dead import) is exactly right:

- **Re-exports** in `__init__.py` barrels: prefer `__all__` declarations over bare `# noqa` to make intent explicit for contributors and linters alike. Ruff's `--select F401 --extend-select F401` respects `__all__` automatically.
- **Dead imports**: safe to remove once tests confirm nothing relies on the transitive import.

Accepted for `0.10.1`. Given the volume (~388), a draft PR with a running classification table (file | line | decision) is the best way to make the work reviewable incrementally. Feel free to start with the highest-density files (likely the `__init__.py` barrels in `src/apm_cli/`) and build from there.

If you find any suppressions hiding genuinely surprising re-export patterns, flag them in the PR -- those are worth a separate discussion about module interface design.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

This is an internal code hygiene issue with no direct user-surface implications. The task is well-scoped: ~388 # noqa: F401 suppressions in src/ to classify as re-exports (keep noqa or convert to __all__) vs dead code (remove). Converting genuine re-exports to __all__ is a Python best practice that improves contributor legibility and makes module contracts explicit. No CLI command, help text, or user-facing flow is affected. The issue maps cleanly to contributor experience improvement rather than any end-user capability.

Supply Chain Security Expert -- Risk-Surface Reviewer

No risk-surface implication. Auditing F401 suppressions is a code hygiene task touching import declarations only -- not download paths, lockfile integrity, marketplace name resolution, MCP configuration, auth, or signing. If anything, removing genuinely dead imports reduces attack surface by eliminating potential import-time side effects from unused modules. No theme/security or theme/governance required.

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- author is a COLLABORATOR with prior project interactions; tone tuning for new or low-interaction contributors is not warranted here.

Python Architect -- Architecture Reviewer

Not activated -- this is a mechanical import audit with no new design decisions, interface changes, or cross-cutting module contracts required. The two options (noqa vs all conversion) are well-established Python patterns that require no architectural deliberation.

Doc Writer -- Documentation Reviewer

Not activated -- dead import cleanup does not affect user-facing CLI surface, API contracts, or documentation pages in docs/src/content/docs/. No area/docs-site secondary label warranted.

APM CEO -- Triage Arbiter

Clear accept. The issue is well-scoped, mechanical, and contributes to codebase maintainability and contributor experience without touching any product surface. Pure infra classification (area/cli only) is correct -- no theme/* label required per label construction rules. type/refactor + priority/low + milestone 0.10.1 (the active development bucket with 42 open issues) is the right home for this work. The human-applied tech-debt label is preserved as-is.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": null,
  "areas": ["area/cli"],
  "type": "type/refactor",
  "status": "status/accepted",
  "priority": "priority/low",
  "preserved_labels": [],
  "milestone": "0.10.1",
  "next_action": "Identify the 5-10 files with the highest concentration of F401 suppressions and open a draft PR with a classification table to invite early feedback.",
  "comment_markdown": "Thanks for filing this, @sergio-sisternes-epam -- and for the clear scope and reference to #999.\n\nAuditing the ~388 `# noqa: F401` suppressions is a solid code hygiene win. The two-bucket approach (re-export vs dead import) is exactly right:\n\n- **Re-exports** in `__init__.py` barrels: prefer `__all__` declarations over bare `# noqa` to make intent explicit for contributors and linters alike. Ruff's `--select F401 --extend-select F401` respects `__all__` automatically.\n- **Dead imports**: safe to remove once tests confirm nothing relies on the transitive import.\n\nAccepted for `0.10.1`. Given the volume (~388), a draft PR with a running classification table (file | line | decision) is the best way to make the work reviewable incrementally. Feel free to start with the highest-density files (likely the `__init__.py` barrels in `src/apm_cli/`) and build from there.\n\nIf you find any suppressions hiding genuinely surprising re-export patterns, flag them in the PR -- those are worth a separate discussion about module interface design."
}

---

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.

Generated by Triage Panel for issue #1003 · ● 613.4K · ◷