isar-tools 0.1.0__py3-none-any.whl

isar_tools/__init__.py

@@ -0,0 +1 @@
+"""Source tooling for Isabelle/Isar projects."""

isar_tools/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from isar_tools.cli import main
+
+sys.exit(main())

isar_tools/checks/cli.py

@@ -0,0 +1,156 @@
+"""``isar check``: project and source hygiene."""
+
+import argparse
+import sys
+from collections import Counter
+from pathlib import Path
+
+from isar_tools.checks.docs import check_docs
+from isar_tools.checks.findings import CODES, DEFAULT_GROUPS, GROUPS, Finding
+from isar_tools.checks.locales import check_locales
+from isar_tools.checks.project import check_project
+from isar_tools.checks.theory import check_proofs, check_symbols, check_syntax
+from isar_tools.project.workspace import add_include_option, load
+from isar_tools.render import RENDERERS, Column, Table, display_path
+from isar_tools.style import Style, add_color_option
+
+FORMATS = ("text", "json", "csv")
+
+
+def register(sub: "argparse._SubParsersAction[argparse.ArgumentParser]") -> None:  # pyright: ignore[reportPrivateUsage]
+    codes = "\n".join(f"  {code:22} {group:8} {desc}" for code, (group, desc) in CODES.items())
+    check = sub.add_parser(
+        "check",
+        help="Check project and source hygiene",
+        description="Check project and source hygiene. Groups: "
+        f"{', '.join(GROUPS)}; default: {', '.join(DEFAULT_GROUPS)}.",
+        epilog=f"codes:\n{codes}",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    check.add_argument(
+        "paths", nargs="*", type=Path, default=[Path()], help="project directories or .thy files"
+    )
+    check.add_argument(
+        "--group",
+        dest="groups",
+        action="append",
+        choices=GROUPS,
+        help="run this group of checks (repeatable; default: all but symbols, docs, and locales)",
+    )
+    check.add_argument(
+        "--ignore",
+        action="append",
+        default=[],
+        choices=sorted(CODES),
+        metavar="CODE",
+        help="do not report this code (repeatable)",
+    )
+    check.add_argument(
+        "--include-comments", action="store_true", help="symbols: also check (* *) comments"
+    )
+    check.add_argument(
+        "--allow",
+        action="append",
+        default=[],
+        metavar="NAME",
+        help="locales: do not report this identifier (repeatable)",
+    )
+    check.add_argument("--format", choices=FORMATS, default="text")
+    add_color_option(check)
+    add_include_option(check)
+    check.set_defaults(func=run)
+
+
+def normalize_argv(argv: list[str]) -> list[str]:
+    """``check GROUP ...`` means ``check --group GROUP ...``."""
+    args = list(argv)
+    if len(args) > 1 and args[0] == "check" and args[1] in GROUPS:
+        args[1:2] = ["--group", args[1]]
+    return args
+
+
+def collect_findings(args: argparse.Namespace) -> list[Finding]:
+    groups: set[str] = set(args.groups or DEFAULT_GROUPS)
+    workspace = load(args.paths, args.include)
+    findings: list[Finding] = []
+    if "project" in groups:
+        for project in workspace.projects:
+            findings += check_project(project)
+    if groups & {"proofs", "syntax", "symbols", "docs"}:
+        for source in workspace.sources:
+            theory = source.parse()
+            if "proofs" in groups:
+                findings += check_proofs(source.path, theory)
+            if "syntax" in groups:
+                findings += check_syntax(source.path, theory)
+            if "symbols" in groups:
+                findings += check_symbols(
+                    source.path, theory, include_comments=args.include_comments
+                )
+            if "docs" in groups:
+                findings += check_docs(source.path, theory)
+    if "locales" in groups:
+        findings += check_locales(workspace.sources, allow=args.allow)
+    ignored = set(args.ignore)
+    return sorted({f for f in findings if f.code not in ignored})
+
+
+def findings_table(findings: list[Finding]) -> Table:
+    return Table(
+        "findings",
+        "Findings",
+        [
+            Column("path", "path"),
+            Column("line", "line", True),
+            Column("column", "column", True),
+            Column("code", "code"),
+            Column("message", "message"),
+        ],
+        [
+            {
+                "path": display_path(f.path),
+                "line": f.line,
+                "column": f.column,
+                "code": f.code,
+                "message": f.message,
+            }
+            for f in findings
+        ],
+    )
+
+
+# Colour of a finding's code, by group.
+_GROUP_COLORS = {
+    "project": "magenta",
+    "proofs": "yellow",
+    "syntax": "red",
+    "symbols": "cyan",
+    "docs": "green",
+    "locales": "blue",
+}
+
+
+def summary(findings: list[Finding]) -> str:
+    """``2 findings: 1 missing-theory, 1 unfinished-proof``, most frequent first."""
+    if not findings:
+        return "no findings"
+    counts = Counter(f.code for f in findings)
+    parts = ", ".join(
+        f"{n} {code}" for code, n in sorted(counts.items(), key=lambda c: (-c[1], c[0]))
+    )
+    noun = "finding" if len(findings) == 1 else "findings"
+    return f"{len(findings)} {noun}: {parts}"
+
+
+def run(args: argparse.Namespace) -> int:
+    findings = collect_findings(args)
+    if args.format == "text":
+        style = Style.for_stream(args.color, sys.stdout)
+        for f in findings:
+            where = style(display_path(f.path), "bold") + style(f":{f.line}:{f.column}:", "dim")
+            code = style(f.code, _GROUP_COLORS[CODES[f.code][0]], "bold")
+            print(f"{where} {code}: {f.message}")
+        print(summary(findings), file=sys.stderr)
+    else:
+        RENDERERS[args.format]([findings_table(findings)], sys.stdout)
+    return 1 if findings else 0

isar_tools/checks/docs.py

@@ -0,0 +1,114 @@
+"""Documentation coverage: the opt-in ``docs`` group.
+
+A style policy, ported from Voblint's ``extract_definitions.py --lint``:
+theories, headings, and locales and classes carry prose, routine
+declarations need not. All rules are stated over the command sequence of
+:class:`~isar_tools.source.theory.Theory`:
+
+- A *text block* is a ``text`` (or ``txt``) command, with any argument form
+  and document tag. ``text_raw`` is raw LaTeX, not prose, and does not count.
+  Neither do ``(* *)`` comments, which are not part of the document, nor
+  formal comments ``\\<comment> \\<open>...\\<close>``, which annotate one
+  term or proof step and belong to the command they occur in.
+- ``undocumented-theory``: no text block before the first command that is
+  none of: the ``theory`` header, a document command (heading, text,
+  ``text_raw``), or a preamble command that only opens a context or adjusts
+  syntax and name visibility (``context``, ``unbundle``, ``declare``,
+  ``hide_const``, ``notation``, ...; see ``_PREAMBLE``). Text before the
+  header counts.
+- ``undocumented-heading``: a heading (``chapter`` ... ``subparagraph``)
+  whose next command is not a text block and whose previous command is not a
+  text block either. For a heading right before the ``theory`` header, the
+  next command is the first one after the header.
+- ``undocumented-locale`` / ``undocumented-class``: a ``locale`` or ``class``
+  declaration whose previous command is not a text block.
+
+"Next" and "previous" mean adjacent in the command sequence: blank lines and
+comments in between do not matter, any other command does.
+"""
+
+from itertools import dropwhile
+from pathlib import Path
+
+from isar_tools.checks.findings import Finding
+from isar_tools.source.keywords import DOCUMENT, CommandKind
+from isar_tools.source.theory import Command, Theory, significant, unquote
+
+# Commands that may precede a theory's opening text: they open a context or
+# adjust syntax and name visibility, but declare nothing.
+_PREAMBLE = frozenset(
+    {
+        "context",
+        "unbundle",
+        "declare",
+        "hide_class",
+        "hide_type",
+        "hide_const",
+        "hide_fact",
+        "notation",
+        "no_notation",
+        "type_notation",
+        "no_type_notation",
+        "no_syntax",
+        "no_translations",
+    }
+)
+_SKIPPED = DOCUMENT | {CommandKind.THY_BEGIN}
+# Declarations that must be preceded by a text block, with their finding code.
+_DECLARATIONS = {"locale": "undocumented-locale", "class": "undocumented-class"}
+
+
+def _is_text(command: Command | None) -> bool:
+    return command is not None and command.kind is CommandKind.DOCUMENT_BODY
+
+
+def _argument(theory: Theory, command: Command) -> str:
+    """The first argument of ``command``, after modifiers (``private``) and
+    document tags, on one line."""
+    tokens = significant(command.tokens(theory.tokens))
+    args = list(dropwhile(lambda t: t.text != command.name, tokens))[1:]
+    while len(args) > 1 and args[0].text == "%":
+        args = args[2:]
+    return " ".join(unquote(args[0]).split()) if args else ""
+
+
+def check_docs(path: Path, theory: Theory) -> list[Finding]:
+    commands = theory.commands
+    findings: list[Finding] = []
+
+    def report(command: Command, code: str, message: str) -> None:
+        findings.append(Finding.at(path, theory.lines, theory.start(command), code, message))
+
+    header = next((c for c in commands if c.kind is CommandKind.THY_BEGIN), None)
+    if header is not None:
+        opening = (
+            c for c in commands if _is_text(c) or not (c.kind in _SKIPPED or c.name in _PREAMBLE)
+        )
+        first = next(opening, None)
+        if not _is_text(first):
+            report(
+                header,
+                "undocumented-theory",
+                "theory has no text block before its first declaration",
+            )
+    for i, command in enumerate(commands):
+        previous = commands[i - 1] if i > 0 else None
+        if command.kind is CommandKind.DOCUMENT_HEADING:
+            j = i + 1
+            if j < len(commands) and commands[j].kind is CommandKind.THY_BEGIN:
+                j += 1
+            following = commands[j] if j < len(commands) else None
+            if not _is_text(following) and not _is_text(previous):
+                title = _argument(theory, command)
+                report(
+                    command,
+                    "undocumented-heading",
+                    f"{command.name} {title!r} has no text block next to it",
+                )
+        elif command.name in _DECLARATIONS and not _is_text(previous):
+            report(
+                command,
+                _DECLARATIONS[command.name],
+                f"{command.name} {_argument(theory, command)} is not preceded by a text block",
+            )
+    return findings

isar_tools/checks/findings.py

@@ -0,0 +1,55 @@
+"""Findings of ``isar check`` and the registry of their codes."""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from isar_tools.source.lexer import LineIndex
+
+
+@dataclass(frozen=True, order=True)
+class Finding:
+    path: Path
+    line: int  # 1-based
+    column: int  # 1-based
+    code: str
+    message: str
+
+    @classmethod
+    def at(cls, path: Path, lines: LineIndex, offset: int, code: str, message: str) -> "Finding":
+        return cls(path, lines.line(offset), lines.column(offset), code, message)
+
+
+# code -> (group, description). Codes are stable identifiers for --ignore and
+# machine-readable output.
+CODES: dict[str, tuple[str, str]] = {
+    "root-syntax": ("project", "a ROOT file does not parse"),
+    "duplicate-session": ("project", "two sessions have the same name"),
+    "missing-theory": ("project", "a theories entry names no existing theory"),
+    "missing-directory": ("project", "a session or directories entry names no directory"),
+    "missing-document-file": ("project", "a document_files entry names no file"),
+    "duplicate-theory-name": (
+        "project",
+        "two theory files with the same name on one session's search path",
+    ),
+    "unreached-theory": (
+        "project",
+        "a theory file on a session's search path that no session builds",
+    ),
+    "unfinished-proof": ("proofs", "sorry or \\<proof> leaves a goal unproved"),
+    "oops": ("proofs", "oops abandons a goal"),
+    "unclosed-proof": ("proofs", "a proof does not end before the next theory command"),
+    "lexical-error": ("syntax", "an unterminated comment, string, cartouche, or verbatim"),
+    "document-argument": ("syntax", "a document command without exactly one text argument"),
+    "non-ascii": ("symbols", "a non-ASCII character outside (* *) comments"),
+    "undocumented-theory": ("docs", "no text block before a theory's first declaration"),
+    "undocumented-heading": ("docs", "a heading with no text block right after or before it"),
+    "undocumented-locale": ("docs", "a locale with no text block right before it"),
+    "undocumented-class": ("docs", "a type class with no text block right before it"),
+    "locale-free-variable": (
+        "locales",
+        "a locale or context header term names something defined nowhere (heuristic)",
+    ),
+}
+
+GROUPS = ("project", "proofs", "syntax", "symbols", "docs", "locales")
+DEFAULT_GROUPS = ("project", "proofs", "syntax")