cli_core library

Portable Ball CLI verbs — the single source of truth for the report text produced by ball info, ball validate, ball tree, ball audit, and ball version.

Every function here is a pure Program/Module-IR → report-String transform with no dart:io: the native CLI shells own argv and stream I/O, and this library owns the report text. Because it depends only on the generated proto types (plus the equally-portable capability/termination analyzers), it round-trips through DartEncoder into dart/self_host/cli.ball.json and executes on the Ball engine, so the CLI verbs run identically whether invoked natively or self-hosted (see the parity gate in dart/cli/test/cli_core_parity_test.dart).

Engine-safe authoring rules (this file is round-tripped and executed by the tree-walking engine over proto3-JSON maps, per .claude/rules/dart.md):

  • Prefer explicit for loops over .every/.fold/.where/.firstOrNull.
  • Never mutate a collection via .addAll (mis-routed to list_concat); append per-item with .add.
  • Access a presence-sensitive message/oneof field only after a hasX()/whichX() guard (these route to the ball_proto module).

Functions

analyzeCapabilities(Program program) → Map<String, Object?>
Analyze a Ball program and return a structured capability report Map. Every function is analyzed (whole-program view).
analyzeCapabilitiesReachable(Program program) → Map<String, Object?>
Reachability-scoped capability analysis: analyze only the transitive closure of the program's entry function. Native-only (ball audit --reachable-only).
analyzeModuleCapabilities(Module module, {Iterable<Module> imports = const []}) → Map<String, Object?>
Analyze a library module (e.g. ball_protobuf) plus any inline imports and return its capability report Map. A library has no entry point, so reachability does not apply and every function is analyzed. Native-only (the self-hosted auditReport never audits a bare Module).
analyzeModuleTermination(Module module, {Iterable<Module> imports = const []}) → List<Object?>
Analyze a library module (and any inline imports) for termination and control-flow issues — audited as the Module it is. Native-only.
analyzeTermination(Program program) → List<Object?>
Analyze a Ball program for termination and control-flow issues. Returns the list of warning Maps (empty ⇒ no issues).
auditReport(Program program) → String
The report printed by ball audit <input.ball.json> for a program with default options (all functions analyzed, termination check on). Reuses the shared capability + termination analyzers so the native verb and this function are a single implementation.
buildCapabilityTable() → Map<String, String>
Build the "module.function" -> capability-name table. Provably complete: every base function that can perform a side effect appears here.
capabilityModuleNames() → List<String>
The base module names keyed in buildCapabilityTable, in scan order. The audit's bare-name fallback (lookupCapabilityByName) walks these prefixes, so this list MUST stay in sync with the modules present in the table — the capability_table group in capability_analyzer_test.dart guards against drift and against any bare-name collision that would make the fallback ambiguous.
capabilityNames() → List<String>
The capability category names, in report-iteration order. Each program function is tagged with a subset of these; 'pure' means no side effects.
capabilityRisk(String capability) → String
Risk level associated with a capability name ('none' for 'pure').
checkPolicy(Map report, {Set<String> deny = const {}}) → List<String>
Check a report Map against a deny list of capability names. Returns the list of violation strings (empty = pass). Native-friendly wrapper over the engine-safe checkPolicyViolations.
checkPolicyViolations(Map ctx) → List<String>
Engine-safe policy check: ctx = {report, deny(List<String>)}. Returns a list of violation strings, one per denied call site.
formatCapabilityReport(Map report) → String
Format a capability report Map as human-readable text (byte-identical to the legacy proto-report renderer). Built from a line list joined with \n plus a trailing newline — reproducing StringBuffer.writeln semantics — so it self-hosts on the compiled TS/C++/Rust CLIs (which have no StringBuffer).
formatTerminationReport(List warnings) → String
Format a termination warning List as human-readable text. Built from a line list joined with \n plus a trailing newline (reproducing StringBuffer.writeln) so it self-hosts on the StringBuffer-less compiled TS/C++/Rust CLIs.
infoReport(Program program) → String
The report printed by ball info <input.ball.json> (no trailing newline).
lookupBaseModuleByName(Map table, String function) → String
The base module that declares bare function, or '' if none does. Companion to lookupCapabilityByName (same globally-unique-bare-name guarantee, so at most one module matches) — resolves the owning module so the audit can name the shadowed base function in full, e.g. std_concurrency.mutex_create (issue #420).
lookupCapability(Map table, String module, String function) → String
The capability of a base function call, or '' for non-base / user-defined functions (which are pure by construction — they can only call other functions in this table). table is a buildCapabilityTable() result.
lookupCapabilityByName(Map table, String function) → String
Resolve a base-function capability by BARE function name alone, ignoring the (attacker-controllable) call-site module. Scans the known base modules in capabilityModuleNames and returns the capability of the single base function named function, or '' when no base function has that name.
terminationHasErrors(List warnings) → bool
Whether every warning has severity == 'error' in the list (helper for the native --exit-code gate).
treeReport(Program program) → String
The report printed by ball tree <input.ball.json> (no trailing newline).
validateOk(Program program) → bool
Whether program is valid (no validation errors) — drives the native verb's exit code and stream selection.
validateReport(Program program) → String
The report printed by ball validate <input.ball.json> (no trailing newline). On the valid path this is the Valid: … block; on the invalid path the Invalid: … block. The native verb routes it to stdout/stderr and picks the exit code via validateOk.
validationErrors(Program program) → List<String>
The validation errors for program (empty ⇒ valid). Mirrors the checks the native ball validate verb historically inlined.
versionLine(String version) → String
The line printed by ball version: ball <version>.