codetrail-cli 1.4.1__py3-none-any.whl

codetrail/extract/python.py

@@ -0,0 +1,221 @@
+"""The python extractor: projects, modules, packages and imports (design section 5.2).
+
+Every `pyproject.toml` marks a project root. A `.py` file belongs to the nearest root above it, and its dotted name is
+its path from that root, with a leading `src/` dropped and `__init__` naming its package. Imports are read with
+tree-sitter, which tolerates syntax errors, and resolve to the project's own modules first, then to a declared
+package by top-level name. Standard-library imports are dropped; anything else is counted as unresolved.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+import tomllib
+from collections.abc import Iterator, Mapping, Sequence
+from pathlib import PurePosixPath
+from typing import Any
+
+import tree_sitter_python
+from tree_sitter import Language, Node, Parser
+
+from codetrail.extract import FileFacts, Reference, Resolution, without_credentials
+from codetrail.facts import Entity, EntityKind, Relation, RelationKind, Source
+
+PYTHON = Language(tree_sitter_python.language())
+REQUIREMENT = re.compile(r"\s*([A-Za-z0-9][A-Za-z0-9._-]*)\s*(\[[^\]]*\])?\s*([^;]*)")
+# Import names that differ from the distribution that provides them.
+IMPORT_TO_DISTRIBUTION = {
+    "yaml": "pyyaml",
+    "jwt": "pyjwt",
+    "dotenv": "python-dotenv",
+    "PIL": "pillow",
+    "dateutil": "python-dateutil",
+    "multipart": "python-multipart",
+    "magic": "python-magic",
+    "bs4": "beautifulsoup4",
+    "sklearn": "scikit-learn",
+    "cv2": "opencv-python",
+}
+
+
+def normalise_distribution(name: str) -> str:
+    return re.sub(r"[-_.]+", "-", name).lower()
+
+
+def project_id(root: str) -> str:
+    return f"project:{root or '.'}"
+
+
+class PythonExtractor:
+    name = "python"
+    version = 1
+
+    def __init__(self) -> None:
+        self._roots: list[str] = []
+        self._parser = Parser(PYTHON)
+
+    def handles(self, path: str) -> bool:
+        return path.endswith(".py") or PurePosixPath(path).name == "pyproject.toml"
+
+    def prepare(self, paths: Sequence[str]) -> None:
+        roots = [str(PurePosixPath(path).parent) for path in paths if PurePosixPath(path).name == "pyproject.toml"]
+        # Deepest first, so a nested project wins over the one around it.
+        self._roots = sorted((("" if root == "." else root) for root in roots), key=len, reverse=True)
+
+    def extract(self, path: str, content: bytes) -> FileFacts:
+        if PurePosixPath(path).name == "pyproject.toml":
+            return self._extract_project(path, content)
+        return self._extract_module(path, content)
+
+    def _extract_project(self, path: str, content: bytes) -> FileFacts:
+        data = tomllib.loads(content.decode("utf-8"))
+        root = str(PurePosixPath(path).parent)
+        project = project_id("" if root == "." else root)
+        table = data.get("project", {})
+        attributes = {
+            key: value
+            for key, value in (("name", table.get("name")), ("requires_python", table.get("requires-python")))
+            if isinstance(value, str) and value
+        }
+        entities = [Entity(project, EntityKind.PROJECT, attributes, (Source(path),))]
+        references = []
+        groups: dict[str, list[Any]] = {"main": table.get("dependencies", [])}
+        groups.update(data.get("dependency-groups", {}))
+        for group, requirements in groups.items():
+            for requirement in requirements:
+                match = REQUIREMENT.match(requirement) if isinstance(requirement, str) else None
+                if not match:
+                    continue
+                package = f"package:pypi/{normalise_distribution(match.group(1))}"
+                entities.append(Entity(package, EntityKind.PACKAGE, {}, (Source(path),)))
+                references.append(
+                    Reference(
+                        project,
+                        RelationKind.DEPENDS_ON,
+                        package,
+                        (Source(path),),
+                        {"specifier": without_credentials(match.group(3).strip()), "group": group},
+                    )
+                )
+        return FileFacts(path, tuple(entities), tuple(references))  # fmt: skip
+
+    def _extract_module(self, path: str, content: bytes) -> FileFacts:
+        root = self._root_of(path)
+        if root is None:
+            return FileFacts(path)
+        name = self._module_name(path, root)
+        module_id = f"module:{path}"
+        module = Entity(module_id, EntityKind.MODULE, {"name": name, "project": project_id(root)}, (Source(path),))
+        package = name.split(".") if path.endswith("__init__.py") else name.split(".")[:-1]
+        references = [Reference(project_id(root), RelationKind.CONTAINS, module_id, (Source(path),))]
+        for target, names, line in self._imports(content, package):
+            references.append(
+                Reference(module_id, RelationKind.IMPORTS, target, (Source(path, line, line),), {"names": names})
+            )
+        return FileFacts(path, (module,), tuple(references))
+
+    def _root_of(self, path: str) -> str | None:
+        for root in self._roots:
+            if not root or path.startswith(root + "/"):
+                return root
+        return None
+
+    @staticmethod
+    def _module_name(path: str, root: str) -> str:
+        relative = PurePosixPath(path[len(root) + 1 :] if root else path)
+        parts = list(relative.with_suffix("").parts)
+        if parts and parts[0] == "src":
+            parts = parts[1:]
+        if parts and parts[-1] == "__init__":
+            parts = parts[:-1]
+        return ".".join(parts)
+
+    def _imports(self, content: bytes, package: list[str]) -> Iterator[tuple[str, list[str], int]]:
+        """(module, imported names, line) for every import statement, relative ones made absolute."""
+        for node in _walk(self._parser.parse(content).root_node):
+            line = node.start_point[0] + 1
+            if node.type == "import_statement":
+                for child in node.children_by_field_name("name"):
+                    yield _dotted(child), [], line
+            elif node.type == "import_from_statement":
+                module_node = node.child_by_field_name("module_name")
+                if module_node is None:
+                    continue
+                names = [_dotted(child) for child in node.children_by_field_name("name")]
+                if module_node.type == "relative_import":
+                    level = sum(
+                        len(child.text or b"") for child in module_node.children if child.type == "import_prefix"
+                    )
+                    rest = [child for child in module_node.children if child.type == "dotted_name"]
+                    base = package[: len(package) - (level - 1)] if level - 1 <= len(package) else []
+                    target = ".".join([*base, *([_dotted(rest[0])] if rest else [])])
+                else:
+                    target = _dotted(module_node)
+                if target:
+                    yield target, names, line
+
+    def resolve(self, files: Sequence[FileFacts], known: Mapping[str, Entity]) -> Resolution:
+        modules: dict[str, dict[str, str]] = {}  # project -> dotted name -> module id
+        for entity in known.values():
+            if entity.kind is EntityKind.MODULE:
+                modules.setdefault(str(entity.attributes["project"]), {})[str(entity.attributes["name"])] = entity.id
+        relations: list[Relation] = []
+        unresolved = 0
+        for file in files:
+            for reference in file.references:
+                if reference.kind is not RelationKind.IMPORTS:
+                    relations.append(Relation(reference.source_id, reference.kind, reference.target,
+                                              reference.attributes, reference.sources))  # fmt: skip
+                    continue
+                source = known.get(reference.source_id)
+                project = str(source.attributes["project"]) if source else ""
+                names = list(reference.attributes.get("names", []))
+                targets: list[str] | None = _local_targets(reference.target, names, modules.get(project, {}))
+                if not targets:
+                    targets = _package_target(reference.target, known)
+                if targets is None:
+                    unresolved += 1
+                    continue
+                relations.extend(
+                    Relation(reference.source_id, RelationKind.IMPORTS, target, {}, reference.sources)
+                    for target in targets
+                    if target != reference.source_id
+                )
+        return Resolution(relations, unresolved)
+
+
+def _local_targets(target: str, names: list[str], modules: Mapping[str, str]) -> list[str]:
+    """The project's modules an import reaches: submodules named in a from-import, else the longest module prefix."""
+    found = [modules[f"{target}.{name}"] for name in names if f"{target}.{name}" in modules]
+    if found and len(found) == len(names):
+        return found
+    parts = target.split(".")
+    for end in range(len(parts), 0, -1):
+        candidate = ".".join(parts[:end])
+        if candidate in modules:
+            return [*found, modules[candidate]]
+    return found
+
+
+def _package_target(target: str, known: Mapping[str, Entity]) -> list[str] | None:
+    """A declared package for a third-party import, [] for the standard library, None when unknown."""
+    top = target.split(".")[0]
+    if top in sys.stdlib_module_names or top == "__future__":
+        return []
+    package = f"package:pypi/{normalise_distribution(IMPORT_TO_DISTRIBUTION.get(top, top))}"
+    return [package] if package in known else None
+
+
+def _dotted(node: Node) -> str:
+    if node.type == "aliased_import":
+        name = node.child_by_field_name("name")
+        node = name if name is not None else node
+    return (node.text or b"").decode("utf-8", "replace")
+
+
+def _walk(node: Node) -> Iterator[Node]:
+    stack = [node]
+    while stack:
+        current = stack.pop()
+        yield current
+        stack.extend(reversed(current.children))

codetrail/extract/swift.py

@@ -0,0 +1,204 @@
+"""The swift extractor: Swift packages, their targets, dependencies, and the imports of each target (design 5.2).
+
+`Package.swift` is read for the package's name, its targets (with their source folder and dependencies) and the
+packages it fetches by URL (without any credentials in it). The manifest is untrusted, so reading it stays linear:
+brackets are paired in one pass, a target call inside another is skipped, and every pattern's tail is bounded.
+
+Each `.swift` file belongs to the target whose folder holds it; its `import` lines, read with tree-sitter, become
+edges from that target to another target or to an external package's product. Apple's frameworks (Foundation,
+SwiftUI...) resolve to nothing and are counted once each.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterator, Mapping, Sequence
+from functools import cache
+from pathlib import PurePosixPath
+
+import tree_sitter_swift
+from tree_sitter import Language, Parser
+
+from codetrail.extract import FileFacts, Reference, Resolution, without_credentials
+from codetrail.facts import Entity, EntityKind, Relation, RelationKind, Source
+
+SWIFT = Language(tree_sitter_swift.language())
+TARGET_CALL = re.compile(r"\.(target|testTarget|executableTarget)\s*\(")
+NAME = re.compile(r'\bname\s*:\s*"([^"]+)"')
+PATH = re.compile(r'\bpath\s*:\s*"([^"]+)"')
+PRODUCT = re.compile(r'\.product\s*\(\s*name\s*:\s*"([^"]+)"\s*,\s*package\s*:\s*"([^"]+)"[^)]{0,2000}\)')
+NAMED_TARGET = re.compile(r'\.(?:target|byName)\s*\(\s*name\s*:\s*"([^"]+)"[^)]{0,2000}\)')
+QUOTED = re.compile(r'"([^"]+)"')
+REMOTE_PACKAGE = re.compile(r'\.package\s*\(\s*url\s*:\s*"([^"]+)"([^)]{0,2000})\)')
+VERSION = re.compile(r'"([0-9][^"]*)"')
+IMPORT_KINDS = {"typealias", "struct", "class", "enum", "protocol", "let", "var", "func"}
+
+
+def package_id(name: str) -> str:
+    return f"package:swift/{name.removesuffix('.git').lower()}"
+
+
+def _balanced(text: str, start: int, opening: str, closing: str) -> str | None:
+    """The text between the bracket at `start` and its match, or None when it never closes."""
+    depth = 0
+    for index in range(start, len(text)):
+        if text[index] == opening:
+            depth += 1
+        elif text[index] == closing:
+            depth -= 1
+            if depth == 0:
+                return text[start + 1 : index]
+    return None
+
+
+def _closing_brackets(text: str) -> dict[int, int]:
+    """Each "(" position paired with its ")", found in one pass; a bracket that never closes has no entry."""
+    pairs, open_at = {}, []
+    for index, character in enumerate(text):
+        if character == "(":
+            open_at.append(index)
+        elif character == ")" and open_at:
+            pairs[open_at.pop()] = index
+    return pairs
+
+
+def _calls(text: str) -> Iterator[tuple[str, str]]:
+    """Each target call and its arguments; one inside another call's arguments is skipped, so no text is read twice."""
+    closing = _closing_brackets(text)
+    read_to = -1
+    for match in TARGET_CALL.finditer(text):
+        start = match.end() - 1
+        if start > read_to and start in closing:
+            read_to = closing[start]
+            yield match.group(1), text[start + 1 : read_to]
+
+
+class SwiftExtractor:
+    name = "swift"
+    version = 1
+
+    def __init__(self) -> None:
+        self._parser = Parser(SWIFT)
+
+    def handles(self, path: str) -> bool:
+        return path.endswith(".swift")
+
+    def prepare(self, paths: Sequence[str]) -> None:
+        return None
+
+    def extract(self, path: str, content: bytes) -> FileFacts:
+        if PurePosixPath(path).name == "Package.swift":
+            return self._manifest(path, content.decode("utf-8", "replace"))
+        imports = []
+        for node in self._parser.parse(content).root_node.children:
+            if node.type == "import_declaration":
+                words = [word for word in (node.text or b"").decode().split() if not word.startswith("@")]
+                words = [word for word in words[1:] if word not in IMPORT_KINDS]  # drop "import" and a kind
+                if words:
+                    line = node.start_point[0] + 1
+                    imports.append(Reference(f"file:{path}", RelationKind.IMPORTS, words[0].split(".")[0],
+                                             (Source(path, line, line),)))  # fmt: skip
+        return FileFacts(path, (), tuple(imports))
+
+    def _manifest(self, path: str, text: str) -> FileFacts:
+        folder = str(PurePosixPath(path).parent)
+        project = f"project:{folder}"
+        package_call = text.find("Package(")
+        named = NAME.search(text, package_call if package_call != -1 else 0)
+        package_name = named.group(1) if named else PurePosixPath(folder).name
+        source = (Source(path),)
+        entities = [Entity(project, EntityKind.PROJECT, {"name": package_name, "language": "swift"}, source)]
+        references: list[Reference] = []
+        for url, rest in REMOTE_PACKAGE.findall(text):
+            url = without_credentials(url)
+            external = package_id(url.rstrip("/").rsplit("/", 1)[-1])
+            entities.append(Entity(external, EntityKind.PACKAGE, {"url": url}, source))
+            version = VERSION.search(rest)
+            references.append(Reference(project, RelationKind.DEPENDS_ON, external, source,
+                                        {"version": version.group(1) if version else ""}))  # fmt: skip
+        for kind, body in _calls(text):
+            name = NAME.search(body)
+            if name is None:
+                continue
+            target_name = name.group(1)
+            explicit = PATH.search(body)
+            default = ("Tests" if kind == "testTarget" else "Sources") + f"/{target_name}"
+            target_path = f"{folder}/{explicit.group(1) if explicit else default}".removeprefix("./")
+            target = f"swift_target:{folder}/{target_name}"
+            entities.append(Entity(target, EntityKind.SWIFT_TARGET,
+                                   {"name": target_name, "kind": "test" if kind == "testTarget" else "target",
+                                    "package": package_name, "path": target_path}, source))  # fmt: skip
+            references.append(Reference(project, RelationKind.CONTAINS, target, source))
+            start = body.find("dependencies:")
+            bracket = body.find("[", start) if start != -1 else -1
+            dependencies = _balanced(body, bracket, "[", "]") if bracket != -1 else None
+            if dependencies is None:
+                continue
+            for product, package in PRODUCT.findall(dependencies):
+                references.append(Reference(target, RelationKind.DEPENDS_ON, package_id(package), source,
+                                            {"product": product}))  # fmt: skip
+            remaining = PRODUCT.sub("", dependencies)
+            names = NAMED_TARGET.findall(remaining) + QUOTED.findall(NAMED_TARGET.sub("", remaining))
+            for dependency in names:
+                references.append(Reference(target, RelationKind.DEPENDS_ON, f"target-name:{dependency}", source))
+        return FileFacts(path, tuple(entities), tuple(references))
+
+    def resolve(self, files: Sequence[FileFacts], known: Mapping[str, Entity]) -> Resolution:
+        targets = [entity for entity in known.values() if entity.kind is EntityKind.SWIFT_TARGET]
+        products = {
+            str(reference.attributes["product"]): reference.target
+            for file in files
+            for reference in file.references
+            if "product" in reference.attributes
+        }
+
+        # Indexed once, so each name is a lookup rather than a scan of every target; the first target wins.
+        first_named: dict[str, str] = {}
+        first_named_in_folder: dict[tuple[str, str], str] = {}
+        for swift_target in targets:
+            target_name = swift_target.attributes.get("name")
+            if not isinstance(target_name, str):
+                continue
+            first_named.setdefault(target_name, swift_target.id)
+            first_named_in_folder.setdefault((swift_target.id.rsplit("/", 1)[0], target_name), swift_target.id)
+
+        def by_name(name: str, near: str) -> str | None:
+            """The target with that name, preferring one beside `near`."""
+            return first_named_in_folder.get((near.rsplit("/", 1)[0], name)) or first_named.get(name)
+
+        # Each target's folder; when two targets share one, the last wins.
+        folders = {str(target.attributes.get("path", "")): target.id for target in targets}
+
+        @cache  # once per file: a deep path's walk would otherwise be repeated for each of its imports
+        def owner(path: str) -> str | None:
+            """The target whose folder holds the file; the deepest one when folders nest."""
+            end = path.rfind("/")
+            while end != -1:  # each folder above the file, deepest first
+                if path[:end] in folders:
+                    return folders[path[:end]]
+                end = path.rfind("/", 0, end)
+            return None
+
+        relations: dict[tuple[str, str, str], Relation] = {}
+        unresolved_names: set[str] = set()
+        for file in files:
+            for reference in file.references:
+                source_id = reference.source_id
+                if source_id.startswith("file:"):
+                    holder = owner(source_id.removeprefix("file:"))
+                    if holder is None:
+                        continue
+                    source_id = holder
+                if source_id not in known:  # e.g. a target dropped for its overlong id: no relation can start there
+                    continue
+                target = reference.target
+                if target.startswith("target-name:") or reference.kind is RelationKind.IMPORTS:
+                    name = target.removeprefix("target-name:")
+                    target = by_name(name, source_id) or products.get(name) or ""
+                    if not target:
+                        unresolved_names.add(name)
+                        continue
+                if target in known and target != source_id:
+                    relation = Relation(source_id, reference.kind, target, reference.attributes, reference.sources)
+                    relations.setdefault(relation.key, relation)
+        return Resolution(list(relations.values()), len(unresolved_names))

codetrail/extract/terraform.py

@@ -0,0 +1,166 @@
+"""The terraform extractor: modules, resources, module calls and references (design section 5.2).
+
+Every folder holding `.tf` files is a Terraform module. `resource` blocks are resources the module contains; a
+reference such as `google_storage_bucket.audio.name` inside a resource is an edge to that resource in the same module;
+a `module` block whose `source` is a relative path is an edge to the module folder it names, when that folder is in
+the repository. Registry and remote sources are counted as unresolved, never fetched.
+"""
+
+from __future__ import annotations
+
+import posixpath
+import re
+from collections.abc import Mapping, Sequence
+from pathlib import PurePosixPath
+
+import tree_sitter_hcl
+from tree_sitter import Language, Node, Parser
+
+from codetrail.extract import FileFacts, Reference, Resolution
+from codetrail.facts import Entity, EntityKind, Relation, RelationKind, Source
+
+HCL = Language(tree_sitter_hcl.language())
+REFERENCE = re.compile(r"\b([a-z][a-z0-9]*_[a-z0-9_]+)\.([A-Za-z_][A-Za-z0-9_-]*)\b")
+
+
+def module_id(folder: str) -> str:
+    return f"terraform_module:{folder}"
+
+
+PATH_NAMES = {b"source_dir", b"source", b"context", b"dockerfile", b"path", b"working_dir"}
+PATH_SEGMENT = re.compile(r"[A-Za-z0-9._-]+")
+
+
+class TerraformExtractor:
+    name = "terraform"
+    version = 2  # resources record their `paths`
+
+    def __init__(self, max_paths: int = 20) -> None:
+        self._parser = Parser(HCL)
+        self._max_paths = max_paths
+
+    def handles(self, path: str) -> bool:
+        return path.endswith(".tf")
+
+    def prepare(self, paths: Sequence[str]) -> None:
+        return None
+
+    def extract(self, path: str, content: bytes) -> FileFacts:
+        folder = str(PurePosixPath(path).parent)
+        module = module_id(folder)
+        entities = [Entity(module, EntityKind.TERRAFORM_MODULE, {"name": PurePosixPath(folder).name or folder})]
+        references: list[Reference] = []
+        root = self._parser.parse(content).root_node
+        body = next((child for child in root.children if child.type == "body"), None)
+        for block in body.children if body is not None else []:
+            if block.type != "block":
+                continue
+            kind, labels = _block_head(block)
+            line = block.start_point[0] + 1
+            source = (Source(path, line, block.end_point[0] + 1),)
+            if kind == "resource" and len(labels) == 2:
+                resource = f"resource:{folder}/{labels[0]}.{labels[1]}"
+                attributes: dict[str, object] = {"type": labels[0], "name": labels[1], "module": folder}
+                found = _paths(folder, block, self._max_paths)
+                if found:
+                    attributes["paths"] = found
+                entities.append(Entity(resource, EntityKind.RESOURCE, attributes, source))
+                references.append(Reference(module, RelationKind.CONTAINS, resource, source))
+                text = (block.text or b"").decode("utf-8", "replace")
+                for match in sorted(set(REFERENCE.findall(text))):
+                    if match != (labels[0], labels[1]):
+                        target = f"resource:{folder}/{match[0]}.{match[1]}"
+                        references.append(Reference(resource, RelationKind.REFERENCES, target, source))
+            elif kind == "module" and labels:
+                called = _module_source(block)
+                if called is not None and called.startswith("."):
+                    target_folder = posixpath.normpath(posixpath.join(folder, called))
+                    references.append(Reference(module, RelationKind.REFERENCES, module_id(target_folder), source,
+                                                {"call": labels[0]}))  # fmt: skip
+                else:
+                    references.append(Reference(module, RelationKind.REFERENCES, "", source, {"call": labels[0]}))
+        return FileFacts(path, tuple(entities), tuple(references))
+
+    def resolve(self, files: Sequence[FileFacts], known: Mapping[str, Entity]) -> Resolution:
+        relations: list[Relation] = []
+        unresolved = 0
+        for file in files:
+            for reference in file.references:
+                if reference.target in known:
+                    relations.append(Relation(reference.source_id, reference.kind, reference.target,
+                                              reference.attributes, reference.sources))  # fmt: skip
+                elif reference.kind is RelationKind.REFERENCES and reference.source_id.startswith("terraform_module:"):
+                    unresolved += 1  # a registry, remote or missing module
+                # a resource name that matches no resource (a data source, a provider attribute) is not a reference
+        return Resolution(relations, unresolved)
+
+
+def _paths(folder: str, block: Node, limit: int) -> list[str]:
+    """Plain-string path attributes of the block (nested blocks too), resolved lexically against the module's folder.
+
+    Only an attribute whose value is one plain string counts: no interpolation, heredoc or comment, every part a plain
+    path segment (so nothing credential-shaped), and nothing absolute or climbing above the repository.
+    """
+    found: set[str] = set()
+    stack = [block]
+    while stack:
+        node = stack.pop()
+        for child in node.children:
+            if child.type in ("body", "block"):
+                stack.append(child)
+            elif child.type == "attribute":
+                name = next((part for part in child.children if part.type == "identifier"), None)
+                value = _plain_string(child) if name is not None and name.text in PATH_NAMES else None
+                if value is None or value.startswith("/"):
+                    continue
+                parts = [part for part in value.split("/") if part not in ("", ".")]
+                if not parts or any(part != ".." and not PATH_SEGMENT.fullmatch(part) for part in parts):
+                    continue
+                joined = posixpath.normpath(posixpath.join(folder, value))
+                if joined != ".." and not joined.startswith("../"):
+                    found.add("" if joined == "." else joined)
+    return sorted(found)[:limit]
+
+
+def _plain_string(attribute: Node) -> str | None:
+    """The attribute's value when it is exactly one quoted string with no interpolation."""
+    expression = next((part for part in attribute.children if part.type == "expression"), None)
+    literal = expression.children[0] if expression is not None and expression.child_count == 1 else None
+    string = (
+        literal.children[0]
+        if literal is not None and literal.type == "literal_value" and literal.child_count == 1
+        else None
+    )
+    if string is None or string.type != "string_lit":
+        return None
+    texts = [part for part in string.children if part.type == "template_literal"]
+    others = [part for part in string.children if part.type not in ("template_literal", "quoted_template_start",
+                                                                  "quoted_template_end")]  # fmt: skip
+    return (texts[0].text or b"").decode("utf-8", "replace") if len(texts) == 1 and not others else None
+
+
+def _block_head(block: Node) -> tuple[str, list[str]]:
+    kind = ""
+    labels = []
+    for child in block.children:
+        if child.type == "identifier" and not kind:
+            kind = (child.text or b"").decode()
+        elif child.type == "string_lit":
+            labels.append(
+                "".join((part.text or b"").decode() for part in child.children if part.type == "template_literal")
+            )
+        elif child.type == "block_start":
+            break
+    return kind, labels
+
+
+def _module_source(block: Node) -> str | None:
+    body = next((child for child in block.children if child.type == "body"), None)
+    for attribute in body.children if body is not None else []:
+        if attribute.type != "attribute":
+            continue
+        name = next((child for child in attribute.children if child.type == "identifier"), None)
+        if name is not None and name.text == b"source":
+            literal = re.search(rb'"([^"]*)"', attribute.text or b"")
+            return literal.group(1).decode() if literal else None
+    return None