opencrbasic 1.0.0__py3-none-any.whl

opencrbasic/catalog.py

@@ -0,0 +1,173 @@
+"""Instruction catalog: the names a CRBasic program can use, per logger profile.
+
+Built only from `profiles.get(name)` (`instructions`, `functions`, `symbols`, the tables extracted
+from each logger's compiler by `tools/extract_tables.py`). There is no second instruction list.
+`docs/lsp-api.md` ("Instruction catalog") describes the kinds, the overlaps and the keyword rule.
+"""
+
+import functools
+from collections.abc import Iterator
+from dataclasses import dataclass
+
+from . import profiles
+
+KINDS = ("instruction", "function", "symbol", "keyword")
+
+# Words that structure a program or a declaration. Each is also a row of the instruction table of
+# the profiles that have it (the parser dispatches on it in `Parser._parse_statement`, or reads it
+# as an ordinary instruction row such as `NextScan`, `EndTable`). A profile gets the entry only
+# when its own instruction table has the word, with the table's spelling.
+TABLE_KEYWORDS = (
+    "If",
+    "ElseIf",
+    "Else",
+    "EndIf",
+    "Select",
+    "Case",
+    "EndSelect",
+    "For",
+    "Next",
+    "Do",
+    "Loop",
+    "While",
+    "WEnd",
+    "Exit",
+    "ExitFor",
+    "ExitDo",
+    "ExitSub",
+    "ExitFunction",
+    "ExitScan",
+    "ContinueScan",
+    "Return",
+    "Sub",
+    "EndSub",
+    "Function",
+    "EndFunction",
+    "Call",
+    "End",
+    "Const",
+    "Public",
+    "Dim",
+    "Alias",
+    "Units",
+    "Include",
+    "IncludeSection",
+    "BeginProg",
+    "EndProg",
+    "Scan",
+    "SubScan",
+    "NextScan",
+    "NextSubScan",
+    "DataTable",
+    "EndTable",
+    "ConstTable",
+    "EndConstTable",
+)
+
+# Language words the instruction table lacks. Each is matched by name in the parser
+# (`parser.py`): `Then` (`_parse_if`, `_parse_elseif`), `Step` (`_parse_for`), `As` (declarations,
+# `_parse_subdef`, `_parse_param`), `Optional` (`_parse_param`). They are the same on every profile.
+EXTRA_KEYWORDS = ("Then", "Step", "As", "Optional")
+
+
+@dataclass(frozen=True)
+class CatalogEntry:
+    name: str  # the profile's spelling
+    kind: str  # one of KINDS
+    profile: str  # profile name ("cr6", ...)
+    source: str  # "instructions.json" | "functions.json" | "symbols.json" |
+    # "keyword:table" | "keyword:parser"
+    params: tuple[int, ...] = ()  # instruction: type codes (docs/type-codes.md)
+    value: int | None = None  # symbol: the integer value
+    code: int | None = None  # function: table `code`
+    func_kind: int | None = None  # function: table `kind`
+    argspec: int | None = None  # function: table `argspec`
+    nargs: int | None = None  # function: present only for some rows
+    argtypes: tuple[int, ...] | None = None
+
+
+def _build(name: str) -> tuple[CatalogEntry, ...]:
+    prof = profiles.get(name)
+    out: list[CatalogEntry] = []
+    for row in prof.instructions.values():
+        out.append(
+            CatalogEntry(
+                row["name"], "instruction", prof.name, "instructions.json", params=tuple(row.get("params", ()))
+            )
+        )
+    for row in prof.functions.values():
+        argtypes = row.get("argtypes")
+        out.append(
+            CatalogEntry(
+                row["name"],
+                "function",
+                prof.name,
+                "functions.json",
+                code=row.get("code"),
+                func_kind=row.get("kind"),
+                argspec=row.get("argspec"),
+                nargs=row.get("nargs"),
+                argtypes=None if argtypes is None else tuple(argtypes),
+            )
+        )
+    for row in prof.symbols.values():
+        out.append(CatalogEntry(row["name"], "symbol", prof.name, "symbols.json", value=row.get("value")))
+    for word in TABLE_KEYWORDS:
+        row = prof.instructions.get(word.upper())
+        if row is not None:
+            out.append(CatalogEntry(row["name"], "keyword", prof.name, "keyword:table"))
+    for word in EXTRA_KEYWORDS:
+        out.append(CatalogEntry(word, "keyword", prof.name, "keyword:parser"))
+    return tuple(out)
+
+
+class InstructionCatalog:
+    """Every name of one profile, by kind. Lookup is case-insensitive and keeps the profile's
+    spelling. A name may exist under several kinds (`If` is an instruction row, a symbol and a
+    keyword); `get` returns one entry by the priority instruction, function, symbol, keyword and
+    `entries` returns all of them."""
+
+    def __init__(self, profile: str):
+        self.profile = profiles.get(profile).name
+        self._entries = _build(self.profile)
+        self._by_name: dict[str, list[CatalogEntry]] = {}
+        for entry in self._entries:
+            self._by_name.setdefault(entry.name.upper(), []).append(entry)
+
+    @classmethod
+    def for_profile(cls, name: str) -> InstructionCatalog:
+        """The cached catalog of a profile name (`ValueError` for an unknown one)."""
+        return _cached(profiles.get(name).name)
+
+    def entries(self, name: str) -> tuple[CatalogEntry, ...]:
+        return tuple(self._by_name.get(name.upper(), ()))
+
+    def get(self, name: str, kind: str | None = None) -> CatalogEntry | None:
+        found = self._by_name.get(name.upper(), ())
+        if kind is not None:
+            return next((e for e in found if e.kind == kind), None)
+        for k in KINDS:
+            for e in found:
+                if e.kind == k:
+                    return e
+        return None
+
+    def names(self, kind: str | None = None) -> tuple[str, ...]:
+        """Profile spellings of one kind (all kinds when None), sorted case-insensitively and
+        without repeats."""
+        seen = {e.name for e in self._entries if kind is None or e.kind == kind}
+        return tuple(sorted(seen, key=lambda n: (n.upper(), n)))
+
+    def __iter__(self) -> Iterator[CatalogEntry]:
+        return iter(self._entries)
+
+    def __len__(self) -> int:
+        return len(self._entries)
+
+    def __contains__(self, name: object) -> bool:
+        return isinstance(name, str) and name.upper() in self._by_name
+
+
+@functools.cache
+def _cached(name: str) -> InstructionCatalog:
+    return InstructionCatalog(name)

opencrbasic/checkconfig.py

@@ -0,0 +1,144 @@
+"""`opencrbasic.toml`: check severities and scoped suppressions (`PLAN.md` "Configuration",
+`docs/checker.md` "Check configuration and report file"). Configuration never touches the reference
+channel: every problem is a `ConfigError` that the caller reports on stderr."""
+
+import fnmatch
+import os
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from . import profiles
+
+FILE_NAME = "opencrbasic.toml"
+SEVERITIES = ("error", "warning", "info", "off")
+
+
+class ConfigError(Exception):
+    pass
+
+
+@dataclass
+class Suppression:
+    code: str
+    file: str  # glob, relative to the configuration file, case-insensitive
+    line: int | None
+    reason: str
+
+
+@dataclass
+class Config:
+    path: Path | None = None  # None: no file, built-in defaults
+    checks: dict[str, str] = field(default_factory=dict)
+    profile: dict[str, dict[str, str]] = field(default_factory=dict)
+    entry: dict[str, dict[str, str]] = field(default_factory=dict)  # key: normalized relative path
+    suppress: list[Suppression] = field(default_factory=list)
+
+    @property
+    def root(self) -> Path | None:
+        return self.path.parent if self.path else None
+
+
+def norm(path: str) -> str:
+    return Path(os.path.normpath(path)).as_posix().lower()
+
+
+def find(entry: Path) -> Path | None:
+    """The workspace root: the nearest ancestor directory of the entry file holding the file."""
+    for directory in entry.resolve().parents:
+        if (directory / FILE_NAME).is_file():
+            return directory / FILE_NAME
+    return None
+
+
+def _severities(table: object, codes, where: str) -> dict[str, str]:
+    if not isinstance(table, dict):
+        raise ConfigError(f"{where} must be a table")
+    out = {}
+    for code, value in table.items():
+        if code not in codes:
+            raise ConfigError(f"{where}: unknown check code {code}")
+        if value not in SEVERITIES:
+            raise ConfigError(f"{where}: unknown severity {value!r} for {code}; choose from {', '.join(SEVERITIES)}")
+        out[code] = value
+    return out
+
+
+def parse_overrides(items: list[str], codes) -> dict[str, str]:
+    """`CODE=severity` strings (`--check`, an LSP setting) as a severity map."""
+    out = {}
+    for item in items:
+        code, sep, value = item.partition("=")
+        if not sep:
+            raise ConfigError(f"--check {item}: expected CODE=SEVERITY")
+        out.update(_severities({code: value}, codes, f"--check {item}"))
+    return out
+
+
+def load(path: Path, codes) -> Config:
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as e:
+        raise ConfigError(f"{path}: cannot read: {e}") from None
+    return loads(text, path, codes)
+
+
+def loads(text: str, path: Path, codes) -> Config:
+    """`load` of a file's text already read (the language server reads it through its sources)."""
+    try:
+        data = tomllib.loads(text)
+    except tomllib.TOMLDecodeError as e:
+        raise ConfigError(f"{path}: {e}") from None
+    name = str(path)
+    if unknown := set(data) - {"checks", "profile", "entry", "suppress"}:
+        raise ConfigError(f"{name}: unknown key {sorted(unknown)[0]}")
+    cfg = Config(path=path.resolve())
+    cfg.checks = _severities(data.get("checks", {}), codes, f"{name} [checks]")
+    for logger, table in _tables(data, "profile", name).items():
+        if logger not in profiles.PROFILES:
+            raise ConfigError(f"{name} [profile.{logger}]: unknown logger profile")
+        cfg.profile[logger] = _severities(table.get("checks", {}), codes, f"{name} [profile.{logger}.checks]")
+    for entry, table in _tables(data, "entry", name).items():
+        cfg.entry[norm(entry)] = _severities(table.get("checks", {}), codes, f'{name} [entry."{entry}".checks]')
+    suppress = data.get("suppress", [])
+    if not isinstance(suppress, list):
+        raise ConfigError(f"{name}: suppress must be an array of tables ([[suppress]])")
+    for i, s in enumerate(suppress, 1):
+        where = f"{name} [[suppress]] #{i}"
+        if not isinstance(s, dict) or set(s) - {"code", "file", "line", "reason"}:
+            raise ConfigError(f"{where}: keys are code, file, line, reason")
+        if not isinstance(s.get("code"), str) or s["code"] not in codes:
+            raise ConfigError(f"{where}: unknown check code {s.get('code')}")
+        if not isinstance(s.get("file"), str) or not s["file"]:
+            raise ConfigError(f"{where}: file (a glob) is required")
+        if not isinstance(s.get("reason"), str) or not s["reason"].strip():
+            raise ConfigError(f"{where}: reason is required")
+        line = s.get("line")
+        if line is not None and (not isinstance(line, int) or isinstance(line, bool) or line < 1):
+            raise ConfigError(f"{where}: line must be a positive integer")
+        cfg.suppress.append(Suppression(s["code"], s["file"].lower(), line, s["reason"]))
+    return cfg
+
+
+def _tables(data: dict, key: str, name: str) -> dict[str, dict]:
+    tables = data.get(key, {})
+    if not isinstance(tables, dict) or not all(isinstance(t, dict) for t in tables.values()):
+        raise ConfigError(f"{name}: {key} must hold tables ([{key}.<name>.checks])")
+    return tables
+
+
+def severity(
+    cfg: Config, code: str, default: str, logger: str, entry: str, cli: dict[str, str], lsp: dict[str, str]
+) -> str:
+    """Highest layer that names `code`: CLI, LSP, entry, profile, `[checks]`, built-in default."""
+    for layer in (cli, lsp, cfg.entry.get(entry, {}), cfg.profile.get(logger, {}), cfg.checks):
+        if code in layer:
+            return layer[code]
+    return default
+
+
+def suppression(cfg: Config, code: str, file: str, line: int) -> Suppression | None:
+    return next(
+        (s for s in cfg.suppress if s.code == code and fnmatch.fnmatchcase(file, s.file) and s.line in (None, line)),
+        None,
+    )