Arid 2.1.0 — Auditable Maintenance

Arid 2.1 makes maintenance and discovery decisions auditable without changing the detector itself.

Auditable maintenance. Explainable discovery. Same focused detector.

Arid still finds exact normalized Python duplicate code and reports DUP001. V2.1 adds suppression lifecycle auditing, stale-maintenance enforcement, targeted path explanation, an ignore-file traversal override, deterministic administrative machine contracts, and a concise human-facing total scan-time footer around that same detector.

Highlights

Suppression lifecycle auditing

--suppression-status audits every effective Arid suppression region and classifies it as exactly one of:

• active — removing the suppression would expose otherwise-reportable duplicate code or allow a duplicate to cross the suppression boundary
• stale — the suppression is no longer needed under the current analysis settings

arid . --suppression-status
arid . --suppression-status --json

Suppression directives are idempotent state setters:

• # arid: disable while already disabled is a valid no-op
• # arid: enable while already enabled is a valid no-op
• # arid: disable through EOF is valid and does not require a matching enable

The audit uses one suppression-disabled preparation view and one normal detector pass rather than rerunning duplicate detection once per region.

Stale-maintenance enforcement

--fail-on-stale can turn obsolete accepted state into exit status 1 for both suppression and baseline maintenance:

arid . --suppression-status --fail-on-stale
arid . --baseline-status arid-baseline.json --fail-on-stale

This supports a maintenance ratchet of:

zero new duplication + zero obsolete suppression

Existing baseline comparison, pruning, serialization, fingerprints, and baseline-v1 compatibility remain unchanged.

Explainable discovery

--explain-path <PATH> explains why one path is included or excluded by the effective Arid discovery policy:

arid . --explain-path src/generated/example.py
arid . --explain-path src/generated/example.py --json

Path explanation reuses the same discovery policy as real traversal. It does not parse Python, run duplicate detection, or recursively enumerate a directory tree merely to explain one target.

The deterministic path-explanation-v1 contract reports the path, kind, symlink/explicit state, include/exclude decision, and stable reason vocabulary.

Ignore-file traversal override

--no-ignore-files disables ignore-file-derived filtering for one invocation:

arid . --no-ignore-files
arid . --list-files --no-ignore-files

It bypasses ignore-file sources such as .ignore, .gitignore, global Git ignores, parent ignore files, and .git/info/exclude.

It does not bypass Arid's own configured/CLI exclude rules, hidden-path policy, .py / .pyi source selection, or symlink policy.

Deterministic administrative JSON

V2.1 adds two versioned machine contracts:

schemas/suppression-status-v1.schema.json
schemas/path-explanation-v1.schema.json

Both administrative modes can write direct JSON files with:

--report json=PATH

For the same invocation, JSON stdout and the direct administrative JSON file are rendered from the same typed model and are byte-equivalent.

The existing 2.0 machine contracts remain unchanged, including:

• report-v4
• error-v1
• baseline-v1
• capabilities-v1
• finding fingerprint identity
• SARIF 2.1.0 integration

Human-facing total scan time

Completed normal text scans now end with a concise timing footer:

Total time: 18.7 ms

Timing is deliberately presentation-only.

It is absent from:

• JSON
• Markdown
• SARIF
• supplemental report files
• exit-2/incomplete output
• report-v4 and every other versioned machine contract

The footer uses adaptive microsecond, millisecond, or second units and does not introduce a profiling, telemetry, or per-stage timing framework.

Compatibility with Arid 2.0

V2.1 is additive and preserves the qualified 2.0 detector and contracts.

Unchanged behavior includes:

• exact normalized duplicate semantics
• DUP001
• report schema v4
• finding fingerprints
• baseline schema v1 and existing baseline files
• error schema v1
• normal suppression effect
• normalization semantics
• [tool.arid] configuration
• normal CLI invocation
• serial default execution
• numeric --workers N
• --workers auto
• ordinary scan exit meanings 0 / 1 / 2
• supported release platforms

The new CLI controls are:

--suppression-status
--fail-on-stale
--explain-path <PATH>
--no-ignore-files

The only intentional ordinary text-output addition is the Total time: footer on completed normal text scans.

Qualification

Arid 2.1 was qualified through source, prerelease, published-artifact, real-world, and performance validation.

The release line passed:

• the full inherited v2 integration suite
• the focused v2.1 suppression, stale-policy, discovery, path-explanation, administrative-output, and timing suite
• Black, Django, mypy, Rich, Unicode/space-path, malformed-source, and worker-determinism validation
• the production release build matrix on Linux x86-64, Linux aarch64, macOS arm64, macOS x86-64, and Windows x86-64
• exact published GitHub standalone validation
• exact published PyPI installation validation
• suppression-status-v1 and path-explanation-v1 schema validation against published executable output
• administrative JSON stdout/direct-file byte-equivalence validation

The published 2.1.0-beta.1 artifact also passed the full real-world detector campaign directly, rather than only a repository build.

A disposable real-Polaris-layout beta exercise verified:

• one suppression around a real Polaris duplicate classified active
• one deliberately unnecessary disable-through-EOF suppression classified stale
• suppression JSON was byte-deterministic across workers 1 and 4
• --fail-on-stale enforced stale maintenance with exit 1
• an ignored Python path was explained as ignore-file
• repeated path explanation was byte-deterministic
• --no-ignore-files made the ignored Python path includable
• --explain-path agreed with actual --list-files traversal
• normal text contained exactly one Total time: footer
• machine JSON remained timing-free

No product, packaging, machine-contract, or detector-semantic defect was found during beta stabilization.

Performance

The final release qualification compared the published Linux x86-64 2.0.0 artifact directly against the published Linux x86-64 2.1.0-beta.1 artifact on the same machine, using the same pinned Requests, Pydantic, and Polaris corpora with Hyperfine.

Corpus       v2.0.0       v2.1 beta    Delta
requests      17.08 ms      16.57 ms    -3.03%
pydantic     239.69 ms     238.80 ms    -0.37%
polaris      503.95 ms     503.59 ms    -0.07%

No measurable performance regression was found.

Install

With uv:

uv tool install "arid==2.1.0"
arid --version

Or with pip:

python -m pip install "arid==2.1.0"
arid --version

Expected output:

arid 2.1.0

Official GitHub Action

- uses: sponge-b0b/arid@v2.1.0
  with:
    paths: .

The tagged Action installs the exact released PyPI package version encoded in its release metadata.

Machine-readable contracts

Published Arid-owned schemas are under schemas/:

• report-v4.schema.json
• error-v1.schema.json
• capabilities-v1.schema.json
• baseline-v1.schema.json
• suppression-status-v1.schema.json
• path-explanation-v1.schema.json

Arid 2.1 keeps duplicate detection focused and familiar while making accepted duplication state maintainable, filesystem discovery explainable, automation contracts deterministic, and normal scan speed visible to humans.