Files
marqdo-cli/docs/adr/0002-executables-only-in-function-bodies.md
T
cflmy 49835424ee docs(spec): adopt RFC-LANG-0002 unified language semantics
Replace the Strong/Emph/List/Quote mapping in place with the single
@exec/@knowledge heading-mode model, unified payload carriers and keyword
control flow.

- add the authoritative RFC, ADR-0052 and a historical ADR index
- rewrite spec/mapping.md and spec/expression.ebnf as the normative
  mapping/statement grammar; update evaluation, references, math,
  foreign, package-format, plugin-abi, security and schema notes
- rewrite README, AGENTS, COMPATIBILITY and CHANGELOG for the breaking
  language change; update the architecture index/overview and active docs
- mark superseded planning docs, compute RFCs, evidence and syntax-role
  ADRs as historical/superseded without rewriting their decisions
- add migration guide, per-file inventory and dev-only audit scripts

The frontend/stdlib migration is completed in the following commits; this
commit contains documentation only.
2026-11-21 12:24:19 +08:00

7.4 KiB

ADR-0002: Executable nodes execute only inside level-2 function bodies

Historical / superseded in part. The execution-scope decision (payloads only inside an owning H2 function, never at module top level) remains, but the carrier/role rules in this ADR (Strong executes, Emph returns, lists and quotes are instructions) were replaced by ADR-0052 and spec/mapping.md. The syntax examples below are the syntax at the time of the decision, not current syntax.

Status: Accepted (historical mapping superseded by ADR-0052) Date: 2026-11-20

Context

The blueprint (§1.2 execution context, §3.2 control flow, unresolved issue S-03) establishes that Strong (execute), Emph (return), ordered lists (branch), bullet lists (loop) and block quotes (call) have program meaning inside a function body, i.e. inside the range of a level-2 heading. It leaves the module top level under-specified: if a document has **x = 1** before any function, should that be a hard error, a silent no-op, or an explicit top-level statement?

Two failure modes had to be avoided:

  1. Silent execution at module scope. There is no function frame, no return target and no entry point, so top-level effects would be surprising and would make check/inspect harder to reason about.
  2. Hard error. Ordinary Markdown documents routinely use **bold**, *italic*, 1. ordered and > quotes in prose. Treating every such node outside a function as a fatal compile error would make the language hostile to normal documentation and would break the "renders normally" goal.

The chosen baseline was: executable nodes only execute inside function bodies; elsewhere they are ordinary document content, but this must not happen silently.

Decision

  1. A function body is the child-block range of a heading(level=2) up to the next heading of level ≤ 2 (crates/marqdo-frontend/src/units.rs, FunctionScope.body_start..body_end). Executable roles are assigned only inside those ranges by crates/marqdo-frontend/src/map.rs.
  2. Outside every function body, strong, emph, list and block_quote nodes are inert document content. They are not mapped to IR, are not executed, and prose is not inspected for keywords.
  3. The frontend emits a warning markdown.inert_executable for every would-be execution node found outside a function body. The document still compiles and runs; only check's diagnostic output reflects the warning. The warning is produced once per top-level node and has a hint to move the construct under a ## function heading.
    • block_quote → "a block quote invocation ... is inert document content";
    • list → "a list control structure ...";
    • paragraph → the first strong/emph found in the paragraph ("an execution statement" / "a return statement").
    • warnings are emitted only while scanning the document's direct top-level blocks: headings, tables, code/math blocks and other non-paragraph blocks produce none. A top-level paragraph is walked recursively, so a strong/emph nested under a link or strikethrough inside that paragraph can still produce the inert warning. Nodes inside a function body produce no warning (they are mapped or rejected by the strict executable-shape rules instead).
  4. Warnings do not change exit codes: check exits 0 when there are no error diagnostics even if warnings exist; run/call execute normally. JSON check output sets success = (errors == 0) and includes the warning entries in diagnostics.

Rationale for the nodes covered: these are exactly the block-level constructs that map.rs would otherwise turn into statements if a function body existed. Inline nodes inside a paragraph are covered by one paragraph-level warning rather than one per node, which keeps normal prose readable.

Alternatives

  1. Hard error for every executable-looking node outside a function. Rejected (see context); it forbids emphasis in ordinary Markdown and makes writing a README a compile failure.
  2. Silent inert behaviour with no diagnostic. Rejected: an author could believe top-level **x = 1** had executed. The blueprint explicitly wants invalid execution intent surfaced.
  3. Execute top-level nodes in an implicit module frame. Rejected: no defined entry semantics, no return target, would make imported modules potential side-effect roots (violating "modules register definitions only").
  4. Compile-time error only when the payload parses as a statement. Rejected: this is the forbidden heuristic ("parses as code → execute") from blueprint §1.3; role must come from node type and position, not from guessing.
  5. Warning per AST node. Rejected as noisy for nested content; one warning per top-level construct is enough to point at the problem.

Markdown AST shape

No new node kinds. Relevant structure:

document
  heading(level=2) "f"        <-- opens a function body
    paragraph -> strong(text "x = 1")   <-- executes (Stmt::Assign)
  paragraph (before any heading)
    strong(text "x = 1")      <-- inert; emits markdown.inert_executable
  list(ordered)               <-- inert outside function; warning
  block_quote                 <-- inert outside function; warning

A level-2 heading without a preceding level-1 heading is a module-root function (## main) and its body executes normally. A ### section inside the function range stays inside the function body; headings never execute.

Compatibility

  • Warning code markdown.inert_executable is part of the CLI diagnostic contract. Renaming it requires an ADR and a CLI version note.
  • Making this a hard error later would be a breaking language change: documents that currently compile (with warnings) would stop. If that is ever desired it needs a migration plan (e.g. an opt-in strict lint).
  • No package/ABI/IR shape change: inert nodes are simply absent from the IR.
  • Prose invariance is preserved: editing narrative text outside functions cannot change the IR.

Security

No effect: inert nodes never reach the interpreter, host or kernels. The warning reduces the chance of a false belief that a side effect happened, which is a security-relevant honesty property. A document cannot cause an execute-by-accident through top-level prose.

Testing

  • crates/marqdo-frontend/src/units.rs::tests:: executable_outside_function_warns_but_does_not_execute asserts the warning and that the function index is still built.
  • units.rs tests for function ranges, nested sections, root-level ## main and duplicate/empty headings.
  • crates/marqdo-frontend/src/analyze.rs tests hard errors for invalid executable shapes inside function bodies (the companion rule: when a node is executable, its shape is strictly checked).
  • Conformance/negative fixtures under crates/cli/tests and tests/ (work in progress by the fixtures workstream) are expected to cover the warning and the inert behavior; spec/mapping.md §4 documents the contract.

Migration & rollout

M0.5 ships with warnings. Rollout guidance:

  • document authors move executable constructs under ## function headings;
  • tooling should show the warning in editors (the diagnostic already has a precise span);
  • if a future release makes inert execution a hard error, add a deprecation window and a check flag so existing documents can be migrated.