@orygn/opa-mcp 0.1.11 → 0.1.12

package/CHANGELOG.md

@@ -17,6 +17,72 @@ not part of the public surface and may change in minor releases.
 
 ## [Unreleased]
 
+## [0.1.12] - 2026-05-25
+
+### Added
+
+- **`rego_verify` (49 tools total)** -- formal SMT-based verification for Rego
+  policies using Microsoft Z3 (WASM). Unlike testing, which checks specific
+  inputs, `rego_verify` examines ALL possible inputs mathematically and either
+  proves a property holds or returns a concrete counterexample. Three property
+  kinds are supported: `always_true` (prove a rule is true for every input),
+  `never_true` (prove a rule never fires), and `satisfiable` (find at least one
+  satisfying input as a witness). Supports equality and inequality operators,
+  string built-ins (`startswith`, `endswith`, `contains`, `regex.match`),
+  comparison operators (`<`, `<=`, `>`, `>=`), multi-clause rules (OR
+  semantics), cross-rule inlining (depth <= 5, cycle-safe), and mixed-type
+  input paths. Reports `INCONCLUSIVE` for negation-as-failure (`not`),
+  comprehensions, and other constructs that cannot be encoded in Z3.
+  Counterexamples are returned as nested JSON ready for use with `opa eval
+  --input`. Powered by a layered pipeline: OPA AST walker (IR), Z3 type
+  inferencer, and SMT encoder.
+
+### Fixed
+
+- **Transitive local variable chains in type inferencer.** Sort inference
+  previously stopped after one level of indirection (`x := input.user.role`
+  was resolved, but `y := x; y == "admin"` was not). The inferencer now
+  follows chains of arbitrary depth with a cycle guard, so intermediate
+  local variables are correctly typed regardless of how many assignments
+  separate them from an `input.*` path.
+
+- **Multi-expression helper rule inlining.** Helper rules with multiple body
+  expressions (e.g. `is_adult { x := input.age; x >= 18 }`) previously only
+  inlined the first expression. The walker now flattens all body expressions
+  into the caller clause as AND conjuncts, matching OPA's actual evaluation
+  semantics. Inlining also correctly handles per-expression negation-as-failure
+  and `with` modifiers inside the helper body.
+
+- **`.*` regex patterns always encode as true.** `regex.match(".*", x)` and
+  equivalent anchored forms (`^.*$`, `^.*`, `.*$`) previously created an
+  unsatisfiable or redundant Z3 string constraint. They now short-circuit to
+  `Bool.val(true)` since any string matches the pattern.
+
+- **`unsatisfiable` verdict for dead-code rules.** When verifying a
+  `satisfiable` property and Z3 returns UNSAT, the tool now returns
+  `verdict: "unsatisfiable"` with a clear message indicating the rule is dead
+  code or has contradictory conditions. Previously this case fell through as a
+  generic inconclusive result.
+
+- **Default-only rule verdicts.** Rules with only a `default` clause (e.g.
+  `default allow = false`) previously returned `INCONCLUSIVE` because the
+  solver found no non-default clauses to encode. The engine now detects this
+  case and returns the correct verdict directly -- `PROVEN`, `COUNTEREXAMPLE`,
+  `SATISFIABLE`, or `UNSATISFIABLE` -- without invoking Z3, using an empty
+  `{}` witness where applicable.
+
+- **Unsupported construct attribution scoped to target rule.** The
+  `unsupportedConstructs` field in the result previously listed constructs from
+  any rule in the module, including unrelated rules that were never evaluated.
+  It is now filtered to only constructs that appear in the target rule's own
+  clause expressions.
+
+- **Per-call Z3 variable namespacing.** All Z3 constant names are now prefixed
+  with a monotonically increasing call ID (`v0_`, `v1_`, ...). This prevents
+  sort-redeclaration errors when the same input path is inferred as different
+  sorts across successive calls (e.g. one policy uses `input.x` as a string,
+  the next uses it as an int) within the shared Z3 WASM singleton context.
+
 ## [0.1.11] - 2026-05-24
 
 ### Added
@@ -623,7 +689,8 @@ wrappers end-to-end. CI matrix: Ubuntu, macOS, and Windows on Node
 20 and 22, plus CodeQL security scanning and weekly Dependabot updates
 for npm, GitHub Actions, and Docker base images.
 
-[Unreleased]: https://github.com/OrygnsCode/opa-mcp-server/compare/v0.1.11...HEAD
+[Unreleased]: https://github.com/OrygnsCode/opa-mcp-server/compare/v0.1.12...HEAD
+[0.1.12]: https://github.com/OrygnsCode/opa-mcp-server/compare/v0.1.11...v0.1.12
 [0.1.11]: https://github.com/OrygnsCode/opa-mcp-server/compare/v0.1.10...v0.1.11
 [0.1.10]: https://github.com/OrygnsCode/opa-mcp-server/compare/v0.1.9...v0.1.10
 [0.1.9]: https://github.com/OrygnsCode/opa-mcp-server/compare/v0.1.8...v0.1.9

package/README.md

@@ -15,13 +15,13 @@ VS Code, Windsurf, Zed, and others) into a first-class
 environment.
 
 ```
-+--------------------+  MCP / stdio  +-----------------+  spawn / HTTP  +------------------------+
-|  Claude · Cursor · | ------------> |  @orygn/opa-mcp | -------------> |  opa · regal · conftest |
-|   VS Code · ...    | <------------ |                 | <------------- |  OPA REST API          |
-+--------------------+   48 tools    +-----------------+                +------------------------+
++--------------------+ MCP/stdio  +-----------------+ spawn/HTTP +---------------------+
+|  Claude · Cursor · |----------> | @orygn/opa-mcp  |----------> | opa · regal         |
+|   VS Code · ...    |<---------- |                 |<---------- | conftest · REST API  |
++--------------------+  49 tools  +-----------------+            +---------------------+
 ```
 
-> **Status:** v0.1.11. Tool surface, error codes, and
+> **Status:** v0.1.12. Tool surface, error codes, and
 > environment variables follow [SemVer](https://semver.org/) from
 > v0.1.0 forward.
 
@@ -400,18 +400,19 @@ point at a reachable server.
 The differentiation surface. These compose lower-level primitives into
 the tasks agents are actually asked to do.
 
-| Tool                          | What it does                                                                                                                                                                                                                                                                                                                                                                      |
-| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `rego_explain_decision`       | Walk through every rule that fired (and didn't) for a given query. Wraps `rego_eval_with_explain` and produces a step-by-step natural-language trace.                                                                                                                                                                                                                             |
-| `rego_generate_test_skeleton` | Given a policy, generate a `_test.rego` skeleton covering each rule.                                                                                                                                                                                                                                                                                                              |
-| `rego_describe_policy`        | Summarize what a policy does, its inputs, decisions, and assumptions.                                                                                                                                                                                                                                                                                                             |
-| `rego_suggest_fix`            | For a failed `rego_check` or `rego_lint`, propose minimal patches.                                                                                                                                                                                                                                                                                                                |
-| `rego_coverage_gaps`          | Run `opa test --coverage` and return per-file uncovered line ranges, sorted worst first. Use `threshold` to focus on files below a target percentage.                                                                                                                                                                                                                             |
-| `rego_security_audit`         | Run regal lint restricted to `security` and `bugs` categories across a directory. Returns severity-grouped findings with remediation guidance.                                                                                                                                                                                                                                    |
-| `rego_infer_input_schema`     | Statically analyse a policy (or directory of policies) with `opa parse` and return a JSON Schema describing every `input.*` field the policy reads. No running OPA required. Correct starting point for writing integration tests or configuring `opa check --schema`.                                                                                                            |
-| `rego_fix`                    | Run `regal fix` to auto-apply mechanical fixes: `opa-fmt`, `use-rego-v1`, `use-assignment-operator`, `no-whitespace-comment`, and `directory-package-mismatch`. Use `dryRun: true` to preview changes first. Returns a per-file breakdown of which rules were applied and, for `directory-package-mismatch`, the new path the file was moved to.                                  |
-| `rego_format_write`           | Run `opa fmt --write` to canonically format one or more Rego files or directories in place. Use `dryRun: true` to list which files would change without modifying them. Validates all files parse successfully before writing any. Supports `regoV1`, `v0Compatible`, and `v1Compatible` flags. Only requires `opa`.                                                              |
-| `rego_policy_diff`            | Evaluate the same query against two policies in parallel and compare the results. Returns `equal: true/false`, the raw value from each side (`resultA`/`resultB`), and `changedPaths` -- dot/bracket JSON paths that differ. Each side takes inline source or a file/directory path. Useful for verifying refactor equivalence or mapping divergence between two policy versions. |
+| Tool                          | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `rego_explain_decision`       | Walk through every rule that fired (and didn't) for a given query. Wraps `rego_eval_with_explain` and produces a step-by-step natural-language trace.                                                                                                                                                                                                                                                                                                                                                                           |
+| `rego_generate_test_skeleton` | Given a policy, generate a `_test.rego` skeleton covering each rule.                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `rego_describe_policy`        | Summarize what a policy does, its inputs, decisions, and assumptions.                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `rego_suggest_fix`            | For a failed `rego_check` or `rego_lint`, propose minimal patches.                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `rego_coverage_gaps`          | Run `opa test --coverage` and return per-file uncovered line ranges, sorted worst first. Use `threshold` to focus on files below a target percentage.                                                                                                                                                                                                                                                                                                                                                                           |
+| `rego_security_audit`         | Run regal lint restricted to `security` and `bugs` categories across a directory. Returns severity-grouped findings with remediation guidance.                                                                                                                                                                                                                                                                                                                                                                                  |
+| `rego_infer_input_schema`     | Statically analyse a policy (or directory of policies) with `opa parse` and return a JSON Schema describing every `input.*` field the policy reads. No running OPA required. Correct starting point for writing integration tests or configuring `opa check --schema`.                                                                                                                                                                                                                                                          |
+| `rego_fix`                    | Run `regal fix` to auto-apply mechanical fixes: `opa-fmt`, `use-rego-v1`, `use-assignment-operator`, `no-whitespace-comment`, and `directory-package-mismatch`. Use `dryRun: true` to preview changes first. Returns a per-file breakdown of which rules were applied and, for `directory-package-mismatch`, the new path the file was moved to.                                                                                                                                                                                |
+| `rego_format_write`           | Run `opa fmt --write` to canonically format one or more Rego files or directories in place. Use `dryRun: true` to list which files would change without modifying them. Validates all files parse successfully before writing any. Supports `regoV1`, `v0Compatible`, and `v1Compatible` flags. Only requires `opa`.                                                                                                                                                                                                            |
+| `rego_policy_diff`            | Evaluate the same query against two policies in parallel and compare the results. Returns `equal: true/false`, the raw value from each side (`resultA`/`resultB`), and `changedPaths` -- dot/bracket JSON paths that differ. Each side takes inline source or a file/directory path. Useful for verifying refactor equivalence or mapping divergence between two policy versions.                                                                                                                                               |
+| `rego_verify`                 | Formally verify a property about a Rego rule using SMT solving (Microsoft Z3 via WASM). Unlike testing, this checks ALL possible inputs mathematically and either proves the property holds or returns a concrete counterexample. Supports `always_true`, `never_true`, and `satisfiable` property kinds. Handles equality, comparison, string built-ins (`startswith`, `endswith`, `contains`, `regex.match`), multi-clause rules, and cross-rule inlining. Reports `INCONCLUSIVE` for negation-as-failure and comprehensions. |
 
 ### Category F: Conftest (configuration policy testing)
 

package/dist/constants.d.ts

@@ -4,5 +4,5 @@
  * (server.ts -> tools -> meta -> server.ts).
  */
 export declare const SERVER_NAME = "orygn-opa-mcp";
-export declare const SERVER_VERSION = "0.1.11";
+export declare const SERVER_VERSION = "0.1.12";
 //# sourceMappingURL=constants.d.ts.map

package/dist/constants.js

@@ -4,5 +4,5 @@
  * (server.ts -> tools -> meta -> server.ts).
  */
 export const SERVER_NAME = 'orygn-opa-mcp';
-export const SERVER_VERSION = '0.1.11';
+export const SERVER_VERSION = '0.1.12';
 //# sourceMappingURL=constants.js.map

package/dist/lib/rego-ast-types.d.ts

@@ -0,0 +1,81 @@
+/**
+ * TypeScript types mirroring the JSON output of `opa parse --format=json`.
+ *
+ * Field names and value shapes are verified against real OPA 0.69 output.
+ * Exact operator names confirmed: equal(==), eq(=), assign(:=), neq, gt,
+ * gte, lt, lte, startswith, endswith, contains, regex.match (compound ref).
+ */
+export type OpaTermType = 'null' | 'boolean' | 'number' | 'string' | 'var' | 'ref' | 'array' | 'set' | 'object' | 'call' | 'every' | 'arraycomprehension' | 'setcomprehension' | 'objectcomprehension';
+export interface OpaLocation {
+    file: string;
+    row: number;
+    col: number;
+}
+export interface OpaTerm {
+    type: OpaTermType;
+    value: OpaTermValue;
+    location?: OpaLocation;
+}
+/**
+ * Union of possible value shapes for each term type:
+ *   null       → null
+ *   boolean    → boolean
+ *   number     → number
+ *   string/var → string
+ *   ref/array  → OpaTerm[]
+ *   object     → Array<[OpaTerm, OpaTerm]>  (key-value pairs)
+ *   call       → OpaTerm[]  (first element is the function ref)
+ *   every      → OpaEvery
+ *   *comprehension → OpaComprehension
+ */
+export type OpaTermValue = null | boolean | number | string | OpaTerm[] | Array<[OpaTerm, OpaTerm]> | OpaEvery | OpaComprehension;
+export interface OpaEvery {
+    key?: OpaTerm;
+    value: OpaTerm;
+    domain: OpaTerm;
+    body: OpaExpression[];
+}
+export interface OpaComprehension {
+    term?: OpaTerm;
+    key?: OpaTerm;
+    value?: OpaTerm;
+    body: OpaExpression[];
+}
+/**
+ * A single expression in a rule body.
+ *
+ * `terms` is EITHER a single OpaTerm (bare expression: boolean literal,
+ * var reference, or input ref truthiness check) OR an OpaTerm[] where the
+ * first element is a ref to the operator/builtin and the rest are arguments.
+ *
+ * `negated: true` signals negation-as-failure (`not expr`).
+ */
+export interface OpaExpression {
+    index: number;
+    terms: OpaTerm | OpaTerm[];
+    negated?: boolean;
+    with?: unknown;
+}
+export interface OpaRuleHead {
+    name: string;
+    value?: OpaTerm;
+    key?: OpaTerm;
+    args?: OpaTerm[];
+    assign?: boolean;
+    ref?: OpaTerm[];
+}
+export interface OpaRule {
+    head: OpaRuleHead;
+    body: OpaExpression[];
+    default?: boolean;
+    else?: OpaRule;
+}
+export interface OpaModule {
+    package: {
+        path: OpaTerm[];
+    };
+    imports?: unknown[];
+    rules: OpaRule[];
+    comments?: unknown[];
+}
+//# sourceMappingURL=rego-ast-types.d.ts.map

package/dist/lib/rego-ast-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rego-ast-types.d.ts","sourceRoot":"","sources":["../../src/lib/rego-ast-types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,WAAW,GACnB,MAAM,GACN,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,KAAK,GACL,KAAK,GACL,OAAO,GACP,KAAK,GACL,QAAQ,GACR,MAAM,GACN,OAAO,GACP,oBAAoB,GACpB,kBAAkB,GAClB,qBAAqB,CAAC;AAE1B,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,YAAY,CAAC;IACpB,QAAQ,CAAC,EAAE,WAAW,CAAC;CACxB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,YAAY,GACpB,IAAI,GACJ,OAAO,GACP,MAAM,GACN,MAAM,GACN,OAAO,EAAE,GACT,KAAK,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,GACzB,QAAQ,GACR,gBAAgB,CAAC;AAErB,MAAM,WAAW,QAAQ;IACvB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,aAAa,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,aAAa,EAAE,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,GAAG,OAAO,EAAE,CAAC;IAC3B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,OAAO,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,aAAa,EAAE,CAAC;IACtB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE;QAAE,IAAI,EAAE,OAAO,EAAE,CAAA;KAAE,CAAC;IAC7B,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC;IACpB,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;CACtB"}

package/dist/lib/rego-ast-types.js

@@ -0,0 +1,9 @@
+/**
+ * TypeScript types mirroring the JSON output of `opa parse --format=json`.
+ *
+ * Field names and value shapes are verified against real OPA 0.69 output.
+ * Exact operator names confirmed: equal(==), eq(=), assign(:=), neq, gt,
+ * gte, lt, lte, startswith, endswith, contains, regex.match (compound ref).
+ */
+export {};
+//# sourceMappingURL=rego-ast-types.js.map

package/dist/lib/rego-ast-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rego-ast-types.js","sourceRoot":"","sources":["../../src/lib/rego-ast-types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/lib/rego-ast-walker.d.ts

@@ -0,0 +1,21 @@
+/**
+ * AST walker: OpaModule → VerifyWalkResult.
+ *
+ * Responsibilities:
+ *   1. Traverse all rules in the module, grouping clauses by rule name.
+ *   2. Inline cross-module rule references (non-recursive, depth <= MAX_INLINE_DEPTH).
+ *   3. Collect all input.* paths referenced anywhere in scope.
+ *   4. Detect and record every construct Phase 1 cannot handle.
+ *
+ * The encoder never touches OPA AST types -- all AST knowledge lives here.
+ */
+import type { OpaModule } from './rego-ast-types.js';
+import type { VerifyWalkResult } from './rego-ir.js';
+export declare function walkModule(ast: OpaModule): VerifyWalkResult;
+/**
+ * Collect all input.* paths recursively from a raw OPA AST value.
+ * Used for deep scans of comprehension bodies (Phase 2), but exported
+ * here for reuse in the engine's path-discovery pass.
+ */
+export declare function collectAllInputPaths(node: unknown, out: Map<string, string[]>): void;
+//# sourceMappingURL=rego-ast-walker.d.ts.map

package/dist/lib/rego-ast-walker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rego-ast-walker.d.ts","sourceRoot":"","sources":["../../src/lib/rego-ast-walker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAiB,SAAS,EAAoB,MAAM,qBAAqB,CAAC;AACtF,OAAO,KAAK,EAA2B,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAoB9E,wBAAgB,UAAU,CAAC,GAAG,EAAE,SAAS,GAAG,gBAAgB,CAiB3D;AA4lBD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,IAAI,CA6BpF"}