opencrbasic 1.0.0__py3-none-any.whl

opencrbasic/profiles.py

@@ -0,0 +1,266 @@
+"""Logger profiles: the per-model data and conventions the compiler is parameterised by.
+
+Each profile names the directory of tables extracted from that model's compiler
+(`tools/extract_tables.py`) and the few output conventions that differ between models.
+"""
+
+import json
+from dataclasses import dataclass
+from functools import cached_property
+from pathlib import Path
+
+DATA = Path(__file__).resolve().parent / "data"
+
+
+class DottedName(str):
+    """An undeclared name used as `Name.member` in an expression (CR300/CR350 read it as a table)."""
+
+
+class DottedAwareMessage(str):
+    """`{name} is not defined.`, except that a `DottedName` is `Could not find DataTable <name>.`
+    (oracle, CR300/CR350, 2026-10-11, `docs/checker.md` "Undeclared dotted names")."""
+
+    def format(self, *args, **kw):
+        name = kw.get("name")
+        if isinstance(name, DottedName):
+            return f"Could not find DataTable {name}."
+        return str.format(self, *args, **kw)
+
+
+@dataclass(frozen=True)
+class Profile:
+    name: str  # "cr6", "cr1000x", ...
+    display: str  # logger name as the exe prints it
+    version: str  # OS version string of the reference compiler
+    date: str  # build date string of the reference compiler
+    data_dir: Path
+    reports_mode: bool  # True: "Compiled in <X>Mode."; False: "Compiled OK."
+    exe_name: str  # reference compiler file name in compiler/
+    # An unresolved predefined-symbol name at a checked expression position (`checker/expressions.py`):
+    # CR6/CR1000X word it "Invalid symbol in expression: {name}."; CR300/CR350 use "{name} is not
+    # defined." for the same case (oracle evidence: `docs/loggers.md`). `{name}` = the identifier
+    # as written in source (not case-normalised).
+    unresolved_symbol_message: str = "Invalid symbol in expression: {name}."
+    # `checker/__init__.py`'s call to `warnings.check_early` (reachability/fnotch/background-
+    # calibration): CR6/CR1000X run it unconditionally, oracle-confirmed genuinely ungated even
+    # when a later, unrelated tier-B error exists in the same file (`docs/instructions.md` "Two
+    # ungated call sites"; the `caf5c15cd16b.CR6` fuzz reproducer explicitly shows a tier-B
+    # placement/fallback error *and* a reachability warning together on CR6). CR300/CR350 do
+    # **not** share this: an undefined-symbol-class error anywhere in the file (tier A's
+    # `check_consts`, or tier B's `expressions.check`) suppresses every `check_early` warning in
+    # the *whole* file, including ones on lines textually before the error and on statements that
+    # are themselves otherwise clean (oracle, this round, `docs/loggers.md`: `PanelTemp(PTemp,
+    # 15000)` on its own line 4 loses its own fnotch warning merely because a *different*,
+    # unrelated `TCDiff` two lines later references an undefined name; reachability shows the same
+    # suppression). A same-file error that is *not* itself an undefined-symbol-class finding (e.g.
+    # `FileManage`'s own drive-string validation, not implemented by this project but visible in
+    # the corpus's own oracle transcripts) does **not** suppress it (`tablefile_1.CR6` keeps its
+    # own fnotch warning alongside an unrelated `Invalid drive` error) -- consistent with gating
+    # `check_early` on CR300/CR350 behind the *same* "tier A and tier B both clean" condition tier
+    # C already uses, rather than a blanket "any error anywhere" rule.
+    early_warnings_gated: bool = False
+    # CR300/CR350 only (`checker/structure.py`'s `_check_call_pass2`, `docs/loggers.md`): a bare
+    # call whose head name resolves to nothing (not a declared `Sub`, built-in function, or
+    # recognised instruction -- most often an instruction name this logger's own smaller table
+    # lacks entirely, e.g. `DisplayMenu`/`CardOut`/`ACPower`) gets its own `{name} is not
+    # defined.` line immediately before the existing generic `Invalid, or out of place
+    # expression: %s.` fallback line, and this shape's before-`BeginProg` placement follow-up
+    # (`Expr illegally occurs before BeginProg.`) and pass-2 stop do **not** fire (oracle-
+    # confirmed, `docs/loggers.md`) -- unlike CR6/CR1000X, which show only the fallback line and
+    # do apply the placement follow-up/stop there (unchanged). The *other* two branches of the
+    # same check (a bare call resolving to a declared `Sub` or a built-in function) are
+    # unaffected either way -- oracle-confirmed identical on all four loggers, `docs/loggers.md`.
+    undefined_call_message: bool = False
+    # CR300/CR350: the generic `Invalid, or out of place expression: %s.` echo keeps the raw line's
+    # terminator, so the closing `.` is printed on the next line (oracle: 144 help examples,
+    # e.g. acpower_1.CR6 on cr300comp.exe; `checker/structure.py` `_out_of_place`).
+    fallback_echo_newline: bool = False
+    # CR6/CR1000X: a statement whose first token is a known name is syntax-checked in pass 1, so an
+    # unclosed `(` there is a pass-1 `No Matching, or out of place ) in expression: %s.`
+    # (`checker/structure.py`, `docs/checker.md` "Pass-1 fallback: statements that start with a
+    # known word"). CR300/CR350 report that message on every such line regardless (not modelled).
+    known_first_word_pass1: bool = True
+    # CR300/CR350 print an included file's name with its drive (`<CPU:Lib.crb>`, `<cpu:Lib.crb>`
+    # when none was written); CR6/CR1000X without it (`diagnostics.Diagnostic.cr6comp`).
+    include_drive_prefix: bool = False
+    # CR6/CR1000X: a missing main-file `Include` warning is printed before every other message of
+    # the file, whatever line the other message is on (`compiler.CompileResult.result_lines`,
+    # `docs/checker.md` "Missing include warnings come first"). CR300/CR350 print it in line order.
+    include_warning_first: bool = False
+    # CR300/CR350 report pass-2 findings (undefined names, the generic fallback) even after a
+    # pass-1 error (oracle: `Dim Z banana` then `X = Q` prints both); CR6/CR1000X do not.
+    single_pass: bool = False
+    # Identifier exceptions to the predefined-CONST namespace rule, observed in
+    # docs/checker.md#predefined-constant-name-collisions. STRING and FP2 stay reserved.
+    declarable_predefined_names: frozenset[str] = frozenset()
+
+    def _load(self, name: str) -> list[dict]:
+        return json.loads((self.data_dir / f"{name}.json").read_text())
+
+    @cached_property
+    def instructions(self) -> dict[str, dict]:
+        """Upper-case name -> record (with `id` = table index + 1)."""
+        rows = self._load("instructions")
+        return {r["name"].upper(): {**r, "id": r["index"] + 1} for r in rows}
+
+    @cached_property
+    def functions(self) -> dict[str, dict]:
+        return {r["name"].upper(): r for r in self._load("functions")}
+
+    @cached_property
+    def symbols(self) -> dict[str, dict]:
+        return {r["name"].upper(): r for r in self._load("symbols")}
+
+    @cached_property
+    def status_members(self) -> frozenset[str]:
+        """Upper-case `Status.<name>` read names (`data/**/status_members.json`); empty: unchecked."""
+        path = self.data_dir / "status_members.json"
+        return frozenset(json.loads(path.read_text())["names"]) if path.exists() else frozenset()
+
+    @cached_property
+    def mode_rules(self) -> dict:
+        """Sequential/PipelineMode trigger lists (`mode.py`, `docs/modes.md`)."""
+        return json.loads((self.data_dir / "mode.json").read_text())
+
+    @cached_property
+    def pipeline_tasks(self) -> dict:
+        """PipeLine Mode placement rules (`structure.pipeline_task_errors`) with only fixture-backed
+        instructions.
+
+        CR6/CR1000X have separate observed subsets and same-line ordering exceptions; CR300/CR350
+        have no file and therefore no placement rule.
+        """
+        path = self.data_dir / "pipeline_tasks.json"
+        return json.loads(path.read_text()) if path.is_file() else {"tasks": {}}
+
+    @cached_property
+    def terminals(self) -> dict:
+        """Channel-argument (`U1..U12`-style) range checks (`checker/terminals.py`)."""
+        path = self.data_dir / "terminals.json"
+        return json.loads(path.read_text()) if path.is_file() else {"channels": {}, "instructions": {}}
+
+    @cached_property
+    def fnotch(self) -> dict:
+        """`fN1`/fnotch argument check, `docs/instructions.md`: CR300/CR350 a fixed value set
+        (warning, `checker/warnings.py`), CR6/CR1000X a minimum frequency (error, `min_hz`,
+        `checker/instr_measure.py`)."""
+        path = self.data_dir / "fnotch.json"
+        return json.loads(path.read_text()) if path.is_file() else {}
+
+    @cached_property
+    def measure(self) -> dict:
+        """Value-set/value-range checks for `Range` codes, `SW12`, `Delay`, `CS616`,
+        `TimerInput` and `ExciteV`/`ExciteI` (`checker/instr_measure.py`, `docs/instructions.md`).
+        Absent (`{}`) means none of these are oracle-confirmed for this logger yet."""
+        path = self.data_dir / "measure.json"
+        return json.loads(path.read_text()) if path.is_file() else {}
+
+    @cached_property
+    def settings_fields(self) -> dict:
+        """`SetSetting`/`SetStatus` field-name lists and spelling rules (`checker/instr_rules.py`'s
+        `check_settings_fields`, `docs/instructions.md` "SetSetting and SetStatus field names")."""
+        return json.loads((self.data_dir / "settings_fields.json").read_text())
+
+    @cached_property
+    def before_beginprog(self) -> frozenset[str]:
+        """Instructions rejected with `%s illegally occurs before BeginProg.` when they are the
+        first executable statement before `BeginProg` (`checker/structure.py`, `docs/checker.md`
+        "Instructions before BeginProg"). Only oracle-probed keywords are listed."""
+        path = self.data_dir / "before_beginprog.json"
+        return frozenset(json.loads(path.read_text())["instructions"]) if path.is_file() else frozenset()
+
+    @cached_property
+    def background_calibration(self) -> dict:
+        """`Scan` interval threshold, in whole milliseconds, below which the "background
+        calibration will be disabled" warning fires (CR6/CR1000X only, `checker/warnings.py`,
+        `docs/instructions.md`). Absent (`{}`) for CR300/CR350, which were oracle-probed down to a
+        100us scan interval with no such warning (`docs/instructions.md`)."""
+        path = self.data_dir / "background_calibration.json"
+        return json.loads(path.read_text()) if path.is_file() else {}
+
+
+_DECLARABLE_NUMERIC_TYPES = frozenset(
+    {
+        "FLOAT",
+        "LONG",
+        "BOOLEAN",
+        "IEEE8",
+        "IEEE4",
+        "BOOL8",
+        "UINT1",
+        "UINT2",
+        "UINT4",
+        "DOUBLE",
+    }
+)
+
+PROFILES = {
+    "cr6": Profile(
+        "cr6",
+        "CR6",
+        "CR6.14.2.0",
+        "03/04/2025",
+        DATA,
+        True,
+        "CR6Comp.exe",
+        include_warning_first=True,
+        declarable_predefined_names=_DECLARABLE_NUMERIC_TYPES,
+    ),
+    "cr1000x": Profile(
+        "cr1000x",
+        "CR1000X",
+        "CR1000X.8.2.0",
+        "03/04/2025",
+        DATA / "cr1000x",
+        True,
+        "cr1000xcomp.exe",
+        include_warning_first=True,
+        declarable_predefined_names=_DECLARABLE_NUMERIC_TYPES,
+    ),
+    "cr300": Profile(
+        "cr300",
+        "CR300",
+        "CR300.Std.11.02",
+        "02/04/2025",
+        DATA / "cr300",
+        False,
+        "cr300comp.exe",
+        unresolved_symbol_message=DottedAwareMessage("{name} is not defined."),
+        early_warnings_gated=True,
+        undefined_call_message=True,
+        fallback_echo_newline=True,
+        known_first_word_pass1=False,
+        include_drive_prefix=True,
+        single_pass=True,
+    ),
+    "cr350": Profile(
+        "cr350",
+        "CR350",
+        "CR350.Std.1.07",
+        "02/04/2025",
+        DATA / "cr350",
+        False,
+        "cr350comp.exe",
+        unresolved_symbol_message=DottedAwareMessage("{name} is not defined."),
+        early_warnings_gated=True,
+        undefined_call_message=True,
+        fallback_echo_newline=True,
+        known_first_word_pass1=False,
+        include_drive_prefix=True,
+        single_pass=True,
+    ),
+}
+
+EXTENSIONS = {".cr6": "cr6", ".cr1x": "cr1000x", ".cr300": "cr300", ".cr350": "cr350"}
+
+
+def get(name: str) -> Profile:
+    try:
+        return PROFILES[name.lower()]
+    except KeyError:
+        raise ValueError(f"unknown logger {name!r}; choose from {', '.join(PROFILES)}") from None
+
+
+def for_file(path: Path, default: str = "cr6") -> Profile:
+    """Profile implied by a program's extension (`.CR6`, `.CR1X`, `.CR300`, `.CR350`)."""
+    return get(EXTENSIONS.get(path.suffix.lower(), default))

opencrbasic/provenance.py

@@ -0,0 +1,17 @@
+"""Types for loader metadata attached after parsing, without adding runtime defaults."""
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .source import LineSpan, Occurrence
+
+
+class LoadProvenance:
+    """Annotations only: loaders populate these attributes when the corresponding data exists."""
+
+    pull_log: list[tuple[tuple[int, ...], tuple[int, ...]]]
+    pull_site: dict[str, tuple[int, ...]]
+    include_paths: dict[str, Path]
+    line_map: dict[str, dict[int, list[LineSpan]]]
+    occurrences: list[Occurrence]

opencrbasic/quickfix.py

@@ -0,0 +1,331 @@
+"""Quick fixes for editor tooling: candidate code actions for a bounded set of compiler messages.
+Protocol independent (no pygls): an `Edit` is a physical range, a 0-based line and decoded-character
+columns (byte offsets into the line), exactly as `navigation.py` reports them; the server converts
+to the client's position encoding. See `docs/lsp-api.md` "Quick fixes (LSP-07c)" for the message
+families, the ranking and the limits.
+
+Every edit replaces one identifier token (or the file-name part of an include string) by a name
+that already exists: a declared name visible at the use (`bindings.BindingIndex.lookup`), a catalog
+name, or a file in the include directory's listing. Nothing is inserted or deleted otherwise, and
+a token without an exact one-slice range (`navigation`) gets no action.
+"""
+
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import NamedTuple
+
+from . import bindings, navigation, positions, profiles
+from .catalog import InstructionCatalog
+from .sources import DiskSource, OverlaySource, SourceProvider
+
+__all__ = ["Edit", "CodeAction", "code_actions", "apply_edits", "edit_distance", "MAX_ACTIONS", "FAMILIES"]
+
+MAX_ACTIONS = 5
+
+# Message families (docs/lsp-api.md). Each: (id, compiled pattern, name group or None).
+FAMILIES = (
+    ("undefined-symbol", re.compile(r"^Invalid symbol in expression: ", re.S), None),
+    ("undefined-symbol", re.compile(r"^(?P<n>[A-Za-z_][A-Za-z0-9_]*\$?) is not defined\.$"), "n"),
+    ("undefined-call", re.compile(r"^Invalid, or out of place expression: ", re.S), None),
+    ("undefined-sub", re.compile(r"^Sub (?P<n>\S+) not defined\.$"), "n"),
+    ("undefined-sub", re.compile(r"^(?P<n>\S+) is not declared as a Subroutine\.$"), "n"),
+    ("missing-include", re.compile(r"^Cannot open include file  (?P<n>.*)\.$", re.S), "n"),
+)
+
+_NAME_ROLES = (
+    bindings.READ,
+    bindings.WRITE,
+    bindings.CALL,
+    bindings.ARGUMENT,
+    bindings.MEMBER_BASE,
+    bindings.TABLE_REF,
+    bindings.ALIAS_TARGET,
+    bindings.UNITS_TARGET,
+)
+_VARIABLES = ("public", "dim", "static", "param", "alias")
+_TABLES = ("datatable", "consttable")
+_EXTERNAL = {"instruction", "function", "symbol"}
+
+
+class Edit(NamedTuple):
+    path: Path
+    line: int  # physical, 0-based
+    start: int  # decoded column, inclusive
+    end: int  # decoded column, exclusive
+    new_text: str
+
+
+@dataclass(frozen=True)
+class CodeAction:
+    title: str
+    edits: tuple[Edit, ...]
+    kind: str = "quickfix"
+    family: str = ""
+
+
+def edit_distance(a: str, b: str) -> int:
+    """Damerau-Levenshtein distance (unrestricted transpositions), case-insensitive."""
+    a, b = a.upper(), b.upper()
+    if a == b:
+        return 0
+    inf = len(a) + len(b)
+    last: dict[str, int] = {}
+    d = [[inf] * (len(b) + 2) for _ in range(len(a) + 2)]
+    for i in range(len(a) + 1):
+        d[i + 1][0] = inf
+        d[i + 1][1] = i
+    for j in range(len(b) + 1):
+        d[0][j + 1] = inf
+        d[1][j + 1] = j
+    for i in range(1, len(a) + 1):
+        last_match = 0
+        for j in range(1, len(b) + 1):
+            i1 = last.get(b[j - 1], 0)
+            j1 = last_match
+            cost = 1
+            if a[i - 1] == b[j - 1]:
+                cost = 0
+                last_match = j
+            d[i + 1][j + 1] = min(
+                d[i][j] + cost, d[i + 1][j] + 1, d[i][j + 1] + 1, d[i1][j1] + (i - i1 - 1) + 1 + (j - j1 - 1)
+            )
+        last[a[i - 1]] = i
+    return d[len(a) + 1][len(b) + 1]
+
+
+def _max_distance(name: str) -> int:
+    return 1 if len(name) <= 3 else 2
+
+
+def apply_edits(data: bytes, edits) -> bytes:
+    """`data` with `edits` (all for one file) applied; columns are Latin-1 characters of a line."""
+    lines = data.split(b"\n")
+    for e in sorted(edits, key=lambda e: (e.line, e.start), reverse=True):
+        text = lines[e.line].decode("latin-1")
+        lines[e.line] = (text[: e.start] + e.new_text + text[e.end :]).encode("latin-1")
+    return b"\n".join(lines)
+
+
+# ------------------------------------------------------------------ names
+
+
+def _profile_name(profile) -> str:
+    return profiles.get(profile if isinstance(profile, str) else profile.name).name
+
+
+def _kind_ok(role: str, explicit_call: bool, decl) -> bool:
+    kind = decl.external.kind if decl.kind == "external" and decl.external else decl.kind
+    external = decl.kind == "external"
+    if explicit_call:
+        return kind == "sub" and not external
+    if role == bindings.WRITE:
+        return kind in _VARIABLES and not external
+    if role == bindings.CALL:
+        return kind in ("sub", "function", "instruction") or (external and kind == "function")
+    if role == bindings.TABLE_REF:
+        return kind in _TABLES
+    if role == bindings.MEMBER_BASE:
+        return kind in _VARIABLES + _TABLES or decl.kind == "system_table"
+    if role in (bindings.ALIAS_TARGET, bindings.UNITS_TARGET):
+        return kind in _VARIABLES
+    read = kind in _VARIABLES + ("const", "function") or (external and kind == "symbol")
+    if role == bindings.ARGUMENT:
+        return read or kind in _TABLES
+    return read  # READ
+
+
+def _pool(index: bindings.BindingIndex, catalog: InstructionCatalog) -> dict[str, str]:
+    """upper-case name -> spelling: declared names (first spelling wins) and catalog names."""
+    pool: dict[str, str] = {}
+    for d in index.declarations:
+        if d.kind in ("field", "structure_member", "label", "external", "system_table") or d.scope in (
+            "structure",
+            "table",
+        ):
+            continue
+        pool.setdefault(d.name.upper(), d.name)
+    used: dict[str, str] = {}  # a catalog name keeps the spelling the program uses
+    for r in index.references:
+        if len(r.resolved) == 1 and r.resolved[0].kind == "external":
+            used.setdefault(r.name.upper(), r.name)
+    for entry in catalog:
+        if entry.kind in _EXTERNAL:
+            pool.setdefault(entry.name.upper(), used.get(entry.name.upper(), entry.name))
+    for extra in bindings._EXTRA_PREDEFINED:
+        pool.setdefault(extra, extra)
+    return pool
+
+
+def suggest(
+    index: bindings.BindingIndex,
+    catalog: InstructionCatalog,
+    ref: bindings.Reference,
+    pool: dict[str, str] | None = None,
+) -> list[str]:
+    """Up to `MAX_ACTIONS` spellings for the unresolved reference `ref`: Damerau-Levenshtein <= 2
+    (<= 1 for a name of up to 3 characters; a distance of 2 needs the same first letter),
+    case-insensitive, nearest first, then user-declared
+    before catalog names, then alphabetical; each must resolve at the use, with no ambiguity, to a
+    declaration whose kind fits the reference's role."""
+    pool = pool if pool is not None else _pool(index, catalog)
+    name = ref.name
+    limit = _max_distance(name)
+    explicit = bool(getattr(ref.node, "explicit", False)) and ref.role == bindings.CALL
+    ranked = []
+    for upper, spelling in pool.items():
+        if abs(len(upper) - len(name)) > limit or upper == name.upper():
+            continue
+        dist = edit_distance(name, spelling)
+        if dist > limit or (dist == 2 and upper[0] != name[0].upper()):
+            continue
+        res = index.lookup(spelling, ref.routine, ref.role)
+        if not res.candidates or res.ambiguity:
+            continue
+        if not all(_kind_ok(ref.role, explicit, c) for c in res.candidates):
+            continue
+        user = any(c.kind != "external" for c in res.candidates)
+        if (
+            not user
+            and ref.role in (bindings.READ, bindings.ARGUMENT)
+            and (catalog.get(spelling, "instruction") or catalog.get(spelling, "keyword") or upper == "TO")
+        ):
+            continue  # `Do`, `For`, `Scan`, `To`: a statement word, not the value meant
+        ranked.append((dist, not user, upper, spelling))
+    ranked.sort()
+    return [r[3] for r in ranked[:MAX_ACTIONS]]
+
+
+# ------------------------------------------------------------------ entry point
+
+_cache: tuple | None = None  # (result, profile name, index, navigation)
+
+
+def _tools(result, profile_name: str, index):
+    global _cache
+    if index is None and _cache is not None and _cache[0] is result and _cache[1] == profile_name:
+        return _cache[2], _cache[3]
+    ix = index if index is not None else bindings.build(result.program, profile_name)
+    nav = navigation.navigation(result, ix)
+    if index is None:
+        _cache = (result, profile_name, ix, nav)
+    return ix, nav
+
+
+def _norm(path) -> str:
+    return os.path.normcase(str(Path(path).absolute()))
+
+
+def code_actions(
+    result, path, diagnostic, profile, *, index=None, source: SourceProvider | None = None
+) -> list[CodeAction]:
+    """Quick fixes for `diagnostic` (an `AnalysisDiagnostic` of `result`) in the file `path`.
+    Empty for any message outside `FAMILIES` or when no exact range exists. `profile` is a profile
+    name or `Profile`. `source` (default: the disk plus `result.request.overlays`) is read for the
+    include families. Never raises for a program."""
+    try:
+        return _code_actions(result, Path(path), diagnostic, _profile_name(profile), index, source)
+    except Exception:
+        return []
+
+
+def _code_actions(result, path: Path, diag, profile_name: str, index, source) -> list[CodeAction]:
+    message = diag.message
+    family = name = None
+    for fam, pattern, group in FAMILIES:
+        m = pattern.match(message)
+        if m:
+            family, name = fam, (m.group(group) if group else None)
+            break
+    if family is None:
+        return []
+    if family == "missing-include":
+        assert name is not None  # its pattern always captures the include spec
+        return _include_actions(result, path, diag, name, source)
+    if getattr(result, "program", None) is None:
+        return []
+    ix, nav = _tools(result, profile_name, index)
+    if diag.line and diag.span is None:
+        return []
+    if diag.line and diag.path is not None and _norm(diag.path) != _norm(path):
+        return []
+    catalog = InstructionCatalog.for_profile(profile_name)
+    pool = _pool(ix, catalog)
+    nav._build()
+    here = _norm(path)
+    actions: list[CodeAction] = []
+    seen: set = set()
+    for ref in ix.references:
+        if ref.status != "unresolved" or ref.role not in _NAME_ROLES:
+            continue
+        if name is not None and ref.name.upper() != name.upper():
+            continue
+        if family in ("undefined-sub", "undefined-call") and ref.role not in (bindings.CALL, bindings.WRITE):
+            continue
+        site = nav._site_of.get(id(ref))
+        if site is None or site.path is None or _norm(site.path) != here:
+            continue
+        if diag.line and not (diag.span[0] - 1 <= site.line <= diag.span[1] - 1):
+            continue
+        for spelling in suggest(ix, catalog, ref, pool):
+            edit = Edit(site.path, site.line, site.start, site.end, spelling)
+            if edit in seen:
+                continue
+            seen.add(edit)
+            actions.append(CodeAction(f"Change to `{spelling}`", (edit,), family=family))
+    return actions
+
+
+# ------------------------------------------------------------------ include family
+
+_DRIVE = re.compile(r"^(?:CPU|USR|CRD|USB):", re.I)
+_STRING = re.compile(r'"([^"]*)"')
+_INCLUDE_EXTENSIONS = (".crb", ".cr6")
+
+
+def _include_actions(result, path: Path, diag, spec: str, source) -> list[CodeAction]:
+    if diag.path is None or _norm(diag.path) != _norm(path) or diag.span is None:
+        return []
+    src = source or OverlaySource(DiskSource(), getattr(result.request, "overlays", None))
+    data = src.read(path)
+    listing = src.list_dir(path.parent)
+    if data is None or not listing:
+        return []
+    wanted = _DRIVE.sub("", spec.strip())
+    if not wanted or "/" in wanted or "\\" in wanted:
+        return []
+    entry = Path(result.request.entry).absolute().name.lower()
+    ranked = []
+    for fname in listing:
+        if fname.lower() == entry or not fname.lower().endswith(_INCLUDE_EXTENSIONS) or fname == wanted:
+            continue
+        dist = edit_distance(wanted, fname)
+        if dist <= _max_distance(wanted):
+            ranked.append((dist, fname.upper(), fname))
+    ranked.sort()
+    if not ranked:
+        return []
+    lines = positions.physical_lines(data)
+    actions: list[CodeAction] = []
+    for lineno in range(diag.span[0], diag.span[1] + 1):
+        if not 1 <= lineno <= len(lines):
+            continue
+        text = lines[lineno - 1].decode("latin-1")
+        for m in _STRING.finditer(text):
+            inner = m.group(1)
+            if _DRIVE.sub("", inner.strip()) != wanted:
+                continue
+            at = m.start(1) + inner.find(wanted)
+            if at < m.start(1):
+                continue
+            for _, _, fname in ranked[:MAX_ACTIONS]:
+                actions.append(
+                    CodeAction(
+                        f"Change to `{fname}`",
+                        (Edit(path, lineno - 1, at, at + len(wanted), fname),),
+                        family="missing-include",
+                    )
+                )
+            return actions
+    return actions