codeterrain-terraform 0.2.0__tar.gz

codeterrain_terraform-0.2.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.codeterrain/
+dist/
+build/
+*.egg-info/
+
+# Local, private overlays (not part of the project)
+CLAUDE.local.md

codeterrain_terraform-0.2.0/PKG-INFO

@@ -0,0 +1,39 @@
+Metadata-Version: 2.5
+Name: codeterrain-terraform
+Version: 0.2.0
+Summary: Terraform for codeterrain: resources, modules, providers and references of .tf files in terrain def and refs.
+Project-URL: Homepage, https://github.com/benchli-sports/codeterrain
+Project-URL: Issues, https://github.com/benchli-sports/codeterrain/issues
+Author: Mitbolas GmbH
+License: Apache-2.0
+Requires-Python: >=3.12
+Requires-Dist: codeterrain>=0.3
+Description-Content-Type: text/markdown
+
+# codeterrain-terraform
+
+Terraform for [codeterrain](https://github.com/benchli-sports/codeterrain): the definitions and
+references of `.tf` files, in `terrain def` and `terrain refs`.
+
+```
+uv tool install "<path-to-the-codeterrain-checkout>[terraform]"
+terrain def logs                    # resource aws_s3_bucket.logs  infra/storage.tf:12
+terrain refs var.region             # every expression that reads it, and the block it sits in
+terrain def --kind module           # every module call, with its file, source and version
+terrain def --kind required_provider  # every pinned provider and its version constraint
+terrain refs provider.aws.east      # the resources and module calls that select that provider
+```
+
+Not published yet: install from a checkout of the codeterrain repository, where this pack lives under
+`packages/`. Once published, `pip install "codeterrain[terraform]"` will do the same.
+`terrain doctor` lists the installed packs (`language packs: terraform 0.2.0`).
+
+Names follow Terraform's own references: `aws_s3_bucket.logs`, `data.aws_ami.base`, `module.vpc`,
+`var.region`, `local.tags`, `output.url`, and `provider.aws` for both an entry of
+`required_providers` (kind `required_provider`) and a `provider "aws"` block (kind `provider`;
+`provider.aws.east` with `alias = "east"`). A module call's doc is its `source` and `version`, as
+is a required provider's. A resource's `provider = aws.east` and a module's
+`providers = { aws = aws.east }` are references to `provider.aws.east`. References are found in attribute values and inside string
+and heredoc templates. The reader is a tokenizer, not an evaluator: it follows no module source,
+expands no `count` or `for_each` and reads no `.tfvars`. A resource that selects no provider uses
+its default one implicitly; that is not listed as a reference. `.tf.json` files are not read.

codeterrain_terraform-0.2.0/README.md

@@ -0,0 +1,27 @@
+# codeterrain-terraform
+
+Terraform for [codeterrain](https://github.com/benchli-sports/codeterrain): the definitions and
+references of `.tf` files, in `terrain def` and `terrain refs`.
+
+```
+uv tool install "<path-to-the-codeterrain-checkout>[terraform]"
+terrain def logs                    # resource aws_s3_bucket.logs  infra/storage.tf:12
+terrain refs var.region             # every expression that reads it, and the block it sits in
+terrain def --kind module           # every module call, with its file, source and version
+terrain def --kind required_provider  # every pinned provider and its version constraint
+terrain refs provider.aws.east      # the resources and module calls that select that provider
+```
+
+Not published yet: install from a checkout of the codeterrain repository, where this pack lives under
+`packages/`. Once published, `pip install "codeterrain[terraform]"` will do the same.
+`terrain doctor` lists the installed packs (`language packs: terraform 0.2.0`).
+
+Names follow Terraform's own references: `aws_s3_bucket.logs`, `data.aws_ami.base`, `module.vpc`,
+`var.region`, `local.tags`, `output.url`, and `provider.aws` for both an entry of
+`required_providers` (kind `required_provider`) and a `provider "aws"` block (kind `provider`;
+`provider.aws.east` with `alias = "east"`). A module call's doc is its `source` and `version`, as
+is a required provider's. A resource's `provider = aws.east` and a module's
+`providers = { aws = aws.east }` are references to `provider.aws.east`. References are found in attribute values and inside string
+and heredoc templates. The reader is a tokenizer, not an evaluator: it follows no module source,
+expands no `count` or `for_each` and reads no `.tfvars`. A resource that selects no provider uses
+its default one implicitly; that is not listed as a reference. `.tf.json` files are not read.

codeterrain_terraform-0.2.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "codeterrain-terraform"
+version = "0.2.0"
+description = "Terraform for codeterrain: resources, modules, providers and references of .tf files in terrain def and refs."
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Mitbolas GmbH" }]
+dependencies = ["codeterrain>=0.3"]
+
+[project.entry-points."codeterrain.languages"]
+terraform = "codeterrain_terraform:language"
+
+[project.urls]
+Homepage = "https://github.com/benchli-sports/codeterrain"
+Issues = "https://github.com/benchli-sports/codeterrain/issues"
+
+[tool.uv.sources]
+codeterrain = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/codeterrain_terraform"]

codeterrain_terraform-0.2.0/src/codeterrain_terraform/__init__.py

@@ -0,0 +1,470 @@
+"""Terraform for codeterrain: the definitions and references of ``.tf`` files.
+
+Definitions are named the way Terraform code refers to them:
+
+- ``resource "aws_s3_bucket" "logs"`` is ``aws_s3_bucket.logs``;
+- ``data "aws_ami" "base"`` is ``data.aws_ami.base``;
+- ``module "vpc"`` is ``module.vpc``, ``variable "region"`` is ``var.region``, an entry of a
+  ``locals`` block is ``local.name`` and ``output "url"`` is ``output.url``;
+- an entry of ``required_providers`` is ``provider.aws``, and ``provider "aws"`` is
+  ``provider.aws`` too, or ``provider.aws.east`` with ``alias = "east"``.
+
+A module call's doc is its ``source`` and ``version``, a required provider's the same; a
+resource's ``provider = aws.east`` and a module's ``providers = { aws = aws.east }`` are
+references to ``provider.aws.east``.
+
+References are the expressions that name one of those (``var.region``, ``aws_s3_bucket.logs.arn``,
+``module.vpc.id``), in attribute values and inside string and heredoc templates, with the
+definition they sit in as their scope. The reader is a tokenizer, not an evaluator: it follows no
+module source, expands no ``count`` or ``for_each`` and reads no ``.tfvars``.
+"""
+
+from __future__ import annotations
+
+import re
+import string
+import sys
+import textwrap
+from dataclasses import dataclass
+from importlib.metadata import PackageNotFoundError, version
+from typing import Any
+
+try:
+    __version__ = version("codeterrain-terraform")
+except PackageNotFoundError:  # run from a source tree
+    __version__ = "0"
+
+#: Labels each top-level block takes, and how its definition is named.
+_BLOCKS = {"resource": 2, "data": 2, "module": 1, "variable": 1, "output": 1, "provider": 1}
+_PREFIX = {"resource": "", "data": "data.", "module": "module.", "variable": "var.",
+           "output": "output.", "provider": "provider."}
+#: Objects whose attributes are never a definition of this configuration.
+_BUILTIN = frozenset({"each", "count", "path", "terraform", "self"})
+#: A resource type: a provider name, ``_``, then the type (``aws_s3_bucket``, ``random_id``).
+_RESOURCE_TYPE = re.compile(r"[a-z][a-z0-9]*_[a-z0-9_]+\Z")
+#: A Terraform identifier: Unicode letters, digits, ``_`` and ``-``, not starting with a digit.
+_IDENT = re.compile(r"[^\W\d][\w-]*")
+#: Operators of more than one character, kept as one token so ``==`` is never read as ``=``.
+_OPERATOR = re.compile(r"==|!=|<=|>=|=>|&&|\|\||\.\.\.|::")
+_HEREDOC = re.compile(r"<<-?([^\W\d][\w-]*)[ \t]*\r?\n")
+#: What a quoted string's single-character escapes stand for.
+_ESCAPES = {"n": "\n", "r": "\r", "t": "\t", '"': '"', "\\": "\\"}
+#: Deepest nesting of templates inside templates read before the file is given up.
+MAX_NESTING = 64
+MAX_DOC = 200
+
+
+class TerraformError(ValueError):
+    pass
+
+
+@dataclass
+class Tok:
+    #: "ident", "str" (a literal string: its text), "punct", "mark" (a directive's ``%{`` or end)
+    kind: str
+    value: str
+    line: int
+
+
+class _Lexer:
+    def __init__(self, src: str) -> None:
+        self.src = src
+        self.i = 0
+        self.line = 1
+        self.out: list[Tok] = []
+
+    def _advance(self, to: int) -> None:
+        self.line += self.src.count("\n", self.i, to)
+        self.i = to
+
+    def run(self) -> list[Tok]:
+        self._code(stop=None, depth=0)
+        return self.out
+
+    def _code(self, stop: str | None, depth: int) -> None:
+        """Tokens up to the ``}`` that closes an interpolation (``stop``), or the end."""
+        if depth > MAX_NESTING:
+            raise TerraformError("templates nested too deeply")
+        src, braces = self.src, 0
+        while self.i < len(src):
+            c = src[self.i]
+            if c == "\n" or c in " \t\r":
+                self._advance(self.i + 1)
+            elif c == "#" or src.startswith("//", self.i):
+                end = src.find("\n", self.i)
+                self._advance(len(src) if end < 0 else end)
+            elif src.startswith("/*", self.i):
+                end = src.find("*/", self.i + 2)
+                self._advance(len(src) if end < 0 else end + 2)
+            elif c == '"':
+                self._string(depth)
+            elif src.startswith("<<", self.i) and (m := _HEREDOC.match(src, self.i)):
+                self._heredoc(m, depth)
+            elif m := _IDENT.match(src, self.i):
+                self.out.append(Tok("ident", m.group(), self.line))
+                self._advance(m.end())
+            elif m := _OPERATOR.match(src, self.i):
+                self.out.append(Tok("punct", m.group(), self.line))
+                self._advance(m.end())
+            elif c in "{[(":
+                braces += c == "{"
+                self.out.append(Tok("punct", c, self.line))
+                self._advance(self.i + 1)
+            elif c == "}" and stop is not None and braces == 0:
+                self._advance(self.i + 1)
+                return
+            else:
+                braces -= c == "}"
+                self.out.append(Tok("punct", c, self.line))
+                self._advance(self.i + 1)
+
+    def _template(self, end: int, depth: int, quoted: bool = True) -> str:
+        """Read template text up to ``end`` (exclusive), or in a quoted string up to its closing
+        quote or the end of its line, lexing each ``${...}`` as code: the code lexer finds where
+        an interpolation ends, so its comments, strings and braces never end the template. The
+        literal text, for a block label. A backslash escapes only in a quoted string: a heredoc
+        keeps it as text."""
+        src, text = self.src, []
+        while self.i < end:
+            if quoted and src[self.i] in '"\n':
+                break
+            if src.startswith(("$${", "%%{"), self.i):
+                text.append(src[self.i + 1:self.i + 3])
+                self._advance(self.i + 3)
+            elif src.startswith(("${", "%{"), self.i):
+                directive = src[self.i] == "%"
+                if directive:
+                    self.out.append(Tok("mark", "%{", self.line))
+                # a ``~`` strip marker (``%{~ endfor }``) is part of the opener, not code
+                self._advance(self.i + 2 + src.startswith("~", self.i + 2))
+                self._code(stop="}", depth=depth + 1)
+                if directive:
+                    self.out.append(Tok("mark", "%}", self.line))
+            elif quoted and src[self.i] == "\\" and self.i + 1 < end:
+                text.append(self._escape())
+            else:
+                text.append(src[self.i])
+                self._advance(self.i + 1)
+        return "".join(text)
+
+    def _escape(self) -> str:
+        """The character a quoted string's escape at ``self.i`` stands for (``\\n``, ``\\t``,
+        ``\\u00e9``), moving past it; an unknown escape keeps the character after the backslash."""
+        src, i = self.src, self.i
+        kind = src[i + 1]
+        width = {"u": 4, "U": 8}.get(kind)
+        if width:
+            digits = src[i + 2:i + 2 + width]
+            if len(digits) == width and all(c in string.hexdigits for c in digits):
+                code = int(digits, 16)
+                if code <= sys.maxunicode and not 0xD800 <= code <= 0xDFFF:  # no lone surrogate
+                    self._advance(i + 2 + width)
+                    return chr(code)
+        self._advance(i + 2)
+        return _ESCAPES.get(kind, kind)
+
+    def _string(self, depth: int) -> None:
+        line = self.line
+        self._advance(self.i + 1)
+        text = self._template(len(self.src), depth)
+        self.out.append(Tok("str", text, line))
+        if self.i < len(self.src) and self.src[self.i] == '"':
+            self._advance(self.i + 1)
+
+    def _heredoc(self, m: re.Match[str], depth: int) -> None:
+        line = self.line
+        self._advance(m.end())
+        close = re.compile(rf"^[ \t]*{re.escape(m.group(1))}[ \t]*\r?$", re.M)
+        found = close.search(self.src, self.i)
+        end = found.start() if found else len(self.src)
+        text = self._template(end, depth, quoted=False)
+        # the literal text, for a description: ``<<-`` strips the common indentation
+        self.out.append(Tok("str", textwrap.dedent(text).strip(), line))
+        if found:
+            self._advance(found.end())
+
+
+def _punct(toks: list[Tok], i: int, value: str) -> bool:
+    """Whether ``toks[i]`` is the punctuation ``value``: never a string's text that reads the same
+    (the ``.`` that ends ``"${var.domain}."``)."""
+    return 0 <= i < len(toks) and toks[i].kind == "punct" and toks[i].value == value
+
+
+def _entry(toks: list[Tok], i: int) -> bool:
+    """Whether ``toks[i]`` separates an object entry's key from its value: ``=`` or ``:``. A
+    block body's attributes take only ``=``."""
+    return _punct(toks, i, "=") or _punct(toks, i, ":")
+
+
+def _mark(toks: list[Tok], i: int, value: str) -> bool:
+    """Whether ``toks[i]`` is where a template directive starts (``%{``) or ends (``%}``)."""
+    return 0 <= i < len(toks) and toks[i].kind == "mark" and toks[i].value == value
+
+
+def _traversal(toks: list[Tok], i: int) -> list[str]:
+    """The names of ``a.b.c`` starting at ``toks[i]``, up to an index or the end."""
+    parts = [toks[i].value]
+    j = i + 1
+    while j + 1 < len(toks) and _punct(toks, j, ".") and toks[j + 1].kind == "ident":
+        parts.append(toks[j + 1].value)
+        j += 2
+    return parts
+
+
+def _iterators(toks: list[Tok]) -> frozenset[str]:
+    """The iterator names of the file's ``dynamic`` blocks: the label (``dynamic "rule"`` gives
+    ``rule.value``), or the ``iterator = name`` that replaces it, written directly in that
+    block's body."""
+    found = set()
+    depth = 0
+    bodies: list[int] = []  # the brace depth of each open dynamic block's body
+    for i, tok in enumerate(toks):
+        if tok.kind == "punct" and tok.value == "{":
+            depth += 1
+        elif tok.kind == "punct" and tok.value == "}":
+            depth -= 1
+            while bodies and bodies[-1] > depth:
+                bodies.pop()
+        elif i + 2 < len(toks) and tok.kind == "ident":
+            if tok.value == "dynamic" and toks[i + 1].kind == "str" and _punct(toks, i + 2, "{"):
+                found.add(toks[i + 1].value)
+                bodies.append(depth + 1)
+            elif (
+                tok.value == "iterator" and bodies and bodies[-1] == depth
+                and _punct(toks, i + 1, "=") and toks[i + 2].kind == "ident"
+                and not _punct(toks, i + 3, ".")
+            ):
+                found.add(toks[i + 2].value)
+    return frozenset(found)
+
+
+def _bound(toks: list[Tok]) -> set[int]:
+    """The indexes of the tokens that name a ``for`` binding rather than the configuration:
+    ``local`` in ``[for local in var.items : local.name]`` reads the element. An expression's
+    names hold from its ``:`` to its closing bracket; a template directive's from the end of
+    ``%{ for x in xs }`` to its ``%{ endfor }``."""
+    found: set[int] = set()
+    frames: list[set[str]] = []  # the names bound inside each open bracket
+    questions: list[int] = []  # the ``?`` of each open bracket still waiting for their ``:``
+    directives: list[set[str]] = []
+    # Each ``for`` whose collection is still being read: its names, its bracket depth (None: a
+    # directive) and the directive it opens (how many were open with it). A ``for`` nested in
+    # that collection stacks above it.
+    pending: list[tuple[set[str], int | None, int]] = []
+    open_marks = 0  # directives opened and not yet ended
+    for i, tok in enumerate(toks):
+        if tok.kind == "punct" and tok.value in "{[(":
+            frames.append(set())
+            questions.append(0)
+        elif tok.kind == "punct" and tok.value in "}])":
+            if frames:
+                closed = len(frames)
+                frames.pop()
+                questions.pop()
+                pending = [p for p in pending if p[1] is None or p[1] < closed]
+        elif tok.kind == "punct" and tok.value == "?" and questions:
+            questions[-1] += 1
+        elif tok.kind == "punct" and tok.value == ":" and questions and questions[-1]:
+            questions[-1] -= 1  # the ``:`` of a conditional
+        elif tok.kind == "punct" and tok.value == ":" and pending and pending[-1][1] == len(frames):
+            if frames:
+                frames[-1] |= pending[-1][0]
+            pending.pop()
+        elif _mark(toks, i, "%{"):
+            open_marks += 1
+        elif _mark(toks, i, "%}"):
+            # only the end of the ``for`` directive's own ``%{ ... }`` starts its binding
+            if pending and pending[-1][1] is None and pending[-1][2] == open_marks:
+                directives.append(pending.pop()[0])
+            open_marks = max(open_marks - 1, 0)
+        elif tok.kind == "ident" and tok.value == "endfor" and _mark(toks, i - 1, "%{"):
+            if directives:
+                directives.pop()
+        elif tok.kind == "ident" and tok.value == "for":
+            names, j = set(), i + 1
+            while j < len(toks) and toks[j].kind == "ident" and toks[j].value != "in":
+                names.add(toks[j].value)
+                j += 1 + _punct(toks, j + 1, ",")
+            if j < len(toks) and toks[j].kind == "ident" and toks[j].value == "in" and names:
+                if _punct(toks, i - 1, "{") or _punct(toks, i - 1, "["):
+                    pending.append((names, len(frames), 0))
+                elif _mark(toks, i - 1, "%{"):
+                    pending.append((names, None, open_marks))
+        elif (
+            tok.kind == "ident" and not _punct(toks, i - 1, ".")
+            and any(tok.value in names for names in (*frames, *directives))
+        ):
+            found.add(i)
+    return found
+
+
+def _reference(parts: list[str], iterators: frozenset[str] = frozenset()) -> str | None:
+    head = parts[0]
+    if head in iterators and parts[1] in ("key", "value"):
+        return None
+    if head in ("var", "local", "module") and len(parts) >= 2:
+        return f"{head}.{parts[1]}"
+    if head == "data" and len(parts) >= 3:
+        return f"data.{parts[1]}.{parts[2]}"
+    if head not in _BUILTIN and len(parts) >= 2 and _RESOURCE_TYPE.match(head):
+        return f"{head}.{parts[1]}"
+    return None
+
+
+def read(source: str) -> dict[str, Any]:
+    toks = _Lexer(source).run()
+    iterators = _iterators(toks)
+    bound = _bound(toks)
+    defs: list[dict[str, Any]] = []
+    refs: list[dict[str, Any]] = []
+    depth, nest, scope, kind = 0, 0, "", ""  # nest: open ( and [ inside the block body
+    current: dict[str, Any] | None = None
+    #: ``source`` and ``version`` of a module or required provider, for its doc
+    settings: dict[int, dict[str, str]] = {}
+    first_ref = 0  # the first reference of the current block, renamed with a provider alias
+    required = 0  # the depth of the body of ``required_providers``, while inside it
+    wanted_provider: dict[str, Any] | None = None  # the required provider being read
+    providers = 0  # the depth of the body of a module's ``providers`` map, while inside it
+    i = 0
+    while i < len(toks):
+        tok = toks[i]
+        if tok.kind == "punct":
+            if tok.value == "{":
+                depth += 1
+            elif tok.value == "}":
+                depth = max(depth - 1, 0)
+                if depth < required:
+                    required = 0
+                if depth <= required:
+                    wanted_provider = None
+                if depth < providers:
+                    providers = 0
+                if depth == 0:
+                    scope, kind, current, nest = "", "", None, 0
+            elif tok.value in "([":
+                nest += 1
+            elif tok.value in ")]":
+                nest = max(nest - 1, 0)
+            i += 1
+            continue
+        if depth == 0 and tok.kind == "ident":
+            labels = []
+            j = i + 1
+            while j < len(toks) and toks[j].kind in ("str", "ident"):
+                labels.append(toks[j].value)
+                j += 1
+            if _punct(toks, j, "{"):
+                kind = tok.value
+                wanted = _BLOCKS.get(kind)
+                if wanted is not None and len(labels) == wanted:
+                    scope = _PREFIX[kind] + ".".join(labels)
+                    current = {"name": scope, "kind": kind, "line": tok.line, "doc": ""}
+                    defs.append(current)
+                else:
+                    scope, current = "", None
+                first_ref = len(refs)
+                depth = 1
+                i = j + 1
+                continue
+        if (
+            kind == "terraform" and depth == 1 and nest == 0 and tok.kind == "ident"
+            and tok.value == "required_providers" and _punct(toks, i + 1, "{")
+        ):
+            required = 2
+            i += 1
+            continue
+        # A required provider: ``aws = { source = "hashicorp/aws", version = "~> 5.0" }``, or
+        # the older ``aws = "~> 5.0"``.
+        if (
+            required and depth == required and nest == 0 and tok.kind == "ident"
+            and _punct(toks, i + 1, "=")
+        ):
+            wanted_provider = {
+                "name": f"provider.{tok.value}", "kind": "required_provider", "line": tok.line,
+                "doc": "",
+            }
+            defs.append(wanted_provider)
+            if i + 2 < len(toks) and toks[i + 2].kind == "str":
+                settings[id(wanted_provider)] = {"version": toks[i + 2].value}
+                i += 3
+            else:
+                i += 2
+            continue
+        if (
+            wanted_provider is not None and depth == required + 1 and nest == 0
+            and tok.kind == "ident" and tok.value in ("source", "version")
+            and _entry(toks, i + 1) and i + 2 < len(toks) and toks[i + 2].kind == "str"
+        ):
+            settings.setdefault(id(wanted_provider), {})[tok.value] = toks[i + 2].value
+            i += 3
+            continue
+        # The provider configurations of a module call: ``providers = { aws = aws.east }``.
+        if (
+            providers and depth == providers and tok.kind == "ident"
+            and _entry(toks, i - 1)
+        ):
+            parts = _traversal(toks, i)
+            refs.append({"name": "provider." + ".".join(parts[:2]), "line": tok.line,
+                         "scope": scope})
+            i += 2 * len(parts) - 1
+            continue
+        # An attribute: ``name =`` starting a line of the block body, outside brackets.
+        if (
+            tok.kind == "ident" and depth == 1 and nest == 0
+            and _punct(toks, i + 1, "=")
+            and (i == 0 or toks[i - 1].line < tok.line or _punct(toks, i - 1, "{"))
+        ):
+            if kind == "locals":
+                scope = f"local.{tok.value}"
+                defs.append({"name": scope, "kind": "local", "line": tok.line, "doc": ""})
+                i += 2
+                continue
+            if (
+                current is not None and tok.value == "description" and i + 2 < len(toks)
+                and toks[i + 2].kind == "str"
+            ):
+                current["doc"] = toks[i + 2].value[:MAX_DOC]
+            literal = toks[i + 2].value if i + 2 < len(toks) and toks[i + 2].kind == "str" else None
+            if current is not None and kind == "module" and tok.value in ("source", "version"):
+                if literal is not None:
+                    settings.setdefault(id(current), {})[tok.value] = literal
+            elif current is not None and kind == "provider" and tok.value == "alias":
+                # ``provider "aws" { alias = "east" }`` is what ``provider = aws.east`` names
+                if literal is not None and _IDENT.fullmatch(literal):
+                    scope = current["name"] = f"{current['name']}.{literal}"
+                    for ref in refs[first_ref:]:
+                        ref["scope"] = scope
+            elif kind in ("resource", "data") and tok.value == "provider" and i + 2 < len(toks):
+                if toks[i + 2].kind == "ident":
+                    parts = _traversal(toks, i + 2)
+                    refs.append({"name": "provider." + ".".join(parts[:2]), "line": tok.line,
+                                 "scope": scope})
+                    i += 2 + 2 * len(parts) - 1
+                    continue
+            elif kind == "module" and tok.value == "providers" and _punct(toks, i + 2, "{"):
+                providers = 2
+        if tok.kind == "ident" and not _punct(toks, i - 1, "."):
+            parts = _traversal(toks, i)
+            name = _reference(parts, iterators) if len(parts) > 1 and i not in bound else None
+            if name is not None:
+                refs.append({"name": name, "line": tok.line, "scope": scope})
+            i += max(1, 2 * len(parts) - 1)
+            continue
+        i += 1
+    for d in defs:
+        found = settings.get(id(d))
+        if found and not d["doc"]:
+            d["doc"] = ", ".join(
+                f"{key} {found[key]}" for key in ("source", "version") if key in found
+            )[:MAX_DOC]
+    return {"defs": defs, "refs": refs}
+
+
+class _Language:
+    interface = 1
+    suffixes = (".tf",)
+    read = staticmethod(read)
+
+
+#: The entry point codeterrain loads (``codeterrain.languages``: ``terraform``).
+language = _Language()

codeterrain_terraform-0.2.0/tests/test_terraform.py

@@ -0,0 +1,519 @@
+from __future__ import annotations
+
+import json
+
+import pytest
+from codeterrain_terraform import language, read
+
+from codeterrain import languages
+from codeterrain.cli import main
+
+MAIN = '''\
+# storage
+variable "region" {
+  description = "Where everything runs"
+  default     = "eu-central-1"
+}
+
+locals {
+  tags = { Team = "core", Region = var.region }
+  name = "logs-${var.region}"
+}
+
+resource "aws_s3_bucket" "logs" {
+  bucket = local.name
+  tags   = local.tags
+}
+
+data "aws_iam_policy_document" "read" {
+  statement {
+    resources = ["${aws_s3_bucket.logs.arn}/*"]
+  }
+}
+
+module "vpc" {
+  source = "./modules/vpc"
+  region = var.region
+}
+
+output "bucket" {
+  value = aws_s3_bucket.logs.id
+}
+'''
+
+
+def _names(facts, key):
+    return [(f["name"], f["line"]) for f in facts[key]]
+
+
+def test_definitions_are_named_the_way_terraform_refers_to_them():
+    facts = read(MAIN)
+    assert [(d["name"], d["kind"], d["line"]) for d in facts["defs"]] == [
+        ("var.region", "variable", 2),
+        ("local.tags", "local", 8),
+        ("local.name", "local", 9),
+        ("aws_s3_bucket.logs", "resource", 12),
+        ("data.aws_iam_policy_document.read", "data", 17),
+        ("module.vpc", "module", 23),
+        ("output.bucket", "output", 28),
+    ]
+    assert facts["defs"][0]["doc"] == "Where everything runs"
+
+
+@pytest.mark.parametrize("opener", ["<<-", "<<"])
+def test_a_heredoc_description_is_the_definition_doc(opener):
+    text = (
+        'variable "env" {\n'
+        f'  description = {opener}EOT\n'
+        '    The environment to deploy to.\n'
+        '    One of dev or prod.\n'
+        '  EOT\n'
+        '  default = var.fallback\n'
+        '}\n'
+    )
+    facts = read(text)
+    assert facts["defs"][0]["doc"] == "The environment to deploy to.\nOne of dev or prod."
+    assert _names(facts, "refs") == [("var.fallback", 6)]
+
+
+@pytest.mark.parametrize(("written", "doc"), [
+    (r"First line\nSecond line", "First line\nSecond line"),
+    (r"a\tb \"quoted\" back\\slash", 'a\tb "quoted" back\\slash'),
+    (r"café \U0001F600", "café \U0001F600"),
+    (r"short \u00e and \q", "short u00e and q"),
+    (r"surrogate \uD800", "surrogate uD800"),
+])
+def test_a_quoted_description_decodes_its_escapes(written, doc):
+    text = f'variable "env" {{\n  description = "{written}"\n}}\n'
+    assert read(text)["defs"][0]["doc"] == doc
+
+
+def test_references_carry_the_definition_they_sit_in():
+    facts = read(MAIN)
+    assert [(r["name"], r["line"], r["scope"]) for r in facts["refs"]] == [
+        ("var.region", 8, "local.tags"),
+        ("var.region", 9, "local.name"),
+        ("local.name", 13, "aws_s3_bucket.logs"),
+        ("local.tags", 14, "aws_s3_bucket.logs"),
+        ("aws_s3_bucket.logs", 19, "data.aws_iam_policy_document.read"),
+        ("var.region", 25, "module.vpc"),
+        ("aws_s3_bucket.logs", 29, "output.bucket"),
+    ]
+
+
+@pytest.mark.parametrize("text", [
+    'value = "var.region is not read here"\n',
+    "# value = var.region\n",
+    "// value = var.region\n",
+    "/* value =\n var.region */\n",
+    'value = "$${var.region}"\n',
+    "value = each.value\nother = count.index\nmore = self.id\nlast = path.module\n",
+])
+def test_text_comments_escapes_and_builtins_are_not_references(text):
+    assert read(f'resource "null_resource" "x" {{\n{text}}}\n')["refs"] == []
+
+
+def test_heredoc_and_nested_templates_are_read():
+    text = '''\
+resource "aws_instance" "web" {
+  user_data = <<-EOT
+    region=${var.region}
+    %{ if var.debug }debug=on%{ endif }
+  EOT
+  name = "${upper("${var.prefix}-web")}"
+  ami  = data.aws_ami.base.id
+  subnet_id = module.vpc.subnets[0]
+  depends_on = [aws_iam_role.web]
+}
+'''
+    assert _names(read(text), "refs") == [
+        ("var.region", 3), ("var.debug", 4), ("var.prefix", 6), ("data.aws_ami.base", 7),
+        ("module.vpc", 8), ("aws_iam_role.web", 9),
+    ]
+
+
+def test_a_dynamic_block_iterator_is_not_a_reference():
+    text = """resource "aws_lambda_alias" "live" {
+  dynamic "routing_config" {
+    for_each = var.weights
+    content {
+      weight = routing_config.value
+    }
+  }
+  dynamic "ingress_rule" {
+    for_each = var.rules
+    iterator = rule_item
+    content {
+      port = rule_item.value.port
+      key  = rule_item.key
+    }
+  }
+}
+"""
+    assert _names(read(text), "refs") == [("var.weights", 3), ("var.rules", 9)]
+
+
+def test_an_object_literal_inside_an_interpolation_does_not_end_the_string():
+    text = (
+        'locals { msg = "${lookup({ a = "ok" }, "a")}-suffix" }\n'
+        'output "env" { value = var.env }\n'
+    )
+    facts = read(text)
+    assert [d["name"] for d in facts["defs"]] == ["local.msg", "output.env"]
+    assert [(r["name"], r["scope"]) for r in facts["refs"]] == [("var.env", "output.env")]
+
+
+def test_an_attribute_named_iterator_outside_a_dynamic_block_hides_nothing():
+    text = '''\
+variable "value" {}
+locals {
+  iterator = var.value
+}
+output "value" {
+  value = var.value
+}
+'''
+    assert _names(read(text), "refs") == [("var.value", 3), ("var.value", 6)]
+
+
+def test_a_backslash_in_a_heredoc_does_not_escape_an_interpolation():
+    text = r'''output "env" {
+  value = <<EOT
+C:\${var.env}
+EOT
+}
+'''
+    assert _names(read(text), "refs") == [("var.env", 3)]
+
+
+def test_a_comparison_in_an_expression_is_not_a_local():
+    text = '''\
+variable "names" {}
+locals {
+  selected = [for name in var.names : name if name == "prod"]
+  other    = var.names != null ? (count >= 1) : {}
+}
+'''
+    facts = read(text)
+    assert [d["name"] for d in facts["defs"]] == ["var.names", "local.selected", "local.other"]
+    assert [(r["name"], r["scope"]) for r in facts["refs"]] == [
+        ("var.names", "local.selected"), ("var.names", "local.other"),
+    ]
+
+
+def test_a_key_inside_brackets_or_after_another_token_is_not_a_local():
+    text = '''\
+locals {
+  tags = merge(var.base, { owner = var.owner })
+  list = [{ name = var.first }]
+}
+'''
+    assert [d["name"] for d in read(text)["defs"]] == ["local.tags", "local.list"]
+
+
+@pytest.mark.parametrize("escaped", ["$${", "%%{"])
+def test_an_escaped_template_opener_does_not_hide_the_closing_quote(escaped):
+    text = f'locals {{ marker = "{escaped}" }}\noutput "env" {{ value = "prod" }}\n'
+    assert [d["name"] for d in read(text)["defs"]] == ["local.marker", "output.env"]
+
+
+def test_unicode_identifiers_keep_their_whole_names():
+    text = '''\
+variable "région" {}
+locals {
+  café = var.région
+}
+output "region" {
+  value = var.région
+}
+'''
+    facts = read(text)
+    assert [d["name"] for d in facts["defs"]] == ["var.région", "local.café", "output.region"]
+    assert _names(facts, "refs") == [("var.région", 3), ("var.région", 6)]
+
+
+def test_a_for_binding_is_not_a_reference_to_the_configuration():
+    text = '''\
+variable "items" {}
+locals {
+  name = "global"
+}
+output "names" {
+  value = [for local in var.items : local.name]
+}
+output "pairs" {
+  value = {for var, module in local.map : var.id => module.vpc}
+}
+output "after" {
+  value = [local.name, var.items]
+}
+'''
+    assert _names(read(text), "refs") == [
+        ("var.items", 6), ("local.map", 9), ("local.name", 12), ("var.items", 12),
+    ]
+
+
+@pytest.mark.parametrize("value", [
+    "[for local in [for x in var.items : x] : local.name]",
+    "[for local in (var.on ? var.items : []) : local.name]",
+    "[for local in var.on ? var.items : [] : local.name]",
+    "{for local in {for k, v in var.map : k => v} : local.name => 1}",
+])
+def test_a_for_inside_another_for_collection_keeps_the_outer_binding(value):
+    text = f'output "names" {{\n  value = {value}\n}}\n'
+    refs = [r["name"] for r in read(text)["refs"]]
+    assert "local.name" not in refs
+    assert "var.items" in refs or "var.map" in refs
+
+
+def test_a_template_for_directive_over_a_comprehension_binds_its_names():
+    text = '''\
+output "list" {
+  value = <<EOT
+%{ for local in [for x in var.items : x] }${local.name}%{ endfor }
+EOT
+}
+'''
+    assert _names(read(text), "refs") == [("var.items", 3)]
+
+
+@pytest.mark.parametrize("body", ["${local.endfor}${local.name}", "${local.for}${local.name}"])
+def test_only_a_directive_opens_or_closes_a_template_binding(body):
+    text = f'output "list" {{\n  value = "%{{ for local in var.items }}{body}%{{ endfor }}"\n}}\n'
+    assert [r["name"] for r in read(text)["refs"]] == ["var.items"]
+
+
+@pytest.mark.parametrize("loop", [
+    "%{ for local in var.items }${local.name}%{~ endfor }",
+    "%{~ for local in var.items ~}${local.name}%{~ endfor ~}",
+    "%{~for local in var.items~}${~local.name~}%{~endfor~}",
+])
+def test_strip_markers_do_not_hide_a_directive(loop):
+    text = f'output "names" {{\n  value = "{loop}${{local.name}}"\n}}\n'
+    assert [r["name"] for r in read(text)["refs"]] == ["var.items", "local.name"]
+
+
+def test_a_directive_inside_a_template_for_collection_does_not_start_its_binding():
+    # The inner `if` directive's end began the outer loop's binding early.
+    text = (
+        'output "names" {\n'
+        '  value = "%{ for local in ["%{ if var.on }${local.name}%{ endif }"] }'
+        '${local.name}%{ endfor }"\n'
+        '}\n'
+    )
+    assert [r["name"] for r in read(text)["refs"]] == ["var.on", "local.name"]
+
+
+def test_a_template_for_directive_binds_its_names_until_endfor():
+    text = '''\
+output "list" {
+  value = <<EOT
+%{ for local in var.items }${local.name}%{ endfor }
+${local.name}
+EOT
+}
+'''
+    assert _names(read(text), "refs") == [("var.items", 3), ("local.name", 4)]
+
+
+@pytest.mark.parametrize("inside", [
+    '/* quote: " */ var.env',
+    'var.env # quote: "\n',
+    'var.env // quote: "\n',
+    'lookup({ a = "}" }, "a", var.env)',
+    'join("", [<<EOT\n"\nEOT\n, var.env])',
+])
+def test_what_an_interpolation_contains_does_not_end_its_string(inside):
+    text = (
+        'variable "env" {}\n'
+        f'locals {{ msg = "${{ {inside} }}-suffix" }}\n'
+        'output "env" { value = var.env }\n'
+    )
+    facts = read(text)
+    assert [d["name"] for d in facts["defs"]] == ["var.env", "local.msg", "output.env"]
+    assert [(r["name"], r["scope"]) for r in facts["refs"]] == [
+        ("var.env", "local.msg"), ("var.env", "output.env"),
+    ]
+
+
+@pytest.mark.parametrize("value", ['"${var.domain}."', '"${var.domain}{"', '"${var.domain}="'])
+def test_string_text_that_reads_like_punctuation_is_text(value):
+    text = f'''\
+variable "domain" {{}}
+locals {{
+  fqdn  = {value}
+  other = var.domain
+}}
+'''
+    facts = read(text)
+    assert [d["name"] for d in facts["defs"]] == ["var.domain", "local.fqdn", "local.other"]
+    assert [(r["name"], r["scope"]) for r in facts["refs"]] == [
+        ("var.domain", "local.fqdn"), ("var.domain", "local.other"),
+    ]
+
+
+def test_an_attribute_after_an_index_is_not_a_new_reference():
+    text = 'output "first" {\n  value = aws_instance.web[0].private_ip\n}\n'
+    assert _names(read(text), "refs") == [("aws_instance.web", 2)]
+
+
+def test_templates_nested_too_deeply_are_refused():
+    deep = "x = " + '"${' * 100 + "1" + '}"' * 100 + "\n"
+    with pytest.raises(ValueError, match="nested too deeply"):
+        read(deep)
+
+
+PROVIDERS = '''\
+terraform {
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "~> 5.0"
+    }
+    random = "~> 3.0"
+  }
+}
+
+provider "aws" {
+  region = var.region
+}
+
+provider "aws" {
+  region = var.east
+  alias  = "east"
+}
+
+module "network" {
+  source  = "terraform-aws-modules/vpc/aws"
+  version = "5.1.0"
+  providers = {
+    aws = aws.east
+  }
+  name = var.name
+}
+
+module "iam" {
+  source = "../../modules/iam"
+}
+
+resource "aws_s3_bucket" "logs" {
+  provider = aws.east
+  version  = "not a module's"
+  bucket   = local.name
+}
+
+data "aws_ami" "base" {
+  provider = aws
+}
+'''
+
+
+def test_providers_are_definitions_and_module_calls_carry_their_source():
+    facts = read(PROVIDERS)
+    assert [(d["name"], d["kind"], d["line"], d["doc"]) for d in facts["defs"]] == [
+        ("provider.aws", "required_provider", 3, "source hashicorp/aws, version ~> 5.0"),
+        ("provider.random", "required_provider", 7, "version ~> 3.0"),
+        ("provider.aws", "provider", 11, ""),
+        ("provider.aws.east", "provider", 15, ""),
+        ("module.network", "module", 20, "source terraform-aws-modules/vpc/aws, version 5.1.0"),
+        ("module.iam", "module", 29, "source ../../modules/iam"),
+        ("aws_s3_bucket.logs", "resource", 33, ""),
+        ("data.aws_ami.base", "data", 39, ""),
+    ]
+
+
+def test_a_provider_alias_names_its_block_and_what_selects_it():
+    # An alias set after the block's first attribute still renames the references read before it.
+    refs = [(r["name"], r["line"], r["scope"]) for r in read(PROVIDERS)["refs"]]
+    assert refs == [
+        ("var.region", 12, "provider.aws"),
+        ("var.east", 16, "provider.aws.east"),
+        ("provider.aws.east", 24, "module.network"),
+        ("var.name", 26, "module.network"),
+        ("provider.aws.east", 34, "aws_s3_bucket.logs"),
+        ("local.name", 36, "aws_s3_bucket.logs"),
+        ("provider.aws", 40, "data.aws_ami.base"),
+    ]
+
+
+def test_object_entries_separated_by_a_colon_are_read():
+    facts = read(
+        'terraform {\n  required_providers {\n'
+        '    aws = { source: "hashicorp/aws", version: "5.0" }\n  }\n}\n'
+        'module "m" {\n  source = "./m"\n  providers = { aws: aws.east }\n}\n'
+    )
+    assert facts["defs"][0]["doc"] == "source hashicorp/aws, version 5.0"
+    assert [(r["name"], r["scope"]) for r in facts["refs"]] == [("provider.aws.east", "module.m")]
+
+
+def test_terrain_def_kind_filters_before_the_match_limit(tmp_path, capsys):
+    # More same-named definitions of other kinds than the match limit never hide the one asked.
+    root = tmp_path / "repo"
+    root.mkdir()
+    blocks = [f'variable "v{n}" {{}}\noutput "x{n}" {{}}\n' for n in range(120)]
+    text = "".join(f'resource "aws_s3_bucket" "logs{n}" {{}}\n' for n in range(120))
+    (root / "a.tf").write_text(
+        text.replace('"logs0"', '"logs"') + "".join(blocks), encoding="utf-8"
+    )
+    (root / "b.tf").write_text(
+        "".join(f'resource "aws_instance{n}" "logs" {{}}\n' for n in range(120)), encoding="utf-8"
+    )
+    (root / "c.tf").write_text('module "logs" {}\n', encoding="utf-8")
+    argv = ["--root", str(root), "--cache-dir", str(tmp_path / "cache")]
+    assert main(["def", "logs", "--kind", "module", "--json", *argv]) == 0
+    rows = json.loads(capsys.readouterr().out)["rows"]
+    assert [r["name"] for r in rows] == ["module.logs"]
+
+
+def test_a_module_description_is_kept_over_its_source():
+    facts = read('module "m" {\n  description = "shared"\n  source = "./m"\n}\n')
+    assert facts["defs"][0]["doc"] == "shared"
+
+
+def test_terrain_def_lists_every_definition_of_a_kind(tmp_path, capsys):
+    root = tmp_path / "repo"
+    (root / "envs" / "dev").mkdir(parents=True)
+    (root / "envs" / "dev" / "main.tf").write_text(PROVIDERS, encoding="utf-8")
+    (root / "app.py").write_text("class Thing:\n    pass\n", encoding="utf-8")
+    argv = ["--root", str(root), "--cache-dir", str(tmp_path / "cache")]
+    assert main(["def", "--kind", "module", "--json", *argv]) == 0
+    rows = json.loads(capsys.readouterr().out)["rows"]
+    assert [(r["name"], r["file"], r["doc"]) for r in rows] == [
+        ("module.network", "envs/dev/main.tf",
+         "source terraform-aws-modules/vpc/aws, version 5.1.0"),
+        ("module.iam", "envs/dev/main.tf", "source ../../modules/iam"),
+    ]
+    assert main(["def", "aws", "--kind", "provider", "--json", *argv]) == 0
+    rows = json.loads(capsys.readouterr().out)["rows"]
+    assert [(r["name"], r["line"]) for r in rows] == [("provider.aws", 11)]
+    assert main(["def", "--kind", "class", "--json", *argv]) == 0
+    assert [r["name"] for r in json.loads(capsys.readouterr().out)["rows"]] == ["app.Thing"]
+    assert main(["def", "--kind", "nope", *argv]) == 1
+    err = capsys.readouterr().err
+    assert "no definition of kind nope; kinds here: class, data, module, provider," in err
+    assert main(["def", *argv]) == 2
+    assert main(["refs", "provider.aws.east", *argv]) == 0
+    assert "2 references" in capsys.readouterr().out
+
+
+def test_the_pack_answers_def_and_refs_through_terrain(tmp_path, capsys):
+    found, problems = languages.discover()
+    assert "terraform" in [lang.name for lang in found], problems
+    root = tmp_path / "repo"
+    (root / "infra").mkdir(parents=True)
+    (root / "infra" / "main.tf").write_text(MAIN, encoding="utf-8")
+    argv = ["--root", str(root), "--cache-dir", str(tmp_path / "cache")]
+    assert main(["def", "logs", "--json", *argv]) == 0
+    rows = json.loads(capsys.readouterr().out)["rows"]
+    assert [(r["name"], r["file"], r["line"], r["language"]) for r in rows] == [
+        ("aws_s3_bucket.logs", "infra/main.tf", 12, "terraform"),
+    ]
+    assert main(["refs", "var.region", *argv]) == 0
+    out = capsys.readouterr().out
+    assert "variable var.region  infra/main.tf:2" in out
+    assert "3 references" in out
+
+
+def test_the_language_object_matches_the_interface():
+    assert language.interface == languages.INTERFACE
+    assert language.suffixes == (".tf",)