Skip to content

wandelbotsgmbh/wandelbots-nova / nova/agent_skills/nova-app-review

nova-app-review

Verified

Review a robot cell application built on the Wandelbots NOVA Python SDK (wandelbots-nova) for safety, motion, PLC/IO, async runtime, performance, lifecycle, device handling and NOVA SDK usage, and report findings with severity, evidence and concrete fixes. Use when the user asks to review, audit, check, lint or harden a NOVA app, a @nova.program, a NOVAx app or any robot application; asks about best practices, common pitfalls, cycle time, safety or commissioning readiness; or asks 'is my robot code OK?'.

scripts/scan.py

View on GitHub
#!/usr/bin/env python3
"""Static candidate scanner for the nova-app-review skill (Python standard library only).

Usage:
    python scan.py [ROOT ...]

Prints JSON with rule candidates and project facts. Candidates are hints: the reviewing agent
must confirm every candidate by reading the code before reporting it as a finding.
"""

from __future__ import annotations

import argparse
import ast
import io
import json
import re
import sys
import tokenize
from collections import defaultdict
from dataclasses import asdict, dataclass
from pathlib import Path

SCANNER_VERSION = 1

SKIP_DIRS = {
    ".agents",
    ".claude",
    ".codex",
    ".cursor",
    ".git",
    ".github",
    ".mypy_cache",
    ".nox",
    ".pytest_cache",
    ".ruff_cache",
    ".tox",
    ".venv",
    "__pycache__",
    "build",
    "dist",
    "node_modules",
    "site-packages",
    "venv",
}

SEVERITY = {
    "ASY-001": "error",
    "ASY-004": "error",
    "ASY-005": "warning",
    "CFG-002": "info",
    "ERR-001": "error",
    "ERR-005": "warning",
    "IO-002": "error",
    "IO-005": "warning",
    "LIFE-004": "warning",
    "LIFE-007": "info",
    "MOT-001": "error",
    "MOT-002": "error",
    "MOT-003": "error",
    "MOT-006": "warning",
    "MOT-007": "warning",
    "MOT-009": "warning",
    "MOT-011": "warning",
    "OBS-001": "warning",
    "PERF-001": "warning",
    "PERF-004": "warning",
    "PERF-006": "warning",
    "SAF-003": "error",
    "SAF-005": "error",
    "SAF-010": "error",
    "SAF-012": "warning",
    "STR-001": "error",
    "STR-003": "info",
}
SEVERITY_ORDER = {"error": 0, "warning": 1, "info": 2}

GENERATED_RE = re.compile(r"(?i)(auto-?generated|do not edit|generated by)")
CONFIG_FILE_RE = re.compile(r"(?i)(config|settings|profiles?|constants|params|parameters)")
SIM_FLAG_RE = re.compile(
    r"(?i)(virtual|simulat|mock|dry_?run|fake|bypass|ignore_\w*check|skip_\w*check)"
)
BYPASS_FLAG_RE = re.compile(r"(?i)(bypass|ignore_\w*check|skip_\w*check)")
SAFETY_FUNC_RE = re.compile(r"(?i)(safe|interlock)")
SIGNAL_LITERAL_RE = re.compile(r"^(In|Out)\.[A-Z]")
COMMENTED_CODE_RE = re.compile(
    r"^#\s*(await |return |if |elif |for |while |async |def |[\w.\[\]]+\s*\(|[\w.\[\]]+\s*=[^=])"
)
TODO_RE = re.compile(r"\b(TODO|FIXME|XXX|HACK)\b")
TODO_REF_RE = re.compile(r"(#\d+|\b[A-Z][A-Z0-9]+-\d+\b|@\w+|\(\w[\w .-]*\)|https?://)")
PAYLOAD_COMMENT_RE = re.compile(r"(?i)(\bkg\b|\bpayload\b|\bCoG\b|cent(er|re) of gravity|\bmass\b)")
TRUTHY_DEFAULTS = {True, 1, "1", "true", "True", "TRUE", "yes", "on"}

MOTION_CALLS = {"plan", "execute", "plan_and_execute", "stream_execute"}
TIMEOUT_CONTEXTS = {"timeout", "timeout_at", "fail_after", "fail_at", "move_on_after", "move_on_at"}
IO_WAIT_CALLS = {"wait_for_bus_io", "wait_for_bool_io"}
IO_KEY_CALLS = {
    "io_write",
    "read",
    "write",
    "wait_for_bool_io",
    "get_bus_io_value",
    "set_bus_io_value",
    "wait_for_bus_io",
}
BLOCKING_CALLS = {
    "time.sleep",
    "subprocess.run",
    "subprocess.call",
    "subprocess.check_call",
    "subprocess.check_output",
    "os.system",
    "urllib.request.urlopen",
}
SLEEP_CALLS = {"asyncio.sleep", "anyio.sleep", "trio.sleep", "nova.actions.wait"}
UNIT_CONVERSIONS = {
    "math.radians",
    "math.degrees",
    "numpy.deg2rad",
    "numpy.rad2deg",
    "numpy.radians",
    "numpy.degrees",
}
ENV_CALLS = {"os.getenv", "os.environ.get", "decouple.config"}
SDK_PRIVATE_ATTRS = {
    "_api_client",
    "_nova_api",
    "_api_gateway",
    "_io_access",
    "_current_motion",
    "_motion_group_id",
    "_controller_id",
}
SDK_OBJECT_RE = re.compile(r"(?i)(^nova$|cell|controller|motion_group|^mg$|robot)")
PUBLIC_UNDERSCORE_ATTRS = {"_replace", "_asdict", "_fields", "_make"}
MOTION_RECEIVER_RE = re.compile(r"(?i)(^mg$|^mg_|_mg$|motion|robot|^arm$|_arm$|^arm_)")
LOG_METHODS = {"debug", "info", "warning", "warn", "error", "exception", "critical", "log"}
PLANNING_ERRORS = {"PlanTrajectoryFailed", "NoInverseKinematicsSolutionFound"}


@dataclass
class Candidate:
    rule: str
    severity: str
    confidence: str
    file: str
    line: int
    excerpt: str
    message: str
    path_kind: str


def path_kind(rel: Path) -> str:
    parts = {p.lower() for p in rel.parts[:-1]}
    if parts & {"tests", "test"} or rel.name.startswith("test_") or rel.name == "conftest.py":
        return "test"
    if parts & {"scripts", "tools"}:
        return "script"
    if parts & {"examples", "example"}:
        return "example"
    return "app"


def is_config_file(rel: Path) -> bool:
    return bool(CONFIG_FILE_RE.search(rel.stem)) or any(
        CONFIG_FILE_RE.search(p) for p in rel.parts[:-1]
    )


def dotted(node: ast.AST) -> str | None:
    if isinstance(node, ast.Name):
        return node.id
    if isinstance(node, ast.Attribute):
        base = dotted(node.value)
        return f"{base}.{node.attr}" if base else None
    return None


def last_identifier(node: ast.AST) -> str:
    if isinstance(node, ast.Name):
        return node.id
    if isinstance(node, ast.Attribute):
        return node.attr
    if isinstance(node, ast.Call):
        return last_identifier(node.func)
    if isinstance(node, ast.Await):
        return last_identifier(node.value)
    return ""


def call_name(node: ast.Call) -> str:
    return last_identifier(node.func)


def numeric_value(node: ast.AST) -> float | None:
    if isinstance(node, ast.Constant) and isinstance(node.value, (int, float)):
        if isinstance(node.value, bool):
            return None
        return float(node.value)
    if isinstance(node, ast.UnaryOp) and isinstance(node.op, (ast.USub, ast.UAdd)):
        inner = numeric_value(node.operand)
        if inner is None:
            return None
        return -inner if isinstance(node.op, ast.USub) else inner
    return None


def has_raise(nodes: list[ast.stmt]) -> bool:
    return any(isinstance(n, ast.Raise) for stmt in nodes for n in ast.walk(stmt))


def has_log_call(nodes: list[ast.stmt]) -> bool:
    for stmt in nodes:
        for n in ast.walk(stmt):
            if isinstance(n, ast.Call) and call_name(n) in LOG_METHODS:
                return True
    return False


def exception_names(handler: ast.ExceptHandler) -> set[str]:
    if handler.type is None:
        return {"<bare>"}
    types = handler.type.elts if isinstance(handler.type, ast.Tuple) else [handler.type]
    return {last_identifier(t) for t in types}


class FileScanner(ast.NodeVisitor):
    def __init__(self, rel: Path, source: str, report: ProjectReport):
        self.rel = rel
        self.lines = source.splitlines()
        self.report = report
        self.kind = path_kind(rel)
        self.config_file = is_config_file(rel)
        self.imports: dict[str, str] = {}
        self.func_stack: list[bool] = []
        self.timeout_depth = 0
        self.loop_depth = 0
        self.while_depth = 0
        self.main_depth = 0
        self.with_managed: set[int] = set()
        self.module_has_async = "async def" in source

    # -- helpers ---------------------------------------------------------------------------

    def add(self, rule: str, node: ast.AST, confidence: str, message: str) -> None:
        line = getattr(node, "lineno", 0)
        self.report.add(self.rel, self.kind, rule, line, self.excerpt(line), confidence, message)

    def excerpt(self, line: int) -> str:
        if 0 < line <= len(self.lines):
            return self.lines[line - 1].strip()[:160]
        return ""

    def resolve(self, node: ast.AST) -> str:
        name = dotted(node)
        if not name:
            return ""
        head, _, rest = name.partition(".")
        head = self.imports.get(head, head)
        return f"{head}.{rest}" if rest else head

    @property
    def in_async(self) -> bool:
        return bool(self.func_stack) and self.func_stack[-1]

    @property
    def in_function(self) -> bool:
        return bool(self.func_stack)

    # -- imports ---------------------------------------------------------------------------

    def visit_Import(self, node: ast.Import) -> None:
        for alias in node.names:
            if alias.asname:
                self.imports[alias.asname] = alias.name
            else:
                top = alias.name.split(".")[0]
                self.imports[top] = top
            self.report.note_import(alias.name)

    def visit_ImportFrom(self, node: ast.ImportFrom) -> None:
        module = node.module or ""
        for alias in node.names:
            self.imports[alias.asname or alias.name] = f"{module}.{alias.name}"
            self.report.note_import(f"{module}.{alias.name}")

    # -- scopes ----------------------------------------------------------------------------

    def _visit_function(self, node: ast.FunctionDef | ast.AsyncFunctionDef, is_async: bool):
        self.check_safety_stub(node)
        self.check_program_decorator(node)
        saved = (self.timeout_depth, self.loop_depth, self.while_depth)
        self.timeout_depth = self.loop_depth = self.while_depth = 0
        self.func_stack.append(is_async)
        self.generic_visit(node)
        self.func_stack.pop()
        self.timeout_depth, self.loop_depth, self.while_depth = saved

    def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
        self._visit_function(node, is_async=False)

    def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef) -> None:
        self._visit_function(node, is_async=True)

    def visit_For(self, node: ast.For) -> None:
        self.loop_depth += 1
        self.generic_visit(node)
        self.loop_depth -= 1

    def visit_AsyncFor(self, node: ast.AsyncFor) -> None:
        self.loop_depth += 1
        self.generic_visit(node)
        self.loop_depth -= 1

    def visit_While(self, node: ast.While) -> None:
        self.loop_depth += 1
        self.while_depth += 1
        self.generic_visit(node)
        self.while_depth -= 1
        self.loop_depth -= 1

    def visit_If(self, node: ast.If) -> None:
        test = node.test
        is_main = (
            isinstance(test, ast.Compare)
            and isinstance(test.left, ast.Name)
            and test.left.id == "__name__"
        )
        self.check_sim_bypass(node)
        if is_main:
            self.main_depth += 1
        self.generic_visit(node)
        if is_main:
            self.main_depth -= 1

    def _visit_with(self, node: ast.With | ast.AsyncWith) -> None:
        bounded = False
        for item in node.items:
            expr = item.context_expr
            if isinstance(expr, ast.Call):
                self.with_managed.add(id(expr))
                if call_name(expr) in TIMEOUT_CONTEXTS:
                    bounded = True
                if self.resolve(expr.func).endswith("suppress") and any(
                    last_identifier(a) == "CancelledError" for a in expr.args
                ):
                    self.add(
                        "ASY-004",
                        node,
                        "medium",
                        "contextlib.suppress(CancelledError) swallows cancellation; "
                        "only acceptable when awaiting an already-cancelled task.",
                    )
        if bounded:
            self.timeout_depth += 1
        self.generic_visit(node)
        if bounded:
            self.timeout_depth -= 1

    def visit_With(self, node: ast.With) -> None:
        self._visit_with(node)

    def visit_AsyncWith(self, node: ast.AsyncWith) -> None:
        self._visit_with(node)

    # -- statements ------------------------------------------------------------------------

    def visit_Expr(self, node: ast.Expr) -> None:
        value = node.value
        if isinstance(value, ast.Call):
            resolved = self.resolve(value.func)
            receiver = (
                last_identifier(value.func.value) if isinstance(value.func, ast.Attribute) else ""
            )
            if resolved in {"asyncio.create_task", "asyncio.ensure_future"} or (
                call_name(value) == "create_task" and "loop" in receiver.lower()
            ):
                self.add(
                    "ASY-005",
                    node,
                    "high",
                    "Task result is discarded; keep a reference, log failures, cancel on shutdown.",
                )
        self.generic_visit(node)

    def visit_Assign(self, node: ast.Assign) -> None:
        for target in node.targets:
            if isinstance(target, ast.Name) and target.id.isupper():
                if "SETTLE" in target.id or "GRACE" in target.id:
                    self.add(
                        "PERF-004",
                        node,
                        "medium",
                        "Settle/grace constant suggests poll + settle instead of an event/future.",
                    )
        self.generic_visit(node)

    def visit_ExceptHandler(self, node: ast.ExceptHandler) -> None:
        names = exception_names(node)
        body = node.body
        reraises = has_raise(body)
        if "CancelledError" in names and not reraises:
            self.add(
                "ASY-004",
                node,
                "high",
                "CancelledError is caught and not re-raised; cancellation (and motion stop) is hidden.",
            )
        elif names & {"BaseException", "<bare>"} and not reraises:
            self.add(
                "ASY-004",
                node,
                "medium",
                "Bare/BaseException handler without re-raise also swallows CancelledError.",
            )
        if names & PLANNING_ERRORS and not reraises:
            self.add(
                "SAF-005",
                node,
                "medium",
                "Planning failure handled without re-raise; check for retry/alternative target "
                "instead of latching manual recovery.",
            )
        if "CancelledError" not in names:
            trivial = all(
                isinstance(s, (ast.Pass, ast.Continue))
                or (isinstance(s, ast.Expr) and isinstance(s.value, ast.Constant))
                for s in body
            )
            print_only = len(body) == 1 and (
                isinstance(body[0], ast.Expr)
                and isinstance(body[0].value, ast.Call)
                and call_name(body[0].value) == "print"
            )
            if trivial or print_only:
                self.add("ERR-001", node, "high", "Exception swallowed (pass/continue/print only).")
            elif names & {"Exception", "BaseException", "<bare>"} and not (
                reraises or has_log_call(body)
            ):
                self.add(
                    "ERR-001",
                    node,
                    "low",
                    "Broad except without raise or logging; check that the error is handled.",
                )
        self.generic_visit(node)

    # -- expressions -----------------------------------------------------------------------

    def visit_Await(self, node: ast.Await) -> None:
        value = node.value
        if isinstance(value, ast.Call) and isinstance(value.func, ast.Attribute):
            name = value.func.attr
            receiver = last_identifier(value.func.value)
            if receiver not in {"self", "cls"} and self.timeout_depth == 0:
                if name == "plan_and_execute" or (
                    name in MOTION_CALLS and self.looks_like_motion_call(value)
                ):
                    self.add(
                        "MOT-001",
                        node,
                        "high" if name == "plan_and_execute" else "medium",
                        f"`{name}` awaited without asyncio.timeout/wait_for; "
                        "the SDK has no timeout parameter.",
                    )
            if name == "stop" and not value.args and MOTION_RECEIVER_RE.search(receiver):
                self.add(
                    "SAF-003",
                    node,
                    "medium",
                    "MotionGroup.stop() is not functional in the current SDK; cancel the execute "
                    "task or use TrajectoryCursor.pause().",
                )
        self.generic_visit(node)

    def looks_like_motion_call(self, node: ast.Call) -> bool:
        keywords = {k.arg for k in node.keywords}
        if keywords & {"tcp", "actions", "joint_trajectory", "start_joint_position"}:
            return True
        return (call_name(node) == "plan" and len(node.args) >= 2) or len(node.args) >= 3

    def visit_Call(self, node: ast.Call) -> None:
        resolved = self.resolve(node.func)
        name = call_name(node)
        self.report.note_call(name, resolved, node, self)

        if name == "wait_for" and resolved.split(".")[0] in {"asyncio", "wait_for"}:
            self.timeout_depth += 1
            self.generic_visit(node)
            self.timeout_depth -= 1
            return

        self.check_blocking(node, resolved)
        self.check_sleep(node, resolved)
        self.check_io(node, name)
        self.check_tcp(node, name)
        self.check_literals(node, name, resolved)
        self.check_env(node, resolved)

        if name == "print" and isinstance(node.func, ast.Name) and self.main_depth == 0:
            self.add("OBS-001", node, "medium", "print() bypasses logging; use a logger.")
        if resolved == "os._exit" or (resolved == "sys.exit" and self.in_async):
            self.add("LIFE-007", node, "medium", f"{resolved} skips the ordered shutdown path.")
        if resolved in UNIT_CONVERSIONS and not self.config_file:
            self.add(
                "MOT-003",
                node,
                "low",
                "Unit conversion in job code; convert once at the boundary and suffix units.",
            )
        if (
            name == "Nova"
            and resolved in {"Nova", "nova.Nova", "nova.core.nova.Nova"}
            and id(node) not in self.with_managed
        ):
            self.add(
                "LIFE-004", node, "medium", "Nova() not used as `async with`; session may leak."
            )
        if name == "getattr" and len(node.args) >= 2:
            attr = node.args[1]
            if (
                isinstance(attr, ast.Constant)
                and isinstance(attr.value, str)
                and attr.value.startswith("_")
                and not attr.value.startswith("__")
            ):
                self.add(
                    "ERR-005", node, "medium", f"Private attribute access via getattr: {attr.value}"
                )
        self.generic_visit(node)

    def check_blocking(self, node: ast.Call, resolved: str) -> None:
        blocking = resolved in BLOCKING_CALLS or resolved.startswith("requests.")
        if blocking and self.in_async:
            self.add("ASY-001", node, "high", f"Blocking call `{resolved}` inside async def.")
        elif blocking and self.in_function and self.module_has_async:
            self.add(
                "ASY-001",
                node,
                "low",
                f"Blocking call `{resolved}` in a sync helper of an async module; "
                "check whether it is called from the event loop.",
            )
        if call_name(node) == "open" and isinstance(node.func, ast.Name):
            if self.in_async and self.loop_depth > 0:
                self.add(
                    "PERF-006", node, "medium", "Synchronous open() inside a loop in async code."
                )

    def check_sleep(self, node: ast.Call, resolved: str) -> None:
        if resolved not in SLEEP_CALLS or not node.args:
            return
        seconds = numeric_value(node.args[0])
        if self.while_depth > 0:
            self.add(
                "PERF-004",
                node,
                "low",
                "Sleep inside a while loop: polling. Prefer an event, future or push subscription.",
            )
        elif seconds is not None and seconds >= 0.1:
            self.add(
                "PERF-001",
                node,
                "medium",
                f"Fixed sleep of {seconds:g} s; wait on the actual condition with a timeout.",
            )

    def check_io(self, node: ast.Call, name: str) -> None:
        if name in IO_WAIT_CALLS and self.timeout_depth == 0:
            self.add(
                "IO-002",
                node,
                "high",
                f"`{name}` has no timeout parameter and is not wrapped in asyncio.timeout.",
            )
        if name in IO_KEY_CALLS and node.args:
            key = node.args[0]
            literal = isinstance(key, ast.Constant) and isinstance(key.value, str)
            if (
                literal
                and name in {"read", "write"}
                and not (
                    isinstance(node.func, ast.Attribute)
                    and "controller" in last_identifier(node.func.value).lower()
                )
            ):
                literal = False
            if literal and not self.config_file:
                self.add(
                    "IO-005",
                    node,
                    "low",
                    "IO signal name as string literal; reference a generated/config symbol.",
                )

    def check_tcp(self, node: ast.Call, name: str) -> None:
        tcp_nodes = [k.value for k in node.keywords if k.arg == "tcp"]
        if name in MOTION_CALLS and len(node.args) >= 2:
            tcp_nodes.append(node.args[1])
        for tcp in tcp_nodes:
            if not isinstance(tcp, ast.Constant) or self.config_file:
                continue
            if isinstance(tcp.value, int) or (
                isinstance(tcp.value, str) and tcp.value.strip().isdigit()
            ):
                self.add("MOT-002", tcp, "high", f"Numeric TCP literal {tcp.value!r}.")
            elif isinstance(tcp.value, str):
                self.add(
                    "MOT-002", tcp, "low", f"TCP literal {tcp.value!r}; reference it from config."
                )

    def check_literals(self, node: ast.Call, name: str, resolved: str) -> None:
        if name == "MotionSettings" and not self.config_file:
            numeric = [k.arg for k in node.keywords if numeric_value(k.value) is not None]
            if numeric:
                self.add(
                    "MOT-006",
                    node,
                    "medium",
                    f"Numeric MotionSettings literal ({', '.join(str(n) for n in numeric)}); "
                    "use named profiles.",
                )
        if name == "Pose" and node.args:
            values = self.literal_numbers(node.args[0])
            if values is not None and len(values) >= 3 and all(v != 0 for v in values[:3]):
                self.add(
                    "MOT-007",
                    node,
                    "low" if self.config_file else "medium",
                    "Absolute pose literal; load taught poses from a dataset or frame.",
                )
        if name in {"joint_ptp", "jnt"} and node.args:
            values = self.literal_numbers(node.args[0])
            if values is not None and len(values) >= 5:
                self.add(
                    "MOT-007",
                    node,
                    "low" if self.config_file else "medium",
                    "Literal joint target; load taught positions from a dataset.",
                )

    @staticmethod
    def literal_numbers(node: ast.AST) -> list[float] | None:
        if not isinstance(node, (ast.Tuple, ast.List)):
            return None
        values = [numeric_value(e) for e in node.elts]
        if any(v is None for v in values):
            return None
        return [v for v in values if v is not None]

    def check_env(self, node: ast.Call, resolved: str) -> None:
        if resolved not in ENV_CALLS or not node.args:
            return
        key = node.args[0]
        key_name = key.value if isinstance(key, ast.Constant) and isinstance(key.value, str) else ""
        default = node.args[1] if len(node.args) > 1 else None
        for k in node.keywords:
            if k.arg == "default":
                default = k.value
        if key_name and SIM_FLAG_RE.search(key_name):
            if isinstance(default, ast.Constant) and default.value in TRUTHY_DEFAULTS:
                self.add(
                    "SAF-010",
                    node,
                    "high",
                    f"Simulation flag {key_name} defaults to on; production must opt in.",
                )
        if not self.config_file:
            self.add(
                "CFG-002",
                node,
                "low",
                "Environment read outside the config module; parse config once, typed.",
            )

    def visit_Subscript(self, node: ast.Subscript) -> None:
        index = node.slice
        if isinstance(index, ast.Constant) and isinstance(index.value, int):
            value = node.value
            ident = last_identifier(value).lower()
            if (
                isinstance(value, ast.Await)
                and isinstance(value.value, ast.Call)
                and call_name(value.value) == "controller"
            ) or (
                not isinstance(value, ast.Await)
                and (ident.endswith("controller") or ident.endswith("ctrl"))
            ):
                self.add(
                    "MOT-009",
                    node,
                    "high",
                    "Motion group selected by index; use controller.motion_group(<id>).",
                )
            elif "tcp" in ident and not self.config_file:
                self.add("MOT-002", node, "high", "TCP chosen by list index.")
        if dotted(node.value) == "os.environ" and not self.config_file:
            self.add("CFG-002", node, "low", "Environment read outside the config module.")
        self.generic_visit(node)

    def visit_Constant(self, node: ast.Constant) -> None:
        if (
            isinstance(node.value, str)
            and SIGNAL_LITERAL_RE.match(node.value)
            and not self.config_file
        ):
            self.add(
                "IO-005",
                node,
                "low",
                f"Signal name literal {node.value!r}; reference a generated/config symbol.",
            )

    def visit_Attribute(self, node: ast.Attribute) -> None:
        attr = node.attr
        if (
            attr.startswith("_")
            and not attr.startswith("__")
            and attr not in PUBLIC_UNDERSCORE_ATTRS
        ):
            receiver = last_identifier(node.value)
            if receiver not in {"self", "cls", "super"}:
                if attr in SDK_PRIVATE_ATTRS:
                    self.add("ERR-005", node, "high", f"Private SDK attribute `{attr}`.")
                elif SDK_OBJECT_RE.search(receiver):
                    self.add(
                        "ERR-005", node, "medium", f"Private attribute `{attr}` on `{receiver}`."
                    )
        self.generic_visit(node)

    # -- definitions -----------------------------------------------------------------------

    def check_safety_stub(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> None:
        if not SAFETY_FUNC_RE.search(node.name):
            return
        body = list(node.body)
        if body and isinstance(body[0], ast.Expr) and isinstance(body[0].value, ast.Constant):
            body = body[1:]
        if (
            len(body) == 1
            and isinstance(body[0], ast.Return)
            and isinstance(body[0].value, ast.Constant)
            and body[0].value.value is True
        ):
            self.add(
                "SAF-012",
                node,
                "high",
                f"`{node.name}` unconditionally returns True; stubbed safety check.",
            )

    def check_program_decorator(self, node: ast.FunctionDef | ast.AsyncFunctionDef) -> None:
        for dec in node.decorator_list:
            target = dec.func if isinstance(dec, ast.Call) else dec
            resolved = self.resolve(target)
            if not (resolved == "nova.program" or resolved.endswith("nova.program.program")):
                continue
            program_id = node.name
            if isinstance(dec, ast.Call):
                for k in dec.keywords:
                    if (
                        k.arg == "id"
                        and isinstance(k.value, ast.Constant)
                        and isinstance(k.value.value, str)
                    ):
                        program_id = k.value.value
            self.report.programs[program_id].append((self.rel, self.kind, node.lineno, self))
            self.report.facts["nova_entry_points"].append(
                f"{self.rel.as_posix()}:{node.lineno} @nova.program id={program_id}"
            )

    def check_sim_bypass(self, node: ast.If) -> None:
        test = node.test
        if isinstance(test, ast.UnaryOp) and isinstance(test.op, ast.Not):
            test = test.operand
        if not isinstance(test, (ast.Name, ast.Attribute)):
            return
        ident = last_identifier(test)
        if not SIM_FLAG_RE.search(ident):
            return
        skips = any(isinstance(s, (ast.Return, ast.Continue, ast.Pass)) for s in node.body)
        if skips or BYPASS_FLAG_RE.search(ident):
            self.add(
                "SAF-010",
                node,
                "medium",
                f"Bypass gated by a single flag `{ident}`; require a per-job opt-in AND a "
                "global simulation flag, and log it at startup.",
            )

    # -- comments --------------------------------------------------------------------------

    def scan_comments(self, source: str) -> None:
        try:
            tokens = list(tokenize.generate_tokens(io.StringIO(source).readline))
        except (tokenize.TokenError, IndentationError, SyntaxError):
            return
        run: list[int] = []
        code_like = 0

        def flush() -> None:
            if len(run) >= 5 and code_like >= 3:
                line = run[0]
                self.report.add(
                    self.rel,
                    self.kind,
                    "STR-003",
                    line,
                    self.excerpt(line),
                    "medium",
                    f"{len(run)} consecutive commented-out lines that look like code.",
                )

        for tok in tokens:
            if tok.type != tokenize.COMMENT:
                continue
            line, text = tok.start[0], tok.string
            stripped = self.lines[line - 1].strip() if line <= len(self.lines) else ""
            if stripped.startswith("#"):
                if run and line == run[-1] + 1:
                    run.append(line)
                else:
                    flush()
                    run, code_like = [line], 0
                if COMMENTED_CODE_RE.match(text):
                    code_like += 1
            if TODO_RE.search(text) and not TODO_REF_RE.search(text):
                self.report.add(
                    self.rel,
                    self.kind,
                    "STR-003",
                    line,
                    self.excerpt(line),
                    "low",
                    "TODO/FIXME without owner or issue reference.",
                )
            if PAYLOAD_COMMENT_RE.search(text):
                self.report.payload_comments.append((self.rel, self.kind, line, self.excerpt(line)))
        flush()


class ProjectReport:
    def __init__(self, root: Path):
        self.root = root
        self.candidates: dict[tuple[str, str, int], Candidate] = {}
        self.programs: dict[str, list[tuple[Path, str, int, FileScanner]]] = defaultdict(list)
        self.payload_comments: list[tuple[Path, str, int, str]] = []
        self.first_motion_site: tuple[Path, str, int, str] | None = None
        self.files_scanned = 0
        self.skipped_generated: list[str] = []
        self.parse_errors: list[str] = []
        self.facts: dict = {
            "nova_entry_points": [],
            "queries_tcp_names": False,
            "uses_motion_group_by_id": False,
            "uses_payload": False,
            "uses_singularity_handling": False,
            "uses_path_triggers": False,
            "uses_trajectory_cursor": False,
            "uses_datasets": False,
            "uses_collision_free": False,
            "uses_cycle_events": False,
            "uses_signal_handlers": False,
            "uses_logging": False,
            "uses_controller_limits": False,
        }

    def add(self, rel, kind, rule, line, excerpt, confidence, message) -> None:
        key = (rule, rel.as_posix(), line)
        if key in self.candidates:
            return
        self.candidates[key] = Candidate(
            rule=rule,
            severity=SEVERITY[rule],
            confidence=confidence,
            file=rel.as_posix(),
            line=line,
            excerpt=excerpt,
            message=message,
            path_kind=kind,
        )

    def note_import(self, name: str) -> None:
        if name.split(".")[0] in {"logging", "loguru"} or name.startswith("nova.logging"):
            self.facts["uses_logging"] = True
        if name.endswith(("remote_dataset", "local_dataset")) or name.startswith("nova.datasets"):
            self.facts["uses_datasets"] = True

    def note_call(self, name: str, resolved: str, node: ast.Call, scanner: FileScanner) -> None:
        facts = self.facts
        keywords = {k.arg for k in node.keywords}
        if name in {"tcp_names", "tcps"}:
            facts["queries_tcp_names"] = True
        if name == "motion_group":
            facts["uses_motion_group_by_id"] = True
        if "payload_override" in keywords or name in {
            "payloads",
            "payload_names",
            "active_payload",
            "active_payload_name",
        }:
            facts["uses_payload"] = True
        if "singularity_handling" in keywords:
            facts["uses_singularity_handling"] = True
        if name in {"after_start", "before_target", "at_path_fraction"} or (
            name == "io_write" and "at" in keywords
        ):
            facts["uses_path_triggers"] = True
        if name == "TrajectoryCursor":
            facts["uses_trajectory_cursor"] = True
        if name in {"collision_free", "multi_collision_free"}:
            facts["uses_collision_free"] = True
        if name == "cycle":
            facts["uses_cycle_events"] = True
        if resolved in {"signal.signal"} or name == "add_signal_handler":
            facts["uses_signal_handlers"] = True
        if name == "get_description":
            facts["uses_controller_limits"] = True
        if name == "Novax":
            facts["nova_entry_points"].append(f"{scanner.rel.as_posix()}:{node.lineno} Novax()")
        if name in MOTION_CALLS and self.first_motion_site is None:
            self.first_motion_site = (
                scanner.rel,
                scanner.kind,
                node.lineno,
                scanner.excerpt(node.lineno),
            )

    def finish(self) -> None:
        for program_id, sites in self.programs.items():
            if len(sites) < 2:
                continue
            others = ", ".join(f"{rel.as_posix()}:{line}" for rel, _, line, _ in sites)
            for rel, kind, line, scanner in sites:
                self.add(
                    rel,
                    kind,
                    "STR-001",
                    line,
                    scanner.excerpt(line),
                    "high",
                    f"Duplicate @nova.program id {program_id!r} ({others}); "
                    "the registry silently keeps only the last one.",
                )
        if self.first_motion_site and not self.facts["queries_tcp_names"]:
            rel, kind, line, excerpt = self.first_motion_site
            self.add(
                rel,
                kind,
                "MOT-002",
                line,
                excerpt,
                "medium",
                "No startup TCP validation found (mg.tcp_names()/tcps()) anywhere in the project.",
            )
        if not self.facts["uses_payload"]:
            for rel, kind, line, excerpt in self.payload_comments:
                self.add(
                    rel,
                    kind,
                    "MOT-011",
                    line,
                    excerpt,
                    "low",
                    "Payload/mass mentioned in a comment but no payload API usage in the project.",
                )

    def to_json(self) -> dict:
        candidates = sorted(
            self.candidates.values(),
            key=lambda c: (SEVERITY_ORDER[c.severity], c.rule, c.file, c.line),
        )
        return {
            "skill": "nova-app-review",
            "scanner_version": SCANNER_VERSION,
            "root": str(self.root),
            "sdk_version": installed_sdk_version(),
            "files_scanned": self.files_scanned,
            "skipped_generated": self.skipped_generated,
            "parse_errors": self.parse_errors,
            "facts": self.facts,
            "candidates": [asdict(c) for c in candidates],
        }


def installed_sdk_version() -> str | None:
    try:
        from importlib.metadata import PackageNotFoundError, version
    except ImportError:
        return None
    try:
        return version("wandelbots-nova")
    except PackageNotFoundError:
        return None


def iter_python_files(root: Path):
    if root.is_file():
        if root.suffix == ".py":
            yield root
        return
    for path in sorted(root.rglob("*.py")):
        rel_parts = path.relative_to(root).parts
        if any(part in SKIP_DIRS or part.endswith(".egg-info") for part in rel_parts[:-1]):
            continue
        yield path


def scan(root: Path) -> dict:
    root = root.resolve()
    base = root.parent if root.is_file() else root
    report = ProjectReport(root)
    for path in iter_python_files(root):
        rel = path.relative_to(base)
        try:
            source = path.read_text(encoding="utf-8")
        except (OSError, UnicodeDecodeError) as e:
            report.parse_errors.append(f"{rel.as_posix()}: {e}")
            continue
        head = "\n".join(source.splitlines()[:5])
        if GENERATED_RE.search(head):
            report.skipped_generated.append(rel.as_posix())
            continue
        try:
            tree = ast.parse(source, filename=str(path))
        except SyntaxError as e:
            report.parse_errors.append(f"{rel.as_posix()}:{e.lineno}: {e.msg}")
            continue
        report.files_scanned += 1
        scanner = FileScanner(rel, source, report)
        scanner.visit(tree)
        scanner.scan_comments(source)
    report.finish()
    return report.to_json()


def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0] if __doc__ else None)
    parser.add_argument("roots", nargs="*", default=["."], help="App root(s) or files to scan.")
    args = parser.parse_args(argv)
    results = [scan(Path(r)) for r in args.roots]
    json.dump(results[0] if len(results) == 1 else results, sys.stdout, indent=2)
    sys.stdout.write("\n")
    return 0


if __name__ == "__main__":
    sys.exit(main())
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall