feat: improve scripts and write tests

This commit is contained in:
alexm committed 2026-10-11 07:22:13 -04:00
1 parent bc3091647e
commit cf4bd07a8e
32 files changed
+3817 -723

No files matched your search

+258
View File
@@ -0,0 +1,258 @@
"""
Small, dependency-free helpers for finding hosts inside a ``flake.nix``.
This is deliberately *not* a Nix parser. It is a lexical scanner that is
just smart enough to answer "where are the real braces?" by ignoring
everything that is not code:
* ``# line comments`` and ``/* block comments */``
* ``"double quoted strings"`` (with ``\\`` escapes)
* ``''indented strings''`` (with ``'''``, ``''$`` and ``''\\`` escapes)
* the *text* of strings, while still treating code inside ``${ ... }``
interpolations as code
The central trick is :func:`mask_non_code`, which returns a string of the
same length as the input in which all non-code characters are replaced by
spaces. Regexes and brace counting can then run on the masked text without
being fooled by a ``{`` in a comment, and every offset is valid in the
original text too.
Limitations (all reported as errors rather than silently mishandled):
* only bare-identifier attribute names are recognized (``willow = ...``,
not ``"willow" = ...``)
* only entries of the form ``<name> = <...>nixosSystem { ... };`` are
recognized as hosts
"""
from __future__ import annotations
import re
from dataclasses import dataclass
class FlakeError(Exception):
"""flake.nix is not shaped the way these tools expect."""
# Nix keywords that can never be used as a bare attribute name.
NIX_KEYWORDS = frozenset(
{"if", "then", "else", "assert", "with", "let", "in", "rec", "inherit", "or"}
)
# Nix identifier: [a-zA-Z_][a-zA-Z0-9_'-]*
_IDENT = r"[A-Za-z_][A-Za-z0-9_'-]*"
# `<name> = [<path>.]nixosSystem {`, at the start of a line or directly after
# a `{` or `;` (so one-line attrsets work too).
_HOST_RE = re.compile(
rf"(?:^|(?<=[{{;]))([ \t]*)({_IDENT})[ \t]*=\s*(?:[A-Za-z_][\w'-]*\.)*nixosSystem\s*\{{",
re.MULTILINE,
)
_NIXOS_CONFIGS_RE = re.compile(r"(?<![\w'-])nixosConfigurations\s*=\s*\{")
def line_indent(src: str, pos: int) -> str:
"""Leading whitespace of the line containing offset ``pos``."""
line_start = src.rfind("\n", 0, pos) + 1
m = re.compile(r"[ \t]*").match(src, line_start)
return m.group(0) if m else ""
def mask_non_code(src: str) -> str:
"""Return ``src`` with comments and string contents blanked out.
Newlines are preserved so line structure (and ``^`` anchors) still work.
The returned string always has ``len(result) == len(src)``.
"""
out = list(src)
n = len(src)
def blank(a: int, b: int) -> None:
for k in range(a, min(b, n)):
if out[k] != "\n":
out[k] = " "
# While inside a ``${ ... }`` interpolation we remember which kind of
# string we came from and the brace depth of the enclosing code.
interp: list[tuple[str, int]] = []
state = "code" # code | dq | ind
depth = 0
i = 0
while i < n:
c = src[i]
if state == "code":
if c == "#":
j = src.find("\n", i)
j = n if j == -1 else j
blank(i, j)
i = j
elif c == "/" and src.startswith("/*", i):
j = src.find("*/", i + 2)
j = n if j == -1 else j + 2
blank(i, j)
i = j
elif c == '"':
state = "dq"
i += 1
elif c == "'" and src.startswith("''", i):
state = "ind"
i += 2
elif c == "{":
depth += 1
i += 1
elif c == "}":
if depth == 0 and interp:
# This brace closes a ${ ... } interpolation.
blank(i, i + 1)
state, depth = interp.pop()
else:
depth -= 1
i += 1
else:
i += 1
elif state == "dq":
if c == "\\":
blank(i, i + 2)
i += 2
elif c == '"':
state = "code"
i += 1
elif c == "$" and src.startswith("${", i):
blank(i, i + 2)
interp.append(("dq", depth))
state, depth = "code", 0
i += 2
else:
blank(i, i + 1)
i += 1
else: # state == "ind"
if src.startswith("'''", i) or src.startswith("''$", i):
blank(i, i + 3)
i += 3
elif src.startswith("''\\", i):
blank(i, i + 4)
i += 4
elif src.startswith("''", i):
state = "code"
i += 2
elif c == "$" and src.startswith("${", i):
blank(i, i + 2)
interp.append(("ind", depth))
state, depth = "code", 0
i += 2
else:
blank(i, i + 1)
i += 1
return "".join(out)
def find_matching_brace(masked: str, open_pos: int) -> int | None:
"""Index of the ``}`` matching the ``{`` at ``open_pos``, or ``None``."""
if open_pos >= len(masked) or masked[open_pos] != "{":
raise ValueError(f"no '{{' at offset {open_pos}")
depth = 0
for i in range(open_pos, len(masked)):
c = masked[i]
if c == "{":
depth += 1
elif c == "}":
depth -= 1
if depth == 0:
return i
return None
def braces_balanced(src: str) -> bool:
"""True if every code-level ``{`` has a matching ``}``."""
depth = 0
for c in mask_non_code(src):
if c == "{":
depth += 1
elif c == "}":
depth -= 1
if depth < 0:
return False
return depth == 0
@dataclass(frozen=True)
class HostEntry:
"""One ``<name> = ...nixosSystem { ... };`` binding."""
name: str
indent: str # leading whitespace of the line the entry starts on
start: int # offset where the entry begins (leading indent included)
end: int # offset just past the terminating ``;``
@dataclass(frozen=True)
class ConfigBlock:
"""Location of the ``nixosConfigurations = { ... }`` attrset."""
open_pos: int # offset of ``{``
close_pos: int # offset of matching ``}``
def locate_configurations(src: str, masked: str | None = None) -> ConfigBlock:
"""Find the ``nixosConfigurations`` attrset or raise :class:`FlakeError`."""
masked = mask_non_code(src) if masked is None else masked
m = _NIXOS_CONFIGS_RE.search(masked)
if not m:
raise FlakeError(
"could not find a literal `nixosConfigurations = { ... }` attrset "
"(is it generated by a function such as mapAttrs?)"
)
open_pos = m.end() - 1
close_pos = find_matching_brace(masked, open_pos)
if close_pos is None:
raise FlakeError("unbalanced braces: nixosConfigurations is never closed")
return ConfigBlock(open_pos, close_pos)
def find_hosts(src: str) -> list[HostEntry]:
"""Top-level host entries of ``nixosConfigurations``, in file order.
Entries nested deeper than the attrset itself (e.g. inside a ``let``)
are ignored.
"""
masked = mask_non_code(src)
block = locate_configurations(src, masked)
hosts: list[HostEntry] = []
pos = block.open_pos + 1
depth = 0 # brace depth relative to the nixosConfigurations body
for m in _HOST_RE.finditer(masked, block.open_pos + 1, block.close_pos):
if m.start() < pos:
continue # nested inside a host entry we already consumed
# Advance the running depth up to the start of this match.
for c in masked[pos : m.start()]:
if c == "{":
depth += 1
elif c == "}":
depth -= 1
pos = m.start()
if depth != 0:
continue
open_brace = m.end() - 1
close_brace = find_matching_brace(masked, open_brace)
if close_brace is None:
raise FlakeError(f"unbalanced braces in host entry `{m.group(2)}`")
semi = re.compile(r"\s*;").match(masked, close_brace + 1)
if semi is None:
raise FlakeError(
f"host entry `{m.group(2)}` is not terminated by `;` after its closing brace"
)
hosts.append(HostEntry(m.group(2), line_indent(src, m.start()), m.start(), semi.end()))
# Skip over the entry body so we don't double count nested braces.
pos = semi.end()
# `pos` jumped past the body, whose braces are balanced, so depth is unchanged.
return hosts