feature - build artifact report for generated Rust and emitted outputs

[dannymeijer]

Area

• Compiler (frontend/backend/codegen)
• Tooling (CLI/formatter/test runner)
• Documentation

Problem statement

Incan intentionally emits Rust and native artifacts, but the build surface does not yet provide a stable machine-readable report of what was emitted, which Rust crates/features were involved, which Incan/stdlib modules participated, and where generated outputs live. Users and agents can inspect target/, but that is discover-by-accident rather than a supported contract.

This overlaps with generated Rust inspection work in #567, but the requested surface is broader: a build artifact report that lets tools, CI, docs, and agents understand a build without reverse-engineering directory layout or Cargo output.

Proposed solution

Add a build report output, with exact CLI spelling to be finalized. Candidate surface:

incan build path/to/main.incn --report json
incan build --lib --report json

The report should include, where available:

• schema version
• Incan compiler version and target profile
• source entrypoint or library root
• generated Rust project path
• emitted binary/library/artifact paths
• package name/version from incan.toml
• Rust crate dependencies and enabled features
• Incan dependencies and stdlib modules used
• Rust interop imports/adapters generated or linked
• build policy flags such as offline/locked/frozen
• generated support/helper crates where applicable
• artifact sizes and build timings where cheap and reliable
• warnings or partial-report notes when data is unavailable

The report should complement human build output and generated Rust inspection tooling, not replace them.

Alternatives considered

• Keep printing generated paths in human output only. This helps interactive users but is weak for tools and agents.
• Make chore - v0.4 generated Rust inspection tooling and quality gates #567 own every build-report concern. chore - v0.4 generated Rust inspection tooling and quality gates #567 should stay focused on generated Rust quality and inspection; a build report is a general artifact contract that can also serve package/runtime work.
• Depend on Cargo JSON output directly. Cargo can provide useful low-level data, but Incan needs to report Incan source modules, stdlib surfaces, interop adapters, and compiler-owned artifact semantics.

Scope / acceptance criteria

• In scope:

  • Define a versioned JSON build report schema.
  • Emit the report for executable and library builds.
  • Include generated Rust paths, emitted artifact paths, package metadata, dependency/feature summaries, and build policy flags.
  • Link or reference generated Rust inspection output where chore - v0.4 generated Rust inspection tooling and quality gates #567 provides it.
  • Add tests for report shape on a small executable and a small library build.
  • Document the report as a tooling/agent-facing artifact.

• Out of scope:

  • Exact binary-size attribution by symbol or function.
  • Full compile-time profiling beyond coarse timings already available cheaply.
  • Stabilizing generated Rust internals as public API.
  • Replacing Cargo diagnostics or Cargo's own JSON message format.

• Done when:

  • incan build ... --report json emits a deterministic report for successful builds.
  • The report names the generated Rust project and emitted final artifact paths.
  • The report includes enough dependency/module/interoperability context for tooling to explain what participated in the build.
  • Documentation explains the relationship to chore - v0.4 generated Rust inspection tooling and quality gates #567 generated Rust inspection work.

[dannymeijer]

0.4 triage note: pulled into the 0.4 milestone because this is the concrete build/artifact-report side of the inspection release. Keep the slice narrow: deterministic report schema, generated Rust paths, emitted artifact paths, package/dependency summary, and docs that connect it to #567. Avoid broader profiling or registry/package-manager scope here.