Add `-ast`, outputting annotated AST information for Anvil files by wxwern · Pull Request #83 · AnvilHDL/anvil

wxwern · 2026-03-17T13:14:34Z

A preliminary implementation of outputting annotated AST information from the AnvilHDL compiler.

This allows for language servers to query AST information from Anvil, and supply hover hints, jump to definition, etc., to code editors, for an improved user experience.

Together with anvil-lsp, this resolves #73.

Current limitations:

Compiler warnings are lone print statements and have no mechanism to be collected and outputted at this time. This should be added in the future.
Not all symbols are annotated with their exact ranges without much more significant refactors. This makes it impossible to support symbol renames under LSP.
Definitions and types with unknown parameters are not analyzed by the compiler. This means most LSP features currently don't work correctly if a definition contains type parameters.

Important side effects:

Many nodes are now wrapped with ast_node or have codespan information added.
Added ErrorCollector to support collecting multiple errors, by injecting a modified raise function into the global scope when opened.

this includes unimplemented: - definition span annotations - event graph annotations this does not include a public API to obtain the JSON output yet

this invokes and outputs the internally implemented ast-to-JSON conversion

This commit adds experimental support for collecting a set of errors instead of bailing out on any error. These errors are reported within the AST as an example.

arj4web · 2026-07-12T07:46:09Z

+let collect_errors : bool ref = ref false
+
+(* Method injection *)
+let raise (e: exn) =


This is problematic right ?

Sometimes we may have structural errors, after which we should not continue

That's why there's an alternate pathway where errors can be raised through raise_fatal instead.

The idea is this intercepts all raise methods in the file if opened, and therefore makes the default behaviour fallthrough and we can use the fatal variant if we can't recover from it.

Generally, if there are strict structural errors that we can't handle, the OCaml type checker will prevent compilation anyways, since raise will fall-through with a return type unit, in which case we can decide ourselves if there's a fallback we can use or if we should change it to be a fatal exception.

arj4web

This almost seems fine, except for a few redundant additions and what appear to be some genuine errors.

You can try fixing the errors first.

This PR is very detail-oriented, so hopefully I didn't miss anything major. I'll still ask Copilot to look for any remaining details.

Copilot

Pull request overview

Copilot reviewed 31 out of 32 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

lib/graphBuilder.ml:177

The argument-count check for function calls only guards the raise line; List.iter2 and the recursive call execute unconditionally. When ErrorCollector.collect_errors is enabled, raise will not abort, so List.iter2 can throw due to list-length mismatch and crash instead of producing a collected compiler error.

      if List.length td_args <> List.length func.args then
        raise (event_graph_error_default "Arguments missing in function call" e.span);
        List.iter2 (fun td arg ->

jasonyu1996 · 2026-08-01T21:48:15Z

+    let cunit_json = compilation_unit_with_event_graph_to_yojson cunit gcol_list in
+    let _ = assert (cunit.cunit_file_name = Some fname) in
+    cunit_json


Do we want to fix this? Is it possible that there's no file name when -ast is supplied?

Ok I suppose this is an implicit invariant specific to the implementation. assertion looks reasonable

jasonyu1996 · 2026-07-26T21:53:55Z

@wxwern Sorry let me review in the next few days. Always forgot

jasonyu1996 · 2026-08-01T21:50:00Z

-(** Create successful JSON output *)
-let success_output output_str =
-  { success = true; errors = []; output = Some output_str }
+let transpiled_output output_str =


Perhaps unimportant: why is it called "transpile"?

cuz it's transpiled to system verilog technically and it makes it clear that this is source code output

jasonyu1996 · 2026-08-01T22:07:08Z

+let has_collected_errors () : bool =
+  !_global_errors <> []
+
+let dedup_collected_errors () =


Why do we need to do dedup?

for non-blocking errors many will be re-reported if a validation pathway reencounters the same issue after a loop or any repeated evaluation, and it was easier to just deduplicate it than to trace every instance of duplication

jasonyu1996 · 2026-08-01T22:19:30Z

+          add_msg msg ev ({d = {ty = Recv msg; until = ev}; def_span = ac_span.def_span; action_event = ac_span.action_event; span = ac_span.span})
        | ImmediateSend (msg, td) ->
-          add_msg msg ev ({d = {ty = Send (msg, td); until = ev}; span = ac_span.span})
+          add_msg msg ev ({d = {ty = Send (msg, td); until = ev}; def_span = ac_span.def_span; action_event = ac_span.action_event; span = ac_span.span})


This pattern shows up quite a lot it seems. Maybe can have a polymorphic function, something like map : (U -> V) -> (U ast_node) -> (V ast_node).

this would result in a much larger refactor than the already large PR, but i'm fine if y'all are fine with that

jasonyu1996

Look good overall. Just some minor questions/nits

wxwern added 30 commits February 26, 2026 07:32

add lang ast-to-json conversion internals

e89dbad

this includes unimplemented: - definition span annotations - event graph annotations this does not include a public API to obtain the JSON output yet

add -ast flag

ae97cbc

this invokes and outputs the internally implemented ast-to-JSON conversion

add ast annotation helpers

906dcf0

add event annotations on the AST for external output

a9b6982

add definition annotations on the AST for external output

d6533d7

report success = false on partial errors for JSON output

c35f25d

improved ast annotations and reporting fixes

15eea4e

fix def span annotations for multi-expr tokens

73d1cf5

fix comment

06ec693

add error collection, multi-error-reporting in AST

bd33852

This commit adds experimental support for collecting a set of errors instead of bailing out on any error. These errors are reported within the AST as an example.

Merge branch 'master' into add-annotated-ast-output

e77f8d7

Merge branch 'master' into add-annotated-ast-output

19b16b3

Merge branch 'dev' into add-annotated-ast-output

055a565

Merge branch 'dev' into add-annotated-ast-output

416431b

add more event annotations

c736fe7

fix record (struct) field order in AST JSON output

21037d8

fix all msg spec def ast annotations

3c418e4

fix spawn_def ast def span annotations

5c2ae0a

fix missing error filename for multi-error collection

90385d2

update ast annot; wrap variant and record fields in ast node

c01e25a

update ast annot; add record and variant construct def spans

e05e124

fix indirect lvalue def span annot

139941f

fix ast def span annot order and dedup

5fe4ca5

fix missing event graph collections

e0b1760

disable ast annotator when unused

d075c20

add json schema version string to cunit in ast output

e6f9a03

add possible sustained cycle timings in ast annotations

30e1189

add eval delay cycles to ast annotations

6199e2b

Merge branch 'fix-printouts' into add-annotated-ast-output

41b403c

rewrite cycle delay annot as symbolic sum

93fbd9d