wandelbotsgmbh/wandelbots-nova / nova/agent_skills/nova-app-review
nova-app-review
VerifiedReview 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?'.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.5 KB |
| references/nova-sdk-mapping.md | markdown | 9.3 KB |
| references/reference-numbers.md | markdown | 1007 B |
| references/rules/async.md | markdown | 4.2 KB |
| references/rules/configuration.md | markdown | 1.5 KB |
| references/rules/devices.md | markdown | 3.0 KB |
| references/rules/errors.md | markdown | 2.5 KB |
| references/rules/io.md | markdown | 3.5 KB |
| references/rules/lifecycle.md | markdown | 3.2 KB |
| references/rules/motion.md | markdown | 6.8 KB |
| references/rules/observability.md | markdown | 1.6 KB |
| references/rules/performance.md | markdown | 4.8 KB |
| references/rules/safety.md | markdown | 9.6 KB |
| references/rules/structure.md | markdown | 1.3 KB |
| references/rules/testing.md | markdown | 1.0 KB |
| scripts/scan.py | script | 38.4 KB |
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())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |