Add source linter, negative test fixtures, and fallback guidance
- scripts/lint.py: reject raw rectangles, absolute coordinates, hue-budget and callout/group/formula-order violations at the source level - tests/invalid/ + tests/lint-invalid/: negative fixtures proving the package and linter reject bad input; test.sh now runs both directions - references/fallback.md: degraded path when no LaTeX is available - tests/group-callout.tex: exercise \stgroup and \stcallout - agents/openai.yaml: agent config - Docs and .sty updated to match
This commit is contained in:
dela
Executable
+175
@@ -0,0 +1,175 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Static source checks for supertensor figures.
|
||||
|
||||
The TeX package owns geometry at render time; this linter catches source-level
|
||||
escapes that TeX cannot see: mutable ledgers, hand placement, formula order,
|
||||
raw rectangles, repeated anonymous dimensions, and per-row hue budget.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import re
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
DIM_RE = re.compile(r"\\stdim\{([^{}]+)\}\{([^{}]+)\}")
|
||||
ROLE_RE = re.compile(r"\\stsetrole\{([^{}]+)\}\{([^{}]+)\}")
|
||||
FACE_RE = re.compile(
|
||||
r"\\(stface|ststack|stindexface)(?:\[[^\]]*\])?"
|
||||
r"\{([^{}]+)\}\{([^{}]*)\}\{([^{}]+)\}\{([^{}]+)\}",
|
||||
re.DOTALL,
|
||||
)
|
||||
ROW_RE = re.compile(r"\\strow\{[^{}]+\}\{[^{}]+\}(.*?)\\strowend", re.DOTALL)
|
||||
ROW_NAME_RE = re.compile(r"\\strow\{([^{}]+)\}\{[^{}]+\}")
|
||||
ROLE_KEY_RE = re.compile(r"role\s*=\s*([A-Za-z0-9_-]+)")
|
||||
CALLOUT_RE = re.compile(r"\\stcallout\{([^{}]+)\}\{[^{}]+\}\{([^{}]+)\}")
|
||||
|
||||
|
||||
def strip_comments(source: str) -> str:
|
||||
return re.sub(r"(?<!\\)%.*$", "", source, flags=re.MULTILINE)
|
||||
|
||||
|
||||
def line_of(source: str, offset: int) -> int:
|
||||
return source.count("\n", 0, offset) + 1
|
||||
|
||||
|
||||
def directives(source: str) -> set[str]:
|
||||
found: set[str] = set()
|
||||
for match in re.finditer(r"^\s*%\s*supertensor-lint:\s*(.+)$", source, re.MULTILINE):
|
||||
found.update(item.strip() for item in match.group(1).split(","))
|
||||
return found
|
||||
|
||||
|
||||
def check_unique(
|
||||
source: str, pattern: re.Pattern[str], kind: str, errors: list[str]
|
||||
) -> dict[str, str]:
|
||||
values: dict[str, str] = {}
|
||||
for match in pattern.finditer(source):
|
||||
name, value = (part.strip() for part in match.groups())
|
||||
previous = values.get(name)
|
||||
if previous is not None and previous != value:
|
||||
errors.append(
|
||||
f"line {line_of(source, match.start())}: {kind} {name!r} changes "
|
||||
f"from {previous!r} to {value!r}"
|
||||
)
|
||||
else:
|
||||
values[name] = value
|
||||
return values
|
||||
|
||||
|
||||
def lint(path: Path) -> list[str]:
|
||||
raw = path.read_text(encoding="utf-8")
|
||||
allowed = directives(raw)
|
||||
source = strip_comments(raw)
|
||||
errors: list[str] = []
|
||||
|
||||
dimensions = check_unique(source, DIM_RE, "axis", errors)
|
||||
roles = check_unique(source, ROLE_RE, "role", errors)
|
||||
|
||||
formula_positions = [m.start() for m in re.finditer(r"\\sttopformula\b", source)]
|
||||
row_ends = [m.start() for m in re.finditer(r"\\strowend\b", source)]
|
||||
if not formula_positions and "allow-missing-formula" not in allowed:
|
||||
errors.append("missing \\sttopformula (add an explicit lint exemption for galleries/tests)")
|
||||
elif formula_positions and row_ends and formula_positions[-1] < row_ends[-1]:
|
||||
errors.append(
|
||||
f"line {line_of(source, formula_positions[-1])}: \\sttopformula must follow the last \\strowend"
|
||||
)
|
||||
|
||||
tracked = set(re.findall(r"\\sttrack\{([^{}]+)\}", source))
|
||||
raw_dimensions: dict[str, list[int]] = {}
|
||||
for match in FACE_RE.finditer(source):
|
||||
_macro, name, coordinate, rows, cols = match.groups()
|
||||
if coordinate.strip() and name not in tracked and "allow-absolute" not in allowed:
|
||||
errors.append(
|
||||
f"line {line_of(source, match.start())}: absolute object {name!r} has no \\sttrack{{{name}}}"
|
||||
)
|
||||
for value in (rows.strip(), cols.strip()):
|
||||
if value.isdigit() and value != "1":
|
||||
raw_dimensions.setdefault(value, []).append(line_of(source, match.start()))
|
||||
|
||||
if "allow-repeated-raw-dim" not in allowed:
|
||||
for value, lines in sorted(raw_dimensions.items()):
|
||||
if len(lines) > 1:
|
||||
errors.append(
|
||||
f"lines {', '.join(map(str, lines))}: raw dimension {value!r} is reused; declare a symbolic axis with \\stdim"
|
||||
)
|
||||
|
||||
if "allow-raw-tikz" not in allowed:
|
||||
for match in re.finditer(
|
||||
r"\\(?:draw|fill|path)\b[^;]*\brectangle\b", source, re.DOTALL
|
||||
):
|
||||
errors.append(
|
||||
f"line {line_of(source, match.start())}: hand-drawn rectangle bypasses \\stface"
|
||||
)
|
||||
|
||||
# \stgroup is a block. An unclosed one silently swallows the rest of the
|
||||
# band into the group's fit list, which TeX only reports as an empty row.
|
||||
opened = len(re.findall(r"\\stgroup(?![A-Za-z])", source))
|
||||
closed = len(re.findall(r"\\stgroupend(?![A-Za-z])", source))
|
||||
if opened != closed:
|
||||
errors.append(
|
||||
f"{opened} \\stgroup vs {closed} \\stgroupend: every group must be closed"
|
||||
)
|
||||
|
||||
# A callout hangs off a BAND. Anchored to a face it becomes the floating
|
||||
# commentary card between two operands that layout.md forbids, and two of
|
||||
# them on one band is a dashboard, not a figure.
|
||||
band_names = set(ROW_NAME_RE.findall(source))
|
||||
callout_anchors: dict[str, str] = {}
|
||||
for match in CALLOUT_RE.finditer(source):
|
||||
name, anchor = (part.strip() for part in match.groups())
|
||||
line = line_of(source, match.start())
|
||||
if anchor not in band_names:
|
||||
errors.append(
|
||||
f"line {line}: callout {name!r} is anchored to {anchor!r}, which is not a "
|
||||
f"\\strow band; a card hanging off a single object reads as a step"
|
||||
)
|
||||
elif anchor in callout_anchors:
|
||||
errors.append(
|
||||
f"line {line}: callout {name!r} is the second card on band {anchor!r} "
|
||||
f"(after {callout_anchors[anchor]!r}); one aside per band"
|
||||
)
|
||||
callout_anchors.setdefault(anchor, name)
|
||||
|
||||
for row_number, row in enumerate(ROW_RE.finditer(source), start=1):
|
||||
row_roles = set(ROLE_KEY_RE.findall(row.group(1)))
|
||||
colors = {roles.get(role, "<undeclared>") for role in row_roles}
|
||||
active = colors - {"stGray"}
|
||||
if len(active) > 4:
|
||||
errors.append(
|
||||
f"line {line_of(source, row.start())}: row {row_number} uses {len(active)} active hue families "
|
||||
f"({', '.join(sorted(active))}); maximum is 4 plus gray"
|
||||
)
|
||||
|
||||
# Declared dimensions are intentionally allowed to be illustrative. This
|
||||
# lookup merely keeps the declaration parse exercised and future-proof.
|
||||
del dimensions
|
||||
return errors
|
||||
|
||||
|
||||
def main() -> int:
|
||||
parser = argparse.ArgumentParser(description="lint a supertensor .tex source")
|
||||
parser.add_argument("sources", nargs="+", type=Path)
|
||||
args = parser.parse_args()
|
||||
|
||||
failed = False
|
||||
for path in args.sources:
|
||||
if not path.is_file():
|
||||
print(f"supertensor-lint: no such file: {path}", file=sys.stderr)
|
||||
failed = True
|
||||
continue
|
||||
errors = lint(path)
|
||||
if errors:
|
||||
failed = True
|
||||
print(f"!! {path}", file=sys.stderr)
|
||||
for error in errors:
|
||||
print(f" {error}", file=sys.stderr)
|
||||
else:
|
||||
print(f" lint {path}")
|
||||
return 1 if failed else 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
Reference in New Issue
Block a user