Docs audit: natural-language constructs that read like valid WFL but don't work (precedence, `/`, `finally`, `between`, error binding)

[logbie]

While auditing every ```wfl code block in Docs/ (new harness scripts/test_docs_code_blocks.py, see TestPrograms/docs_examples/DOC_CODE_AUDIT.md), several constructs turned up that read like perfectly natural WFL and appear throughout the docs, but do not work on the release interpreter (26.7.9). Most doc failures were plain syntax drift and are being fixed in the docs; the items below are language-side rough edges worth a maintainer decision (implement the feature, or make the docs stop teaching it). All repros verified against target/release/wfl.

High severity

1. Arithmetic binds looser than comparison inside conditions

The most natural conditional a beginner writes fails to type-check:

store y as 3
check if y plus 1 is equal to 4:
    display "yes"
end check

→ error: Condition must be a boolean expression - Expected Boolean but found Number
It parses as y plus (1 is equal to 4). Affects plus, minus, times, divided by, and %. Workaround: parenthesize the arithmetic, (y plus 1) is equal to 4.

2. of-call binds tighter than arithmetic → breaks recursion

display fibonacci of n minus 1

parses as (fibonacci of n) minus 1, so a recursive argument never decreases (non-termination / type error). Workaround: fibonacci of (n minus 1). Combined with #1, the precedence of of-calls vs. arithmetic vs. comparison needs a coherent, documented ladder.

3. / division operator fails to lex

display 10 / 2

→ Lexing error at position N: unexpected input /``. +, `-`, `*`, `%` all work as symbols; only `/` does not (presumably because `//` starts a comment). `divided by` works. The operator reference lists `/` as valid.

4. finally is not implemented

The docs described a full try/catch/finally, but there is no finally token/parser branch — finally: is read as an undefined variable. Only cleanup placed after end try works. (Note otherwise: is not a finally: it is a fallback for error types no when clause matched, and never runs on success.)

Medium severity

5. between is unusable outside pattern quantifiers

between is a reserved keyword but only wired into pattern quantifiers. Both of these — used in the docs — fail with Unexpected token in expression: KeywordBetween:

check if x is between 1 and 10:      -- range check
store d as random int between 1 and 6 -- random in range

Real forms today: two comparisons and-ed together; random_int of 1 and 6.

6. repeat N times is not supported

repeat 3 times:
    display "hi"
end repeat

→ Expected 'while', 'until', 'forever', or ':' after 'repeat' (collides with the times multiply operator). Workaround: count from 1 to 3:.

7. is above / is below are lexed but not parsed

above/below are keywords (lexer comment: // e.g., "is above 100") but the expression parser rejects temperature is above 30 with Unexpected token in expression: KeywordAbove. Only is greater than / is less than work.

8. No word form for modulo, and no text→number conversion

12 modulo 4 → Variable 'modulo' is not defined (only %). Separately, convert text to number doesn't parse and no to_number/parse builtin exists — yet the type checker's own hint says "Try converting the text to a number using 'convert to number'." Both fight the natural-language / minimize-special-characters principles.

9. Caught-error binding: only implicit error_message works

when error: binds an implicit error_message (single identifier) which works. But the natural binding form when error as e: is a parse error (Expected ':' after error type), and the two-word error message fails (Variable 'message' is not defined).

Lower severity / inference gaps

• Action/function return-type inference often yields Nothing. define action called double with parameters n: return n times 2 end action then double of 5 minus 1 → Cannot perform Minus operation on Nothing and Number. Untyped params defeat inference.
• Type-safety gap: docs promise Number plus Text is a compile error, but display age plus name (25, "Alice") silently prints 25Alice.
• Action parameters are immutable: change x to x plus 10 on a param → Cannot modify constant 'x'.
• Zero-arg action reference in a boolean condition is evaluated eagerly (no short-circuit) and type-errors as Function() -> ….
• list files … as <var> inline binding doesn't parse though store <var> as list files in "." does.
• Web-server example: the release binary leaves an orphaned server process holding the port after its parent is killed on timeout (Address already in use for later runs).

---

Filed from a documentation code-examples audit; the docs themselves are being corrected to the working forms in branch claude/docs-code-examples-audit-c9xzl9. Deciding these at the language level (vs. documenting the workarounds) affects WFL's "no-unlearning" natural-language promise, since each of the above is the form a beginner reaches for first.

[logbie]

Additional findings — audit of sections 04–06 + guides

Extending the audit to the Advanced Features, Standard Library, Best Practices, and guides docs (all now fixed & verified; corpus went 630 → 849 runnable blocks) surfaced more items. The confirmed functional bugs are the priority ones — these produce wrong results, not just parse errors.

Confirmed functional bugs (wrong result / crash, not doc drift)

1. list files in <dir> with pattern <glob> always returns zero. list files in "input" lists files, but list files in "input" with pattern "*.txt" — and even an exact "report.txt" — returns 0 matches when the file exists. The glob-filtered path in src/stdlib/filesystem.rs drops everything. TestPrograms/file_io_comprehensive.wfl uses this form but never asserts on the count.
2. pattern_find_all ignores the one or more quantifier. For create pattern word: one or more letter over a sentence it returns ~35 single-character matches instead of the 9 words — it advances one char at a time (src/pattern/vm.rs).
3. Nested for-each over a growing list crashes. The classic manual-dedupe pattern (outer for each item + inner for each x in growing_list) aborts with Variable 'x' has already been defined in an outer scope — the inner loop variable from a prior outer iteration isn't torn down. Plain nested loops are fine; only re-entering the inner loop over a mutated list fails.
4. format_date/format_time/format_datetime ignore friendly patterns. format_date of d and "YYYY-MM-DD" returns the literal string "YYYY-MM-DD" (passed straight to chrono strftime; only %Y-%m-%d works), while current time formatted as "yyyy-MM-dd" does translate friendly patterns. Inconsistent and silently wrong (exit 0).

Silent wrong-result footguns

5. X ends with Y / X starts with Y mis-parse with an identifier. check if filename ends with ".txt": is read as the variable filename ends → not-defined; it runs but never matches. endswith of filename and ".txt" is the reliable form. This broken form is also in TestPrograms/comprehensive_web_server_demo.wfl (file_path ends with ".html"), where the route silently never fires.
6. with-form action calls silently concatenate instead of calling (also in the original list). store r as double with 21 yields the string action double21 and exits 0 — so wrong call syntax passes without error. A warning here would catch a very common mistake.
7. add <value> to <list-of-Any> (e.g. a list from []) prints a spurious Cannot add Text to list of Any; in --test mode the append is silently dropped, breaking assertions. push with xs and v is reliable.

Scope / inference gaps

8. path of req / method of req are scope-dependent. Fatal at top level ('path' is not a function, exit 3) but fine inside a main loop: block. starts with similarly only parses inside main loop:.
9. setup-scoped list mutated from a test block doesn't persist (behaves like a read-only snapshot); defining the list inside the test works.
10. External property mutation unsupported: store obj.prop as x / change obj.prop to x both fail to parse; properties are only settable at creation or from inside an action.
11. Weak inference: for-each element over a literal list infers Any (so num times 2 warns); action/method return types often infer Nothing; map-index results (resp.headers["x"]) can't be inferred; container-type param Task mismatches actual Instance<Task>.

Smaller API/ergonomics gaps

12. No line continuation — an expression ending in with at EOL → Unexpected end of line in expression.
13. Match object fields start/end are reserved words, so match.start won't parse — only match["start"].
14. find all <pattern> in <text> doesn't exist (only find <pattern> in <text>); use pattern_find_all.
15. Pattern engine has no character-set construct — symbol from "._-" is unsupported (only letter/digit/whitespace/any/literals/alternation), so email/username patterns can't be expressed as documented.
16. substring of s from N length <var> only accepts a literal length; a variable gets swallowed (substring of s and N and len works).
17. path_join caps at 2 args; is_directory alias is missing; wrong at-form calls (is_file at "x") emit a misleading Cannot index into Function(...) error.
18. Undocumented builtin identifiers shadow variables in with position — timestamp, size, format_date behave like reserved names but aren't listed, so a user variable silently collides ('timestamp' is not callable).

The docs have been corrected to the working forms throughout; this list is for the language/stdlib side. Full per-file state is in TestPrograms/docs_examples/DOC_CODE_AUDIT.md on branch claude/docs-code-examples-audit-c9xzl9.

---

Generated by Claude Code

[logbie]

Assessment: primary items implemented in open PR #577; residual items split into #578 — recommend closing once #577 merges.

Verified state on main today: the headline items from this audit — arithmetic-vs-comparison precedence, of-call args absorbing arithmetic, / as division, modulo, is between/is above/is below, a real finally clause, and when error as e: error binding — are the subject of PR #577 ("feat: fix natural-language precedence, add finally/between/is-above-below, /-division, modulo, and error binding (#571)"), currently open on branch claude/docs-audit-natural-language-precedence-6zpter. The remaining, riskier items from this issue and its follow-up comment (type inference, repeat N times, text→number, the pattern VM, filesystem glob, scope/API ergonomics) were split into #578 so they can be scoped independently — a good call; this issue had grown broad.

Recommendation: keep this open only as the tracking anchor for PR #577; once #577 merges, close it and let #578 carry the residual work. Suggested labels: docs, parser, tracking.

Posted by the WFL repo warden (automated triage pass).

[logbie]

Status update after re-verifying against current main.

The high/medium-severity language items here were implemented in PR #577 and now work on main: arithmetic-vs-comparison precedence (y plus 1 is equal to 4), of-call vs arithmetic (fibonacci of n minus 1), / division, finally, is between, is above/is below, modulo, and when error as e: binding — all verified with fresh repros.

The remaining items are tracked in the #578 follow-up and were confirmed still open here: repeat N times (collides with the times operator) and text→number conversion (convert … to number has no parse form / builtin), plus the deeper inference, pattern-VM, and filesystem-glob gaps. These warrant their own focused PRs rather than being folded into the current bug-fix batch.

---

Generated by Claude Code

[logbie]

Verified fixed on WFL 26.7.36 (fc21f2f, Linux release build) during the #610 Phase 1 open-issue inventory.

Fixed by PR #577 — arithmetic now binds tighter than comparison; of-call arguments absorb arithmetic (so recursion terminates); / lexes as division; modulo, is between, is above, is below, finally, and when error as <name> are real constructs.

Repro checks now behave:

$ wfl repro.wfl
precedence-yes     # (y plus 1) is equal to 4
5                  # 10 divided by 2
5                  # 10 / 2
between-ok         # x is between 1 and 10
[exit 0]

The remaining, deliberately-deferred items from this audit (type inference edge cases, list files … with pattern, pattern-VM quantifier, text→number, filesystem glob, etc.) are tracked in the follow-up #578, which stays open. Closing this one as completed.

---

Generated by Claude Code