@0xcraft/powershot 1.1.1 → 1.1.2

package/docs/architecture.md

@@ -64,7 +64,7 @@ engine. The engine does not depend on a workflow provider or terminal layout.
 | `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/lang/` | Language-pack data, isolated parser workers, 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 |
@@ -107,7 +107,7 @@ sequenceDiagram
       Plan->>Judge: bounded related-file bundles
       Judge-->>Manifest: judged findings + usage
     end
-    Manifest->>Manifest: compute complete / partial / failed
+    Manifest->>Manifest: compute full or portable completion / partial / failed
     Manifest->>Report: one result, many formats
     Report-->>User: terminal, Markdown, SARIF, JSON
 ```
@@ -126,6 +126,12 @@ A run can contain a typed TypeScript file beside a Python file or a TypeScript f
 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 policy decides what an absent capability means. Under default `portable` coverage,
+self-contained syntax and manifest oracles remain a complete verdict while unavailable
+`types`, `references`, and `python-types` are recorded as optional depth. Under
+`strict` coverage, or when a check is named explicitly, the same gap is required and
+makes the review partial.
+
 ### Monorepo grounding follows the change
 
 For each changed TypeScript or JavaScript file, grounding inspects only its ancestor
@@ -140,21 +146,40 @@ exists, only changed files are parsed and type-dependent capabilities remain abs
 That keeps a configless or mixed-language monorepo proportional to the review rather
 than to the repository.
 
+Python dependency grounding follows the same rule. Local modules are discovered from
+direct entries on each changed file's ancestor chain and conventional `src`, `lib`, or
+`python` roots. It never recursively crawls an unrelated monorepo tree.
+
+### Grammar memory is isolated by language
+
+Tree-sitter WASM compilation outlives its JavaScript parser objects. Keeping every
+declared grammar in one process pushed measured RSS past 690MB. Production parsing
+therefore groups changed files by language, sends at most 128 files or 8MB of source to
+one disposable worker, hydrates plain AST data in the parent, and terminates the worker.
+Compiled-grammar memory is bounded by one language batch rather than by the
+repository's language count; hydrated AST data remains proportional to the selected
+diff, not the whole repository. A parser failure for a declared language fails
+selection instead of quietly waiving the 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.
+one. `RunManifest` accounts for selected files, executed and unavailable checks, judge
+units, failures, limits, and skips. `state` answers whether required work completed;
+`coverage` separately says `full` or `portable`. Renderers and the CLI consume that
+record 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 --> Full: every file, unit, and enriched oracle accounted for
+    Selected --> Portable: required work complete; enriched gaps named
+    Selected --> Partial: required oracle, budget, or cancellation gap
     Selected --> Failed: required stage or file failed
-    Complete --> Exit0: no findings
-    Complete --> Exit1: findings
+    Full --> Exit0: no findings
+    Full --> Exit1: findings
+    Portable --> Exit0: no findings
+    Portable --> Exit1: findings
     Partial --> Exit3
     Failed --> Exit3
 ```
@@ -178,8 +203,9 @@ and duplicated runs waste both time and tokens.
 ### 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.
+to `src/langtest.ts` and include it in the all-languages review regression. Development
+fixtures and production parsing both isolate grammars by process, so no supported pack
+shares one unbounded WASM heap with the rest.
 
 ### Add a report format
 

package/docs/ci.md

@@ -16,6 +16,11 @@ There are two independent decisions:
 2. Do findings block the change? Set this per repository. Exit `1` is a complete
    verdict with findings, not an engine failure.
 
+A completed verdict has a separate coverage level. `full` means every applicable
+configured oracle ran. `portable` means every self-contained oracle ran while missing
+compiler/reference depth was named. Set `"coverage": "strict"` in
+`powershot.config.json` when portable depth must become exit `3` instead.
+
 | Exit | Meaning | Recommended CI handling |
 |---:|---|---|
 | `0` | Complete, no findings | Pass |
@@ -49,8 +54,6 @@ jobs:
         with:
           fetch-depth: 0
 
-      - run: npm ci --ignore-scripts
-
       - uses: xcrft/powershot@v1
         with:
           verify-only: 'true'
@@ -60,12 +63,16 @@ jobs:
           fail-on-findings: 'true'
 ```
 
-Type-aware checks use the checked-out project's declarations, so install its
-dependencies before PowerShot. Lifecycle scripts are disabled here because pull
-request code is untrusted; use the equivalent safe install for another package
-manager. For a monorepo without a root install, repeat the safe install step with the
-relevant package `working-directory`. PowerShot finds nested `tsconfig.json` and
-`tsconfig.*.json` files automatically; the workflow does not need to list projects.
+Portable coverage deliberately needs no repository install. This keeps fork and
+private-monorepo pull requests free of registry credentials while still running each
+declared language's syntax-backed oracles. When a trusted job already has dependencies,
+PowerShot uses the available declarations and can reach `full` coverage. Do not pass a
+private package token into a pull-request job merely to enrich review depth.
+
+PowerShot finds nested `tsconfig.json` and `tsconfig.*.json` files along changed-file
+ancestor chains; the workflow does not list projects. Python local-module discovery is
+bounded the same way. Foreign-language grammars run in disposable per-language workers
+and bounded batches, so all declared languages can coexist in one monorepo review.
 
 Set `upload-sarif: 'false'` and omit `security-events: write` when GitHub code scanning
 is unavailable or the workflow should not publish SARIF.
@@ -94,10 +101,10 @@ lives at [`examples/github-actions/action.yml`](../examples/github-actions/actio
 | `comment` | `true` | Maintain a pull-request comment |
 | `inline-comments` | `false` | Post up to ten proven verified findings as one inline review |
 | `fail-on-findings` | `false` | Turn a complete finding verdict into a failed job |
-| `approve` | `false` | Approve only a complete, clean review |
+| `approve` | `false` | Approve only a complete, clean, full-coverage review |
 
-The outputs are `findings` and `complete`. `complete` is the important one when a
-later job decides whether to publish or deploy.
+The outputs are `findings`, `complete`, and `coverage`. Gate infrastructure on
+`complete`; use `coverage == 'full'` for decisions that require semantic depth.
 
 ## Direct CLI on GitHub Actions
 
@@ -108,7 +115,7 @@ step inside a larger quality job. The complete example is
 The core pattern is:
 
 ```bash
-npm install --global --ignore-scripts @0xcraft/powershot@1.1.1
+npm install --global --ignore-scripts @0xcraft/powershot@1.1.2
 
 STATUS=0
 psh review --verify-only \
@@ -156,6 +163,7 @@ and artifact declaration.
 - 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.
+- Read the manifest or Action `coverage` output before treating portable depth as full.
 - 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.

package/examples/github-actions/action.yml

@@ -16,11 +16,6 @@ jobs:
         with:
           fetch-depth: 0
 
-      # Type-aware checks need the repository's declared types. Keep lifecycle
-      # scripts disabled when pull-request code is not trusted. In a monorepo,
-      # install at the workspace root or set working-directory to the package root.
-      - run: npm ci --ignore-scripts
-
       - uses: xcrft/powershot@v1
         with:
           verify-only: 'true'

package/examples/github-actions/cli.yml

@@ -19,7 +19,7 @@ jobs:
           node-version: '24'
 
       - name: Install PowerShot
-        run: npm install --global --ignore-scripts @0xcraft/powershot@1.1.1
+        run: npm install --global --ignore-scripts @0xcraft/powershot@1.1.2
 
       - name: Review pull request
         env:

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

@@ -5,7 +5,7 @@ powershot:
   variables:
     GIT_DEPTH: "0"
   before_script:
-    - npm install --global --ignore-scripts @0xcraft/powershot@1.1.1
+    - npm install --global --ignore-scripts @0xcraft/powershot@1.1.2
   script:
     - |
       STATUS=0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@0xcraft/powershot",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "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>",