dircue 0.5.0

Dircue 0.5.0 adds project declarations and offline comparison of saved profiles. Learn how a directory's projects describe their workspaces, requirements and entrypoints, then compare those observations across snapshots.

The Linguist-compatible command stays the same:

dircue --json

The new capabilities are opt-in. Existing language, metrics, project and structural commands retain their output contracts.

Project declarations

dircue analyze declarations --json /checkout

This command reads supported manifests without classifying unrelated file contents or starting the structural worker. It reports stable manifest-path identities, evidence, requirements, relationships and named interfaces across these ecosystem groups:

• npm: package identity, engines, package-manager declarations, dependency scopes, workspaces, explicit local references, script names and binary entrypoints. Script bodies are withheld.
• Go: module and workspace declarations, minimum language versions, suggested toolchains, dependencies and selected local replacement targets. It does not consult the module cache or installed toolchains.
• Python and uv: pyproject.toml metadata, Python requirements, build backends, dependency groups, named entrypoints, workspace members and supported source mappings. Environment markers remain unevaluated; a lockfile's presence does not establish freshness.
• Cargo: package/workspace membership, supported inherited metadata and dependencies, local paths, explicit targets and build-script observations. Feature selection and automatic target discovery are not fully evaluated.
• .NET: the existing static project/configuration reader's requirements and references, with raw build conditions withheld in this new report.
• Maven and Gradle: the existing Maven declarations and conservative Gradle observations, without executing build logic.

Declarations can be requested alongside other profiling:

dircue analyze all --declarations --discovery --json /checkout

Supported manifests remain visible even when they are excluded from language statistics; installed node_modules manifests are excluded. At a Git repository root, automatic selection normally uses committed HEAD. Add --source directory to inspect current filesystem contents. Directory mode remains a live view, not an atomic snapshot.

A declared relationship or present target does not establish that a build succeeds. Missing, conditional, unsupported and unresolved observations retain their qualifications. Reads, pattern matching and retained output are bounded, with diagnostics and coverage for omitted work. Check module status as well as process success.

Compare saved profiles

dircue compare before.json after.json --json

The inputs are aggregate reports, such as those from analyze all --json or analyze declarations --json. Linguist-style language-only JSON is not a comparison input. Saved reports can be compared after their source directories have been removed; the command does not rescan them or open evidence paths.

Comparison covers supported language/content observations, project and workspace declarations, requirements and interfaces, discovery, registry declarations, caller-rule observations, imported package evidence, and line metrics. Per-file metrics are compared separately when both reports include them. Detailed structural/function and graph comparison remain outside this release.

Each module distinguishes observed changes from changes in provider, policy or selection. Missing provenance and incomplete coverage limit conclusions: absence from a partial report is not automatically a deletion. The caller chooses the pair; dircue does not infer repository identity or renames. Comparison exits zero when valid reports differ. Malformed or unsupported inputs fail explicitly, including oversized numeric tokens and exponents.

Contracts and distribution

Reports containing declarations use aggregate schema 1.4.0. Other profiling invocations keep their existing schemas. Comparison has its own schema 1.0.0, including scope, compatibility, evidence and omission counts.

Both new operations run in the core Go executable without a structural worker, package manager, interpreter or compiler. Core archives continue to target Linux and macOS on AMD64/ARM64, plus Windows AMD64. Python wheels package the same core executables and require Python 3.10 or newer for their launcher; the optional structural worker remains separate. This release does not introduce PyPI publishing.

Release assembly now requires a declaration/comparison smoke receipt for each of the five native platforms. The checks use extracted core executables, synthetic manifests, and offline saved reports; they verify expected facts, unchanged default output, qualified coverage and malformed-input rejection. These gates add five receipts to the existing release asset set, for 44 attached assets. Each receipt identifies the tested executable and inputs; assembly verifies all five platforms and downloads the uploaded assets again to check their hashes.

Each native job also installs its wheel into an isolated environment without contacting a package index, then exercises the installed console command. The release receipt retains those checks, including declaration profiling and comparison after the inspected source has been removed. Linux launcher checks use glibc; the musl wheels receive payload verification but are not executed by those jobs.

See the declaration guide, comparison guide, and capability matrix for supported inputs and limits.

The validation report records compatibility checks, public repository coverage, measured costs and their limits.