dircue 1.0.1

dircue 1.0.1

dircue 1.0.1 keeps the 1.0.0 CLI and map behavior. It updates the bundled README and adds a separate, manual path for publishing the release's seven platform wheels to PyPI, making a pinned dircue dependency available through ordinary uv sync once that upload is complete.

The PyPI workflow verifies the published GitHub Release, its signed checksums, build attestations, wheel metadata and bundled executable hashes before uploading those exact wheel files. Upload requires approval in the protected pypi GitHub environment and a configured PyPI Trusted Publisher. Neither a tag push nor GitHub Release publication triggers a PyPI upload.

The wheels include the core dircue and dirq commands for Linux x64/ARM64, macOS Intel/Apple Silicon, and Windows x64. The optional structural worker remains a separate download. Python 3.10 or later is required for the wheel launcher; the standalone release archives do not require Python.

Until this version is published on PyPI, install a compatible wheel or standalone archive from this GitHub Release. After PyPI publication, a separate project can pin dircue==1.0.1 in its pyproject.toml and run uv sync on a supported host. See the distribution guide for platform details and installation examples.

dircue 1.0.0

dircue 1.0.0

Try it

dircue map --summary /path/to/checkout
dircue map --json /path/to/checkout > map.json

The directory-map guide documents the schema, coverage semantics, attachments, comparison, routing and SARIF location support. The compatibility policy lists what 1.x keeps stable.

dircue 1.0 adds the map. One deterministic, offline command answers what an unfamiliar directory contains and how it is built and run: projects, deployables, declared interfaces and capabilities, and the relationships between them. Every fact carries evidence identifying its source file and rule; a source span is included when the analyzer can locate one. Every question has a coverage status. The strict Linguist-compatible language commands remain available with their 0.9 output contract; changes to other commands are listed below.

The map

• dircue map [path] writes a portable map document (schema/map.schema.json, schema version 1.0.0) for a committed Git tree or an ordinary directory. Redirected output defaults to JSON; a terminal gets a one-screen summary (--summary). Inspected content is never executed.

• Output. Nodes (content populations, components, deployables, interfaces, capabilities, packages) and edges (contains, member_of, depends_on_local, depends_on, builds, runs, exposes, declares, uses_capability, packaged_in, analyzed_by) have stable IDs derived from paths and declared names. Evidence identifies the source file and rule, with a span when available. Coverage (complete, partial, unknown, not_run, tool_error) includes named reasons. Dockerfile COPY observations include the copy_source and copy_source_stage fact kinds; recognized Maven archive attribution uses the dockerfile_copy_source_matches_maven_archive edge reason.

• What complete means. A question, node or edge says complete only when its evidence is exhaustive for its scope. Heuristic attribution, such as a capability credited to a component by directory containment or a Dockerfile shared by several projects, is partial, with a named reason. Content problems never abort a map; they degrade coverage.

• Components come from static, bounded parsing of 36 component kinds, reported under 27 ecosystem values:

  • npm, Go, Cargo and Python (pyproject, uv, setup.cfg with project metadata, Pipfile, requirements files and their -r includes);
  • Maven, Gradle, .NET and Kbuild;
  • Ruby (Bundler, gemspec, Rails application name) and PHP (Composer);
  • Swift, Dart (including path: dependencies), Elixir, Erlang, Scala (sbt) and Haskell;
  • CMake, Meson and Autoconf;
  • Deno, Bazel, Zig, Julia, R, Clojure and Perl.

  Each component has a role: primary, test, fixture, example, vendored, docs or tooling. The summary leads with primary components. Local project relationships (depends_on_local) come from path, workspace and module references, including Maven reactor sibling dependencies and pub path: dependencies.

• Deployables:

  • Dockerfiles (named by directory);
  • Compose services;
  • Kubernetes objects, one per kind, name and namespace, with every declaring manifest as evidence;
  • Helm charts, one per chart, with static values.yaml images;
  • Terraform modules, one per directory;
  • SAM and Serverless functions, .NET Aspire app hosts, and CI workflows;
  • Maven WAR and EAR packaging, as archive deployables named by finalName or Maven's artifactId-version default, with same-file properties resolved.

• How things build and run. builds and runs edges come from static declarations:

  • Dockerfile co-location;
  • Dockerfile copies that identify a Maven WAR/EAR artifact (dockerfile_copy_source_matches_maven_archive);
  • Skaffold artifacts and exact image references;
  • SAM CodeUri;
  • Aspire AddProject<>();
  • Maven WAR/EAR packaging;
  • GitHub Actions working directories.

  A CodeUri or working directory belongs to the nearest enclosing project root. When that root holds more than one project, the path leaves the repository, or a working directory is created at run time rather than committed, no edge is emitted and the reference is partial with a named reason.

• Interfaces:

  • Go package main binaries;
  • Rust, npm and Python entry points;
  • Spring Boot applications and Maven/Gradle main classes;
  • module-level Flask application objects;
  • declared ports (EXPOSE, including ARG/ENV defaults; Compose ports/expose; Kubernetes containerPort; application listener keys);
  • gRPC services and operations;
  • OpenAPI and Swagger documents and their operations;
  • AsyncAPI documents and GraphQL schemas.

  Runtime prerequisites (npm engines, requires-python) and build backends are recorded as component properties (runtime_requirements, build_backend, build_script), not as interfaces.

• Capabilities (datastores, caches, messaging, search, object storage, auth, HTTP clients, cloud SDKs and more) come from an ecosystem-aware catalog of the most common packages per ecosystem, from declared configuration keys, connection strings and Prisma datasource providers, and from top-level Go and Python imports (including sqlite3). Because Go's net/http also serves inbound requests, it counts as an HTTP client only where a file references a client API; net/http/pprof, httptest, fcgi and cgi never do (rule). There is one capability node per owning component. Optional dependencies (extras, optional and peer dependencies) are conditional. Development-only ones (npm devDependencies, PEP 735 dependency groups, pub dev_dependencies, Pipfile [dev-packages], Gemfile development and test groups) are excluded. Maven test scope is not yet distinguished (#150).

Source identity, forests and hostile filesystems

• Directory maps carry a Git-compatible tree ID computed without Git. A clean checkout has the same ID as its commit's tree, so map compare recognizes the same source across Git and directory maps. Control it with --set source.digest=git|raw|off. On Windows, where Git checks out without executable bits or symlinks and matches names case-insensitively, the digest is partial (windows_checkout_semantics).
• map --forest discovers nested, bare and submodule Git roots, summarizes dependency and build-output trees (node_modules, virtualenvs, target/, …), and accounts for every remaining file. Remote credentials are redacted.
• FIFOs, sockets, devices, symlink loops, escaping symlinks and unreadable directories are skipped with warnings and partial coverage, never followed or fatal.

Joining deeper tools, without importing findings

• map --attach KIND=PATH joins saved Syft, SARIF 2.1.0, OWASP Noir and Bifrost reports:
  • Only facts and run coverage are imported: packages, endpoints, covered files and run state. Findings and verdicts never are.
  • SARIF revision provenance binds a report to the selected commit. --attach-binding caller-asserted records an explicit caller assertion for fully digested directories.
  • Per-attachment record limits degrade coverage instead of failing.
• map route writes inert follow-up plans. map compare compares maps by stable identity; --format markdown gives a readable pull-request summary, and .github/actions/map-diff is a reusable action. map locate annotates SARIF locations with map ownership, with --source-uri and --uri-base for tools that emit container paths or undeclared bases.

Control and measurement

• Presets:

  • balanced (the default);
  • low-memory (fewer workers, a smaller Git object cache, a lower per-file cap; about 60% less peak memory on the Linux kernel);
  • thorough (larger inventory and observation budgets).

  Every setting is typed and visible with map settings, and each is labeled performance-only or coverage-affecting.

• --stats-json PATH writes deterministic cost counters and timings to a separate document, and --cpuprofile/--memprofile write Go profiles. The map document itself is byte-identical across worker counts, locations, locales and time zones.

Git reading

• The binary excludes go-git's transport client, and a build contract test checks the linked executable. The embedded fork's go.mod still downloads unused SSH transport modules. Release binaries are about 11% smaller than 0.9.0, despite the map.
• Git-mode peak memory on the Linux kernel dropped by about 35%.
• SHA-256 object-format repositories and corrupt Git directories fall back to directory mode with a warning.

Distribution

• Two command names. dirq is a shorter name for dircue: the same program, flags, exit statuses and machine-readable output, with help text showing the invoked name. Release archives include dirq (a symlink on Linux and macOS, a copy of the executable on Windows), wheels install both commands, an image built from the Dockerfile has both, and go install github.com/war-and-code/dircue/cmd/dirq@v1.0.0 installs dirq.
• The module path is now github.com/war-and-code/dircue. The maintained Enry, go-git and scc snapshots are embedded in the module with recorded provenance, so no replace directives are needed.
• Release archives for Linux, macOS and Windows (amd64 and arm64 where supported) come with SHA256SUMS and matching Python wheels.
• Every release asset carries a GitHub SLSA build-provenance attestation (gh attestation verify <file> --repo war-and-code/dircue). SHA256SUMS is additionally signed with keyless Sigstore cosign; the bundle (SHA256SUMS.sigstore.json) is attached to the release. See README.md for exact verification commands.
• Bulky evidence receipt files from prior ...

Evidence archive 1

Archived evidence receipts moved out of the repository in #139 (#159).

These files were committed as evidence for earlier releases. They are not regression fences, and no test or CI job reads them. They were removed from the working tree and from all history to keep clones small.

• tests/receipts/evidence-archive.json in the repository lists each file's original path, SHA-256, size and asset name.
• make fetch-receipts downloads, verifies and restores them to their original paths.
• SHA256SUMS covers every asset.

This is not a software release.

dircue 0.9.0

Dircue 0.9.0

Dircue profiles source repositories and other directories of computer content.
This release hardens the current profiling line while 1.0 remains reserved for
the broader directory map described in issue #81.

Highlights

Linguist parity corrections

Language detection now follows the pinned GitHub Linguist 9.7.0 strategy chain
more closely. Filename and extension candidates narrow correctly, Linguist's 23
generic extensions defer to later strategies, and content heuristics inspect the
first 50 KiB. The classifier's separate 50 KiB window is covered by an
adversarial regression test.

These are intentional classification corrections and can change language labels
or totals. The affected cases include Perl scripts with ambiguous extensions and
headers whose distinguishing C++ syntax occurs after the Linguist heuristic
window. Metadata-only discovery keeps filename hints separate from confirmed
language detection.

Bounded Git reads

Git snapshots now use up to three independent object lanes as worker demand
increases. They bound retained pack readers and close storage on success,
failure, and cancellation. The maintained go-git fork avoids repeated replay
when resolving seekable delta bases and closes readers after object-size
lookups and failed pack-cache insertion. Its patch and source provenance are
checked before release.

On a case-sensitive APFS volume containing the same pinned 96,039-path Linux
kernel tree in Git and directory form, three final-source Git runs measured
these medians at 16 workers:

Operation	Git source	Directory source	Git / directory
Code metrics	10.07 s	6.99 s	1.44×
Languages	8.13 s	6.87 s	1.18×

Each Git command produced the same output bytes across runs. Observed peak
resident memory ranged from 789–816 MB (decimal) for metrics and 862–932 MB
for languages. A sampled descriptor check observed 13 open numeric descriptors,
including six pack descriptors. These are observations, not process-wide hard
limits; nested Git deltas can open transient readers beyond the retained-reader
cap. The direct final-binary one-to-16-worker metrics speedup was 4.05×,
compared with 4.69× for directory mode. See the performance receipt
for commands, samples, worker scaling, and a Docker bind-mount case. Docker
Desktop file sharing remains substantially slower than native access on the
tested bind mount; issue #93
tracks that separate bottleneck.

More reliable analysis and comparison

• --on-error continue now retains partial results for supported recoverable
  manifest reads and per-file structural-worker failures. Cancellation,
  startup failures, and protocol violations remain fatal.
• Pattern-only .gitattributes lines are silent no-ops, and supported Cargo
  inherited default-features forms receive edition-aware diagnostics.
• Saved-report comparison can report added or removed languages when both
  warning-free inputs prove that language classification ran. Text comparison
  renders compound identities as readable quoted components while preserving
  stable JSON IDs.
• .NET global.json selection is limited to modeled invocation contexts.
  JSONC syntax is reported explicitly, and independently explained strict-JSON
  gaps no longer make otherwise complete environment coverage partial.
• Directory --tree-size edge behavior remains compatible with Linguist, and
  single-file inspection continues to ignore that directory-only limit.

Better offline guidance

The binary now includes an offline workflow guide, a machine-readable CLI
catalog, and exportable standalone JSON Schemas:

dircue capabilities --guide
dircue capabilities --cli --json
dircue capabilities --schema profile

Help and diagnostics now expose finite choices, suggest nearby supported values,
retain safe underlying error causes, and describe signal termination accurately.
The proposed 1.0 compatibility policy is explicitly a discussion draft: 0.9
keeps the legacy Linguist CLI and JSON as compatibility targets without deciding
whether every existing analyze report becomes a frozen 1.x profile.

Install

While the repository is private, use an authenticated GitHub CLI session to
download the archive for your platform and the attached SHA256SUMS file.
Linux amd64 is shown here:

gh release download v0.9.0 --repo war-and-code/dircue \
  --pattern 'dircue_0.9.0_linux_amd64.tar.gz'
gh release download v0.9.0 --repo war-and-code/dircue --pattern SHA256SUMS
sha256sum -c SHA256SUMS --ignore-missing
tar -xzf dircue_0.9.0_linux_amd64.tar.gz
mkdir -p "$HOME/.local/bin"
install -m 755 dircue "$HOME/.local/bin/dircue"

Core archives are attached for Linux and macOS on amd64 and arm64, plus Windows
amd64. Attached Python wheels contain the same Go executable bytes. Once the
repository is public, a compatible wheel can be installed from its Release URL:

uvx --from \
  https://github.com/war-and-code/dircue/releases/download/v0.9.0/dircue-0.9.0-py3-none-manylinux_2_17_x86_64.whl \
  dircue --breakdown --json /path/to/directory

While the repository remains private, download a compatible wheel with gh
and pass the local file to uvx:

gh release download v0.9.0 --repo war-and-code/dircue \
  --pattern 'dircue-0.9.0-py3-none-manylinux_2_17_x86_64.whl' \
  --dir ./dircue-0.9.0-assets
uvx --offline --no-index \
  --from ./dircue-0.9.0-assets/dircue-0.9.0-py3-none-manylinux_2_17_x86_64.whl \
  dircue --breakdown --json /path/to/directory

The wheels require Python 3.10 or newer. This release does not publish a
package to PyPI. The optional structural worker remains a separate release
archive.

Validation

• The Linguist differential suite completed 600 cases with 582 passes, 18
  documented expected differences, and no unexpected failures.
• Dircue's maintained classifier matched the labels and ordered token
  sequences of all 3,388 pinned Linguist samples; stock Enry is measured
  separately in the conformance notes.
• The source-bound corrected Linux kernel profile matched independent Linguist
  parsed JSON values exactly across all 25 reported languages.
• The 0.8 compatibility gates passed all 319 cases: 304 exact results, 12
  reviewed diagnostic improvements, and three narrowly asserted correctness
  fixes.
• Maintained-fork manifests and regeneration checks passed, along with targeted
  race tests and go vet.

See the changelog
for the complete list of changes and the
capability guide
for supported inputs and current boundaries.

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.

dircue 0.7.0

Dircue 0.7.0 adds focused project profiling, source-availability evidence, and explanations of profiling decisions. Each is opt-in. Existing language commands, including dircue --json, retain their output and exit-status contracts.

Profile a project in its original context

Select a .NET or Python/uv manifest from the original repository or directory root:

dircue analyze focus --project services/app/app.csproj --metrics --files --json /checkout

Dircue inventories the selected source, reads supported declarations, and identifies a qualified project population. Shared configuration and declared relationships remain visible as context. Nested unsupported or malformed projects establish boundaries instead of silently becoming part of their parent.

Optional scc metrics count the primary population. Additional --related-project selections receive separate totals. --affected-by Directory.Build.props queries projects with declared or candidate context relationships to that input.

This is static containment and declaration evidence. It does not evaluate compiler globs, conditions, imports, or build scripts, and it does not claim to reproduce a compiler's complete source list.

Distinguish absent content from acquisition boundaries

dircue analyze availability --json /checkout

The report distinguishes valid Git LFS pointers, pointer-like text, LFS attributes, Gitlinks, submodule declarations, and supported local sparse-checkout metadata. Combined analysis can qualify missing declaration targets against observed boundaries:

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

No repositories are fetched, submodules initialized, or LFS objects hydrated. Checkout sparsity is kept separate from committed-tree evidence. Reads, retained observations, and correlation work are bounded; incomplete evidence stays visible.

Explain a result

dircue analyze explain --file src/main.go --json /checkout
dircue analyze explain --project services/app/app.csproj --json /checkout
dircue analyze explain --file src/main.go --report saved-profile.json --json

Fresh file explanations follow the actual language decision path and retain applicable attribute origins, read extent, detection strategy, and inclusion or exclusion reasons. Project explanations expose retained declaration facts and unresolved relationships.

Saved-report queries never reopen the recorded source. They identify the supplied report bytes and distinguish unavailable evidence from an observed decision. A file absent from a retained inclusion list is not automatically labeled excluded.

Compatibility and scope

Only the new targeted modes use aggregate schema 1.6.0. Existing unfocused schemas remain unchanged. Saved-report comparison explicitly rejects 1.6.0 until it can account for focused populations; saved explanations can read it now.

All three capabilities run in the core binary without the structural worker. Focus supports .NET and Python/uv selection in this release; language profiling retains its broader existing coverage. Focused metrics still pay for the original-root inventory and declaration pass, so small inputs may see no speed benefit.

CI separates ordinary draft updates from full-validation concurrency lanes. Packaged-binary checks now exercise all three capabilities on each supported native platform, and release assembly requires matching receipts.

The candidate validation report records compatibility results, focused-workflow 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, and native verification receipts accompany release assets; PyPI publication remains deferred.

dircue 0.6.1

Dircue 0.6.1 improves bounded file reads and strengthens aggregation checks. Existing commands, output schemas, read limits and exit-status contracts are preserved.

Faster bounded reads

The scanner uses capped file-size hints to reduce allocation when reading ordinary files and Git objects. Hints affect allocation only: read limits still determine how much content is inspected, and files that grow or shrink retain the existing read behavior.

The final eight-input comparison against the 0.6.0 runtime found:

Workload	Median runtime change	Median peak-memory change
XML directory, aggregate analysis	33.90% faster	7.58% higher
XML directory, language analysis	12.29% faster	4.96% lower
Roslyn directory, aggregate analysis	3.27% faster	5.88% lower
Spring Framework Git, aggregate analysis	1.46% faster	4.51% lower

XML aggregate analysis took 64.65 → 42.73 ms, with median process peak RAM 67.53 → 72.65 MiB. Measurements used warm caches on one macOS ARM64 host. The XML fixture contains 2 GiB, but profiling reads bounded prefixes; this is not full-content throughput. Small timing differences on source repositories may be noise, and Roslyn's Git scan had a small memory increase.

Language and aggregate output matched byte-for-byte on every input. All samples, source identities and tradeoffs are retained.

Stronger aggregation checks

Independent Go and Rust property tests compare hotspot aggregation against full-population references. Mutation tests detected all 17 deliberately introduced defects, with passing baseline and restored-code controls.

Optional Bend reference models have 35 checked laws for histogram aggregation and top-K selection, supplemented by executable comparisons and negative controls. These are model proofs and production tests, not proof of the whole application. Bend is not a runtime dependency and does not need to be installed for ordinary CI.

Reader validation includes changing files, short reads and 5,040 compressed Git-stream comparisons. The full Go race suite and vet passed. All 278 retained CLI compatibility cases matched stdout, stderr and exit status; Linguist conformance recorded 404 matches, 16 documented extensions and zero failures.

Resource choices and documentation

The resource guide explains existing concurrency controls and GOMEMLIMIT, a soft Go memory target. It is not a hard process-memory ceiling, and no new memory-limit flag or global garbage-collection setting is introduced. The design principles distinguish analysis scope from execution preferences and require visible coverage limits.

Downloads

Choose the core archive for Linux or macOS on AMD64/ARM64, or Windows AMD64. Structural analysis additionally requires its matching structural-worker archive.

Attached wheels contain the core binary for installation with Python tooling; the worker remains separate. Checksums, provenance and native verification receipts accompany the assets. PyPI publication remains deferred.

dircue 0.6.0

Dircue 0.6.0 adds bounded file-format inspection and function hotspot distributions. Learn more about mixed directories, then select deeper source analysis where it is useful.

Inspect data and artifacts

dircue analyze formats --json /path/to/content
dircue analyze all --formats --discovery --json /path/to/content

Format evidence includes selected vendor and data files that language statistics may exclude. It distinguishes filename hints, header signatures, parsed prefixes and complete supported syntax checks. JSON, XML, UTF-8 text and empty-file checks accompany signatures for several archive, executable, document and image formats.

Reads are bounded to a 64 KiB prefix plus at most one lookahead byte per file, 32 MiB total, and 4,096 candidate files. Coverage and omissions remain visible. XML is not automatically a log; signatures do not establish archive integrity. Nothing is decompressed or executed.

Find measured structural hotspots

dircue analyze structure --hotspots --json \
  --structural-worker /path/to/dircue-structural-worker /checkout

The optional worker reuses its BCA / Tree-sitter parse to measure eligible function spaces before limiting retained evidence. Each language and clean/recovered syntax cohort gets exact fixed-bin distributions and top-ten evidence for BCA cyclomatic sums and physical line spans.

Late functions can rank even when they fall beyond the older function-list caps. Source locations, hashes, measurement definitions and missing populations accompany the results. Nested spaces may overlap; these are inspection aids, not repository grades or defect predictions.

Compare saved observations

dircue compare before.json after.json --json now supports format observations and qualified hotspot distributions. Leaving a top-ten list is not treated as function deletion. Comparison runs offline without reopening the source directories.

The new modules use aggregate schema 1.5.0 only when requested. Existing language, discovery, declaration and other profiling commands retain their contracts. Hotspots require a worker that advertises the new capability; ordinary structural commands continue to work with the previous supported worker.

Downloads

Choose the core archive for Linux or macOS on AMD64/ARM64, or Windows AMD64. Format inspection needs only that core binary. Hotspots additionally require the corresponding structural-worker archive.

Attached wheels contain the core binary for installation with Python tooling; the structural worker remains separate. Checksums, provenance and native verification receipts accompany the assets. PyPI publication remains deferred.

See the format guide, hotspot guide, and validation report for definitions, measured costs and coverage limits.

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.

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.