dircue 0.4.0

Dircue 0.4.0 adds file discovery, project-reference graphs, package evidence, configuration declarations, and function metrics. Start with file metadata, then request the detail you need.

The Linguist-compatible command stays the same:

dircue --json

Existing commands keep their output schemas and process contracts. The new optional modules use aggregate schema 1.3.0.

What's new

• analyze discovery inventories selected regular files, including data and vendor paths excluded from language statistics. It reports filename-based manifest and artifact candidates without reading source payloads. Small manifest candidates remain visible beside large XML files; names alone do not establish their contents.
• analyze graph reports .NET project-reference components, cycles, and degrees from supported declarations. Conditional, missing, and unresolved references stay separate. It does not restore packages or evaluate MSBuild.
• analyze packages --syft-report FILE imports bounded native Syft JSON. Explicit path mapping and source binding govern project association. Dircue does not execute Syft or follow paths from the imported report.
• analyze rules --rules-file FILE applies bounded filename, path, and complete-file literal matches. Reports identify the exact ruleset, selected source, and coverage limits. Content matches include source hashes. Repository contents cannot automatically enable rules or disable other modules.
• analyze registries inspects selected NuGet.Config and .npmrc files. It preserves supported declaration order and qualified names, sanitizes URLs to origins, and reports unsupported syntax. It does not infer an effective feed set, read outside the selected source, expand variables, or contact registries. Retained names, origins, and file paths may identify internal infrastructure.
• analyze structure --functions retains bounded function-space metrics from big-code-analysis, with source spans, hashes, and coverage. It reuses the existing native parse across the 20 supported structural languages. Nested metrics retain their provider semantics; the report does not assign code-quality grades.

For example:

# File metadata, including non-code content.
dircue analyze discovery --json /checkout

# Language and project evidence, declared graph, and package-source configuration.
dircue analyze all --discovery --graph --registries --json /checkout

# Source metrics and bounded function evidence; matching worker required.
dircue analyze structure --functions \
  --structural-worker /tools/dircue-structural-worker --json /checkout

The discovery command shares the existing Git/directory selection: at a repository root it reads the selected committed tree. Add --source directory to inspect current filesystem contents instead. Directory mode is a live view, not an atomic snapshot.

Compatibility and measured costs

The retained differential suite compares stdout, stderr, and exit status with the released 0.3.0 executable, covering 209 legacy, project, argument-validation, and native structural cases. Separate tests cover new modules, combined execution, parser bounds, cancellation, source correspondence, and adversarial inputs.

Ordinary language profiling remains independent of these opt-ins. Benchmarks record the additional cost of optional parsing, with input identities, raw samples, and limitations.

Two measured improvements reduce costs within new functionality:

• Reusing validated JSON traversal reduced median function-response decoding time by 26.3% and allocated bytes by 29.9% on the retained 128-entry fixture.
• Lazy canonical field tables reduced allocated bytes by 6.41 MiB per import (1.65%) on the 20,000-package Syft fixture. Its measured latency change stayed within the noise threshold.

These comparisons are between optimized and unoptimized development implementations. They do not establish a whole-repository speedup over 0.3.0, which had neither function evidence nor Syft import. An attempted importer capacity optimization was rejected after increasing memory use on malformed input; that experiment and its result are retained.

Read module status, scope, and omissions before treating an empty result or a total as complete. A successful process can still report bounded or unsupported coverage. No report establishes that a build works, that all dependencies were found, or that follow-up analysis is unnecessary.

Binaries and installation

Core archives support Linux and macOS on AMD64/ARM64, plus Windows AMD64. The Go binary handles language profiling, scc counting, discovery, projects, graphs, rules, registry declarations, and package import without the structural add-on.

Structural analysis needs the matching 0.4.0 worker, supplied separately with dependency sources, license notices, checksums, and provenance. The 0.3.0 worker does not support --functions and rejects that request explicitly.

Attached Python wheels contain the same core binaries and can be installed from a local download with uv or pip. They require Python 3.10 or newer and do not include the structural worker. This release does not publish packages to PyPI.

See the distribution guide, capability matrix, and validation report for supported inputs, evidence, and limits.