dircue 0.8.0

Dircue 0.8.0 adds declared environment analysis, inert follow-up planning from saved evidence, and offline comparison of focused project and source-availability reports. Each is explicit and opt-in. Existing language commands, including dircue --json, remain supported; the new analysis modules do not run unless requested. Deliberate malformed-input and text-diagnostic corrections are described below.

Inventory declared environments

dircue analyze environments --json /checkout
dircue analyze all --environments --json /checkout

Environment analysis reports language minimums, runtime constraints, toolchain preferences, target frameworks, platform targets, language modes, and project SDK references without running a build or probing installed tools. For .NET projects, it records the nearest selected global.json for an invocation modeled from the project directory, including supported SDK version, roll-forward, prerelease, and search-path declarations.

Requirements remain scoped to their project contexts. Numeric Python constraints are intersected only for a supported comparison subset; unsupported grammar and conditions stay unresolved. The result is declaration evidence, not a claim that a project builds or that a suitable SDK is installed. The declared environments guide documents evidence boundaries and fixed limits.

Build an inert follow-up plan

dircue analyze discovery --json /checkout > first-pass.json
dircue capabilities --json
dircue plan first-pass.json --module declarations --module environments --json

Save the first-pass report outside the inspected directory. dircue plan validates that report and combines retained evidence with the questions or modules selected by the caller. It records supporting observations, prerequisites, candidate quantities, costs, and uncertainties.

Plans never execute commands, reopen the source tree, inspect PATH, probe a structural worker, or contact a service. Each command is a structured, non-executable argument template containing a {source} placeholder. Plans are bound to the exact report bytes and capability version; Git-backed templates preserve the exact retained tree. Missing evidence remains unknown or blocked rather than becoming an instruction to skip inspection. See saved-report follow-up planning for supported questions and safe consumption.

Compare targeted reports offline

dircue compare before.json after.json --json

Reports from 0.7's focus and availability modes can now be compared after their source trees are gone. Primary project files, related projects, shared context, and focused scc metrics remain separate populations. Changed selections or counting policies make a comparison incomparable instead of producing a misleading delta. Partial coverage cannot establish a removal, and availability results retain their acquisition and checkout boundaries.

The comparison reader accepts aggregate reports through schema 1.7.0, so supported modules in a newer aggregate remain usable. Environment and explanation comparison are not supported in 0.8.0.

Corrections from adversarial review

The release also hardens source selection, parsing, validation, and diagnostics. Git snapshots can use an exact immutable --tree selector, and planned commands place -- before the source argument. Corrupt committed sources fail closed instead of silently falling back to a directory scan.

Supported XML and solution readers now accept bounded BOM-signaled UTF-16. Project discovery also recognizes additional MSBuild extensions and strict .slnf solution-filter declarations. global.json accepts supported JSONC comments and trailing commas while continuing to reject malformed or ambiguous values. Structural-worker responses reject duplicate keys, aliases, and unknown fields in every mode.

--on-error continue can retain partial results for recoverable selected-file reads; the default remains fail-fast. Attribute-rule overflow and tree-size limits now produce explicit warnings or skipped modules. Comparison retention is shared fairly across modules, and omitted detail is reported. Text output escapes terminal control characters in filenames while JSON preserves exact paths.

The adversarial review response records every correction, preserved compatibility boundary, and deferred capability.

Compatibility and limits

Environment reports use aggregate schema 1.7.0. Plans and capability descriptions have separate versioned schemas. Existing commands keep their prior default schemas and JSON shapes. Post-review validation matched all 278 inherited cases and all 18 targeted 0.7 cases byte-for-byte for stdout, stderr, and exit status. The candidate also completed 426 Linguist cases with 408 passes, 18 documented expected differences, and no unexpected failures. Six scc conformance checks and the 21-fixture native structural suite passed.

The corrected malformed-input and text-diagnostic behavior is intentionally different. The new features do not expand language catalogs or structural grammars, evaluate build-system conditions and imports, install tools, fetch content, run repository code, or choose and execute a build. Planning can cost more than an unconditional run on small inputs and does not promise a speedup. Recorded language-only measurements varied by workload and run; they support neither a universal improvement nor an absence-of-regression claim.

The 0.8.0 validation report provides the compatibility matrices, performance measurements, source identities, and qualifications.

Downloads

Core archives cover Linux and macOS on AMD64/ARM64, plus Windows AMD64. Wheels contain the same core binaries for installation with Python tooling. The optional structural worker remains a separate archive. Checksums, provenance, native verification receipts, and the new per-platform context receipts accompany the release assets; PyPI publication remains deferred.