Continuous code quality: agentic workflows for refactoring, deduplication, and test coverage

[lpcox]

Problem

As the codebase grows — especially src/docker-manager.ts (3,900+ lines), src/cli.ts (1,700+ lines), and containers/api-proxy/server.js (1,200+ lines post-refactor) — code quality issues accumulate silently:

• Duplicated logic across modules (e.g., env-var parsing patterns, Docker command construction, config generation)
• Large files with multiple responsibilities that should be split
• Test coverage gaps that widen as new features land without proportional test additions
• Dead code and unused exports that accumulate across refactoring cycles
• Inconsistent patterns where similar problems are solved differently in different modules

The recent api-proxy ProviderAdapter refactor (#2409) demonstrated the value of extracting abstractions from a monolithic file. But that was a one-off manual effort. The codebase needs continuous, automated code quality evaluation to catch these issues early and prevent them from compounding.

Proposal

Create a set of scheduled agentic workflows that continuously evaluate different aspects of code quality, similar to how other repositories use daily/weekly agentic workflows for health checks, dependency audits, and code analysis.

Workflow 1: Duplicate Code Detection

Trigger: Weekly schedule + on-demand via workflow_dispatch
Scope: src/**/*.ts, containers/**/*.js

Responsibilities:

• Identify near-duplicate code blocks (functions, patterns, logic sequences)
• Flag copy-paste patterns that should be abstracted into shared utilities
• Track duplication metrics over time
• File issues for high-impact deduplication opportunities

Examples of current duplication:

• Env-var reading/trimming patterns repeated across docker-manager.ts, cli.ts, provider adapters
• Docker exec/run command construction patterns in docker-manager.ts
• Config validation logic duplicated between config-file.ts and schema-validator.ts

Workflow 2: Test Coverage Analysis

Trigger: Weekly schedule + on PR merge to main
Scope: All TypeScript source under src/

Responsibilities:

• Run test coverage and compare against baseline
• Identify files with declining coverage
• Flag new code paths that lack test coverage
• Report uncovered branches in critical security paths (iptables rules, auth injection, domain filtering)
• Post coverage trend reports as GitHub Discussions or issue comments

Priority areas for coverage improvement:

• src/docker-manager.ts — complex container orchestration logic, many untested edge cases
• src/host-iptables.ts — security-critical iptables rule generation
• src/squid-config.ts — domain ACL generation edge cases
• containers/api-proxy/providers/*.js — new adapter modules need comprehensive unit tests

Workflow 3: Refactoring Opportunity Scanner

Trigger: Weekly schedule
Scope: Full codebase

Responsibilities:

• Identify files exceeding complexity thresholds (line count, cyclomatic complexity, function length)
• Flag functions with too many parameters or deep nesting
• Detect modules with mixed responsibilities that should be split
• Suggest extraction points based on logical groupings
• Track refactoring debt metrics over time

Current candidates:

• src/docker-manager.ts (3,900+ lines) — container lifecycle, config generation, volume mounts, env vars, cleanup all in one file
• src/cli.ts (1,700+ lines) — argument parsing, orchestration, signal handling, config merging
• Test files that exceed 1,000 lines and could be split by feature area

Workflow 4: API Surface & Export Audit

Trigger: On PR merge to main
Scope: src/**/*.ts, containers/api-proxy/**/*.js

Responsibilities:

• Detect unused exports (functions, types, constants exported but never imported)
• Flag inconsistent naming conventions across modules
• Identify circular dependencies
• Verify that test files import from the correct modules (not reaching into internal implementation details)

Implementation Notes

• Each workflow should be a separate .md file under .github/workflows/
• Use the Copilot engine with bash and edit tools for code analysis
• Results should be posted as GitHub Issues (for actionable items) or Discussions (for trend reports)
• Workflows should be idempotent — re-running should not create duplicate issues
• Use labels like code-quality, refactoring, test-coverage for organization
• Include network.allowed for any tools that need network access (e.g., fetching coverage artifacts)

Benefits

Metric	Current State	Target
Largest file (docker-manager.ts)	3,900+ lines	< 1,000 lines per module
Test coverage trend	Unknown (no tracking)	Visible, non-declining
Time to add new provider	~2 files + review	1 adapter file (post #2409)
Duplicate code detection	Manual review only	Automated weekly scan
Dead export detection	None	Automated on merge

Related

• Proposal: Refactor api-proxy with provider adapter abstraction #2408 — ProviderAdapter abstraction for api-proxy (demonstrates the value of this kind of refactoring)
• refactor(api-proxy): extract ProviderAdapter abstraction, make core provider-agnostic #2409 — Implementation of the api-proxy refactor