feat: add HTTP/HTTPS proxy and TLS support (#40)

[alerizzo]

Closes #40. Supersedes #39.

Node's global fetch — used by the generated API client and the MITRE CVE lookup in commands/finding.ts — ignores HTTP_PROXY/HTTPS_PROXY/NO_PROXY, so the CLI is unusable behind a corporate proxy.

Approach

Delegate to configureProxy() from @codacy/tooling (0.1.0 → 0.22.0) — the same function the Codacy Analysis CLI calls. We write no proxy logic. Upstream installs a global undici dispatcher with per-request protocol + NO_PROXY routing, bare host:port normalization, and SSL_CERT_FILE/NODE_EXTRA_CA_CERTS CA loading.

Keeping the implementation upstream is the point: it's what makes the environment contract identical across the Codacy tools. A local copy would drift. AGENTS.md now records that proxy behavior changes belong in analysis-cli's packages/tooling/src/proxy.ts, followed by a dependency bump here.

src/utils/proxy.ts is a thin seam — configureProxyFromEnv() calls upstream and routes its throw into handleError(), giving red Error: <message> and exit 1 like every other failure here. It's a module rather than an inline try/catch because nothing in this repo has ever executed src/index.ts, so inline logic would be the only untestable branch in the feature.

Supported variables — same names as the Analysis CLI and the VS Code extension:

Variable	Purpose
HTTPS_PROXY / HTTP_PROXY (or lowercase)	Proxy URL per scheme; bare host:port accepted
NO_PROXY / no_proxy	Hosts that bypass the proxy (*, .suffix), matched per request
SSL_CERT_FILE / NODE_EXTRA_CA_CERTS	PEM CA bundle for a TLS-intercepting proxy
CODACY_CLI_INSECURE	Disable TLS verification, last resort (warns on stderr)

Behaviorally a no-op when none are set — though not free; see the cost note below.

Why not #39

@rattalur found a real gap and their PR's docs — particularly the curl-works-but-the-CLI-doesn't diagnostic — were better than most. But that implementation hand-rolled the proxy logic with undici@8.10.1 as a direct dependency, and review found:

• undici@8.10.1 requires Node >= 22.19.0, against this package's engines: ">=20". Verified on Node v20.20.2 (latest 20.x): require("undici") throws TypeError: webidl.util.markAsUncloneable is not a function at module load, so codacy --version crashed for every Node 20 user with no proxy configured. Tooling's undici@^6.21.0 supports Node >= 18.17.
• NO_PROXY was evaluated once against the Codacy host, then a process-global agent was installed — so NO_PROXY=cveawg.mitre.org was ignored, and NO_PROXY=app.codacy.com disabled the proxy for everything.
• A bare host:port crashed the CLI with a raw undici stack trace. That form is what curl accepts, i.e. exactly this feature's audience.
• No CA support in code — SSL_CERT_FILE was silently ignored.

That Node 20 regression passed CI, because the proxy tests mocked undici wholesale and nothing executed the entry point. So this PR also adds a smoke step running the built CLI three ways (plain, with HTTPS_PROXY, and with a bad SSL_CERT_FILE expected to fail) on both matrix legs.

Verification

Beyond tsc --noEmit and 614 passing tests, verified against a local CONNECT-logging proxy:

• Node v20.20.2 — dist/index.js --version starts fine (the Add undici-based HTTP/HTTPS proxy support with tests and documentation #39 failure mode)
• Proxy set, no NO_PROXY → both app.codacy.com and cveawg.mitre.org logged
• NO_PROXY=app.codacy.com → only cveawg.mitre.org logged; Codacy went direct. This is the per-request routing Add undici-based HTTP/HTTPS proxy support with tests and documentation #39 could not do
• NO_PROXY=* → nothing proxied
• HTTPS_PROXY=proxy.corp:8080 (bare host) → normalized, no crash
• Bad / non-PEM SSL_CERT_FILE → Error: Failed to read CA certificate ... / No PEM certificate found ..., exit 1
• codacy info end-to-end through the proxy with real credentials → succeeded, CONNECT logged

Startup cost — measured, and now zero

@codacy/tooling@0.22.0 imported undici at module scope rather than behind configureProxy's "nothing configured" early-out, so every invocation paid for loading it — --help and --version included, proxy or not. Measured at 27 ms median against a main build.

0.23.0 fixes it, and this branch takes it. The import now sits behind a memoized lazy factory:

main   (no proxy code)  median 101 ms
this branch (0.23.0)    median 101 ms
delta                            0 ms     (was 27 ms on 0.22.0)

Verified the property directly, not just by timing: requiring the tooling barrel and calling configureProxy() with no proxy env leaves undici out of require.cache, while a configured proxy still loads it.

0.23.0 also replaces the bare Invalid URL a malformed proxy value used to produce with a message that names the setting and redacts credentials:

HTTPS_PROXY="ftp://user:hunter2@proxy.corp:8080"
→ Error: Invalid HTTPS_PROXY value "ftp://user:***@proxy.corp:8080":
  unsupported scheme "ftp:"; expected a URL such as http://proxy.corp:8080

Both changes were filed upstream from this branch's review and are recorded in analysis-cli's docs/tech-debt.md. Checked for upgrade breakage before taking it: the CA-bundle error text is unchanged, so the CI smoke step's substring assertion still holds, and bare host:port plus credentialed proxy URLs still resolve.

Note @codacy/tooling also stops being a phantom dependency: src/types/codacy-config.ts uses export type, which tsc erases, so dist/ previously contained no require("@codacy/tooling") at all.

Dependency is pinned exactly, after a correction

This branch first used ^0.22.0, on the reasoning that upstream proxy fixes would then arrive without a bump PR. That reasoning was wrong, and an adversarial review caught it: for a pre-1.0 package the caret spans patches only (^0.22.0 → >=0.22.0 <0.23.0-0), so it would never have picked up the 0.23.0 that actually carries the fixes. It bought silent patch-level drift — against a dependency this repo has no proxy coverage for, since the 4 unit tests mock it away — and none of the intended upside. Now 0.23.0, pinned exactly, bumps deliberate.

For the record, the related claim that "every other dependency here is pinned exactly" was also wrong: cli-table3 was already ^0.6.3 before this branch.

Known gap

The 4 unit tests mock @codacy/tooling entirely, so they pin only this repo's seam — that we delegate with no overrides, and that a throw becomes exit 1 with the message intact. NO_PROXY matching, scheme routing and bare-host handling are verified upstream and by the manual runs above, but nothing in this repo's CI would catch a regression in them. The smoke step covers construction plus the CA-failure message only. Called out rather than papered over; closing it properly means either integration tests with a local proxy here, or trusting upstream's suite, and that's a judgement call worth making explicitly.

🤖 Generated with Claude Code

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 17 complexity · 0 duplication

Metric	Results
Complexity	17
Duplication	0

View in Codacy

AI Reviewer: first review requested successfully. AI can make mistakes. Always validate suggestions.

_{TIP This summary will be updated as you push new changes.}