simplibs-extractor-python 0.1.0__py3-none-any.whl

simplibs/extractor_python/file_rules/python/PYTHON_CONFIG.py

@@ -0,0 +1,18 @@
+from typing import Final
+from simplibs.path.rules import NameIs
+from simplibs.rules import IsIn, Rule
+# Outers
+from ...constants import PYTHON_CONFIG_NAMES
+
+
+PYTHON_CONFIG: Final[Rule] = NameIs(IsIn(PYTHON_CONFIG_NAMES))
+"""The file is Python project configuration (`setup.py`, `tox.ini`, `requirements.txt`...)."""
+
+
+_DESIGN_NOTES = """
+# PYTHON_CONFIG — How the Project Is Built
+
+## Purpose
+Part of the strict Python exclusion. `setup.py` is Python source, but it
+describes packaging; for reading what the project does, it is noise.
+"""

simplibs/extractor_python/file_rules/python/PYTHON_STRICT_EXCLUDE.py

@@ -0,0 +1,24 @@
+from typing import Final
+from simplibs.rules import Rule
+# Outers
+from ..atomic import OUTPUT_DIRS, VCS_DIRS, VENV_DIRS
+# Inners
+from .PYTHON_CONFIG import PYTHON_CONFIG
+from .PYTHON_TESTS import PYTHON_TESTS
+
+
+PYTHON_STRICT_EXCLUDE: Final[Rule] = PYTHON_TESTS | PYTHON_CONFIG | VENV_DIRS | OUTPUT_DIRS | VCS_DIRS
+"""Everything that is Python-looking but not the project's own logic: tests, configuration, environments, build output."""
+
+
+_DESIGN_NOTES = """
+# PYTHON_STRICT_EXCLUDE — Only What the Project Does
+
+## Purpose
+The `exclude` of the profile `python/src-clean`. The old code had a strict
+filter like this, but no profile ever used it.
+
+## How It Combines
+Used together with `PYTHON_BASE` as `include`: a file must be Python source
+and must not be any of these.
+"""

simplibs/extractor_python/file_rules/python/PYTHON_TESTS.py

@@ -0,0 +1,29 @@
+from typing import Final
+from simplibs.path.rules import AnyParentNameIs, NameIs
+from simplibs.rules import IsIn, Regex, Rule
+# Outers
+from ...constants import PYTHON_TEST_DIR_NAMES
+
+
+PYTHON_TESTS: Final[Rule] = (
+    NameIs(Regex(r"^(test_.*|.*_tests?|tests?|conftest)\.py$"))
+    | AnyParentNameIs(IsIn(PYTHON_TEST_DIR_NAMES))
+)
+"""The file is a Python test: by its name (`test_a.py`, `a_test.py`, `tests.py`, `conftest.py`) or by its folder (`tests/`)."""
+
+
+_DESIGN_NOTES = """
+# PYTHON_TESTS — Recognising a Test by Its Name, Not by a Piece of It
+
+## Purpose
+Part of the strict Python exclusion.
+
+## Why a Pattern on the Whole Name
+The old rule asked whether the path CONTAINED `test`, and it threw away
+`latest_data.py`, `contest.py` and `attest.py`. The pattern is anchored at both
+ends: the name starts with `test_`, ends with `_test` or `_tests`, or is
+exactly `test`, `tests` or `conftest`, followed by `.py`.
+
+## Or Anywhere Inside a Tests Folder
+Every file in a folder called `tests` or `test` is a test helper at least.
+"""

simplibs/extractor_python/file_rules/python/__init__.py

@@ -0,0 +1,22 @@
+from .PYTHON_BASE import PYTHON_BASE
+from .PYTHON_CONFIG import PYTHON_CONFIG
+from .PYTHON_STRICT_EXCLUDE import PYTHON_STRICT_EXCLUDE
+from .PYTHON_TESTS import PYTHON_TESTS
+from .build_python_base import build_python_base
+
+
+_DESIGN_NOTES = """
+# python — File Rules for Python Projects
+
+Plain imports, no `__all__` (the package root decides what is public).
+
+## Internal Components Registry
+
+| Component               | Type     | Description                                                          |
+| :---------------------- | :------- | :------------------------------------------------------------------- |
+| `PYTHON_BASE`           | Rule     | The default choice of Python files worth reading.                    |
+| `PYTHON_CONFIG`         | Rule     | Project configuration files.                                         |
+| `PYTHON_STRICT_EXCLUDE` | Rule     | Tests, configuration, environments and build output.                 |
+| `PYTHON_TESTS`          | Rule     | Test files, by name or by folder.                                    |
+| `build_python_base`     | Function | Builds the base rule; switches for `__init__.py`, `__main__.py`.     |
+"""

simplibs/extractor_python/file_rules/python/build_python_base.py

@@ -0,0 +1,58 @@
+from simplibs.path.rules import HasSuffix
+from simplibs.rules import Rule
+from simplibs.validate import validate_call
+# Outers
+from ...constants import PYTHON_SUFFIXES
+from ..atomic import DOT_NAME, IN_DUNDER_DIR, INIT_NAME, MAIN_NAME
+
+
+@validate_call
+def build_python_base(*, include_init: bool = True, include_main: bool = True) -> Rule:
+    """Build the rule that picks the Python files worth reading.
+
+    Python files, without dot files and without anything inside a folder such
+    as `__pycache__`.
+
+    Args:
+        include_init: Take `__init__.py`. Switch off to read only the modules.
+        include_main: Take `__main__.py`. Switch off to leave the entry point out.
+
+    Returns:
+        A rule on the path relative to the source folder.
+    """
+
+    # 1. The core: Python files that are not hidden and not interpreter products
+    rule = HasSuffix(*PYTHON_SUFFIXES) & ~DOT_NAME & ~IN_DUNDER_DIR
+
+    # 2. The two package files, unless asked to leave them out
+    if not include_init:
+        rule = rule & ~INIT_NAME
+    if not include_main:
+        rule = rule & ~MAIN_NAME
+
+    return rule
+
+
+_DESIGN_NOTES = """
+# build_python_base — Which Python Files Are Source
+
+## Purpose
+The `include` of every Python profile, with two switches for the files the old
+code always dropped.
+
+## What Changed From the Old `PythonBase`
+The old rule excluded every file whose name starts with two underscores.
+That took away `__init__.py`, which holds the public names of a package, and
+`__main__.py`, the entry point. Now both are taken by default; the switches
+bring back the old behaviour. Other names of that kind (`__version__.py`,
+`__about__.py`) are ordinary modules and are taken as well.
+
+## Folders
+A folder whose name starts with two underscores is still left out
+(`__pycache__`, `__pypackages__`): it holds what the interpreter made.
+
+## Why the Name Starts With `build_`
+The constant `PYTHON_BASE` has its own file. On Windows and macOS two files
+whose names differ only by case (`python_base.py`, `PYTHON_BASE.py`) are the
+same file, so the function got a name that differs by more than the case.
+"""

simplibs/extractor_python/logic/__init__.py

@@ -0,0 +1,32 @@
+from .python_comment_spans import python_comment_spans
+from .python_outline import python_outline
+from .remove_python_comments import remove_python_comments
+from .remove_python_decorators import remove_python_decorators
+from .remove_python_docstrings import remove_python_docstrings
+from .remove_python_imports import remove_python_imports
+
+
+_DESIGN_NOTES = """
+# logic — The Steps That Read Python
+
+Plain imports, no `__all__` (the package root decides what is public).
+
+## Internal Components Registry
+
+| Component                  | Type     | Description                                                      |
+| :------------------------- | :------- | :--------------------------------------------------------------- |
+| `python_comment_spans`     | Function | The spans of the comments (by `tokenize`).                       |
+| `python_outline`           | Function | Classes and functions as signatures without bodies.              |
+| `remove_python_comments`   | Function | Removes the comments.                                            |
+| `remove_python_decorators` | Function | Removes the decorators of classes and functions.                 |
+| `remove_python_docstrings` | Function | Removes the docstrings; an emptied body gets `pass`.             |
+| `remove_python_imports`    | Function | Removes the imports at any depth; an emptied body gets `pass`.   |
+| `_helpers`                 | Private  | Offsets, the parser guard, statement cutting, finders, outline.  |
+| `_validations`             | Private  | The card of an unreadable source.                                |
+
+## Layering & Design
+- Python is read with `ast` and `tokenize`, never with a regex.
+- Each step is a function of a text and returns a text; the `Action` wrappers come in `actions`.
+- `on_error` is `"raise"` by default: a file that cannot be read is reported, not silently left unclean.
+- The steps import only `annotations`; the ranges they find are `simplibs.text.Span`.
+"""

simplibs/extractor_python/logic/_helpers/SourceOffsets.py

@@ -0,0 +1,82 @@
+import ast
+
+
+class SourceOffsets:
+    """Turns the positions `ast` and `tokenize` report into offsets in the text.
+
+    `ast` counts a column in UTF-8 BYTES, `tokenize` in characters; a span has to be in
+    characters, because that is what a string is cut by.
+
+    Example:
+        offsets = SourceOffsets(text)
+        start, end = offsets.span_of(node)
+    """
+
+    __slots__ = ("_text", "_starts", "_is_ascii")
+
+    def __init__(self, text: str) -> None:
+
+        # 1. The offset where each line begins
+        starts = [0]
+        position = 0
+        for line in text.split("\n")[:-1]:
+            position += len(line) + 1
+            starts.append(position)
+
+        # 2. Keep what the conversions need
+        self._text = text
+        self._starts = starts
+        self._is_ascii = text.isascii()
+
+    def token_offset(self, row: int, column: int) -> int:
+        """The offset of a `tokenize` position (1-based row, column in characters)."""
+
+        # 1. Characters already: only the start of the line is added
+        return self._starts[row - 1] + column
+
+    def ast_offset(self, lineno: int, column: int) -> int:
+        """The offset of an `ast` position (1-based line, column in UTF-8 bytes)."""
+
+        # 1. Where the line begins
+        start = self._starts[lineno - 1]
+
+        # 2. Only ASCII text has one byte per character
+        if self._is_ascii or column == 0:
+            return start + column
+
+        # 3. Count the characters that fit into that many bytes
+        end = self._text.find("\n", start)
+        line = self._text[start:] if end == -1 else self._text[start:end]
+        return start + len(line.encode("utf-8")[:column].decode("utf-8"))
+
+    def span_of(self, node: ast.AST) -> tuple[int, int]:
+        """The `(start, end)` of a node, in characters."""
+
+        # 1. Both ends of the node
+        return (
+            self.ast_offset(node.lineno, node.col_offset),
+            self.ast_offset(node.end_lineno, node.end_col_offset),
+        )
+
+
+_DESIGN_NOTES = """
+# SourceOffsets — Bytes Become Characters
+
+## Purpose
+`ast` reports `col_offset` in UTF-8 bytes. In a line with `é` or `€` before
+the node, a byte column is NOT a character column, and a cut by it lands in
+the wrong place. Every step that cuts by `ast` positions goes through this
+class.
+
+## Why a Class
+The line table is built once per text and used for every node.
+
+## ASCII Is the Common Case
+For a text of ASCII only, a byte and a character are the same thing and the
+conversion is an addition.
+
+## Line Endings
+Lines are split by `\\n` only, which is what `ast` and `tokenize` count for a
+text that has only `\\n`; the steps refuse a text with `\\r` before they get
+here.
+"""

simplibs/extractor_python/logic/_helpers/__init__.py

@@ -0,0 +1,36 @@
+from .SourceOffsets import SourceOffsets
+from .collect_definitions import collect_definitions
+from .cut_statements import cut_statements
+from .describe_source_failure import describe_source_failure
+from .find_decorator_spans import find_decorator_spans
+from .find_docstrings import find_docstrings
+from .find_imports import find_imports
+from .first_doc_line import first_doc_line
+from .format_type_params import format_type_params
+from .guarded_parse import guarded_parse
+from .outline_node import outline_node
+from .parse_python import parse_python
+
+
+_DESIGN_NOTES = """
+# _helpers — Shared Tools of the Python Steps
+
+Private. Plain imports, no `__all__`.
+
+## Internal Components Registry
+
+| Component                 | Type     | Description                                                          |
+| :------------------------ | :------- | :------------------------------------------------------------------- |
+| `SourceOffsets`           | Class    | Turns `ast` byte columns and `tokenize` positions into offsets.      |
+| `collect_definitions`     | Function | The classes and functions a body defines, looking through blocks.    |
+| `cut_statements`          | Function | Removes simple statements; empty blocks get `pass`.                  |
+| `describe_source_failure` | Function | An exception of a parser as a reason and a line.                     |
+| `find_decorator_spans`    | Function | The span of every decorator, from its `@`.                           |
+| `find_docstrings`         | Function | The docstring statements of a module.                                |
+| `find_imports`            | Function | Every import statement, at any depth.                                |
+| `first_doc_line`          | Function | The first line of a docstring as a trailing comment.                 |
+| `format_type_params`      | Function | `[T, U: int]` of a class or function (Python 3.12+).                 |
+| `guarded_parse`           | Function | Runs a parser; decides by `on_error` what a failure means.          |
+| `outline_node`            | Function | The signature lines of one class or function.                        |
+| `parse_python`            | Function | `ast.parse` under the guard.                                         |
+"""

simplibs/extractor_python/logic/_helpers/collect_definitions.py

@@ -0,0 +1,60 @@
+import ast
+from collections.abc import Sequence
+
+
+_DEFINITIONS = (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)
+_BLOCK_FIELDS = ("body", "handlers", "orelse", "finalbody", "cases")
+_CLAUSES = (ast.ExceptHandler, ast.match_case)
+
+
+def collect_definitions(body: Sequence[ast.stmt]) -> list[ast.stmt]:
+    """Collect the classes and functions defined in a body, in source order.
+
+    Args:
+        body: The statements of a module or of a class.
+
+    Returns:
+        The definitions at this level, including those inside `if`, `try`, `with`, `for`,
+        `while` and `match` blocks, which are looked through but not reported.
+    """
+
+    # 1. A definition counts; a block that holds definitions is looked through
+    found: list[ast.stmt] = []
+    for statement in body:
+        if isinstance(statement, _DEFINITIONS):
+            found.append(statement)
+            continue
+        for field in _BLOCK_FIELDS:
+            inner = getattr(statement, field, None)
+            if not isinstance(inner, list):
+                continue
+            for item in inner:
+                # 2. An `except` handler and a `case` hold a body of their own; anything else is a statement
+                found.extend(collect_definitions(item.body if isinstance(item, _CLAUSES) else [item]))
+
+    return found
+
+
+_DESIGN_NOTES = """
+# collect_definitions — What a Body Defines
+
+## Purpose
+The outline lists classes and functions. Which ones belong to a module or a
+class is answered here.
+
+## Looked Through, Not Entered
+A function defined inside another function is a detail of that function and is
+not listed. A definition under `if sys.version_info >= ...:`, inside a `try`
+or under a `case` of a `match` IS a member of the module, so those blocks are
+looked through. The condition is lost; if both branches define `f`, both are
+listed (valid Python, which allows a redefinition).
+
+## Clauses With a Body of Their Own
+An `except` handler and a `case` are not statements: each holds a body of its
+own and is looked into through it. Every other item of a block is a statement
+and is looked at as one. That is all there is, so there is no third kind to
+skip.
+
+## Source Order
+Definitions come in the order they stand in the file, also across blocks.
+"""

simplibs/extractor_python/logic/_helpers/cut_statements.py

@@ -0,0 +1,126 @@
+import ast
+from bisect import bisect_right
+from collections.abc import Collection
+from simplibs.text import remove_spans
+# Inners
+from .SourceOffsets import SourceOffsets
+
+
+_BLOCK_FIELDS = ("body", "orelse", "finalbody")
+
+
+def _extend_over_semicolon(text: str, start: int, end: int) -> tuple[int, int]:
+    """Widen a statement's span over the `;` that joins it to its neighbour on the same line."""
+
+    # 1. A `;` after it: take it and the blanks behind it, so the next statement moves up
+    probe = end
+    while probe < len(text) and text[probe] in " \t":
+        probe += 1
+    if probe < len(text) and text[probe] == ";":
+        probe += 1
+        while probe < len(text) and text[probe] in " \t":
+            probe += 1
+        return start, probe
+
+    # 2. Otherwise a `;` before it: the statement is the last of its line, take the `;` with it
+    probe = start
+    while probe > 0 and text[probe - 1] in " \t":
+        probe -= 1
+    if probe > 0 and text[probe - 1] == ";":
+        probe -= 1
+        while probe > 0 and text[probe - 1] in " \t":
+            probe -= 1
+        return probe, end
+
+    # 3. Alone on its line
+    return start, end
+
+
+def cut_statements(
+    text: str,
+    tree: ast.Module,
+    targets: Collection[ast.stmt],
+    offsets: SourceOffsets,
+) -> str:
+    """Remove simple statements from a module and keep the rest valid Python.
+
+    Args:
+        text: The source the tree was parsed from.
+        tree: The parsed module.
+        targets: The statements to remove: simple ones (an import, an expression), never a compound one.
+        offsets: The offsets of `text`.
+
+    Returns:
+        The text without the statements. A block that would be left empty gets a `pass`.
+    """
+
+    # 1. Nothing to cut — the very same text back
+    if not targets:
+        return text
+
+    # 2. Walk every list of statements, remember what to cut and where a block would be left empty
+    spans: list[tuple[int, int]] = []
+    pass_positions: list[int] = []
+    for node in ast.walk(tree):
+        for field in _BLOCK_FIELDS:
+            statements = getattr(node, field, None)
+            if not isinstance(statements, list) or not statements:
+                continue
+            hits = [statement for statement in statements if statement in targets]
+            if not hits:
+                continue
+            if len(hits) == len(statements) and not isinstance(node, ast.Module):
+                pass_positions.append(offsets.span_of(statements[0])[0])
+            for statement in hits:
+                start, end = offsets.span_of(statement)
+                spans.append(_extend_over_semicolon(text, start, end))
+
+    # 3. Put each `pass` in front of the first statement of its block; the cut then leaves just the `pass`
+    pass_positions.sort()
+    pieces: list[str] = []
+    previous = 0
+    for position in pass_positions:
+        pieces.append(text[previous:position])
+        pieces.append("pass")
+        previous = position
+    pieces.append(text[previous:])
+    padded = "".join(pieces)
+
+    # 4. The spans move with the text: every `pass` inserted at or before an offset pushes it by four
+    shifted = [
+        (start + 4 * bisect_right(pass_positions, start), end + 4 * bisect_right(pass_positions, end))
+        for start, end in spans
+    ]
+
+    # 5. Cut; a line that only held a removed statement disappears whole
+    return remove_spans(padded, shifted)
+
+
+_DESIGN_NOTES = """
+# cut_statements — Taking Statements Out Without Breaking the Syntax
+
+## Purpose
+The one primitive behind `remove_python_docstrings` and
+`remove_python_imports`: the caller decides WHICH statements go, this decides
+how to remove them so that what is left is still Python.
+
+## The Three Traps
+1. **An emptied block.** `try: import x` / `else:` / a class holding only its
+   docstring: a block needs a statement. It gets a `pass` — in a module, an
+   empty body is fine and gets none.
+2. **A statement sharing a line.** `import a; x = 1` and `x = 1; import a`:
+   the `;` that joined them goes with the removed statement, the other one
+   stays on a line of its own. Without it, `; x = 1` would not parse.
+3. **A statement that is not alone on its line.** `import a  # note`: only the
+   statement is removed; what remains of the line is what was there besides.
+
+## How the `pass` Gets There
+It is inserted in front of the first statement of the block and the whole
+block is cut afterwards, so the `pass` takes the place of the removed text,
+indentation and all. Offsets are shifted by four for every `pass` in front
+of them.
+
+## Why Simple Statements Only
+A compound statement (`def`, `if`) contains lists of statements of its own,
+and cutting both would count some of them twice. Nothing here needs it.
+"""

simplibs/extractor_python/logic/_helpers/describe_source_failure.py

@@ -0,0 +1,34 @@
+import tokenize
+
+
+def describe_source_failure(exc: Exception) -> tuple[str, int | None]:
+    """Say in words why a text could not be read, and where.
+
+    Args:
+        exc: What the parser raised.
+
+    Returns:
+        `(reason, line)`; the line is `None` when the exception does not carry one.
+    """
+
+    # 1. A syntax error knows its message and its line
+    if isinstance(exc, SyntaxError):
+        return (exc.msg or "invalid syntax"), exc.lineno
+
+    # 2. The tokenizer puts the message and `(line, column)` into its arguments
+    if isinstance(exc, tokenize.TokenError):
+        reason = str(exc.args[0]) if exc.args else "tokenizing failed"
+        line = exc.args[1][0] if len(exc.args) > 1 and isinstance(exc.args[1], tuple) else None
+        return reason, line
+
+    # 3. The rest has only a text
+    return (str(exc) or type(exc).__name__), None
+
+
+_DESIGN_NOTES = """
+# describe_source_failure — From an Exception to a Sentence
+
+## Purpose
+`SyntaxError`, `tokenize.TokenError` and `ValueError` say the same thing in
+three shapes. The card needs one: a reason and a line.
+"""

simplibs/extractor_python/logic/_helpers/find_decorator_spans.py

@@ -0,0 +1,107 @@
+import ast
+from simplibs.text import Span
+# Inners
+from .SourceOffsets import SourceOffsets
+
+
+def _line_start(text: str, position: int) -> int:
+    """The offset where the line holding `position` begins."""
+    return max(text.rfind("\n", 0, position), text.rfind("\r", 0, position)) + 1
+
+
+def _end_of_line(text: str, position: int) -> int:
+    """The offset of the line break that ends the line holding `position` (or the end of the text)."""
+    while position < len(text) and text[position] not in "\r\n":
+        position += 1
+    return position
+
+
+def _count_opening_brackets(text: str, begin: int, stop: int) -> int:
+    """Count the `(` in `text[begin:stop]`, leaving out comments."""
+    count = 0
+    position = begin
+    while position < stop:
+        if text[position] == "#":
+            position = _end_of_line(text, position)
+            continue
+        if text[position] == "(":
+            count += 1
+        position += 1
+    return count
+
+
+def _skip_filler(text: str, position: int) -> int:
+    """The offset of the first character from `position` on that is no blank, line break or comment."""
+    while position < len(text) and (text[position] in " \t\f\r\n" or text[position] == "#"):
+        position = _end_of_line(text, position) if text[position] == "#" else position + 1
+    return position
+
+
+def find_decorator_spans(text: str, tree: ast.Module, offsets: SourceOffsets) -> list[Span]:
+    """Find the decorators of every class and function, each from its `@` to its end.
+
+    Args:
+        text: The source the tree was parsed from.
+        tree: The parsed module.
+        offsets: The offsets of `text`.
+
+    Returns:
+        One span per decorator.
+    """
+
+    # 1. Every decorator of every class and function
+    spans: list[Span] = []
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            continue
+        for decorator in node.decorator_list:
+            start, end = offsets.span_of(decorator)
+
+            # 2. The `@` stands in front of the expression; an `@` with a `#` before it on its line is in a comment
+            at = text.rfind("@", 0, start)
+            while "#" in text[_line_start(text, at):at]:
+                at = text.rfind("@", 0, at)
+
+            # 3. `@(factory)`: the node does not include its own brackets, so the closing ones are taken too
+            #    (the text parsed, so every opening bracket has its closing one behind the expression)
+            for _ in range(_count_opening_brackets(text, at + 1, start)):
+                end = _skip_filler(text, end) + 1
+
+            spans.append((at, end))
+
+    return spans
+
+
+_DESIGN_NOTES = """
+# find_decorator_spans — From the `@` to the End of the Expression
+
+## Purpose
+`ast` gives the position of the decorator's EXPRESSION, not of the `@`. The
+span has to start at the `@`, or what is left is a line holding a lone `@`.
+
+## Why `rfind`, and Why a Check After It
+The nearest `@` in front of the expression is the decorator's own: between
+them stand only blanks, opening brackets and, inside brackets, comments. A
+comment may hold an `@` of its own (`# mail me@home`), so one more rule is
+needed: the real `@` is the first thing on its line, hence an `@` with a `#`
+in front of it on its line belongs to a comment and is skipped.
+
+## Bracketed Decorators
+`@(lambda f: f)` is valid since Python 3.9. The expression node starts after
+the `(` and ends before the `)`, so a cut by the node alone would leave a
+stray bracket. The brackets in front of the expression are counted and the
+same number of closing ones is taken after it. The text parsed, so every
+opening bracket has its closing one behind the expression; there is nothing
+to check, only to find.
+
+## Comments Inside the Brackets
+Between the `@` and the expression, and between the expression and its `)`,
+no string can stand, so a `#` there always starts a comment. Such a comment
+is skipped when counting the brackets and when looking for the closing one
+(`@(dec  # note)` + line break + `)` has its real `)` on the next line), and
+it stays inside the span.
+
+## What Stays
+A comment AFTER the decorator (`@dec  # note`) is not part of it. Comments are
+a step of their own, normally run first.
+"""