harn_parser/
diagnostic.rs

1use std::io::IsTerminal;
2
3use harn_lexer::Span;
4use yansi::{Color, Paint};
5
6use crate::diagnostic_codes::Repair;
7use crate::ParserError;
8
9pub struct RelatedSpanLabel<'a> {
10    pub span: &'a Span,
11    pub label: &'a str,
12}
13
14/// Normalize diagnostic filenames lexically for display.
15///
16/// This deliberately does not touch the filesystem: diagnostics should cancel
17/// `.` and `..` path components even when the path points at a file that no
18/// longer exists, without resolving symlinks.
19pub fn normalize_diagnostic_path(path: &str) -> String {
20    let posix = path.replace('\\', "/");
21    if posix.is_empty() {
22        return String::new();
23    }
24
25    let bytes = posix.as_bytes();
26    let mut drive = "";
27    let mut rest = posix.as_str();
28    if bytes.len() >= 2 && bytes[0].is_ascii_alphabetic() && bytes[1] == b':' {
29        drive = &posix[..2];
30        rest = &posix[2..];
31    }
32
33    let absolute = rest.starts_with('/');
34    let mut stack: Vec<&str> = Vec::new();
35    for segment in rest.split('/').filter(|segment| !segment.is_empty()) {
36        match segment {
37            "." => {}
38            ".." => {
39                if let Some(top) = stack.last() {
40                    if *top != ".." {
41                        stack.pop();
42                        continue;
43                    }
44                }
45                if !absolute {
46                    stack.push("..");
47                }
48            }
49            _ => stack.push(segment),
50        }
51    }
52
53    let mut normalized = String::new();
54    normalized.push_str(drive);
55    if absolute {
56        normalized.push('/');
57    }
58    normalized.push_str(&stack.join("/"));
59    if normalized.is_empty() {
60        ".".to_string()
61    } else {
62        normalized
63    }
64}
65
66fn has_same_snake_case_segments(a: &str, b: &str) -> bool {
67    if !a.contains('_') || !b.contains('_') {
68        return false;
69    }
70    let mut a_segments: Vec<_> = a.split('_').collect();
71    let mut b_segments: Vec<_> = b.split('_').collect();
72    if a_segments.len() < 2
73        || a_segments.len() != b_segments.len()
74        || a_segments.iter().any(|segment| segment.is_empty())
75        || b_segments.iter().any(|segment| segment.is_empty())
76    {
77        return false;
78    }
79    a_segments.sort_unstable();
80    b_segments.sort_unstable();
81    a_segments == b_segments
82}
83
84/// Find the closest match to `name` among `candidates`, within `max_dist` edits
85/// or by reordering its non-empty underscore-separated segments. Candidates
86/// within the edit-distance threshold rank ahead of reorder-only matches.
87pub fn find_closest_match<'a>(
88    name: &str,
89    candidates: impl Iterator<Item = &'a str>,
90    max_dist: usize,
91) -> Option<&'a str> {
92    candidates
93        .filter(|candidate| *candidate != name)
94        .filter_map(|candidate| {
95            let reordered = has_same_snake_case_segments(name, candidate);
96            if candidate.len().abs_diff(name.len()) > max_dist && !reordered {
97                return None;
98            }
99            let distance = strsim::levenshtein(name, candidate);
100            (distance <= max_dist || reordered).then_some((distance, candidate))
101        })
102        .min_by_key(|(distance, _)| *distance)
103        .map(|(_, candidate)| candidate)
104}
105
106/// Return the replacement for stdlib symbols that were directly renamed.
107pub fn renamed_stdlib_symbol(name: &str) -> Option<&'static str> {
108    match name {
109        "retry_with_backoff" => Some("retry_predicate_with_backoff"),
110        "print" => Some("harness.stdio.print"),
111        "println" => Some("harness.stdio.println"),
112        "eprint" => Some("harness.stdio.eprint"),
113        "eprintln" => Some("harness.stdio.eprintln"),
114        "read_line" => Some("harness.stdio.read_line"),
115        "prompt_user" => Some("harness.stdio.prompt"),
116        "agent_session_open" => Some("harness.agent.open"),
117        "agent_session_workspace_anchor" => Some("harness.agent.workspace_anchor"),
118        "agent_session_set_workspace_anchor" => Some("harness.agent.set_workspace_anchor"),
119        "agent_session_workspace_policy" => Some("harness.agent.workspace_policy"),
120        "agent_session_set_workspace_policy" => Some("harness.agent.set_workspace_policy"),
121        "agent_session_add_root" => Some("harness.agent.add_root"),
122        "agent_session_remove_root" => Some("harness.agent.remove_root"),
123        "agent_session_list_roots" => Some("harness.agent.list_roots"),
124        "agent_session_exists" => Some("harness.agent.exists"),
125        "agent_session_length" => Some("harness.agent.length"),
126        "agent_session_snapshot" => Some("harness.agent.snapshot"),
127        "agent_session_ancestry" => Some("harness.agent.ancestry"),
128        "agent_session_current_id" => Some("harness.agent.current_id"),
129        "agent_session_record_changed_path" => Some("harness.agent.record_changed_path"),
130        "agent_session_actor_chain" => Some("harness.agent.actor_chain"),
131        "agent_session_tool_format" => Some("harness.agent.tool_format"),
132        "agent_session_system_prompt" => Some("harness.agent.system_prompt"),
133        "agent_session_scratchpad" => Some("harness.agent.scratchpad"),
134        "agent_session_set_scratchpad" => Some("harness.agent.set_scratchpad"),
135        "agent_session_clear_scratchpad" => Some("harness.agent.clear_scratchpad"),
136        "agent_session_claim_tool_format" => Some("harness.agent.claim_tool_format"),
137        "agent_session_reset" => Some("harness.agent.reset"),
138        "agent_session_fork" => Some("harness.agent.fork"),
139        "agent_session_fork_at" => Some("harness.agent.fork_at"),
140        "agent_session_rollback" => Some("harness.agent.rollback"),
141        "agent_session_redo" => Some("harness.agent.redo"),
142        "agent_session_close" => Some("harness.agent.close"),
143        "agent_session_trim" => Some("harness.agent.trim"),
144        "agent_session_attach" => Some("harness.agent.attach"),
145        "agent_session_takeover" => Some("harness.agent.takeover"),
146        "agent_session_detach" => Some("harness.agent.detach"),
147        "agent_session_heartbeat" => Some("harness.agent.heartbeat"),
148        "agent_session_live_clients" => Some("harness.agent.live_clients"),
149        "agent_session_client_inject_prompt" => Some("harness.agent.client_inject_prompt"),
150        "agent_session_route_permission" => Some("harness.agent.route_permission"),
151        "agent_session_inject" => Some("harness.agent.inject"),
152        "agent_session_post_event" => Some("harness.agent.post_event"),
153        "agent_session_drain_inbox" => Some("harness.agent.drain_inbox"),
154        "agent_session_seed_from_jsonl" => Some("harness.agent.seed_from_jsonl"),
155        "agent_session_reanchor" => Some("harness.agent.reanchor"),
156        "agent_session_compact" => Some("harness.agent.compact"),
157        _ => None,
158    }
159}
160
161/// Map an ambient clock-capability builtin to its `harness.clock.*`
162/// replacement. Returns the new identifier text (including the receiver
163/// path) so the `bindings/thread-harness-clock` repair can replace the
164/// call-site identifier in place. The mapping is the source of truth for
165/// the E4.3 → E4.6 migration; downstream replatform agents query it via
166/// [`Code::repair_template`].
167pub fn harness_clock_replacement(name: &str) -> Option<&'static str> {
168    match name {
169        "now_ms" => Some("harness.clock.now_ms"),
170        "monotonic_ms" => Some("harness.clock.monotonic_ms"),
171        "sleep_ms" => Some("harness.clock.sleep_ms"),
172        "sleep" => Some("harness.clock.sleep_ms"),
173        "timestamp" => Some("harness.clock.timestamp"),
174        "elapsed" => Some("harness.clock.monotonic_ms"),
175        "date_now" => Some("harness.clock.now"),
176        "date_now_iso" => Some("harness.clock.date_iso"),
177        _ => None,
178    }
179}
180
181/// Map an ambient stdio-capability builtin to its `harness.stdio.*`
182/// replacement so `harn fix` can replace the call in place once the
183/// relevant harness binding is available.
184pub fn harness_stdio_replacement(name: &str) -> Option<&'static str> {
185    match name {
186        "print" => Some("harness.stdio.print"),
187        "println" => Some("harness.stdio.println"),
188        "eprint" => Some("harness.stdio.eprint"),
189        "eprintln" => Some("harness.stdio.eprintln"),
190        "read_line" => Some("harness.stdio.read_line"),
191        "prompt_user" => Some("harness.stdio.prompt"),
192        _ => None,
193    }
194}
195
196/// Map an ambient fs-capability builtin to its `harness.fs.*` replacement.
197/// Backs the `bindings/thread-harness-fs` repair the E4.4 → E4.6
198/// migration uses to rewrite `.harn` scripts off the legacy surface.
199pub fn harness_fs_replacement(name: &str) -> Option<&'static str> {
200    match name {
201        "read_file" => Some("harness.fs.read_text"),
202        "read_file_result" => Some("harness.fs.read_text_result"),
203        "read_file_bytes" => Some("harness.fs.read_bytes"),
204        "write_file" => Some("harness.fs.write_text"),
205        "write_file_bytes" => Some("harness.fs.write_bytes"),
206        "replace_file" => Some("harness.fs.replace_text"),
207        "replace_file_result" => Some("harness.fs.replace_text_result"),
208        "replace_file_bytes" => Some("harness.fs.replace_bytes"),
209        "replace_file_bytes_result" => Some("harness.fs.replace_bytes_result"),
210        "file_exists" => Some("harness.fs.exists"),
211        "path_status" => Some("harness.fs.status"),
212        "delete_file" => Some("harness.fs.delete"),
213        "append_file" => Some("harness.fs.append"),
214        "append_file_locked" => Some("harness.fs.append_locked"),
215        "list_dir" => Some("harness.fs.list_dir"),
216        "mkdir" => Some("harness.fs.mkdir"),
217        "copy_file" => Some("harness.fs.copy"),
218        "temp_dir" => Some("harness.fs.temp_dir"),
219        "workspace_temp_dir" => Some("harness.fs.workspace_temp_dir"),
220        "mkdtemp" => Some("harness.fs.mkdtemp"),
221        "mkdtemp_in_workspace" => Some("harness.fs.mkdtemp_in_workspace"),
222        "stat" => Some("harness.fs.stat"),
223        "move_file" => Some("harness.fs.rename"),
224        "read_lines" => Some("harness.fs.read_lines"),
225        "read_lines_page_result" => Some("harness.fs.read_lines_page_result"),
226        "walk_dir" => Some("harness.fs.walk"),
227        "glob" => Some("harness.fs.glob"),
228        "find_text" => Some("harness.fs.find_text"),
229        "find_evidence" => Some("harness.fs.find_evidence"),
230        _ => None,
231    }
232}
233
234/// Map an ambient env-capability builtin to its `harness.env.*` replacement.
235/// Backs the `bindings/thread-harness-env` repair.
236pub fn harness_env_replacement(name: &str) -> Option<&'static str> {
237    match name {
238        "env" => Some("harness.env.get"),
239        "env_or" => Some("harness.env.get_or"),
240        _ => None,
241    }
242}
243
244/// Map an ambient random-capability builtin to its `harness.random.*`
245/// replacement. Backs the `bindings/thread-harness-random` repair.
246pub fn harness_random_replacement(name: &str) -> Option<&'static str> {
247    match name {
248        "random" => Some("harness.random.f64"),
249        "random_int" => Some("harness.random.range"),
250        "random_choice" => Some("harness.random.choice"),
251        "random_shuffle" => Some("harness.random.shuffle"),
252        _ => None,
253    }
254}
255
256/// Map an ambient net-capability builtin to its `harness.net.*`
257/// replacement. Backs the `bindings/thread-harness-net` repair. Every
258/// script-facing network effect is exposed only through `HarnessNet`; response
259/// constructors and event encoders remain pure globals.
260pub fn harness_net_replacement(name: &str) -> Option<&'static str> {
261    match name {
262        "http_get" => Some("harness.net.get"),
263        "http_post" => Some("harness.net.post"),
264        "http_put" => Some("harness.net.put"),
265        "http_patch" => Some("harness.net.patch"),
266        "http_delete" => Some("harness.net.delete"),
267        "http_request" => Some("harness.net.request"),
268        "http_download" => Some("harness.net.download"),
269        "http_server" => Some("harness.net.server"),
270        "http_server_after" => Some("harness.net.server_after"),
271        "http_server_before" => Some("harness.net.server_before"),
272        "http_server_on_shutdown" => Some("harness.net.server_on_shutdown"),
273        "http_server_readiness" => Some("harness.net.server_readiness"),
274        "http_server_ready" => Some("harness.net.server_ready"),
275        "http_server_request" => Some("harness.net.server_request"),
276        "http_server_route" => Some("harness.net.server_route"),
277        "http_server_security_headers" => Some("harness.net.server_security_headers"),
278        "http_server_set_ready" => Some("harness.net.server_set_ready"),
279        "http_server_shutdown" => Some("harness.net.server_shutdown"),
280        "http_server_test" => Some("harness.net.server_test"),
281        "http_server_tls_edge" => Some("harness.net.server_tls_edge"),
282        "http_server_tls_pem" => Some("harness.net.server_tls_pem"),
283        "http_server_tls_plain" => Some("harness.net.server_tls_plain"),
284        "http_server_tls_self_signed_dev" => Some("harness.net.server_tls_self_signed_dev"),
285        "http_session" => Some("harness.net.session"),
286        "http_session_close" => Some("harness.net.session_close"),
287        "http_session_request" => Some("harness.net.session_request"),
288        "http_stream_close" => Some("harness.net.stream_close"),
289        "http_stream_info" => Some("harness.net.stream_info"),
290        "http_stream_open" => Some("harness.net.stream_open"),
291        "http_stream_read" => Some("harness.net.stream_read"),
292        "sse_close" => Some("harness.net.sse_close"),
293        "sse_connect" => Some("harness.net.sse_connect"),
294        "sse_receive" => Some("harness.net.sse_receive"),
295        "sse_server_cancel" => Some("harness.net.sse_server_cancel"),
296        "sse_server_cancelled" => Some("harness.net.sse_server_cancelled"),
297        "sse_server_close" => Some("harness.net.sse_server_close"),
298        "sse_server_disconnected" => Some("harness.net.sse_server_disconnected"),
299        "sse_server_flush" => Some("harness.net.sse_server_flush"),
300        "sse_server_heartbeat" => Some("harness.net.sse_server_heartbeat"),
301        "sse_server_response" => Some("harness.net.sse_server_response"),
302        "sse_server_send" => Some("harness.net.sse_server_send"),
303        "sse_server_status" => Some("harness.net.sse_server_status"),
304        "websocket_accept" => Some("harness.net.websocket_accept"),
305        "websocket_close" => Some("harness.net.websocket_close"),
306        "websocket_connect" => Some("harness.net.websocket_connect"),
307        "websocket_receive" => Some("harness.net.websocket_receive"),
308        "websocket_route" => Some("harness.net.websocket_route"),
309        "websocket_send" => Some("harness.net.websocket_send"),
310        "websocket_server" => Some("harness.net.websocket_server"),
311        "websocket_server_close" => Some("harness.net.websocket_server_close"),
312        _ => None,
313    }
314}
315
316/// Render a Rust-style diagnostic message.
317///
318/// Example output:
319/// ```text
320/// error: undefined variable `x`
321///   --> example.harn:5:12
322///    |
323///  5 |     let y = x + 1
324///    |             ^ not found in this scope
325/// ```
326pub fn render_diagnostic(
327    source: &str,
328    filename: &str,
329    span: &Span,
330    severity: &str,
331    message: &str,
332    label: Option<&str>,
333    help: Option<&str>,
334) -> String {
335    render_diagnostic_inner(RenderDiagnostic {
336        source,
337        filename,
338        span,
339        severity,
340        code: None,
341        message,
342        label,
343        help,
344        related: &[],
345        repair: None,
346    })
347}
348
349pub fn render_diagnostic_with_code(
350    source: &str,
351    filename: &str,
352    span: &Span,
353    severity: &str,
354    code: crate::diagnostic_codes::Code,
355    message: &str,
356    label: Option<&str>,
357    help: Option<&str>,
358) -> String {
359    let repair_owned = code.repair_template().map(Repair::from_template);
360    render_diagnostic_inner(RenderDiagnostic {
361        source,
362        filename,
363        span,
364        severity,
365        code: Some(code.as_str()),
366        message,
367        label,
368        help,
369        related: &[],
370        repair: repair_owned.as_ref(),
371    })
372}
373
374pub fn render_diagnostic_with_related(
375    source: &str,
376    filename: &str,
377    span: &Span,
378    severity: &str,
379    message: &str,
380    label: Option<&str>,
381    help: Option<&str>,
382    related: &[RelatedSpanLabel<'_>],
383) -> String {
384    render_diagnostic_inner(RenderDiagnostic {
385        source,
386        filename,
387        span,
388        severity,
389        code: None,
390        message,
391        label,
392        help,
393        related,
394        repair: None,
395    })
396}
397
398struct RenderDiagnostic<'a> {
399    source: &'a str,
400    filename: &'a str,
401    span: &'a Span,
402    severity: &'a str,
403    code: Option<&'a str>,
404    message: &'a str,
405    label: Option<&'a str>,
406    help: Option<&'a str>,
407    related: &'a [RelatedSpanLabel<'a>],
408    repair: Option<&'a Repair>,
409}
410
411fn render_diagnostic_inner(input: RenderDiagnostic<'_>) -> String {
412    let mut out = String::new();
413    let source = input.source;
414    let span = input.span;
415    let severity = input.severity;
416    let message = input.message;
417    let label = input.label;
418    let help = input.help;
419    let related = input.related;
420    let filename = normalize_diagnostic_path(input.filename);
421    let severity_color = severity_color(severity);
422    let gutter = style_fragment("|", Color::Blue, false);
423    let arrow = style_fragment("-->", Color::Blue, true);
424    let help_prefix = style_fragment("help", Color::Cyan, true);
425    let note_prefix = style_fragment("note", Color::Magenta, true);
426
427    out.push_str(&style_fragment(severity, severity_color, true));
428    if let Some(code) = input.code {
429        out.push('[');
430        out.push_str(code);
431        out.push(']');
432    }
433    out.push_str(": ");
434    out.push_str(message);
435    out.push('\n');
436
437    let line_num = span.line;
438    let col_num = span.column;
439
440    let gutter_width = line_num.to_string().len();
441
442    out.push_str(&format!(
443        "{:>width$}{arrow} {filename}:{line_num}:{col_num}\n",
444        " ",
445        width = gutter_width + 1,
446    ));
447
448    out.push_str(&format!(
449        "{:>width$} {gutter}\n",
450        " ",
451        width = gutter_width + 1,
452    ));
453
454    let source_line_opt = line_num.checked_sub(1).and_then(|n| source.lines().nth(n));
455    if let Some(source_line) = source_line_opt {
456        out.push_str(&format!(
457            "{:>width$} {gutter} {source_line}\n",
458            line_num,
459            width = gutter_width + 1,
460        ));
461
462        if let Some(label_text) = label {
463            // Span width must use char count, not byte offsets, so carets align with the source text.
464            let span_len = if span.end > span.start && span.start <= source.len() {
465                let span_text = &source[span.start.min(source.len())..span.end.min(source.len())];
466                span_text.chars().count().max(1)
467            } else {
468                1
469            };
470            let col_num = col_num.max(1);
471            let padding = " ".repeat(col_num - 1);
472            let carets = style_fragment(&"^".repeat(span_len), severity_color, true);
473            out.push_str(&format!(
474                "{:>width$} {gutter} {padding}{carets} {label_text}\n",
475                " ",
476                width = gutter_width + 1,
477            ));
478        }
479    }
480
481    if let Some(help_text) = help {
482        out.push_str(&format!(
483            "{:>width$} = {help_prefix}: {help_text}\n",
484            " ",
485            width = gutter_width + 1,
486        ));
487    }
488
489    if let Some(repair) = input.repair {
490        let repair_prefix = style_fragment("repair", Color::Cyan, true);
491        out.push_str(&format!(
492            "{:>width$} = {repair_prefix}: {} [{}] — {}\n",
493            " ",
494            repair.id,
495            repair.safety,
496            repair.summary,
497            width = gutter_width + 1,
498        ));
499    }
500
501    for item in related {
502        out.push_str(&format!(
503            "{:>width$} = {note_prefix}: {}\n",
504            " ",
505            item.label,
506            width = gutter_width + 1,
507        ));
508        render_related_span(
509            &mut out,
510            source,
511            &filename,
512            item.span,
513            item.label,
514            gutter_width,
515        );
516    }
517
518    if let Some(note_text) = fun_note(severity) {
519        out.push_str(&format!(
520            "{:>width$} = {note_prefix}: {note_text}\n",
521            " ",
522            width = gutter_width + 1,
523        ));
524    }
525
526    out
527}
528
529pub fn render_type_diagnostic(
530    source: &str,
531    filename: &str,
532    diag: &crate::typechecker::TypeDiagnostic,
533) -> String {
534    let severity = match diag.severity {
535        crate::typechecker::DiagnosticSeverity::Error => "error",
536        crate::typechecker::DiagnosticSeverity::Warning => "warning",
537    };
538    let related = diag
539        .related
540        .iter()
541        .map(|related| RelatedSpanLabel {
542            span: &related.span,
543            label: &related.message,
544        })
545        .collect::<Vec<_>>();
546    let primary_label = type_diagnostic_primary_label(diag);
547    match &diag.span {
548        Some(span) => render_diagnostic_inner(RenderDiagnostic {
549            source,
550            filename,
551            span,
552            severity,
553            code: Some(diag.code.as_str()),
554            message: &diag.message,
555            label: primary_label.as_deref(),
556            help: diag.help.as_deref(),
557            related: &related,
558            repair: diag.repair.as_ref(),
559        }),
560        None => match diag.repair.as_ref() {
561            Some(repair) => format!(
562                "{severity}[{}]: {}\n  = repair: {} [{}] — {}\n",
563                diag.code, diag.message, repair.id, repair.safety, repair.summary,
564            ),
565            None => format!("{severity}[{}]: {}\n", diag.code, diag.message),
566        },
567    }
568}
569
570pub fn lexer_error_code(err: &harn_lexer::LexerError) -> crate::diagnostic_codes::Code {
571    match err {
572        harn_lexer::LexerError::UnexpectedCharacter(_, _) => {
573            crate::diagnostic_codes::Code::ParserUnexpectedCharacter
574        }
575        harn_lexer::LexerError::UnterminatedString(_) => {
576            crate::diagnostic_codes::Code::ParserUnterminatedString
577        }
578        harn_lexer::LexerError::UnterminatedBlockComment(_) => {
579            crate::diagnostic_codes::Code::ParserUnterminatedBlockComment
580        }
581        harn_lexer::LexerError::IntegerLiteralOutOfRange(_, _) => {
582            crate::diagnostic_codes::Code::ParserIntegerLiteralOutOfRange
583        }
584    }
585}
586
587pub fn parser_error_code(err: &crate::parser::ParserError) -> crate::diagnostic_codes::Code {
588    match err {
589        crate::parser::ParserError::Unexpected { .. } => {
590            crate::diagnostic_codes::Code::ParserUnexpectedToken
591        }
592        crate::parser::ParserError::UnexpectedEof { .. } => {
593            crate::diagnostic_codes::Code::ParserUnexpectedEof
594        }
595    }
596}
597
598fn type_diagnostic_primary_label(diag: &crate::typechecker::TypeDiagnostic) -> Option<String> {
599    match &diag.details {
600        Some(crate::typechecker::DiagnosticDetails::LintRule { rule }) => {
601            Some(format!("lint[{rule}]"))
602        }
603        Some(crate::typechecker::DiagnosticDetails::TypeMismatch) => {
604            Some("found this type".to_string())
605        }
606        _ => None,
607    }
608}
609
610fn render_related_span(
611    out: &mut String,
612    source: &str,
613    filename: &str,
614    span: &Span,
615    label: &str,
616    primary_gutter_width: usize,
617) {
618    let filename = normalize_diagnostic_path(filename);
619    let severity_color = Color::Magenta;
620    let gutter = style_fragment("|", Color::Blue, false);
621    let arrow = style_fragment("-->", Color::Blue, true);
622    let line_num = span.line;
623    let col_num = span.column;
624    let gutter_width = primary_gutter_width.max(line_num.to_string().len());
625
626    out.push_str(&format!(
627        "{:>width$}{arrow} {filename}:{line_num}:{col_num}\n",
628        " ",
629        width = gutter_width + 1,
630    ));
631    out.push_str(&format!(
632        "{:>width$} {gutter}\n",
633        " ",
634        width = gutter_width + 1,
635    ));
636
637    if let Some(source_line) = line_num.checked_sub(1).and_then(|n| source.lines().nth(n)) {
638        out.push_str(&format!(
639            "{:>width$} {gutter} {source_line}\n",
640            line_num,
641            width = gutter_width + 1,
642        ));
643        let span_len = if span.end > span.start && span.start <= source.len() {
644            let span_text = &source[span.start.min(source.len())..span.end.min(source.len())];
645            span_text.chars().count().max(1)
646        } else {
647            1
648        };
649        let padding = " ".repeat(col_num.max(1) - 1);
650        let carets = style_fragment(&"^".repeat(span_len), severity_color, true);
651        out.push_str(&format!(
652            "{:>width$} {gutter} {padding}{carets} {label}\n",
653            " ",
654            width = gutter_width + 1,
655        ));
656    }
657}
658
659fn severity_color(severity: &str) -> Color {
660    match severity {
661        "error" => Color::Red,
662        "warning" => Color::Yellow,
663        "note" => Color::Magenta,
664        _ => Color::Cyan,
665    }
666}
667
668fn style_fragment(text: &str, color: Color, bold: bool) -> String {
669    if !colors_enabled() {
670        return text.to_string();
671    }
672
673    let mut paint = Paint::new(text).fg(color);
674    if bold {
675        paint = paint.bold();
676    }
677    paint.to_string()
678}
679
680thread_local! {
681    /// Per-thread override for color output. When `Some`, it wins over the
682    /// `NO_COLOR` env var and TTY detection. This lets tests force colors off
683    /// deterministically without mutating the process-global `NO_COLOR` env
684    /// var, which races across parallel tests (each test runs on its own
685    /// thread, so the override is naturally isolated).
686    static COLOR_OVERRIDE: std::cell::Cell<Option<bool>> = const { std::cell::Cell::new(None) };
687}
688
689/// Force color output on (`Some(true)`), off (`Some(false)`), or restore the
690/// default env/TTY behavior (`None`) for the current thread only.
691#[cfg(test)]
692pub(crate) fn set_color_override(force: Option<bool>) {
693    COLOR_OVERRIDE.with(|cell| cell.set(force));
694}
695
696fn colors_enabled() -> bool {
697    if let Some(forced) = COLOR_OVERRIDE.with(std::cell::Cell::get) {
698        return forced;
699    }
700    std::env::var_os("NO_COLOR").is_none() && std::io::stderr().is_terminal()
701}
702
703fn fun_note(severity: &str) -> Option<&'static str> {
704    if std::env::var("HARN_FUN").ok().as_deref() != Some("1") {
705        return None;
706    }
707
708    Some(match severity {
709        "error" => "the compiler stepped on a rake here.",
710        "warning" => "this still runs, but it has strong 'double-check me' energy.",
711        _ => "a tiny gremlin has left a note in the margins.",
712    })
713}
714
715pub fn parser_error_message(err: &ParserError) -> String {
716    match err {
717        ParserError::Unexpected { got, expected, .. } => {
718            format!("expected {expected}, found {got}")
719        }
720        ParserError::UnexpectedEof { expected, .. } => {
721            format!("unexpected end of file, expected {expected}")
722        }
723    }
724}
725
726pub fn parser_error_label(err: &ParserError) -> &'static str {
727    match err {
728        ParserError::Unexpected { got, .. } if got == "Newline" => "line break not allowed here",
729        ParserError::Unexpected { .. } => "unexpected token",
730        ParserError::UnexpectedEof { .. } => "file ends here",
731    }
732}
733
734pub fn parser_error_help(err: &ParserError) -> Option<&'static str> {
735    match err {
736        ParserError::UnexpectedEof { expected, .. } | ParserError::Unexpected { expected, .. } => {
737            match expected.as_str() {
738                "}" => Some("add a closing `}` to finish this block"),
739                ")" => Some("add a closing `)` to finish this expression or parameter list"),
740                "]" => Some("add a closing `]` to finish this list or subscript"),
741                "fn, struct, enum, or pipeline after pub" => {
742                    Some("use `pub fn`, `pub pipeline`, `pub enum`, or `pub struct`")
743                }
744                "fn, tool, skill, eval_pack, struct, enum, type, pipeline, const, let, or import after pub" => Some(
745                    "use `pub` with `fn`, `tool`, `skill`, `eval_pack`, `struct`, `enum`, `type`, `pipeline`, `const`, `let`, or `import`",
746                ),
747                _ => None,
748            }
749        }
750    }
751}
752
753#[cfg(test)]
754mod tests {
755    use super::*;
756
757    /// Ensure ANSI colors are off so plain-text assertions work regardless
758    /// of whether the test runner's stderr is a TTY. Uses a thread-local
759    /// override rather than the process-global `NO_COLOR` env var so it can't
760    /// race with color-sensitive assertions in parallel tests.
761    fn disable_colors() {
762        set_color_override(Some(false));
763    }
764
765    #[test]
766    fn test_basic_diagnostic() {
767        disable_colors();
768        let source = "pipeline default(task) {\n    const y = x + 1\n}";
769        let span = Span {
770            start: 28,
771            end: 29,
772            line: 2,
773            column: 13,
774            end_line: 2,
775        };
776        let output = render_diagnostic(
777            source,
778            "example.harn",
779            &span,
780            "error",
781            "undefined variable `x`",
782            Some("not found in this scope"),
783            None,
784        );
785        assert!(output.contains("error: undefined variable `x`"));
786        assert!(output.contains("--> example.harn:2:13"));
787        assert!(output.contains("const y = x + 1"));
788        assert!(output.contains("^ not found in this scope"));
789    }
790
791    #[test]
792    fn test_diagnostic_normalizes_filename() {
793        disable_colors();
794        let source = "const value = thing";
795        let span = Span {
796            start: 12,
797            end: 17,
798            line: 1,
799            column: 13,
800            end_line: 1,
801        };
802        let output = render_diagnostic(
803            source,
804            "/workspace/pipelines/mode/../lib/runtime/loop.harn",
805            &span,
806            "error",
807            "bad value",
808            Some("here"),
809            None,
810        );
811        assert!(output.contains("--> /workspace/pipelines/lib/runtime/loop.harn:1:13"));
812        assert!(!output.contains("/../"));
813    }
814
815    #[test]
816    fn test_diagnostic_with_help() {
817        disable_colors();
818        let source = "const y = xx + 1";
819        let span = Span {
820            start: 8,
821            end: 10,
822            line: 1,
823            column: 9,
824            end_line: 1,
825        };
826        let output = render_diagnostic(
827            source,
828            "test.harn",
829            &span,
830            "error",
831            "undefined variable `xx`",
832            Some("not found in this scope"),
833            Some("did you mean `x`?"),
834        );
835        assert!(output.contains("help: did you mean `x`?"));
836    }
837
838    #[test]
839    fn test_multiline_source() {
840        disable_colors();
841        let source = "line1\nline2\nline3";
842        let span = Span::with_offsets(6, 11, 2, 1); // "line2"
843        let result = render_diagnostic(
844            source,
845            "test.harn",
846            &span,
847            "error",
848            "bad line",
849            Some("here"),
850            None,
851        );
852        assert!(result.contains("line2"));
853        assert!(result.contains("^^^^^"));
854    }
855
856    #[test]
857    fn test_single_char_span() {
858        disable_colors();
859        let source = "const x = 42";
860        let span = Span::with_offsets(4, 5, 1, 5); // "x"
861        let result = render_diagnostic(
862            source,
863            "test.harn",
864            &span,
865            "warning",
866            "unused",
867            Some("never used"),
868            None,
869        );
870        assert!(result.contains('^'));
871        assert!(result.contains("never used"));
872    }
873
874    #[test]
875    fn test_with_help() {
876        disable_colors();
877        let source = "const y = reponse";
878        let span = Span::with_offsets(8, 15, 1, 9);
879        let result = render_diagnostic(
880            source,
881            "test.harn",
882            &span,
883            "error",
884            "undefined",
885            None,
886            Some("did you mean `response`?"),
887        );
888        assert!(result.contains("help:"));
889        assert!(result.contains("response"));
890    }
891
892    #[test]
893    fn closest_match_suggests_reordered_snake_case_segments() {
894        assert_eq!(
895            find_closest_match("parse_json", ["json_parse"].into_iter(), 2),
896            Some("json_parse")
897        );
898        assert_eq!(
899            find_closest_match("read_file", ["file_read"].into_iter(), 2),
900            Some("file_read")
901        );
902        assert_eq!(
903            find_closest_match("parse_json", ["parse_yaml"].into_iter(), 2),
904            None
905        );
906    }
907
908    #[test]
909    fn closest_match_suggests_plain_typo() {
910        assert_eq!(
911            find_closest_match("json_pars", ["json_parse"].into_iter(), 2),
912            Some("json_parse")
913        );
914    }
915
916    #[test]
917    fn test_parser_error_helpers_for_eof() {
918        disable_colors();
919        let err = ParserError::UnexpectedEof {
920            expected: "}".into(),
921            span: Span::with_offsets(10, 10, 3, 1),
922        };
923        assert_eq!(
924            parser_error_message(&err),
925            "unexpected end of file, expected }"
926        );
927        assert_eq!(parser_error_label(&err), "file ends here");
928        assert_eq!(
929            parser_error_help(&err),
930            Some("add a closing `}` to finish this block")
931        );
932    }
933}
harn_parser/diagnostic.rs

harn_parser/
diagnostic.rs
