feat: REPL highlighting + live completion, forge doc/fmt fixes

[humancto]

Summary

Phase 1 final batch — REPL, formatter, and doc generator improvements.

REPL:

• Syntax highlighting: keywords (magenta), builtins (blue), modules (green), strings (yellow), numbers (cyan), comments (dim)
• Tab completion now includes user-defined variables and functions from the live interpreter environment
• env command shows all defined variables and values (not just _last)

forge doc:

• Fix let/let mut declarations being silently skipped (the _ => {} catch-all was swallowing them)
• // comments preceding declarations are now extracted and displayed using SpannedStmt.line

forge fmt:

• Parenthesis depth tracking for multi-line function call continuation indentation

Infrastructure:

• Environment::all_names() method for REPL tab completion
• Roadmap updated: Phase 1 items 1.1-1.4, 1.6-1.8 complete (1.5 spans deferred)

Test plan

• 826 cargo tests pass (2 new formatter, 13 total)
• forge run examples/hello.fg passes
• forge run examples/functional.fg passes
• Manual: forge repl — verify syntax colors, define a variable, tab-complete it
• Manual: forge doc examples/ — verify variables and comments appear
• Manual: forge fmt --check on a file with multi-line function call

[humancto]

Review: REPL highlighting + live completion, forge doc/fmt fixes

Nice batch of improvements — clean, focused changes across three areas with good test coverage. The REPL syntax highlighting, doc generator fixes, and formatter paren tracking are all well-implemented.

What looks good

• extract_preceding_comments — Clean implementation. The 1-based → 0-based conversion via spanned.line.saturating_sub(1) is correct, and the backward walk with proper bounds checking is solid.
• Environment::all_names() — Good use of unwrap_or_else(|p| p.into_inner()) for poisoned mutex recovery, consistent with the rest of the interpreter.
• Arc<Mutex<Vec<String>>> for shared tab-completion state — The right pattern for sharing mutable state between the Helper and the REPL main loop.
• forge fmt paren tracking — Minimal, correct change. The two new tests cover the important cases.
• forge doc Stmt::Let handling — Removes the _ => {} catch-all swallowing declarations. Good catch.
• CHANGELOG and ROADMAP updates — Well-structured entries.
• Unused ast::self import cleanup — Correct; nothing uses the ast:: prefix.

Issues

1. Bug (highlighter): true/false boolean highlighting is dead code — they're already in the KEYWORDS array so they match the keyword branch first and get magenta, never reaching the intended cyan branch. See inline comment.
2. Minor (highlighter): Number highlighting consumes .. (range operator) as part of the number. 1..10 highlights as one cyan token instead of 1, .., 10.
3. Minor (highlighter): Single-quoted strings aren't highlighted — the formatter already treats ' as a string delimiter, so the highlighter should too for consistency.
4. Nit (formatter): count_braces now counts parens but the name doesn't reflect it.

None of these are blocking — the dead-code boolean bug (#1) is worth fixing before merge, the rest are minor polish.

---

Generated by Claude Code

[humancto]

Bug: true and false are already in the KEYWORDS array (lines 148-149), so they'll be matched by the KEYWORDS.contains() check above and highlighted in magenta. This else if branch is unreachable dead code.

To get the intended cyan highlighting for booleans, either:

1. Remove "true" and "false" from KEYWORDS and rely on this explicit check, or
2. Move this check before the KEYWORDS.contains() check

Option 1 seems cleaner since true/false are really literals, not keywords.

---

Generated by Claude Code

[humancto]

Minor: This will consume the range operator .. as part of a number literal. For example, range(1..10) would highlight 1..10 as a single cyan number instead of 1, .., 10.

Consider tightening to allow at most one . (and only if followed by a digit):

if chars[i].is_ascii_digit() {
    result.push_str("\x1B[36m");
    while i < len && chars[i].is_ascii_digit() {
        result.push(chars[i]);
        i += 1;
    }
    // Allow one decimal point followed by digits
    if i < len && chars[i] == '.' && i + 1 < len && chars[i + 1].is_ascii_digit() {
        result.push(chars[i]);
        i += 1;
        while i < len && chars[i].is_ascii_digit() {
            result.push(chars[i]);
            i += 1;
        }
    }
    result.push_str("\x1B[0m");
    continue;
}

Not blocking, but would improve highlighting accuracy for Forge's range() and similar patterns.

---

Generated by Claude Code

[humancto]

Nit: The highlighter handles double-quoted strings but not single-quoted ones. The formatter's count_braces already treats both '"' and '\'' as string delimiters, so Forge does support single-quoted strings. Adding a chars[i] == '\'' branch here (same logic, same color) would be a nice consistency improvement.

---

Generated by Claude Code

[humancto]

Nit: Now that this function counts parentheses too, the name count_braces is slightly misleading. Consider renaming to count_delimiters or count_nesting. Not blocking — just a readability note since the test name count_braces_includes_parens already hints at the mismatch.

---

Generated by Claude Code