feat(ops): a sourceable wrapper so docker is nobody's problem

source ops/shell/ousast.sh     # bash / zsh
    . ops\shell\ousast.ps1         # powershell

    ousast scan .
    ousast scan src/api

The container becomes an implementation detail. The engine is a JVM and ~2 GB
of Joern, and a contributor evaluating this tool should not have to install
either to try it -- what they get is a command.

Path rewriting is what makes it feel local: arguments under the working
directory are mapped to their mounted equivalents, so `src/api` means what the
user expects. Anything outside the mount is passed through unchanged WITH A
WARNING rather than silently rewritten into a path the container cannot see --
a wrong path that looks like it worked is worse than one that complains.

A native install wins when it is present. Someone who installed Joern
deliberately should not be quietly routed through a container, so the wrapper
uses a local joern-parse and venv when both exist; OUSAST_PREFER_NATIVE=0
forces the container. Verified end to end from an unrelated directory.

The image builds itself on first use and says why it is pausing. A first run
that prints a wall of build output and then works is worse than one that
explains itself.

Defaults stay conservative: the working directory mounts READ-ONLY, findings go
to ./.ousast as the only writable mount, and the network is off unless
`ousast-with-judge` asks for it.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_01T7XD7x5KonMdmGRkp63EQG

docker-compose.yml

@@ -15,8 +15,8 @@ services:
         JOERN_VERSION: ${JOERN_VERSION:-v4.0.623}
     image: openultrasast:${OUSAST_VERSION:-dev}
     volumes:
-      - ${TARGET:-.}:/target:ro          # the repository under analysis, read-only
-      - ./reports:/reports               # where findings land, the one writable mount
+      - ${TARGET:-.}:/target:ro                       # the repository under analysis, read-only
+      - ${OUSAST_REPORTS:-./reports}:/reports          # where findings land, the one writable mount
     working_dir: /work
     tmpfs:
       # CPG construction is scratch-heavy and none of it should outlive the run or touch the host.