Design model

Platform spec article

Design model

Back to Build, analyze, and run contract ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (2)

1. 0001-hub-authority Hub authority Accepted

   Hub authority

   Context

   Drift risk.

   Decision

   Hub owns MUST/SHOULD.

   Consequences

   Articles defer.

   Verification anchors

   trudoc.

   Open full ADR page

2. 0002-shared-analysis-pipeline Shared pipeline Accepted

   Shared pipeline

   Context

   CLI/LSP divergence.

   Decision

   Use beskid_analysis aligned with LSP.

   Consequences

   Parity.

   Verification anchors

   pipeline tests.

   Open full ADR page

Articles

• Contracts and edge cases Strict guarantees and failure modes for build, analyze, and run CLI behavior. article Standard
• Design model Conceptual model for `Build, analyze, and run contract` and its subsystem boundaries. article Standard
• Examples Concrete CLI invocations for build, analyze, and run workflows. article Standard
• FAQ and troubleshooting Common questions and fixes for build, analyze, and run CLI behavior. article Standard
• Flow and algorithm Lifecycle and execution flow for `Build, analyze, and run contract`. article Standard
• Verification and traceability Tests and traceability for the build, analyze, and run CLI contract. article Standard

History

0 revisions (git unavailable at build; counts may be empty)

Open full history on GitHub

No commits recorded for this path.

Completeness

OKfeature · 3 SpecSection(s) · 0 H2 heading(s)

Section id	Required	Found
what-this-feature-specifies	yes	yes
implementation-anchors	yes	yes

Full tree: run pnpm verify:platform-spec-layout (writes src/generated/platform-spec-layout-report.json).

Related spec docs

• Area
  CLI

  Parent area

• Feature
  Build, analyze, and run contract

  Parent feature hub

• Area
  Compiler Mods

  Meta host scheduling and diagnostics parity

• Feature
  Stage ordering and lowering

  Host pipeline ordering after graph resolve

Purpose

The beskid executable is a thin orchestration layer over beskid_analysis (project graph, semantic pipeline, document snapshots) and backend-specific drivers (JIT for run/test, AOT for build, CLIF introspection). Every project-scoped command shares the same resolution inputs (ProjectResolveArgs, LockfilePolicyArgs) and must provision bundled corelib before dispatch (ensure_corelib_ready in compiler/crates/beskid_cli/src/cli.rs).

Layered model

flowchart TB
  subgraph cli [beskid_cli]
    Parse[parse / tree / format]
    Analyze[analyze / doc]
    Run[run / test]
    Build[build / mod]
    Pkg[fetch / lock / update / pckg]
  end
  subgraph analysis [beskid_analysis]
    Ctx[CompilationContext]
    Graph[Project graph + CompilePlan]
    Sem[Semantic pipeline + diagnostics]
  end
  subgraph backends [Execution backends]
    JIT[beskid_engine JIT]
    AOT[beskid_aot link]
  end
  Parse --> Ctx
  Analyze --> Ctx
  Run --> Ctx
  Build --> Ctx
  Ctx --> Graph
  Graph --> Sem
  Sem --> JIT
  Sem --> AOT
  Pkg --> Graph

Layer	Responsibility
Argv + global flags	@file expansion, --log-cranelift, subcommand dispatch
Project resolution	Discover Project.proj / Workspace.proj, honor lockfile policy, build CompilationContext
Pipeline observation	Map beskid_pipeline phase IDs to stderr spinners or --plain lines
Command backend	analyze emits diagnostics only; build lowers + AOT; run/test JIT entrypoints

Shared resolution contract

build, run, test, analyze, doc, clif, and format (when given a project input) must enter analysis through the same helpers that construct a CompilationContext for the resolved manifest path. Mod registration on the host compilation must occur after the dependency graph is materialized and before semantic gates, per Stage ordering and lowering.

File-only commands (parse, tree with a single .bd path) may bypass the project graph but still use the parser and formatter crates directly.

Compiler mods on the CLI

Mod projects are graph-discovered packages compiled AOT and loaded during host builds. CLI beskid mod manages artifact cache lifecycle; beskid build / run / test / analyze route mod work through beskid_analysis orchestration—the same entrypoints the LSP uses—so diagnostic codes, capability denial, and generator round caps match IDE behavior.

Concern	Normative rule
Progress	New pipeline phase IDs must surface through the CLI PipelineObserver implementation
Diagnostics	Meta and semantic diagnostics share SemanticDiagnostic / miette shaping
Parity	Changing mod scheduling must update CLI, LSP, and Diagnostics parity together

Implementation anchors

• Subcommand wiring: compiler/crates/beskid_cli/src/cli.rs, compiler/crates/beskid_cli/src/commands/
• Resolution + pipeline UI: compiler/crates/beskid_cli/src/frontend.rs, compiler/crates/beskid_cli/src/project_args.rs
• Analysis services: compiler/crates/beskid_analysis/src/services.rs, compilation_context.rs
• JIT launch: compiler/crates/beskid_engine/
• AOT link: compiler/crates/beskid_aot/