opencrbasic 1.0.0__py3-none-any.whl

opencrbasic/checker/terminals.py

@@ -0,0 +1,249 @@
+"""Per-logger analog-channel and port terminal model.
+
+Generalises the analog-channel range check (originally CR6-only, hard-coded `U1..U12`) across all
+four loggers, driven by oracle-probed per-logger data (`data/<logger>/terminals.json`; evidence,
+probes and the message-text differences: `docs/loggers.md`, `docs/instructions.md`).
+
+Each logger's `terminals.json` names its own channel "kinds" -- CR6 has separate `u_terminal`
+(single-ended-shaped: any `U1..U12`, no oddness constraint; `ACPower`, `CS616`'s `CS616Chan`,
+`ExciteV`/`ExciteI`'s `ExChan`), `u_terminal_diff` (`VoltDiff`/`TCDiff`'s `DiffChan`: `U1..U12` only
+on an *odd* terminal, a second, distinct message when the value is otherwise in range) and
+`u_terminal_se` (`VoltSe`/`TCSe`'s `SEChan`: any `U1..U12`, no oddness) -- both of the latter two
+also allow a burst-mode negative value (`transform: "abs"`); CR1000X and CR300/CR350 instead use
+`diff_chan`/`se_chan`, a plain integer with a different valid range and message
+(`docs/loggers.md`). A `"port"`-shaped kind (`port_c1c4_u1u12` on CR6, `port_c1c8` on CR1000X) is a
+disjoint union of ranges (`PortSet`/`PortGet`'s `Port`, `CS616`'s `CS616Port`); `sdi_port` (CR6) /
+`sdi_port_cr1000x` (CR1000X) is a disjoint union restricted to *odd* terminals only (SDI-12's own
+half-duplex wiring, `docs/instructions.md`). `checker/instructions.py` calls `check` here; the two
+modules stay separate because this one owns the per-logger *data*, while `instructions.py` is the
+shared entry point another workstream also uses.
+
+A `kind` dict:
+  - `ranges`: list of `[min, max]` pairs (a single-range kind may instead give `min`/`max` directly,
+    kept for the pre-existing CR1000X/CR300/CR350 `diff_chan`/`se_chan` entries).
+  - `transform`: `"abs"` (test/show `abs(value)`, burst-mode) or `"none"` (default).
+  - `skip_nonpositive`: CR300/CR350 (`docs/loggers.md`) -- a value `<= 0` is deliberately left
+    unchecked (real, different, not-yet-modelled validation shape there; never guessed at).
+  - `odd_only` + `odd_message`: after the range check passes, the (transformed) value must also be
+    odd, else `odd_message` fires instead of `message` (`docs/instructions.md`'s "Invalid start
+    channel for Differential Measurement..." / "Invalid SDI-12 port..." findings).
+  - `allowed` + `allowed_message`: after the range check passes, the value must also be one of
+    `allowed` (`SPIOpen`'s `C1, U1, U5, or U9`, `TimerInput`'s starting channel).
+  - `secondary_when_invalid`: CR1000X -- an out-of-range value also gets the `odd_message`/
+    `allowed_message` line after `message` (its port converter returns 0 for a bad port, which
+    then fails the instruction's own test; CR6 stops at `message`).
+  - `message`: the range-check failure text, `{v}` = the displayed (transformed) value.
+
+CR6 ports go through one converter (decompiled `FUN_00515ff0`): `C1..C16` (101..116) and
+`U1..U12` (201..212) are valid, `C5..C16` being the same terminals as `U1..U12` (oracle,
+2026-10-01: `PortSet(109,1)`, `SPIOpen(105,...)` compile); CR1000X takes `C1..C8`.
+"""
+
+import math
+
+from .. import consteval
+from .. import syntax as S
+from ..diagnostics import Diagnostics
+from ..profiles import Profile
+
+
+def _ranges(kind: dict) -> list[tuple[int, int]]:
+    if "ranges" in kind:
+        return [tuple(r) for r in kind["ranges"]]
+    return [(kind["min"], kind["max"])]
+
+
+def _in_range(v: float, kind: dict) -> bool:
+    return any(lo <= v <= hi for lo, hi in _ranges(kind))
+
+
+def _cr6_burst_kind(kind: dict) -> bool:
+    return kind.get("transform") == "abs" and _ranges(kind) == [(201, 212)]
+
+
+def _evaluate(value: float, kind: dict) -> tuple[bool, bool, int]:
+    """(in_range, odd_ok, displayed_value) for a constant `value` against one channel `kind`.
+
+    `transform: "abs"`: the real compiler's shown value and both tests use the argument's absolute
+    value -- burst-mode measurements encode "same channel, repeated" as a negative channel number
+    (`docs/loggers.md`, oracle: CR6 `VoltDiff` `DiffChan` -1 (raw -201) compiles, `TCSe` `SEChan`
+    -202 compiles). `transform: "none"` (every other kind): the raw value is both tested and shown.
+    """
+    v = abs(value) if kind.get("transform") == "abs" else value
+    if _cr6_burst_kind(kind) and -200 < value < 0:
+        v = value  # a small negative is no burst code: tested and shown signed (oracle, CR6)
+    if kind.get("port_wrap"):
+        # CR6 ports (PortSet/PortGet/CS616, round 9): the value is cast to a 32-bit integer (out of
+        # range -> -2147483648, which is what the message shows) and any v >= 201 with v mod 200
+        # in 0..12 is accepted besides C1..C16/U1..U12 (400, 1000, 1001, 3012 compile; 200, 213,
+        # 413, 1100 do not).
+        v = int(v) if -(2**31) <= v < 2**31 else -(2**31)
+        in_range = _in_range(v, kind) or (v >= 201 and v % 200 <= 12)
+        return in_range, True, v
+    in_range = _in_range(v, kind)
+    odd_ok = (not kind.get("odd_only")) or (in_range and int(v) % 2 == 1)
+    return in_range, odd_ok, int(v)
+
+
+CR6_BRIDGES = frozenset({"BRHALF", "BRHALF3W", "BRHALF4W", "BRFULL", "BRFULL6W"})
+
+
+def check(program: S.Program, profile: Profile, diags: Diagnostics, env: consteval.Env) -> None:
+    terminals = profile.terminals
+    checked_instructions: dict = terminals.get("instructions", {})
+    channels: dict = terminals.get("channels", {})
+    if not checked_instructions:
+        return
+    from .instr_data import _with_inline
+
+    for stmt in _with_inline(program.statements):  # a one-line If's statement too (round 58)
+        if not isinstance(stmt, S.Instruction):
+            continue
+        positions = checked_instructions.get(stmt.keyword.upper())
+        if not positions:
+            continue
+        if (
+            stmt.keyword.upper() == "ACPOWER"
+            and profile.name == "cr6"
+            and _check_acpower(stmt, channels[positions[0][1]], env, diags)
+        ):
+            continue
+        for pos, kind_name, *extra in positions:
+            # optional third and fourth items: the Reps position and the channels per repetition;
+            # the channel span is then checked (rounds 30-31, docs/checker.md#measurement-
+            # destination-and-channel-spans-round-31)
+            reps = _const_int(stmt, extra[0], env, truncate=True) if extra else None
+            width = extra[1] if len(extra) > 1 else 1
+            kind = channels[kind_name]
+            if reps is not None and profile.name == "cr6" and stmt.keyword.upper() in CR6_BRIDGES:
+                reps = min(reps, 1)  # start channel only: `instr_measure._check_bridge_span` owns the span
+            if reps is not None and "span" in kind:
+                _check_arg(stmt, pos, kind, env, diags, reps=reps, width=width)
+            else:  # CR300/CR350: the last channel used is tested and shown
+                _check_arg(stmt, pos, kind, env, diags, max(reps, 1) * width - 1 if reps is not None else 0)
+
+
+def _const_int(stmt: S.Instruction, pos: int, env: consteval.Env, truncate: bool = False) -> int | None:
+    """An integral constant argument; `truncate` takes the integer part of any finite one."""
+    if pos > len(stmt.args) or stmt.args[pos - 1] is None or not consteval.is_constant(stmt.args[pos - 1], env):
+        return None
+    try:
+        value = consteval.value_of(stmt.args[pos - 1], env)
+    except consteval.NotConstant:
+        return None
+    if not isinstance(value, (int, float)) or isinstance(value, bool) or not math.isfinite(value):
+        return None
+    return int(value) if truncate or value == int(value) else None
+
+
+def _check_acpower(stmt: S.Instruction, kind: dict, env: consteval.Env, diags: Diagnostics) -> bool:
+    """CR6 `ACPower` with a bad `ChanV` (4th) and/or `ChanI` (7th) and one or two `RepsI` (10th)
+    (oracle, 2026-10-10, `tests/fixtures/acpower_channels.json`): a bad voltage channel `v` prints
+    `v, v, -v, v`; per rep `k` (one or two) a bad voltage channel then adds `v` (from the second
+    rep) and a bad current channel `i` adds `-(i+k)`. True when handled."""
+    v, i, reps = (_const_int(stmt, pos, env) for pos in (4, 7, 10))
+    if v is None or i is None or reps not in (1, 2) or v < 0:
+        return False
+    v_bad, i_bad = not _in_range(v, kind), not _in_range(i, kind)
+    shown = [v, v, -v, v] if v_bad else []
+    for k in range(reps):
+        if k and v_bad:
+            shown.append(v)
+        if i_bad:
+            shown.append(-(i + k))
+    for value in shown:
+        diags.error(stmt.line, kind["message"].format(v=value), stmt.file)
+    return True
+
+
+def _check_arg(
+    stmt: S.Instruction,
+    pos: int,
+    kind: dict,
+    env: consteval.Env,
+    diags: Diagnostics,
+    span: int = 0,
+    reps: int | None = None,
+    width: int = 1,
+) -> None:
+    idx = pos - 1
+    if idx >= len(stmt.args) or stmt.args[idx] is None:
+        return
+    arg = stmt.args[idx]
+    huge = False
+    if kind.get("huge_int_min") or "overflow_add" in kind:
+        # CR1000X (oracle, 2026-10-25, round 35): a constant outside int32 becomes INT_MIN; a
+        # single-ended channel then reports it, a differential one compiles, as does one whose
+        # `|channel| + overflow_add` passes INT_MAX (from 2147483641, any Reps)
+        try:
+            folded = consteval.value_of(arg, env) if consteval.is_constant(arg, env) else None
+        except consteval.NotConstant:
+            folded = None
+        if isinstance(folded, (int, float)) and not isinstance(folded, bool) and math.isfinite(folded):
+            huge = not -(2**31) < int(folded) < 2**31  # (INT_MIN itself too: `abs` keeps it)
+            if "overflow_add" in kind and (huge or abs(int(folded)) + kind["overflow_add"] > 2**31 - 1):
+                return
+    if (isinstance(arg, S.String) or huge) and kind.get("string_int_min" if not huge else "huge_int_min"):
+        # a string literal (`PortSet("fuzz",1)`, `"102"`, `""`) folds to INT_MIN (oracle, all
+        # four loggers, 2026-10-12)
+        value = -2147483648
+        in_range, odd_ok, _ = _evaluate(value, kind)
+        shown = value  # (`abs` of INT_MIN is INT_MIN in C: CR1000X `VoltSe(X,1,mV1000,"abc",...)`)
+        if not in_range:
+            diags.error(stmt.line, kind["message"].format(v=shown), stmt.file)
+            if kind.get("secondary_when_invalid") and (not odd_ok or "allowed" in kind):
+                diags.error(
+                    stmt.line,
+                    (kind["odd_message"] if not odd_ok else kind["allowed_message"]).format(v=shown),
+                    stmt.file,
+                )
+        return
+    if not consteval.is_constant(arg, env):
+        return  # a variable here is already rejected by the generic const-expr parameter (type
+        # code 1's own "Variable illegal in Parameter" -- docs/type-codes.md); not our job.
+    try:
+        value = consteval.value_of(arg, env)
+    except consteval.NotConstant:
+        return
+    if not consteval.is_finite_number(value):
+        return
+    if kind.get("truncate") and math.isfinite(value):
+        value = int(value)  # (CR1000X CurrentSE `402.5` is RG2, PulseCount `108.5` C8, round 31)
+    if kind.get("skip_nonpositive") and value <= 0:
+        # CR300/CR350 (docs/loggers.md): a channel <= 0 is accepted far outside any range this
+        # checker would derive with confidence (oracle: DiffChan -4 compiles with a 1..3 range,
+        # -100 fails as "Channel 99"; -1 also compiles for an SEChan that never takes negative
+        # values per its own CHM doc). Left unchecked rather than guessed, per AGENTS.md's "never
+        # falsely reject" priority -- every corpus mismatch this rule fixes is a plain positive
+        # channel number written where a different range or terminal name was required.
+        return
+    if _cr6_burst_kind(kind) and value <= -200 and not -212 <= value <= -201:
+        return  # CR6 -200 and -213 and below behave irregularly (accepted, odd-start or port messages)
+    spec = kind.get("span") if reps is not None else None
+    top = max(hi for _, hi in _ranges(kind))
+    if spec is not None and not spec.get("start_upper", True) and value > top:
+        # CR6: a start channel above U12 is reported as the span (`250`: `Channel 50`, round 31)
+        if kind.get("odd_only") and int(value) % 2 != 1:
+            diags.error(stmt.line, kind["odd_message"].format(v=int(value)), stmt.file)
+        else:
+            diags.error(stmt.line, spec["message"].format(v=int(value) + spec.get("shift", 0)), stmt.file)
+        return
+    in_range, odd_ok, shown = _evaluate(value + span, kind)
+    allowed_ok = "allowed" not in kind or (in_range and shown in kind["allowed"])
+    if not in_range:
+        diags.error(stmt.line, kind["message"].format(v=shown), stmt.file)
+        if not kind.get("secondary_when_invalid"):
+            return
+    if not odd_ok:
+        diags.error(stmt.line, kind["odd_message"].format(v=shown), stmt.file)
+    elif not allowed_ok:
+        diags.error(stmt.line, kind["allowed_message"].format(v=shown), stmt.file)
+    elif spec is not None and reps is not None and reps > 1 and (value > 0 or not in_range):
+        # the last repetition's start channel must stay in the start's own range; the message
+        # shows the first channel past it (`spec`: own `ranges`, `step`, display `shift`). CR300/
+        # CR350 PulseCount spans an invalid start from `invalid_start` (round 31)
+        start = value if in_range else spec["invalid_start"]
+        last = start + (reps - 1) * width * spec.get("step", 1)
+        end = next(hi for lo, hi in _ranges(kind) if lo <= start <= hi)
+        if last > end or not _in_range(last, spec if "ranges" in spec else kind):
+            diags.error(stmt.line, spec["message"].format(v=int(end) + 1 + spec.get("shift", 0)), stmt.file)

opencrbasic/checker/unused.py

@@ -0,0 +1,186 @@
+"""`-u`: `%s declared but not used.` (`docs/cli.md` "-u").
+
+Oracle-confirmed this session (`tools/tdf_probe.py <snippet> --extra=-u`, real `CR6Comp.exe` under
+Wine, cross-checked against `cr1000xcomp.exe`/`cr300comp.exe`/`cr350comp.exe` on the same snippet --
+all four loggers print the identical messages in the identical format, so this module has no
+per-logger branching):
+
+- Flags a `Public`/`Dim` variable (the whole array/`String`, never a single element -- any
+  reference to *any* element marks the whole declaration used) and a `Sub`/`Function` parameter
+  that is never referenced anywhere else in the program text, each as `line N: Warning: %s declared
+  but not used.`.
+- Also flags a `Sub` **or** `Function` that is never referenced anywhere else in the program, as a
+  *bare* `Warning: %s declared but not used.` -- no `line N:` prefix, the same "no line" shape as
+  the pre-existing "table declared but never called" warning (`checker/warnings.py`). An initial
+  reading of one oracle probe (an uncalled `Function` whose body sets its return value the usual
+  way, `MyFunc = value`) looked like an uncalled `Function` is *never* flagged, unlike an uncalled
+  `Sub` -- corrected once the real corpus (`ShuntLib.crb`'s `SampleShunt`, uncalled in
+  `Main.CR6`/`PowerBudget_tester.CR6`/`Preflight_tester.CR6` because its only call site sits behind
+  a false `#If`) turned out to *be* flagged: `MyFunc = value` inside the function's own body is
+  itself a reference to `MyFunc` (an ordinary `Assignment.target`, walked like any other), which is
+  what suppressed the warning in the first probe, not the `Function`/`Sub` distinction; a second
+  probe with `Return value` instead of self-assignment confirmed an uncalled `Function` *is*
+  flagged identically to an uncalled `Sub` once nothing else references its name.
+- **Not** flagged: `Const`/`ConstTable` fields and an `Alias` name. Aliasing merges the alias name
+  and the underlying declared variable into one usage identity: a reference to the alias name
+  elsewhere in the program counts as using the original variable (oracle: `Public X` / `Alias X =
+  Y` / `Y = 1` -- `X` is *not* flagged), but the `Alias`/`Units`/`ReadOnly` statement's own mention
+  of a name is never itself a use (oracle: `Public X` / `Alias X = Y` alone, `Y` never referenced
+  again -- `X` *is* flagged; likewise a bare `Units X = Label` or `ReadOnly X` with no other
+  reference to `X` still flags it). A variable referenced only as a `DataTable` output source (a
+  `Sample`/`Average`/... argument) counts as used.
+- The whole check is suppressed by *any* compile error anywhere in the file, not just the ones
+  after a given declaration (oracle: a single unrelated error anywhere removes every `-u` warning).
+  `compiler.compile_file` only calls `check` after the ordinary checker has run and found no
+  errors; this module does not re-check that itself.
+
+Scope/limits: this project's syntax tree keeps block structure flat (`syntax.py`'s own docstring)
+and does not model lexical scope -- like `checker/symbols.py`'s `declared_names`, a name here is
+"used" if referenced *anywhere* in the program, including inside a different `Sub`/`Function` than
+the one that declares it. Not independently oracle-tested against real per-scope shadowing (not
+observed in this project's corpus). `Static` declarations were not investigated (rejected as
+invalid syntax by the CR6 grammar in every oracle probe tried, and unused in `crbasic/`).
+"""
+
+from .. import syntax as S
+from ..diagnostics import Diagnostics
+
+# Instructions that mention a variable's name as metadata, not as a real reference (oracle-
+# confirmed for all three: `Alias X = Y`, `Units X = Label`, `ReadOnly X` never count as "using"
+# `X` on their own).
+_METADATA_ONLY = frozenset({"ALIAS", "UNITS", "READONLY"})
+
+
+def _base_name(expr: S.Expr | None) -> str | None:
+    """The identifier a bare `Name` or single-element `Index` (`Arr(3)`) expression names, for
+    resolving an `Alias` statement's own operands -- `None` for anything else (a swath/complex
+    alias target, `docs/tdf-rules.md` §11 open question, is left unmerged rather than guessed at).
+    """
+    if isinstance(expr, S.Name):
+        return expr.name
+    if isinstance(expr, S.Index):
+        return expr.name
+    return None
+
+
+def _walk_expr(expr: S.Expr | None, names: set[str]) -> None:
+    if expr is None:
+        return
+    if isinstance(expr, S.Name):
+        names.add(expr.name.upper())
+    elif isinstance(expr, S.Index):
+        names.add(expr.name.upper())
+        for a in expr.args:
+            _walk_expr(a, names)
+    elif isinstance(expr, S.Member):
+        _walk_expr(expr.base, names)
+        for a in expr.args or ():
+            _walk_expr(a, names)
+    elif isinstance(expr, S.Unary):
+        _walk_expr(expr.operand, names)
+    elif isinstance(expr, S.Binary):
+        _walk_expr(expr.left, names)
+        _walk_expr(expr.right, names)
+    elif isinstance(expr, S.ArrayLiteral):
+        for item in expr.items:
+            _walk_expr(item, names)
+    # Number/String: no name to collect.
+
+
+def _walk_stmt(stmt: S.Stmt, names: set[str]) -> None:
+    """Every name a statement *references* (not declares) -- feeds the "used anywhere" set that
+    every declared Public/Dim/param/Sub name is checked against. `Declaration`'s own `VarDecl.name`
+    and `SubDef`'s own `name`/`Param.name` are never walked here (they are declarations, callers
+    collect those separately); a `VarDecl`'s `dims`/`init`/`string_size` and a `Param`'s `default`/
+    `string_size` genuinely can reference some *other* variable, so those are walked.
+    """
+    if isinstance(stmt, S.Declaration):
+        for v in stmt.vars:
+            for d in v.dims:
+                _walk_expr(d, names)
+            for e in v.init or ():
+                _walk_expr(e, names)
+            _walk_expr(v.string_size, names)
+    elif isinstance(stmt, S.ConstDecl):
+        _walk_expr(stmt.value, names)
+    elif isinstance(stmt, S.Assignment):
+        _walk_expr(stmt.target, names)
+        _walk_expr(stmt.value, names)
+    elif isinstance(stmt, S.Instruction):
+        if stmt.keyword.upper() in _METADATA_ONLY:
+            return
+        for a in stmt.args:
+            _walk_expr(a, names)
+    elif isinstance(stmt, S.If):
+        _walk_expr(stmt.cond, names)
+        for s2 in stmt.inline or ():
+            _walk_stmt(s2, names)
+        for s2 in stmt.inline_else or ():
+            _walk_stmt(s2, names)
+    elif isinstance(stmt, S.ElseIf):
+        _walk_expr(stmt.cond, names)
+    elif isinstance(stmt, S.For):
+        _walk_expr(stmt.var, names)
+        _walk_expr(stmt.start, names)
+        _walk_expr(stmt.end, names)
+        _walk_expr(stmt.step, names)
+    elif isinstance(stmt, S.DoLoop):
+        _walk_expr(stmt.cond, names)
+    elif isinstance(stmt, S.Case):
+        for item in stmt.items:
+            for part in item:
+                if isinstance(part, S.Expr):
+                    _walk_expr(part, names)
+    elif isinstance(stmt, S.Call):
+        names.add(stmt.name.upper())  # `Call MySub(...)` / bare `MySub(...)`: a real call.
+        for a in stmt.args:
+            _walk_expr(a, names)
+    elif isinstance(stmt, S.SubDef):
+        for p in stmt.params:
+            _walk_expr(p.default, names)
+            _walk_expr(p.string_size, names)
+    # If/ElseIf/For/DoLoop/Case/Label/Unparsed themselves: nothing else to collect.
+
+
+def check(program: S.Program, diags: Diagnostics) -> None:
+    """Add every `-u` warning for `program` to `diags`. Caller's responsibility (`compiler.py`):
+    only call this when `not diags.errors` (oracle-confirmed gate, see this module's docstring).
+    """
+    variables: list[tuple[str, int, str, str]] = []  # (NAME upper, line, display, file)
+    params: list[tuple[str, int, str, str]] = []
+    subs: list[tuple[str, str, str]] = []  # (NAME upper, display, file)
+    alias_map: dict[str, str] = {}  # ALIAS-TARGET upper -> ORIGINAL-BASE upper
+
+    for stmt in program.statements:
+        if isinstance(stmt, S.Declaration) and stmt.kind.upper() in ("PUBLIC", "DIM"):
+            for v in stmt.vars:
+                variables.append((v.name.upper(), stmt.line, v.name, stmt.file))
+        elif isinstance(stmt, S.SubDef):
+            for p in stmt.params:
+                params.append((p.name.upper(), stmt.line, p.name, stmt.file))
+            subs.append((stmt.name.upper(), stmt.name, stmt.file))
+        elif isinstance(stmt, S.Instruction) and stmt.keyword.upper() == "ALIAS" and stmt.args:
+            original = _base_name(stmt.args[0])
+            if original:
+                for target in stmt.args[1:]:
+                    name = _base_name(target)
+                    if name:
+                        alias_map[name.upper()] = original.upper()
+
+    used: set[str] = set()
+    for stmt in program.statements:
+        _walk_stmt(stmt, used)
+    for name in list(used):
+        mapped = alias_map.get(name)
+        if mapped:
+            used.add(mapped)
+
+    for upper, line, display, file in variables:
+        if upper not in used:
+            diags.warning(line, f"{display} declared but not used.", file)
+    for upper, line, display, file in params:
+        if upper not in used:
+            diags.warning(line, f"{display} declared but not used.", file)
+    for upper, display, file in subs:
+        if upper not in used:
+            diags.warning(0, f"{display} declared but not used.", file)