Arid 2.1.0-alpha.1 — Auditable Maintenance Alpha

Arid 2.1.0-alpha.1 is the first public build of the Arid 2.1 release line.

The duplicate detector remains intentionally unchanged from 2.0: Arid still finds exact normalized Python duplicate code and reports DUP001. V2.1 focuses on making accepted maintenance state auditable, discovery decisions explainable, and normal human-facing scan speed visible.

This is an alpha release. The intended v2.1 functionality is code complete, but packaging and real-world prerelease behavior still need validation from the published artifacts before the release line advances toward beta.

What is new

Suppression lifecycle auditing

--suppression-status audits effective # arid: disable regions and classifies each one as either:

• 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

Suppression directives are idempotent state transitions. Repeated disable while already disabled and repeated enable while already enabled are valid no-ops and do not create separate audit records.

A suppression may also run from # arid: disable through EOF. A matching # arid: enable is not required.

Machine-readable suppression audits use the new stable contract:

• schemas/suppression-status-v1.schema.json

Enforce stale maintenance state

--fail-on-stale turns stale maintenance state into exit status 1 when used with either:

• --suppression-status
• --baseline-status <PATH>

Without --fail-on-stale, stale state remains informational.

This supports a maintenance ratchet of zero new duplication + zero obsolete suppression without changing baseline-v1 or automatically mutating source or baseline files.

Explain one discovery decision

--explain-path <PATH> explains why an existing file or directory is included or excluded under the same discovery policy Arid uses for real traversal.

The stable reason vocabulary distinguishes cases including:

• explicit files and directories
• normal discovery
• paths outside scan roots
• Arid excludes
• ignore-file rules
• hidden paths
• unsupported source types
• symlink policy

Path explanation is deliberately targeted. It does not parse Python source, run duplicate detection, or recursively enumerate descendants merely to explain one decision.

Machine-readable path explanations use the new stable contract:

• schemas/path-explanation-v1.schema.json

Bypass ignore files without bypassing Arid policy

--no-ignore-files disables ignore-file-derived traversal filtering for one invocation, including .ignore, .gitignore, parent Git ignore rules, global Git ignores, and .git/info/exclude.

It does not disable Arid's own exclude policy, does not implicitly include hidden paths, and does not change .py / .pyi source selection or symlink behavior.

Administrative JSON file output

Both new administrative modes support direct supplemental JSON output:

arid . --suppression-status --report json=artifacts/suppressions.json
arid . --explain-path src/example.py --report json=artifacts/path.json

The direct JSON file is rendered from the same typed model and renderer as JSON stdout. Text, Markdown, and SARIF supplemental targets are intentionally not supported for these administrative modes.

Visible total scan time

Completed normal text scans now end with a concise human-facing footer such as:

Total time: 18.7 ms

The formatter uses microseconds below 1 ms, milliseconds below 1 second, and seconds at or above 1 second.

Elapsed timing is presentation-only. It is intentionally absent from:

• JSON
• Markdown
• SARIF
• supplemental report files
• report-v4
• suppression-status-v1
• path-explanation-v1
• other versioned machine contracts
• exit-2 failures

Compatibility

Arid 2.1 is additive relative to 2.0.

The following remain unchanged:

• exact duplicate semantics
• DUP001
• report schema v4
• finding fingerprint identity
• baseline schema v1
• baseline fingerprints and comparison arithmetic
• error schema v1
• normal suppression effect
• normalization semantics
• [tool.arid] configuration
• serial default and worker modes
• ordinary scan exit meanings 0 / 1 / 2
• supported Rust API boundary
• supported platform set

The normal text timing footer is an intentional presentation addition and is not part of Arid's deterministic machine-output guarantees.

Pre-publication validation

Before this alpha, the v2.1 branch passed:

• the complete inherited v2 targeted integration suite
• the dedicated v2.1 maintenance/discovery/timing integration suite
• report-v4, error-v1, capabilities-v1, baseline-v1, suppression-status-v1, and path-explanation-v1 schema validation
• real-world validation against Black, Django, mypy, and Rich
• Django worker determinism checks
• Unicode and filesystem path validation
• the full supported-platform non-publishing release workflow build matrix
• v2.0.0 → v2.1 performance regression qualification on Requests, Pydantic, and Polaris

The measured v2.1 candidate showed no material performance regression against v2.0.0 on the canonical benchmark corpora.

Install the alpha

With pip:

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

Expected version output:

arid 2.1.0-alpha.1

The official GitHub Action can be pinned to the alpha tag:

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

What to test

Useful alpha feedback includes:

• suppression audits on repositories with long-lived intentional suppressions
• stale-suppression CI ratchets using --fail-on-stale
• stale baseline maintenance with --baseline-status --fail-on-stale
• --explain-path behavior in monorepos and unusual ignore layouts
• --no-ignore-files behavior alongside Arid exclude and hidden-path policy
• parsing and schema assumptions for suppression-status-v1 and path-explanation-v1
• direct administrative JSON files versus JSON stdout
• timing footer behavior in normal text workflows
• confirmation that machine-oriented formats remain timing-free
• platform-specific packaging, PyPI installation, standalone binaries, and the GitHub Action

Detector-semantic regressions remain important: equivalent 2.0 and 2.1 scans with equivalent settings should identify the same exact normalized duplicate code.

Known release stage

This alpha freezes the two new administrative JSON contracts for the 2.1 release line and begins published-artifact validation.

Product fixes are allowed during prerelease stabilization. New product scope is not. Any incompatible correction to a published v2.1 machine contract requires an explicit versioned contract decision rather than silent schema mutation.