Correct results of steps with mixed prose and function calls (#123)

The output of exec() calls was already recorded in a `Return` line, but
that value was being duplicated as the enclosing step's `Result`. That
led to clarifying the place of code inlines in descriptive paragraphs,
and realizing we could translate the prose as a no-op `Operation::Prose`
variant so that if trailing prose is present then the result of the step
is then correctly the `Unitus` value.

This extended into the anonymous "Step 0" created when consequential
operations are present in a procedure description. This has been
re-translated as `Operation::Prelude` and then if function calls are
present then they are properly entered and recorded.

Cleanup noise from test output.

Author: istathar

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "technique"
-version = "0.6.2"
+version = "0.6.3"
 edition = "2021"
 description = "A domain specific language for procedures."
 authors = [ "Andrew Cowie" ]

Cargo.toml

@@ -256,11 +256,7 @@ pub fn render_description<'i>(paragraphs: &'i [Paragraph<'i>], renderer: &dyn Re
 }
 
 /// Render step's without descending into nested subscopes.
-pub fn render_step<'i>(
-    scope: &'i Scope,
-    subs: &'i Substitutions,
-    renderer: &dyn Render,
-) -> String {
+pub fn render_step<'i>(scope: &'i Scope, subs: &'i Substitutions, renderer: &dyn Render) -> String {
     let mut sub = Formatter::new(78);
     sub.substitutions = Some(subs);
     match scope {

src/formatting/formatter.rs

@@ -80,7 +80,7 @@ fn link_operation<'i>(
                 link_operation(arg, library, problems);
             }
         }
-        Operation::Sequence(ops) => {
+        Operation::Sequence(ops) | Operation::Prologue(ops) => {
             for op in ops {
                 link_operation(op, library, problems);
             }
@@ -114,6 +114,7 @@ fn link_operation<'i>(
         Operation::Variable(_)
         | Operation::Number(_)
         | Operation::Multiline(_, _)
+        | Operation::Prose(_)
         | Operation::Hole => {}
     }
 }

src/linking/linker.rs

@@ -128,7 +128,13 @@ pub enum Operation<'i> {
     Invoke(Invocable<'i>),
     Execute(Executable<'i>),
     Hole,
+    Prose(&'i str),
     Sequence(Vec<Operation<'i>>),
+    /// The executable work hoisted from a procedure's description is an
+    /// anonymous "step 0". Present only when the description carries
+    /// instructions, not for prose alone. Its outcome folds into the
+    /// procedure's own sign-off rather than prompting itself.
+    Prologue(Vec<Operation<'i>>),
     Section {
         numeral: &'i str,
         title: Option<Box<Operation<'i>>>,

src/program/types.rs

@@ -105,7 +105,7 @@ fn resolve_operation<'i>(
                 resolve_operation(arg, known, arities, problems);
             }
         }
-        Operation::Sequence(ops) | Operation::List(ops) => {
+        Operation::Sequence(ops) | Operation::List(ops) | Operation::Prologue(ops) => {
             for op in ops {
                 resolve_operation(op, known, arities, problems);
             }
@@ -144,6 +144,7 @@ fn resolve_operation<'i>(
         Operation::Variable(_)
         | Operation::Number(_)
         | Operation::Multiline(_, _)
+        | Operation::Prose(_)
         | Operation::Hole => {}
     }
 }
@@ -172,7 +173,7 @@ fn gather_iterated<'i>(op: &Operation<'i>, iterated: &mut HashSet<&'i str>) {
             gather_iterated(body, iterated);
         }
         Operation::Bind { value, .. } => gather_iterated(value, iterated),
-        Operation::Sequence(ops) | Operation::List(ops) => {
+        Operation::Sequence(ops) | Operation::List(ops) | Operation::Prologue(ops) => {
             for op in ops {
                 gather_iterated(op, iterated);
             }
@@ -209,6 +210,7 @@ fn gather_iterated<'i>(op: &Operation<'i>, iterated: &mut HashSet<&'i str>) {
         Operation::Variable(_)
         | Operation::Number(_)
         | Operation::Multiline(_, _)
+        | Operation::Prose(_)
         | Operation::Hole => {}
     }
 }
@@ -231,7 +233,7 @@ fn mark_iterated<'i>(op: &mut Operation<'i>, iterated: &HashSet<&str>) {
             }
             mark_iterated(body, iterated);
         }
-        Operation::Sequence(ops) | Operation::List(ops) => {
+        Operation::Sequence(ops) | Operation::List(ops) | Operation::Prologue(ops) => {
             for op in ops {
                 mark_iterated(op, iterated);
             }
@@ -268,6 +270,7 @@ fn mark_iterated<'i>(op: &mut Operation<'i>, iterated: &HashSet<&str>) {
         Operation::Variable(_)
         | Operation::Number(_)
         | Operation::Multiline(_, _)
+        | Operation::Prose(_)
         | Operation::Hole => {}
     }
 }
@@ -322,7 +325,7 @@ fn check_scope<'i>(
             }
             check_scope(body, scope, problems);
         }
-        Operation::Sequence(ops) | Operation::List(ops) => {
+        Operation::Sequence(ops) | Operation::List(ops) | Operation::Prologue(ops) => {
             for op in ops {
                 check_scope(op, scope, problems);
             }
@@ -356,7 +359,10 @@ fn check_scope<'i>(
                 check_scope(&entry.value, scope, problems);
             }
         }
-        Operation::Number(_) | Operation::Multiline(_, _) | Operation::Hole => {}
+        Operation::Number(_)
+        | Operation::Multiline(_, _)
+        | Operation::Prose(_)
+        | Operation::Hole => {}
     }
 }
 

src/resolution/resolver.rs

@@ -15,7 +15,7 @@ fn text(s: &str) -> Value {
 // evaluator takes once a call is resolved.
 fn call(name: &str, args: &[Value]) -> Result<Value, RunnerError> {
     let library = Library::core();
-    let context = Context::native();
+    let context = Context::capture();
     let id = library
         .resolve(name)
         .expect("builtin registered");
@@ -27,7 +27,7 @@ fn call(name: &str, args: &[Value]) -> Result<Value, RunnerError> {
 fn call_system(name: &str, args: &[Value]) -> Result<Value, RunnerError> {
     let mut library = Library::core();
     library.extend(Library::system());
-    let context = Context::native();
+    let context = Context::capture();
     let id = library
         .resolve(name)
         .expect("builtin registered");

src/runner/checks/library.rs

@@ -1310,6 +1310,70 @@ check :
         .any(|r| r.path == "/check:/2"));
 }
 
+#[test]
+fn description_instruction_records_under_step_zero() {
+    // An exec in the procedure description runs in the anonymous step-0
+    // Prologue scope, recording under the `/0` path ahead of the steps.
+    let source = r#"
+% technique v1
+
+check :
+
+Prepare the ground { exec("true") } before the steps.
+
+1.  Do the work.
+        "#
+    .trim_ascii();
+    let document = parsing::parse(Path::new("Test.tq"), source).expect("parsed");
+    let mut program = translate(&document).expect("translated");
+    resolve(&mut program).expect("resolve");
+    let mut library = Library::core();
+    library.extend(Library::system());
+    crate::linking::link(&mut program, &library).expect("linked");
+
+    let mut fixture = StoreFixture::new("description-step-zero");
+    let mut runner = Runner::new(
+        &program,
+        fixture.take_appender(),
+        HashMap::new(),
+        Automatic::with_handle(Vec::new()),
+        library,
+    );
+    runner
+        .run(Environment::new())
+        .expect("run");
+
+    let pfftt = fixture.pfftt_contents();
+    let records: Vec<_> = pfftt
+        .lines()
+        .filter_map(|line| parse_record(line).ok())
+        .collect();
+    let zero: Vec<_> = records
+        .iter()
+        .filter(|r| r.path == "/check:/0")
+        .map(|r| &r.state)
+        .collect();
+    // The /0 scope is bracketed Begin…Done with the exec's trace between.
+    let State::Begin = zero[0] else {
+        panic!("expected Begin first at /check:/0, got {:?}", zero[0]);
+    };
+    let State::Done(_) = zero[zero.len() - 1] else {
+        panic!(
+            "expected Done last at /check:/0, got {:?}",
+            zero[zero.len() - 1]
+        );
+    };
+    assert!(zero
+        .iter()
+        .any(|state| {
+            if let State::Execute { .. } = state {
+                true
+            } else {
+                false
+            }
+        }));
+}
+
 #[test]
 fn loop_inside_step_produces_one_result() {
     let mut fixture = StoreFixture::new("loop-in-step");
@@ -2615,7 +2679,7 @@ cleanup :
         &program,
         Appender::memory(),
         completed,
-        Automatic::new(false),
+        Automatic::with_handle(Vec::new()),
         Library::stub(),
     );
     let outcome = runner

src/runner/checks/runner.rs

@@ -199,7 +199,9 @@ pub fn evaluate<'i>(
         // A `?` reached outside a procedure invocation has no parameter name
         // to defer against; it stands for an as-yet-unsupplied value.
         Operation::Hole => Ok(Value::Futurae(String::new())),
-        Operation::Section { .. }
+        Operation::Prose(_)
+        | Operation::Prologue(_)
+        | Operation::Section { .. }
         | Operation::Step { .. }
         | Operation::Loop { .. }
         | Operation::Invoke(_) => Ok(Value::Unitus),

src/runner/evaluator.rs

@@ -10,6 +10,7 @@ use crate::language;
 #[derive(Debug, Clone, Eq, PartialEq)]
 pub enum PathSegment<'i> {
     Section(&'i str),
+    Prologue,
     DependentStep(&'i str),
     ParallelStep(usize),
     Iteration(usize),
@@ -125,6 +126,7 @@ pub fn render_path(segments: &[PathSegment]) -> String {
 fn render_segment(segment: &PathSegment) -> Option<String> {
     match segment {
         PathSegment::Section(numeral) => Some(numeral.to_string()),
+        PathSegment::Prologue => Some("0".to_string()),
         PathSegment::DependentStep(ordinal) => Some(ordinal.to_string()),
         PathSegment::ParallelStep(index) => Some(format!("-{}", index)),
         PathSegment::Iteration(number) => Some(format!("[{}]", number)), // you can't "index" into it!