@nolans01/agent-validator 0.1.0 → 0.2.0

package/README.md

@@ -23,6 +23,18 @@ Or as a dev dependency in your project:
 npm install --save-dev @nolans01/agent-validator
 ```
 
+A local install puts the `validator` binary in `node_modules/.bin`, which is not on
+your shell PATH. Invoke it through your package manager's runner:
+
+```bash
+npx validator doctor        # npm
+pnpm exec validator doctor  # pnpm
+yarn validator doctor       # yarn
+```
+
+The examples below use the bare `validator` command, which assumes the global
+install. With a local install, prefix them accordingly.
+
 ## External Tools
 
 agent-validator orchestrates external tools. Install the ones you need:
@@ -38,6 +50,7 @@ pip install lizard
 # Security
 pip install semgrep
 brew install gitleaks        # or: https://github.com/gitleaks/gitleaks
+gem install brakeman         # Rails-specific security checks
 
 # Architecture
 npm install -g madge jscpd knip
@@ -54,6 +67,67 @@ Check which tools are available:
 validator doctor
 ```
 
+## Docker
+
+To avoid installing anything into the project you want to analyze, use the image,
+which ships every external tool preinstalled:
+
+```bash
+docker build -t agent-validator .
+```
+
+Mount the project you want to analyze at `/workspace`:
+
+```bash
+docker run --rm -v "$PWD:/workspace" agent-validator doctor
+docker run --rm -v "$PWD:/workspace" agent-validator scan --gates complexity,security
+```
+
+On PowerShell the mount is written `-v "${PWD}:/workspace"`. The entrypoint is
+`validator`, so pass subcommands directly; the default is `scan`.
+
+### Gates that need the project's own dependencies
+
+`type_safety` (tsc), `architecture` (madge, knip) and `test_quality` (stryker)
+resolve imports through the analyzed project's `node_modules`. A `node_modules`
+directory installed on a Windows or macOS host is not reliably readable inside
+the Linux container — pnpm in particular relies on symlinks that do not survive
+the crossing. Shadow it with a container-local volume and install inside:
+
+```bash
+docker run --rm \
+  -v "$PWD:/workspace" -v /workspace/node_modules \
+  --entrypoint sh agent-validator \
+  -c "pnpm install --frozen-lockfile && validator scan"
+```
+
+Gates that only read source text work against a plain mount: `complexity`
+(lizard), `security` (semgrep, gitleaks) and duplication detection (jscpd).
+
+### Network access
+
+The `security` gate needs network access. semgrep resolves the `p/...` rule packs
+against semgrep.dev on every invocation and keeps no reusable offline cache, so
+running with `--network none` makes Semgrep fail and the security gate fail closed.
+Every other gate runs fully offline.
+
+### File ownership
+
+The image runs as uid 1000. Tools that write into the project — stryker's
+`reports/`, mutmut's cache — will produce files owned by that uid. If your host
+user differs, pass `--user "$(id -u):$(id -g)"`.
+
+### Ruby support
+
+The Rails image includes Ruby syntax checks, Brakeman, and Mutant. Mutant
+requires an explicit usage policy and a compatible project bundle; closed-source
+projects normally require a commercial licence. To include the Ruby tools in
+the general image:
+
+```bash
+docker build --build-arg INSTALL_RUBY_TOOLS=true -t agent-validator .
+```
+
 ## Quick Start
 
 ### CLI Usage
@@ -94,6 +168,32 @@ JSON output for CI:
 validator scan --format json
 ```
 
+Write a complete ANSI-free report to a file. Parent directories are created
+automatically and an existing file is replaced:
+
+```bash
+validator scan --output reports/review.txt
+validator scan --format json --output reports/review.json
+```
+
+Run a project-defined test entry point as a baseline instead of assuming a
+framework command:
+
+```bash
+validator dir app lib \
+  --gates test_quality \
+  --test-command ./rspec.sh \
+  --test-timeout 1200000 \
+  --output reports/test-quality.txt
+```
+
+The command runs from the analyzed project root. A non-zero exit becomes a
+blocker; a successful baseline without mutation testing produces `warn`, not a
+fabricated 100% mutation score. This supports repositories whose scripts build Docker images,
+start databases, or configure non-standard test libraries. If the script writes
+its own detailed logs, those remain the source for raw test output; `--output`
+stores the normalized validator report.
+
 Fail on warnings (default: fail on blockers only):
 
 ```bash
@@ -174,10 +274,13 @@ end
 - **Fail threshold**: score < 70 OR any blocker (CCN > 1.5× threshold)
 
 ### 3. Security Gate
-- **Tools**: `semgrep` (SAST), `gitleaks` (secret detection)
+- **Tools**: `semgrep` (SAST), `gitleaks` (secret detection), `brakeman` (Rails)
 - **Scoring**: -25 per blocker, -10 per warning, -3 per info
 - **Fail threshold**: score < 70 OR any blocker
 
+Gitleaks scans the complete checkout, including configuration, documentation,
+shell, YAML, and dotenv files; it is not restricted to source extensions.
+
 ### 4. Architecture Gate
 - **Tools**: `madge` (circular deps), `jscpd` (duplication), `knip` (dead code)
 - **Scoring**: -15 per blocker, -7 per warning, -3 per info
@@ -187,8 +290,20 @@ end
 - **TypeScript/JavaScript**: `stryker`
 - **Python**: `mutmut`
 - **Ruby**: `mutant`
+- **Custom project runner**: `--test-command`, for example `./rspec.sh`
 - **Scoring**: mutation score (% of killed mutants)
-- **Fail threshold**: score < 70
+- **Fail threshold**: the active profile's mutation threshold
+
+For Rails, `type_safety` first runs `ruby -c` on selected files and then runs
+`RAILS_ENV=test bundle exec rails zeitwerk:check` when Rails and Bundler are
+available. A missing runtime is reported as `skip`, and skipped gates make the
+overall result `warn` rather than a false `pass`.
+
+Mutant runs through `bundle exec`, includes both `app` and `lib`, loads the Rails
+environment, and requires `--mutant-usage opensource|commercial`. Timeouts,
+missing policy, empty output, and unparseable output fail closed.
+The project must declare compatible `mutant` and `mutant-rspec` gems in its
+`Gemfile`; a global installation is not considered bundle availability.
 
 ## Profiles