chore[ux]: compute natspec as part of standard pipeline (vyperlang#3946)

prior to this commit, natspec had to be explicitly requested by the user
(`-f userdoc`, `-f devdoc` or `-f combined_json`). this would lead to
discrepancies between development time and verification time, where a
contract could compile locally (because no natspec was requested), but
not on the verifier's pipeline (because the verifier would request the
natspec via one of the above methods). this commit computes the natspec
as part of the dependencies of the analysed AST (the reasoning being
that, a consumer might expect semantic analysis to include natspec
validation). so, there is no way to produce bytecode for a contract
without validating natspec.

tests/unit/ast/test_natspec.py

@@ -1,6 +1,7 @@
 import pytest
 
 from vyper import ast as vy_ast
+from vyper.compiler import compile_code
 from vyper.compiler.phases import CompilerData
 from vyper.exceptions import NatSpecSyntaxException
 
@@ -65,10 +66,10 @@ def parse_natspec(code):
 
 
 def test_documentation_example_output():
-    userdoc, devdoc = parse_natspec(test_code)
+    natspec = parse_natspec(test_code)
 
-    assert userdoc == expected_userdoc
-    assert devdoc == expected_devdoc
+    assert natspec.userdoc == expected_userdoc
+    assert natspec.devdoc == expected_devdoc
 
 
 def test_no_tags_implies_notice():
@@ -84,13 +85,13 @@ def foo():
     pass
     """
 
-    userdoc, devdoc = parse_natspec(code)
+    natspec = parse_natspec(code)
 
-    assert userdoc == {
+    assert natspec.userdoc == {
         "methods": {"foo()": {"notice": "This one too!"}},
         "notice": "Because there is no tag, this docstring is handled as a notice.",
     }
-    assert not devdoc
+    assert natspec.devdoc == {}
 
 
 def test_whitespace():
@@ -111,9 +112,9 @@ def test_whitespace():
 @author Mr No-linter
                 '''
 """
-    _, devdoc = parse_natspec(code)
+    natspec = parse_natspec(code)
 
-    assert devdoc == {
+    assert natspec.devdoc == {
         "author": "Mr No-linter",
         "details": "Whitespace gets cleaned up, people can use awful formatting. We don't mind!",
     }
@@ -131,9 +132,9 @@ def foo(bar: int128, baz: uint256, potato: bytes32):
     pass
     """
 
-    _, devdoc = parse_natspec(code)
+    natspec = parse_natspec(code)
 
-    assert devdoc == {
+    assert natspec.devdoc == {
         "methods": {
             "foo(int128,uint256,bytes32)": {
                 "details": "we didn't document potato, but that's ok",
@@ -154,9 +155,9 @@ def foo(bar: int128, baz: uint256) -> (int128, uint256):
     return bar, baz
     """
 
-    _, devdoc = parse_natspec(code)
+    natspec = parse_natspec(code)
 
-    assert devdoc == {
+    assert natspec.devdoc == {
         "methods": {
             "foo(int128,uint256)": {"returns": {"_0": "value of bar", "_1": "value of baz"}}
         }
@@ -176,9 +177,9 @@ def notfoo(bar: int128, baz: uint256):
     pass
     """
 
-    _, devdoc = parse_natspec(code)
+    natspec = parse_natspec(code)
 
-    assert devdoc["methods"] == {"foo(int128,uint256)": {"details": "I will be parsed."}}
+    assert natspec.devdoc["methods"] == {"foo(int128,uint256)": {"details": "I will be parsed."}}
 
 
 def test_partial_natspec():
@@ -276,9 +277,9 @@ def foo():
     pass
     """
 
-    _, devdoc = parse_natspec(code)
+    natspec = parse_natspec(code)
 
-    assert devdoc == {"license": license}
+    assert natspec.devdoc == {"license": license}
 
 
 fields = ["title", "author", "license", "notice", "dev"]
@@ -417,3 +418,21 @@ def foo() -> (int128,uint256):
         NatSpecSyntaxException, match="Number of documented return values exceeds actual number"
     ):
         parse_natspec(code)
+
+
+def test_natspec_parsed_implicitly():
+    # test natspec is parsed even if not explicitly requested
+    code = """
+'''
+@noticee x
+'''
+    """
+    with pytest.raises(NatSpecSyntaxException):
+        parse_natspec(code)
+
+    # check we can get ast
+    compile_code(code, output_formats=["ast_dict"])
+
+    # anything beyond ast is blocked
+    with pytest.raises(NatSpecSyntaxException):
+        compile_code(code, output_formats=["annotated_ast_dict"])

vyper/ast/natspec.py

@@ -1,4 +1,5 @@
 import re
+from dataclasses import dataclass
 from typing import Optional, Tuple
 
 from asttokens import LineNumbers
@@ -11,7 +12,13 @@
 USERDOCS_FIELDS = ("notice",)
 
 
-def parse_natspec(annotated_vyper_module: vy_ast.Module) -> Tuple[dict, dict]:
+@dataclass
+class NatspecOutput:
+    userdoc: dict
+    devdoc: dict
+
+
+def parse_natspec(annotated_vyper_module: vy_ast.Module) -> NatspecOutput:
     """
     Parses NatSpec documentation from a contract.
 
@@ -63,7 +70,7 @@ def parse_natspec(annotated_vyper_module: vy_ast.Module) -> Tuple[dict, dict]:
             if fn_natspec:
                 devdoc.setdefault("methods", {})[method_id] = fn_natspec
 
-    return userdoc, devdoc
+    return NatspecOutput(userdoc=userdoc, devdoc=devdoc)
 
 
 def _parse_docstring(

vyper/compiler/output.py

@@ -2,7 +2,7 @@
 from collections import deque
 from pathlib import PurePath
 
-from vyper.ast import ast_to_dict, parse_natspec
+from vyper.ast import ast_to_dict
 from vyper.codegen.ir_node import IRnode
 from vyper.compiler.phases import CompilerData
 from vyper.compiler.utils import build_gas_estimates
@@ -30,13 +30,11 @@ def build_annotated_ast_dict(compiler_data: CompilerData) -> dict:
 
 
 def build_devdoc(compiler_data: CompilerData) -> dict:
-    userdoc, devdoc = parse_natspec(compiler_data.annotated_vyper_module)
-    return devdoc
+    return compiler_data.natspec.devdoc
 
 
 def build_userdoc(compiler_data: CompilerData) -> dict:
-    userdoc, devdoc = parse_natspec(compiler_data.annotated_vyper_module)
-    return userdoc
+    return compiler_data.natspec.userdoc
 
 
 def build_external_interface_output(compiler_data: CompilerData) -> str:

vyper/compiler/phases.py

@@ -5,6 +5,7 @@
 from typing import Optional
 
 from vyper import ast as vy_ast
+from vyper.ast import natspec
 from vyper.codegen import module
 from vyper.codegen.ir_node import IRnode
 from vyper.compiler.input_bundle import FileInput, FilesystemInputBundle, InputBundle
@@ -150,9 +151,19 @@ def _generate_ast(self):
     def vyper_module(self):
         return self._generate_ast
 
+    @cached_property
+    def _annotate(self) -> tuple[natspec.NatspecOutput, vy_ast.Module]:
+        module = generate_annotated_ast(self.vyper_module, self.input_bundle)
+        nspec = natspec.parse_natspec(module)
+        return nspec, module
+
+    @cached_property
+    def natspec(self) -> natspec.NatspecOutput:
+        return self._annotate[0]
+
     @cached_property
     def annotated_vyper_module(self) -> vy_ast.Module:
-        return generate_annotated_ast(self.vyper_module, self.input_bundle)
+        return self._annotate[1]
 
     @cached_property
     def compilation_target(self):
@@ -173,6 +184,8 @@ def storage_layout(self) -> StorageLayout:
     def global_ctx(self) -> ModuleT:
         # ensure storage layout is computed
         _ = self.storage_layout
+        # ensure natspec is computed
+        _ = self.natspec
         return self.annotated_vyper_module._metadata["type"]
 
     @cached_property