@0xcraft/powershot 1.0.0

package/docs/architecture.md

@@ -0,0 +1,191 @@
+# Architecture
+
+PowerShot is a single-package review engine with a small CLI adapter. The package is
+split by runtime responsibility, not by hypothetical deployment boundaries: no module
+below is independently versioned or consumed.
+
+## System shape
+
+```mermaid
+flowchart LR
+    subgraph adapters["Delivery adapters"]
+      CLI["CLI commands"]
+      CI["CI workflows"]
+    end
+
+    subgraph engine["Review engine"]
+      SNAP["Target snapshot"]
+      GROUND["Ground<br/>parsers · types · symbols"]
+      PLAN["Selection plan<br/>per-file capabilities"]
+      VERIFY["Deterministic verifiers"]
+      BUNDLE["Review bundles"]
+      JUDGE["Optional judges"]
+      MANIFEST["Run manifest"]
+    end
+
+    subgraph outputs["Output adapters"]
+      TERM["Terminal"]
+      MD["Markdown"]
+      SARIF["SARIF"]
+      JSON["JSON · manifest"]
+      CQ["GitLab Code Quality"]
+    end
+
+    CLI --> SNAP
+    CI --> CLI
+    SNAP --> GROUND --> PLAN
+    PLAN --> VERIFY --> MANIFEST
+    PLAN -. when enabled .-> BUNDLE --> JUDGE --> MANIFEST
+    MANIFEST --> TERM
+    MANIFEST --> MD
+    MANIFEST --> SARIF
+    MANIFEST --> JSON
+    MANIFEST --> CQ
+
+    classDef adapter fill:#172033,stroke:#57a6ff,color:#f0f6fc,stroke-width:2px
+    classDef core fill:#241b20,stroke:#ff675c,color:#f0f6fc,stroke-width:2px
+    classDef output fill:#17251f,stroke:#4ac58b,color:#f0f6fc,stroke-width:2px
+    class CLI,CI adapter
+    class SNAP,GROUND,PLAN,VERIFY,BUNDLE,JUDGE,MANIFEST core
+    class TERM,MD,SARIF,JSON,CQ output
+```
+
+The dependency direction is inward. Delivery and report adapters depend on the review
+engine. The engine does not depend on a workflow provider or terminal layout.
+
+## Module boundaries
+
+| Module | Owns | Does not own |
+|---|---|---|
+| `src/cli/` | Argument parsing, command dispatch, report publication, exit mapping | Review algorithms |
+| `src/review.ts` | One review run and its stage orchestration | CLI parsing or presentation |
+| `src/ground.ts` | TypeScript project, parse trees, manifests, symbol index | Check selection |
+| `src/plan.ts` | File selection and per-file capability accounting | Finding generation |
+| `src/manifest.ts` | Completion state and the authoritative run record | Rendering |
+| `src/verifiers/` | Deterministic check implementations | Model calls |
+| `src/judges/` | Prompt data, bounded model loop, tool adapter | Git target selection |
+| `src/lang/` | Language-pack data and optional language oracles | Cross-run policy |
+| `src/report/` | Pure output adapters | Re-running or reinterpreting a review |
+| `src/bench.ts` | Historical and labelled evaluation | Production command dispatch |
+| `src/session.ts`, `src/cache.ts` | Reuse of completed judge work | Completion decisions |
+
+`src/cli.ts` contains only the executable boundary. It delegates to `src/cli/app.ts`,
+which routes a command to a deeper module. This keeps a new output format or maintenance
+command from increasing the dependency fan-out of the executable.
+
+### Import discipline
+
+Use `./` while the dependency is reachable without leaving the current directory. Use
+`#app/*.js` instead of `../` traversal. The alias is a native Node.js package import
+mapped to `dist`, so TypeScript, the built CLI, and the installed npm package share one
+resolution rule. Keep `node:*` for the standard library and package names for external
+dependencies. The self-test checks every TypeScript source recursively and rejects
+static, side-effect, dynamic, and CommonJS parent imports.
+
+## Runtime sequence
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User as Developer / CI
+    participant CLI as CLI adapter
+    participant Git as Target snapshot
+    participant Ground as Ground
+    participant Plan as Selection plan
+    participant Verify as Verifiers
+    participant Judge as Judges
+    participant Manifest as Run manifest
+    participant Report as Report adapters
+
+    User->>CLI: psh review
+    CLI->>Git: resolve range and target tree
+    Git->>Ground: changed files + base content
+    Ground->>Plan: parsers, types, references, manifests
+    Plan->>Verify: eligible file/check pairs
+    Verify-->>Manifest: findings + coverage
+    opt model judges enabled
+      Plan->>Judge: bounded related-file bundles
+      Judge-->>Manifest: judged findings + usage
+    end
+    Manifest->>Manifest: compute complete / partial / failed
+    Manifest->>Report: one result, many formats
+    Report-->>User: terminal, Markdown, SARIF, JSON
+```
+
+## Load-bearing invariants
+
+### One target tree
+
+A branch or commit review reads source from the target revision, not from whatever is
+currently present in the working directory. Grounding, verification, bundling, and
+positioning all receive the same tree.
+
+### Capabilities belong to files
+
+A run can contain a typed TypeScript file beside a Python file or a TypeScript file
+excluded from `tsconfig`. Capabilities therefore live on each selected file. A checker
+available somewhere in the run is not evidence that it inspected every file.
+
+### The manifest owns completion
+
+Findings alone cannot distinguish a clean review from an interrupted or unsupported
+one. `RunManifest` accounts for selected files, executed checks, judge units, failures,
+limits, and skips. Renderers and the CLI consume that state instead of deriving their
+own verdict.
+
+```mermaid
+stateDiagram-v2
+    [*] --> Selected
+    Selected --> Complete: every file and unit accounted for
+    Selected --> Partial: capability, budget, or cancellation gap
+    Selected --> Failed: required stage or file failed
+    Complete --> Exit0: no findings
+    Complete --> Exit1: findings
+    Partial --> Exit3
+    Failed --> Exit3
+```
+
+### One run, many reports
+
+`--report` fans one review result into multiple adapters. CI should never execute the
+review once for SARIF and again for Markdown: optional judges can answer differently,
+and duplicated runs waste both time and tokens.
+
+## Extension paths
+
+### Add a deterministic verifier
+
+1. Implement the `Verifier` contract in `src/verifiers/`.
+2. Declare its domain and required capabilities.
+3. Export one unique id from `src/verifiers/index.ts`.
+4. Add positive and negative cases to the self-check suite.
+5. Document the check in the README only after the oracle is exercised by tests.
+
+### Add a language pack
+
+Add grammar data and conventions in `src/lang/packs.ts`, then add a dedicated fixture
+to `src/langtest.ts`. Language packs run in separate processes so all grammars remain
+covered without sharing one unbounded WASM heap.
+
+### Add a report format
+
+Implement a pure function in `src/report/`, register it in `src/cli/reports.ts`, and
+test its consumer contract. A renderer receives findings and the manifest; it does not
+call the review engine.
+
+### Add a CLI command
+
+Place command behavior under `src/cli/` and add one dispatch line to `app.ts`. If the
+command needs review results, use the existing review command interface rather than
+importing individual verifiers into the executable.
+
+## Verification strategy
+
+- `npm run build` checks module contracts with strict TypeScript.
+- `npm test` runs core self-checks and every enabled language pack.
+- `npm run smoke` packs, installs, and exercises the public binary in a clean project.
+- `node dist/cli.js review --verify-only` reviews the working diff through PowerShot's
+  own deterministic pipeline.
+
+See [CI integration](ci.md) for the delivery contract and
+[CONTRIBUTING.md](../CONTRIBUTING.md) for the change workflow.

package/docs/assets/cli-preview.svg

@@ -0,0 +1,68 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="680" viewBox="0 0 1200 680" role="img" aria-labelledby="title desc">
+  <title id="title">PowerShot CLI reporting a swallowed error</title>
+  <desc id="desc">A deterministic PowerShot scan reports one proven high-severity finding in an empty catch block.</desc>
+  <defs>
+    <linearGradient id="canvas" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#080b12"/>
+      <stop offset="1" stop-color="#111827"/>
+    </linearGradient>
+    <filter id="shadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="18" stdDeviation="24" flood-color="#000000" flood-opacity="0.42"/>
+    </filter>
+    <style>
+      .mono { font-family: "SFMono-Regular", "Cascadia Code", "Liberation Mono", Consolas, monospace; }
+      .muted { fill: #778196; }
+      .body { fill: #d9e0ea; }
+      .bright { fill: #f6f8fb; }
+      .red { fill: #ff5a62; }
+      .gold { fill: #ffc857; }
+      .steel { fill: #7dd3fc; }
+      .green { fill: #61d095; }
+    </style>
+  </defs>
+
+  <rect width="1200" height="680" rx="28" fill="url(#canvas)"/>
+  <rect x="44" y="38" width="1112" height="604" rx="18" fill="#0c111b" stroke="#242d3c" filter="url(#shadow)"/>
+  <path d="M44 94H1156" stroke="#242d3c"/>
+  <circle cx="78" cy="66" r="7" fill="#ff5f57"/>
+  <circle cx="102" cy="66" r="7" fill="#febc2e"/>
+  <circle cx="126" cy="66" r="7" fill="#28c840"/>
+  <text x="600" y="72" text-anchor="middle" class="mono muted" font-size="16">powershot — deterministic review</text>
+
+  <g class="mono" font-size="18">
+    <text x="78" y="132" class="green">$</text>
+    <text x="102" y="132" class="bright">psh scan src/example.ts --verify-only</text>
+
+    <text x="78" y="178" class="muted">◇ ground</text>
+    <text x="200" y="178" class="body">1 file · 1 symbol</text>
+    <text x="78" y="208" class="muted">◇ verify</text>
+    <text x="200" y="208" class="body">1 check × 1 file · 0 tokens</text>
+
+    <text x="78" y="256" class="bright" font-weight="700">PowerShot</text>
+    <text x="196" y="256" class="muted">· scan src/example.ts</text>
+    <path d="M78 278H1122" stroke="#2b3444"/>
+
+    <text x="78" y="318" class="steel">src/example.ts</text>
+    <text x="78" y="360" class="gold" font-weight="700">▣ HIGH</text>
+    <text x="174" y="360" class="body">swallowed-error ·</text>
+    <text x="388" y="360" class="red">proven</text>
+
+    <text x="106" y="397" class="bright">Empty catch block — the failure is discarded and the caller is</text>
+    <text x="106" y="425" class="bright">told it succeeded</text>
+
+    <text x="106" y="470" class="muted">3 │</text>
+    <text x="164" y="470" class="body">return JSON.parse(input)</text>
+    <text x="78" y="500" class="red">❯</text>
+    <text x="106" y="500" class="muted">4 │</text>
+    <text x="164" y="500" class="bright">} catch {</text>
+    <text x="252" y="527" class="red">^</text>
+    <text x="106" y="550" class="muted">5 │</text>
+    <text x="164" y="550" class="body">}</text>
+    <text x="164" y="583" class="muted">╰ AST: catch body contains no statements</text>
+
+    <path d="M78 605H1122" stroke="#2b3444"/>
+    <text x="78" y="630" class="bright">1 finding</text>
+    <text x="204" y="630" class="gold">1 high</text>
+    <text x="290" y="630" class="muted">· 1 verified · 0 judged</text>
+  </g>
+</svg>

package/docs/ci.md

@@ -0,0 +1,151 @@
+# CI integration
+
+PowerShot has two CI surfaces:
+
+- the composite GitHub Action for the shortest GitHub setup;
+- the `psh` CLI for GitHub, GitLab, and any runner that can execute Node.js 24.
+
+Use the composite action for GitHub-native reporting or install the versioned npm
+package when the CLI needs to fit into another CI system.
+
+## Choose a policy first
+
+There are two independent decisions:
+
+1. Must the review complete? Usually yes. Exit `2` or `3` should always fail a gate.
+2. Do findings block the change? Set this per repository. Exit `1` is a complete
+   verdict with findings, not an engine failure.
+
+| Exit | Meaning | Recommended CI handling |
+|---:|---|---|
+| `0` | Complete, no findings | Pass |
+| `1` | Complete, findings reported | Pass or fail according to repository policy |
+| `2` | Invalid command or Git input | Fail |
+| `3` | Partial or failed review | Fail |
+| `130` | Interrupted | Fail or retry |
+
+## GitHub Action
+
+The action runs one review, adds a job summary, uploads SARIF, and can maintain one
+pull-request comment.
+
+```yaml
+name: PowerShot
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  pull-requests: write
+  security-events: write
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - uses: xcrft/powershot@v1
+        with:
+          verify-only: 'true'
+          comment: 'true'
+          fail-on-findings: 'true'
+```
+
+The major tag follows compatible `1.x` releases. Pin a full commit SHA in a protected
+required workflow when immutable dependencies are required. The copy-paste version
+lives at [`examples/github-actions/action.yml`](../examples/github-actions/action.yml).
+
+### Action inputs
+
+| Input | Default | Purpose |
+|---|---|---|
+| `verify-only` | `true` | Run deterministic checks without a model |
+| `anthropic-api-key` | empty | Enable configured model judges |
+| `min-severity` | `low` | Filter findings below a severity |
+| `checks` | empty | Select comma-separated check ids |
+| `comment` | `true` | Maintain a pull-request comment |
+| `fail-on-findings` | `false` | Turn a complete finding verdict into a failed job |
+| `approve` | `false` | Approve only a complete, clean review |
+
+The outputs are `findings` and `complete`. `complete` is the important one when a
+later job decides whether to publish or deploy.
+
+## Direct CLI on GitHub Actions
+
+Use the CLI when the workflow needs custom artifact handling or when PowerShot is one
+step inside a larger quality job. The complete example is
+[`examples/github-actions/cli.yml`](../examples/github-actions/cli.yml).
+
+The core pattern is:
+
+```bash
+npm install --global --ignore-scripts @0xcraft/powershot@1.0.0
+
+STATUS=0
+psh review --verify-only \
+  --from "$BASE" --to HEAD \
+  --report sarif=powershot.sarif \
+  --report markdown=powershot.md \
+  --format compact || STATUS=$?
+
+case "$STATUS" in
+  0) exit 0 ;;
+  1) exit 1 ;; # change to 0 when findings are advisory
+  *) exit "$STATUS" ;;
+esac
+```
+
+Do not pipe the review directly into another command without preserving its exit code.
+Do not run once per report: repeated `--report` flags create all artifacts from the
+same verdict.
+
+## GitLab Code Quality
+
+The CLI's `codequality` format is accepted by GitLab's Code Quality report. Use a full
+clone or fetch both merge-request SHAs, then preserve the CLI status separately from
+the redirected report:
+
+```bash
+STATUS=0
+node "$POWERSHOT/dist/cli.js" review --verify-only \
+  --from "$CI_MERGE_REQUEST_DIFF_BASE_SHA" \
+  --to "$CI_COMMIT_SHA" \
+  --format codequality > gl-code-quality-report.json || STATUS=$?
+
+test "$STATUS" -le 1 || exit "$STATUS"
+test "$STATUS" -eq 0
+```
+
+See [`examples/gitlab/.gitlab-ci.yml`](../examples/gitlab/.gitlab-ci.yml) for the job
+and artifact declaration.
+
+## CI checklist
+
+- Use Node.js 24 or newer.
+- Fetch enough Git history for both endpoints of the review range.
+- Use immutable base and head SHAs where the CI provider exposes them.
+- Run `--verify-only` as the fast required check; add model judges only where their
+  cost and latency are intentional.
+- Treat exit `2`, `3`, and `130` as infrastructure or completeness failures.
+- Generate every report from one invocation.
+- Publish the Markdown report for humans and SARIF or Code Quality for annotations.
+- Pin the PowerShot source version in protected workflows.
+- Keep `powershot.config.json` in review so policy changes are visible.
+
+## Local parity
+
+Run the same deterministic gate before pushing:
+
+```bash
+node dist/cli.js review --verify-only --from main --to HEAD
+```
+
+For an uncommitted workspace, omit the range:
+
+```bash
+node dist/cli.js review --verify-only
+```

package/examples/github-actions/action.yml

@@ -0,0 +1,23 @@
+name: PowerShot
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  pull-requests: write
+  security-events: write
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - uses: xcrft/powershot@v1
+        with:
+          verify-only: 'true'
+          comment: 'true'
+          fail-on-findings: 'true'

package/examples/github-actions/cli.yml

@@ -0,0 +1,43 @@
+name: PowerShot CLI
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '24'
+
+      - name: Install PowerShot
+        run: npm install --global --ignore-scripts @0xcraft/powershot@1.0.0
+
+      - name: Review pull request
+        env:
+          BASE: origin/${{ github.base_ref }}
+        run: |
+          STATUS=0
+          psh review --verify-only \
+            --from "$BASE" --to HEAD \
+            --report markdown=powershot.md \
+            --report sarif=powershot.sarif \
+            --format compact || STATUS=$?
+          if [ -f powershot.md ]; then
+            cat powershot.md >> "$GITHUB_STEP_SUMMARY"
+          else
+            echo "PowerShot produced no Markdown report. Exit: $STATUS." >> "$GITHUB_STEP_SUMMARY"
+          fi
+          case "$STATUS" in
+            0) exit 0 ;;
+            1) exit 1 ;;
+            *) exit "$STATUS" ;;
+          esac

package/examples/gitlab/.gitlab-ci.yml

@@ -0,0 +1,21 @@
+powershot:
+  image: node:24
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+  variables:
+    GIT_DEPTH: "0"
+  before_script:
+    - npm install --global --ignore-scripts @0xcraft/powershot@1.0.0
+  script:
+    - |
+      STATUS=0
+      psh review --verify-only \
+        --from "$CI_MERGE_REQUEST_DIFF_BASE_SHA" \
+        --to "$CI_COMMIT_SHA" \
+        --format codequality > gl-code-quality-report.json || STATUS=$?
+      test "$STATUS" -le 1 || exit "$STATUS"
+      test "$STATUS" -eq 0
+  artifacts:
+    when: always
+    reports:
+      codequality: gl-code-quality-report.json

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@0xcraft/powershot",
+  "version": "1.0.0",
+  "description": "Oracle-first code review for machine-written code, with deterministic verification and CI-ready reports.",
+  "license": "Apache-2.0",
+  "author": "aglumova <alina.glumova@gmail.com>",
+  "keywords": [
+    "ai",
+    "ci",
+    "cli",
+    "code-review",
+    "developer-tools",
+    "github-actions",
+    "static-analysis",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xcrft/powershot.git"
+  },
+  "homepage": "https://github.com/xcrft/powershot#readme",
+  "bugs": {
+    "url": "https://github.com/xcrft/powershot/issues"
+  },
+  "type": "module",
+  "imports": {
+    "#app/*.js": "./dist/*.js"
+  },
+  "bin": {
+    "powershot": "dist/cli.js",
+    "psh": "dist/cli.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "files": [
+    "dist/**/*.js",
+    "docs/**/*.md",
+    "docs/assets/*",
+    "examples/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "npm run build && node dist/selftest.js && node dist/langtest.js",
+    "psh": "npm run build && node dist/cli.js",
+    "prepack": "npm run clean && npm run build && npm test",
+    "smoke": "node dist/package-smoke.js"
+  },
+  "dependencies": {
+    "ts-morph": "^23.0.0",
+    "web-tree-sitter": "0.22.6",
+    "tree-sitter-wasms": "0.1.13"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.5.0"
+  }
+}