saferun-cli 0.0.2__py3-none-any.whl

saferun/doctor.py

@@ -0,0 +1,159 @@
+"""`saferun doctor`: read-only diagnostics with PASS / WARNING / FAIL per check. It changes nothing and installs nothing.
+
+Every verdict about an image, the analyzer or the OSV data comes from the same verification `saferun status` and every scan use
+(`setup.component_status`); doctor adds the surrounding facts (Python, OS, Docker state, cosign, directories) and a fix for each problem.
+A check that cannot be carried out is a FAIL or WARNING, never a PASS.
+Exit status: 0 = no FAIL (warnings allowed), 1 = at least one FAIL.
+"""
+from __future__ import annotations
+
+import json
+import os
+import platform
+import sys
+from dataclasses import dataclass
+from importlib import metadata
+from pathlib import Path
+
+from . import dockerdiag, hostos
+from . import setup as st
+from .engine import osvdb
+from .engine.model import clean_text
+from .sandbox import SandboxError
+from .sandbox import cosign_tool
+from .sandbox import images as im
+from .sandbox import signature as sig
+
+PASS, WARN, FAIL = "PASS", "WARNING", "FAIL"
+MIN_PYTHON = (3, 12)
+
+
+@dataclass(frozen=True)
+class Check:
+    name: str
+    level: str
+    detail: str
+    fix: str = ""
+
+    def to_dict(self) -> dict:
+        return {"name": self.name, "level": self.level, "detail": self.detail, "fix": self.fix}
+
+
+def _version() -> str:
+    from . import __version__
+    try:
+        installed = metadata.version("saferun-cli")
+    except metadata.PackageNotFoundError:
+        return f"{__version__} (not installed as a package)"
+    return installed if installed == __version__ else f"{__version__} (package metadata says {installed})"
+
+
+def check_install() -> Check:
+    p = Path(__file__).resolve().parent
+    return Check("SafeRun installation", PASS, f"version {_version()} at {p}")
+
+
+def check_python(v=None) -> Check:
+    v = v or sys.version_info
+    if tuple(v[:2]) >= MIN_PYTHON:
+        return Check("Python", PASS, f"{v[0]}.{v[1]}.{v[2]} ({platform.python_implementation()})")
+    return Check("Python", FAIL, f"{v[0]}.{v[1]} is too old", f"SafeRun needs Python {MIN_PYTHON[0]}.{MIN_PYTHON[1]} or newer")
+
+
+def check_os(system: str | None = None, machine: str | None = None) -> Check:
+    s = (system or platform.system()).lower()
+    m = machine or platform.machine()
+    if s in ("linux", "darwin", "windows"):
+        note = "" if s == "linux" else " (native Windows and macOS support is newer than Linux; see docs/platforms.md)"
+        return Check("Operating system", PASS, f"{platform.system()} {m}{note}")
+    return Check("Operating system", FAIL, f"{platform.system()} is not supported", "SafeRun supports Linux, macOS and Windows")
+
+
+def check_docker(d: dockerdiag.DockerDiagnosis) -> Check:
+    return Check("Docker", PASS if d.ok else FAIL, d.detail, "" if d.ok else d.guidance)
+
+
+def _from_status(name: str, s: st.Status, fix: str) -> Check:
+    level = {st.READY: PASS, st.OUTDATED: WARN}.get(s.state, FAIL)
+    return Check(name, level, clean_text(s.detail, 300) if s.detail else s.state, "" if level == PASS else fix)
+
+
+def check_cosign() -> Check:
+    managed = cosign_tool.managed_cosign()
+    if managed:
+        return Check("Cosign", PASS, f"SafeRun's pinned copy {cosign_tool.COSIGN_VERSION} (SHA-256 verified) at {managed}")
+    path = sig.find_cosign()
+    if path:
+        return Check("Cosign", PASS, f"found on PATH at {path} (not SafeRun's pinned copy)")
+    return Check("Cosign", WARN, "not installed yet; only needed to install the signed analyzer image", "run: saferun init --only analyzer (fetches a verified copy)")
+
+
+def check_directories() -> list[Check]:
+    out = []
+    base = hostos.user_data_base() / "saferun"
+    probe = base
+    while not probe.exists() and probe != probe.parent:
+        probe = probe.parent
+    ok = os.access(probe, os.W_OK)
+    out.append(Check("Data directory", PASS if ok else FAIL, f"{base} ({'exists' if base.exists() else 'will be created'}; writable: {ok})",
+                     "" if ok else f"make {probe} writable by your user"))
+    env = [k for k in ("SAFERUN_OSV_DB", "SAFERUN_ANALYZER_LOCK") if os.environ.get(k)]
+    if env:
+        out.append(Check("Configuration", PASS, "overridden by environment: " + ", ".join(f"{k}={os.environ[k]}" for k in env)))
+    else:
+        out.append(Check("Configuration", PASS, "defaults (no SAFERUN_* overrides)"))
+    return out
+
+
+def check_signature_online(*, verify=sig.verify_release_signature) -> Check:
+    rel = im.ANALYZER_RELEASE
+    if rel is None:
+        return Check("Analyzer release signature", WARN, "no published analyzer release is recorded; the analyzer is built locally")
+    try:
+        n = verify(rel)
+    except SandboxError as e:
+        return Check("Analyzer release signature", FAIL, clean_text(e, 300), "run: saferun init --only analyzer")
+    return Check("Analyzer release signature", PASS, f"{n} valid signature(s) for {rel.reference}")
+
+
+def run_checks(*, online: bool = False, status=st.component_status, diagnose=dockerdiag.diagnose) -> list[Check]:
+    """Run every check. Never raises: a broken probe becomes a FAIL."""
+    checks = [check_install(), check_python(), check_os()]
+    d = diagnose()
+    checks.append(check_docker(d))
+    for key, label in (("python", "Python sandbox image"), ("node", "Node.js sandbox image"), ("analyzer", "Analyzer image")):
+        if not d.ok:
+            checks.append(Check(label, FAIL, "cannot be verified while Docker is unusable", "fix Docker first"))
+        else:
+            checks.append(_from_status(label, status(key), f"run: saferun init --only {key}" + (" --repair" if key == "analyzer" else "")))
+    checks.append(check_cosign())
+    osv = _from_status("OSV database", status("osv-db"), "run: saferun osv-db update")
+    checks.append(osv)
+    checks.extend(check_directories())
+    if online:
+        try:
+            checks.append(check_signature_online())
+        except Exception as e:  # noqa: BLE001
+            checks.append(Check("Analyzer release signature", FAIL, f"{type(e).__name__}: {clean_text(e, 200)}"))
+    return checks
+
+
+def exit_code(checks: list[Check]) -> int:
+    return 1 if any(c.level == FAIL for c in checks) else 0
+
+
+def render_text(checks: list[Check]) -> str:
+    lines = []
+    for c in checks:
+        lines.append(f"[{c.level:<7}] {c.name}: {c.detail}")
+        if c.fix:
+            lines.append(f"{'':11}fix: {c.fix}")
+    n = {lvl: sum(1 for c in checks if c.level == lvl) for lvl in (PASS, WARN, FAIL)}
+    lines.append("")
+    lines.append(f"{n[PASS]} passed, {n[WARN]} warning(s), {n[FAIL]} failed" + (" - SafeRun is ready" if not n[FAIL] and not n[WARN] else
+                 " - SafeRun can run, but review the warnings" if not n[FAIL] else " - SafeRun is NOT ready; apply the fixes above"))
+    return "\n".join(lines)
+
+
+def render_json(checks: list[Check]) -> str:
+    return json.dumps({"schema_version": 1, "ok": exit_code(checks) == 0, "checks": [c.to_dict() for c in checks]}, indent=2, sort_keys=True)

saferun/engine/__init__.py

@@ -0,0 +1,7 @@
+"""SafeRun validation engine (Phase 2). See verdict.py for the verdict rules."""
+from .engine import ValidationOptions, validate_project
+from .model import (CheckResult, CheckStatus, Finding, PackageRef, Severity, ValidationReport, Verdict)
+from .verdict import compute_verdict
+
+__all__ = ["CheckResult", "CheckStatus", "Finding", "PackageRef", "Severity", "ValidationOptions",
+           "ValidationReport", "Verdict", "compute_verdict", "validate_project"]

saferun/engine/analyzer.py

@@ -0,0 +1,30 @@
+"""Run Semgrep and OSV-Scanner inside the verified analyzer container (Phase 5B). There is no host-side path.
+
+`analyzer_runner` has the `ToolRunner` shape the checks already use, but instead of starting a host process it:
+  1. verifies the analyzer image (lock-file ID, pinned tool and rules labels) and gets its immutable ID,
+  2. runs the argv through the Phase 1 sandbox *by that ID*: no network, read-only root, non-root, all capabilities dropped,
+     seccomp/no-new-privileges, memory/swap/CPU/pids/fd/file-size limits, private tmpfs, container-side kill deadline,
+  3. mounts only the sanitized project (read-only) and, for OSV, the vulnerability database directory (read-only).
+The host environment is deliberately not forwarded (`env` is ignored): no host credentials or proxy settings can reach a container.
+Any failure raises (`SandboxError` and subclasses); callers turn that into a non-clean check status. Nothing falls back to the host.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..sandbox import SandboxLimits, run_sandboxed
+from ..sandbox.analyzer import verify_analyzer_image
+from .tools import ToolRun
+
+# Larger than the syntax-check profile: Semgrep needs memory and a few worker processes. Still hard limits.
+ANALYZER_LIMITS = dict(memory_mb=1536, cpus=2.0, pids=256, tmpfs_mb=256, nofile=1024, fsize_mb=64, shm_mb=64)
+
+
+def analyzer_runner(argv: list[str], *, cwd: Path, env=None, timeout_s: float, max_output: int,
+                    mounts: tuple[tuple[Path, str], ...] = (), sandbox=run_sandboxed, verify=verify_analyzer_image) -> ToolRun:
+    image_id = verify()
+    limits = SandboxLimits(timeout_s=timeout_s, max_output_bytes=max_output, **ANALYZER_LIMITS)
+    res = sandbox(cwd, list(argv), limits, image=image_id, readonly_mounts=mounts)
+    killed = bool(res.timed_out or res.output_truncated)
+    return ToolRun(argv=list(argv), exit_code=None if killed else res.exit_code, stdout=res.stdout, stderr=res.stderr,
+                   timed_out=bool(res.timed_out), output_truncated=bool(res.output_truncated), duration_s=res.duration_s)

saferun/engine/context.py

@@ -0,0 +1,27 @@
+"""Shared inputs for checks."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable
+
+from ..sandbox import docker as _docker
+from ..sandbox import run_sandboxed
+from ..sandbox.analyzer import verify_analyzer_image
+from .analyzer import analyzer_runner
+from .tools import ToolRunner
+
+
+@dataclass
+class CheckContext:
+    project: Path                 # sanitized copy of the project (never the user's original directory)
+    home: Path                    # private scratch/HOME for analyzers
+    files: list[str]              # relative posix paths of every regular file in `project`
+    analyzer: ToolRunner = analyzer_runner   # Semgrep / OSV-Scanner run ONLY here (analyzer container); injectable for tests
+    analyzer_available: Callable[[], str] = verify_analyzer_image  # returns the verified image ID or raises SandboxError
+    sandbox: Callable = run_sandboxed                    # container runner; injectable for tests
+    image_available: Callable[[str], None] = _docker.check_available  # raises SandboxError if unusable
+    timeout_s: float = 120.0
+    max_output: int = 8 * 1024 * 1024
+    max_findings: int = 1000
+    options: dict = field(default_factory=dict)

saferun/engine/engine.py

@@ -0,0 +1,100 @@
+"""Validation engine: sanitized copy -> checks -> normalized report -> verdict."""
+from __future__ import annotations
+
+import os
+import tempfile
+from dataclasses import dataclass, replace
+from pathlib import Path
+
+from ..sandbox import SensitivePolicy, WorkspaceLimits
+from ..sandbox.workspace import create_workspace
+from . import node, osv, pysyntax, semgrep
+from .context import CheckContext
+from .model import CheckResult, CheckStatus, Finding, Severity, ValidationReport, clean_text
+from .verdict import compute_verdict
+
+WORKSPACE_CHECK = "workspace-sensitive-files"
+
+
+@dataclass(frozen=True)
+class ValidationOptions:
+    python_analysis: bool = True       # Semgrep
+    python_syntax: bool = True         # compile() in the sandbox
+    dependency_scan: bool = True
+    javascript_check: bool = True
+    tool_timeout_s: float = 120.0      # per external tool / sandbox run
+    osv_offline: bool = True           # kept for compatibility: OSV-Scanner always runs offline (no network) since Phase 5B
+    osv_db_dir: Path | None = None     # offline OSV database directory (default: saferun.engine.osvdb.default_dir())
+    osv_db_max_age_days: float = 30.0  # older (but valid) OSV data makes the dependency check INCOMPLETE, never clean
+    workspace_limits: WorkspaceLimits | None = None
+    sensitive_policy: SensitivePolicy | None = None
+
+
+def _list_files(root: Path) -> list[str]:
+    out = []
+    for dirpath, _dirs, names in os.walk(root, followlinks=False):
+        d = Path(dirpath).relative_to(root).as_posix()
+        out += [n if d == "." else f"{d}/{n}" for n in names]
+    return sorted(out)
+
+
+def _workspace_check(ws) -> CheckResult:
+    """Withheld credential-like files become findings; the content was never read by any analyzer."""
+    findings = []
+    for w in ws.withheld:
+        secret = w.reason.startswith(("private-key", "token:"))
+        findings.append(Finding(
+            check=WORKSPACE_CHECK, rule_id=f"withheld.{clean_text(w.reason, 60)}",
+            severity=Severity.HIGH if secret else Severity.LOW, category="workspace",
+            path=clean_text(w.path, 300),
+            message=("credential-like file found in the project; it was withheld from analysis and the sandbox"
+                     if secret else "file not readable by other users was withheld from analysis (not analysed)")))
+    return CheckResult(WORKSPACE_CHECK, CheckStatus.FINDINGS if findings else CheckStatus.PASSED, findings=findings,
+                       notes=["content of withheld files is never read by SafeRun analyzers"])
+
+
+def _guarded(name: str, fn, ctx: CheckContext) -> CheckResult:
+    """A crashing check is an ERROR result, never an absent (= clean) one."""
+    try:
+        return fn(ctx)
+    except Exception as e:  # noqa: BLE001 - any bug must surface as an operational error
+        return CheckResult(name, CheckStatus.ERROR, detail=clean_text(f"internal error: {type(e).__name__}: {e}"))
+
+
+def validate_project(project_dir, options: ValidationOptions | None = None, *, ctx_overrides: dict | None = None
+                     ) -> ValidationReport:
+    """Validate the project at `project_dir`. Raises SandboxError if a safe copy cannot be made (no verdict
+    is possible then). `ctx_overrides` replaces CheckContext fields (tool runner, sandbox runner) for tests."""
+    opts = options or ValidationOptions()
+    ws = create_workspace(Path(project_dir), opts.workspace_limits, opts.sensitive_policy)
+    try:
+        home = ws.root / "home"
+        home.mkdir(mode=0o700)
+        ctx = CheckContext(project=ws.project, home=home, files=_list_files(ws.project),
+                           timeout_s=opts.tool_timeout_s, options={"osv_offline": True, "osv_db_dir": opts.osv_db_dir,
+                                                   "osv_db_max_age_days": opts.osv_db_max_age_days})
+        if ctx_overrides:
+            ctx = replace(ctx, **ctx_overrides)
+        checks = [_workspace_check(ws)]
+        checks[0].analysis = False
+        for enabled, name, mod in ((opts.python_syntax, pysyntax.NAME, pysyntax),
+                                   (opts.python_analysis, semgrep.NAME, semgrep),
+                                   (opts.dependency_scan, osv.NAME, osv),
+                                   (opts.javascript_check, node.NAME, node)):
+            if enabled:
+                checks.append(_guarded(name, mod.run_check, ctx))
+            else:
+                checks.append(CheckResult(name, CheckStatus.SKIPPED, detail="disabled by options"))
+        partial = []
+        if ws.skipped:
+            partial.append(f"{len(ws.skipped)} entr(y/ies) skipped (symlinks, special files or external hard links)")
+        if ws.withheld:
+            partial.append(f"{len(ws.withheld)} sensitive file(s) withheld")
+        workspace = {"entries_scanned": ws.entries_scanned, "copied_files": ws.copied_files,
+                     "copied_dirs": ws.copied_dirs, "copied_bytes": ws.copied_bytes,
+                     "skipped": [{"path": clean_text(s.path, 300), "reason": s.reason} for s in ws.skipped],
+                     "withheld": [{"path": clean_text(w.path, 300), "reason": clean_text(w.reason, 60)} for w in ws.withheld]}
+        verdict, reasons, complete = compute_verdict(checks, "; ".join(partial))
+        return ValidationReport(verdict, reasons, complete, checks, workspace)
+    finally:
+        ws.cleanup()

saferun/engine/model.py

@@ -0,0 +1,146 @@
+"""Normalized result model for the validation engine.
+
+Two things are kept strictly apart:
+  * a *finding*   - something the analysis found in the project (a security signal), and
+  * a *check status* - whether the analysis itself ran to completion (an operational fact).
+A check that errored, timed out, was unavailable or was skipped has NO findings by definition, and that
+is never the same as a clean result: see `verdict.compute_verdict`.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from enum import Enum
+
+SCHEMA_VERSION = 1
+MAX_TEXT = 500
+
+
+class Severity(str, Enum):
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+    INFO = "info"
+    UNKNOWN = "unknown"  # the tool gave no usable severity; the verdict treats it as MEDIUM
+
+    @property
+    def rank(self) -> int:
+        return _RANK[self]
+
+
+_RANK = {Severity.CRITICAL: 5, Severity.HIGH: 4, Severity.MEDIUM: 3, Severity.UNKNOWN: 3,
+         Severity.LOW: 2, Severity.INFO: 1}
+
+
+class CheckStatus(str, Enum):
+    PASSED = "passed"                    # ran to completion, no findings
+    FINDINGS = "findings"                # ran to completion, findings reported
+    INCOMPLETE = "incomplete"            # ran, but not everything was analysed (partial results kept)
+    ERROR = "error"                      # tool failed / produced unusable output; nothing can be concluded
+    TIMEOUT = "timeout"                  # tool exceeded its time limit; nothing can be concluded
+    UNAVAILABLE = "unavailable"          # tool or runtime missing; the check did not run
+    SKIPPED = "skipped"                  # applicable, but deliberately not run (reason given)
+    NOT_APPLICABLE = "not_applicable"    # nothing for this check to look at (e.g. no JavaScript files)
+
+    @property
+    def completed(self) -> bool:
+        """The analysis ran to completion: its (lack of) findings is a real result."""
+        return self in (CheckStatus.PASSED, CheckStatus.FINDINGS)
+
+    @property
+    def operational_problem(self) -> bool:
+        """Something that should have been checked was not (fully) checked."""
+        return self in (CheckStatus.INCOMPLETE, CheckStatus.ERROR, CheckStatus.TIMEOUT,
+                        CheckStatus.UNAVAILABLE, CheckStatus.SKIPPED)
+
+
+class Verdict(str, Enum):
+    PASS = "PASS"
+    WARNING = "WARNING"
+    FAIL = "FAIL"
+
+
+_CTRL = re.compile(r"[\x00-\x08\x0b-\x1f\x7f-\x9f‪-‮⁦-⁩]")
+
+
+def clean_text(value, limit: int = MAX_TEXT) -> str:
+    """Tool output and project content are untrusted: drop control/escape/bidi characters, bound length."""
+    s = _CTRL.sub("?", str(value)).replace("\r", " ")
+    return s if len(s) <= limit else s[: limit - 1] + "…"
+
+
+@dataclass(frozen=True)
+class PackageRef:
+    name: str
+    version: str = ""
+    ecosystem: str = ""   # OSV ecosystem name, e.g. "PyPI", "npm"
+
+
+@dataclass(frozen=True)
+class Finding:
+    check: str                      # name of the check that produced it
+    rule_id: str                    # rule / vulnerability id
+    severity: Severity
+    message: str
+    category: str = "code"          # code | dependency | syntax | workspace
+    path: str | None = None         # relative, posix, sanitized; None when not file-specific
+    line: int | None = None
+    end_line: int | None = None
+    package: PackageRef | None = None
+    vulnerability_ids: tuple[str, ...] = ()   # primary id first, then aliases (CVE-..., GHSA-...)
+    fixed_versions: tuple[str, ...] = ()
+    cwe: tuple[str, ...] = ()
+
+    def to_dict(self) -> dict:
+        return {
+            "check": self.check, "rule_id": self.rule_id, "severity": self.severity.value,
+            "message": self.message, "category": self.category, "path": self.path,
+            "line": self.line, "end_line": self.end_line,
+            "package": None if self.package is None else vars(self.package).copy(),
+            "vulnerability_ids": list(self.vulnerability_ids),
+            "fixed_versions": list(self.fixed_versions), "cwe": list(self.cwe),
+        }
+
+
+@dataclass
+class CheckResult:
+    name: str
+    status: CheckStatus
+    findings: list[Finding] = field(default_factory=list)
+    detail: str = ""                # human-readable reason, always set for non-passing statuses
+    tool: str = ""                  # tool name and version when known
+    duration_s: float = 0.0
+    errors: list[str] = field(default_factory=list)   # operational problems (never security findings)
+    notes: list[str] = field(default_factory=list)    # coverage notes (what was / was not looked at)
+    truncated_findings: int = 0     # findings dropped because of the per-check cap
+    analysis: bool = True           # False for bookkeeping checks that must not count as 'something was validated'
+
+    def to_dict(self) -> dict:
+        return {
+            "name": self.name, "status": self.status.value, "detail": self.detail, "tool": self.tool,
+            "duration_s": round(self.duration_s, 3), "errors": list(self.errors), "notes": list(self.notes),
+            "truncated_findings": self.truncated_findings,
+            "findings": [f.to_dict() for f in self.findings],
+        }
+
+
+@dataclass
+class ValidationReport:
+    verdict: Verdict
+    reasons: list[str]              # why this verdict (one line each, ordered by importance)
+    complete: bool                  # every applicable check ran to completion on the whole project
+    checks: list[CheckResult]
+    workspace: dict = field(default_factory=dict)   # copy accounting (entries, skipped, withheld)
+    schema_version: int = SCHEMA_VERSION
+
+    @property
+    def findings(self) -> list[Finding]:
+        return [f for c in self.checks for f in c.findings]
+
+    def to_dict(self) -> dict:
+        return {
+            "schema_version": self.schema_version, "verdict": self.verdict.value, "reasons": list(self.reasons),
+            "complete": self.complete, "workspace": dict(self.workspace),
+            "checks": [c.to_dict() for c in self.checks],
+        }

saferun/engine/node.py

@@ -0,0 +1,145 @@
+"""JavaScript syntax validation: `node --check` for every .js/.mjs/.cjs file, INSIDE the sandbox.
+
+`node --check` only compiles a file, but the compiler still parses untrusted input, so it is not run on the
+host: one sandbox run (node:22-slim, same verified restrictions as everything else: no network, read-only,
+non-root, resource limits) executes a fixed driver script that walks /workspace and runs `node --check` on each
+file, printing one JSON line per file. Project code is never executed. node_modules/.git are not walked.
+
+Implemented: syntax validation. NOT implemented (deferred): npm install / dependency acquisition, test runners,
+Semgrep JavaScript rules, ESLint, TypeScript. npm *vulnerability scanning* is done from lockfiles (see osv.py).
+"""
+from __future__ import annotations
+
+import json
+import re
+import time
+
+from ..sandbox import SandboxError, SandboxLimits
+from ..sandbox.profiles import NODE
+from .context import CheckContext
+from .model import CheckResult, CheckStatus, Finding, Severity, clean_text
+
+NAME = "javascript-syntax"
+EXTS = (".js", ".mjs", ".cjs")
+MAX_FILES = 1000
+SKIP_DIRS = frozenset({"node_modules", ".git"})
+
+DRIVER = r"""
+const fs=require('fs'),cp=require('child_process'),path=require('path');
+const ROOT='/workspace',MAX=%d,SKIP=new Set(['node_modules','.git']);
+const out=o=>process.stdout.write(JSON.stringify(o)+'\n');
+const files=[];let truncated=false;
+(function walk(d,depth){
+  if(depth>32)return;
+  let ents;try{ents=fs.readdirSync(d,{withFileTypes:true});}catch(e){out({walk_error:path.relative(ROOT,d)});return;}
+  for(const e of ents){
+    if(e.isDirectory()){if(!SKIP.has(e.name))walk(path.join(d,e.name),depth+1);}
+    else if(e.isFile()&&/\.(js|mjs|cjs)$/.test(e.name)){if(files.length>=MAX)truncated=true;else files.push(path.join(d,e.name));}
+  }
+})(ROOT,0);
+files.sort();
+for(const f of files){
+  const r=cp.spawnSync(process.execPath,['--check',f],{encoding:'utf8',timeout:10000,maxBuffer:65536,env:{}});
+  out({file:path.relative(ROOT,f),status:r.status,signal:r.signal,failed:!!r.error,err:(r.stderr||'').slice(0,2000)});
+}
+out({done:true,count:files.length,truncated});
+""" % MAX_FILES
+
+
+def js_files(files: list[str]) -> list[str]:
+    return [f for f in files if f.endswith(EXTS) and not any(p in SKIP_DIRS for p in f.split("/")[:-1])]
+
+
+def build_command() -> list[str]:
+    return ["node", "-e", DRIVER]
+
+
+_LINE = re.compile(r":(\d+)\s*$")
+
+
+def _syntax_finding(file: str, err: str) -> Finding:
+    lines = [ln for ln in err.splitlines() if ln.strip()]
+    line = next((int(m.group(1)) for ln in lines[:3] if (m := _LINE.search(ln))), None)
+    msg = next((ln for ln in lines if re.match(r"^\w*Error\b", ln)), lines[0] if lines else "syntax error")
+    return Finding(check=NAME, rule_id="javascript.syntax-error", severity=Severity.MEDIUM,
+                   message=clean_text(msg, 300), category="syntax", path=clean_text(file, 300), line=line)
+
+
+def parse_output(text: str, expected: list[str]) -> tuple[list[Finding], list[str], int]:
+    """Return (findings, per-file operational problems, files checked). Raises ValueError if the driver's
+    output is malformed or incomplete (no 'done' marker), so a cut-off run cannot look clean."""
+    findings, problems, count, done = [], [], 0, None
+    known = set(expected)
+    for raw in text.splitlines():
+        if not raw.strip():
+            continue
+        try:
+            o = json.loads(raw)
+        except (json.JSONDecodeError, RecursionError):
+            raise ValueError("driver output is not valid JSON lines") from None
+        if not isinstance(o, dict):
+            raise ValueError("driver output line is not an object")
+        if "walk_error" in o:
+            problems.append(f"{clean_text(o['walk_error'], 200)}: directory could not be read")
+        elif o.get("done") is True:
+            done = o
+        elif isinstance(o.get("file"), str):
+            f = o["file"]
+            if f not in known:
+                raise ValueError("driver reported a file that was not in the project")
+            count += 1
+            if o.get("failed") or o.get("signal") or not isinstance(o.get("status"), int):
+                problems.append(f"{clean_text(f, 200)}: node --check could not complete")
+            elif o["status"] != 0:
+                findings.append(_syntax_finding(f, str(o.get("err", ""))))
+        else:
+            raise ValueError("unrecognised driver output line")
+    if done is None:
+        raise ValueError("driver output ended before its completion marker")
+    if done.get("count") != count:
+        raise ValueError("driver file count does not match its output")
+    if done.get("truncated"):
+        problems.append(f"more than {MAX_FILES} JavaScript files; the rest were not checked")
+    return findings, problems, count
+
+
+def run_check(ctx: CheckContext) -> CheckResult:
+    targets = js_files(ctx.files)
+    if not targets:
+        return CheckResult(NAME, CheckStatus.NOT_APPLICABLE, detail="no JavaScript files")
+    try:
+        ctx.image_available(NODE.image)
+    except SandboxError as e:
+        return CheckResult(NAME, CheckStatus.UNAVAILABLE, tool=f"node --check ({NODE.label})",
+                           detail=clean_text(f"sandbox or image unavailable: {e}"))
+    t0 = time.monotonic()
+    res = CheckResult(NAME, CheckStatus.ERROR, tool=f"node --check ({NODE.label}, sandboxed)")
+    try:
+        r = ctx.sandbox(ctx.project, build_command(), SandboxLimits(timeout_s=ctx.timeout_s, max_output_bytes=ctx.max_output),
+                        image=NODE.image)
+    except SandboxError as e:
+        res.detail = clean_text(f"sandbox refused or failed to run: {e}")
+        return res
+    finally:
+        res.duration_s = time.monotonic() - t0
+    if r.timed_out:
+        res.status, res.detail = CheckStatus.TIMEOUT, f"syntax check exceeded {ctx.timeout_s:g}s and was killed"
+        return res
+    if r.oom_killed or r.output_truncated or r.exit_code != 0:
+        res.detail = clean_text(f"sandboxed run failed (exit {r.exit_code}, oom={r.oom_killed}, "
+                                f"truncated={r.output_truncated}): {r.stderr.strip()[-200:]}")
+        return res
+    try:
+        findings, problems, count = parse_output(r.stdout, targets)
+    except ValueError as e:
+        res.detail = clean_text(f"driver output unusable: {e}")
+        return res
+    res.findings = findings[: ctx.max_findings]
+    res.truncated_findings = max(0, len(findings) - ctx.max_findings)
+    res.errors = problems
+    res.notes = [f"{count} JavaScript file(s) syntax-checked with node --check; no code executed"]
+    if problems:
+        res.status, res.detail = CheckStatus.INCOMPLETE, f"{len(problems)} problem(s): " + "; ".join(problems)[:300]
+    else:
+        res.status = CheckStatus.FINDINGS if findings else CheckStatus.PASSED
+    return res