feat(azure-policy): add policy rule and policy definition parsers (microsoft#660)

Extend the Azure Policy parser to handle complete policyRule and
policyDefinition JSON structures, not just standalone constraints.

Policy rule parser (policy_rule.rs):
- Parse top-level { "if": ..., "then": ... } objects
- Extract effect kind (deny, audit, append, modify, etc.) into typed AST
- Parse "details" structurally when it is an object to pull out
  existenceCondition as a first-class Constraint; fall back to opaque
  JSON for non-object details (e.g. append array form)
- Detect duplicate/missing keys for "if", "then", "effect", "details"

Policy definition parser (policy_definition.rs):
- Handle both wrapped ARM envelope ({ "properties": { ... } }) and
  unwrapped (properties-level keys at top level) forms
- Type-extract displayName, description, mode, metadata, parameters,
  and policyRule; everything else goes into extra
- Parse parameter definitions with type, defaultValue, allowedValues,
  and metadata; detect duplicate parameter names
- Duplicate key detection throughout

Grammar documentation (docs/azure-policy/azurepolicy.ebnf):
- Add formal EBNF grammar covering policy-rule, then-block,
  constraints, conditions, all 19 operators, count expressions,
  JSON values, and ARM template expressions

Test harness changes:
- Add parse_level field to YAML test cases: "constraint" (default),
  "policy_rule", or "policy_definition"
- Un-skip three parse_errors cases that needed policy_rule-level parsing
- Add policy_rule.yaml with 12 cases covering all 9 effect kinds,
  existenceCondition, parameterized effects, complex conditions, and
  extra key handling
- Add policy_definition.yaml with wrapped, unwrapped, parameterized,
  missing-policyRule, and duplicate-key error cases

Author: anakrish

docs/azure-policy/azurepolicy.ebnf

@@ -0,0 +1,77 @@
+(* Azure Policy grammar.
+ *
+ * All key matching is case-insensitive.  JSON object keys are unordered,
+ * so the ordering shown below is for readability only.
+ *)
+
+(* ================================================================
+ * Policy rule & then block
+ * NOTE: Keys may appear in any order; extra keys may appear between
+ *       the recognized ones.  The ordering below is illustrative.
+ * ================================================================ *)
+
+policy-rule    ::= '{' '"if"' ':' constraint ',' '"then"' ':' then-block
+                       (',' STRING ':' json-value)* '}'
+
+then-block     ::= '{' '"effect"' ':' STRING
+                       (',' '"details"' ':' json-value)? '}'
+
+(* ================================================================
+ * Constraints
+ * ================================================================ *)
+
+constraint     ::= allOf | anyOf | not | condition
+
+allOf          ::= '{' '"allOf"' ':' '[' (constraint (',' constraint)*)? ']' '}'
+anyOf          ::= '{' '"anyOf"' ':' '[' (constraint (',' constraint)*)? ']' '}'
+not            ::= '{' '"not"' ':' constraint '}'
+
+(* Keys within a condition are unordered; exactly one lhs-entry and one
+ * op-entry are required. *)
+condition      ::= '{' lhs-entry ',' op-entry '}'
+
+lhs-entry      ::= field | value-lhs | count
+field          ::= '"field"' ':' string-value
+value-lhs      ::= '"value"' ':' json-value
+op-entry       ::= operator ':' json-value
+
+operator       ::= '"contains"' | '"containsKey"' | '"equals"' | '"notEquals"'
+                 | '"greater"' | '"greaterOrEquals"' | '"less"' | '"lessOrEquals"'
+                 | '"exists"' | '"in"' | '"notIn"'
+                 | '"like"' | '"notLike"'
+                 | '"match"' | '"matchInsensitively"'
+                 | '"notMatch"' | '"notMatchInsensitively"'
+                 | '"notContains"' | '"notContainsKey"'
+
+(* ================================================================
+ * Count expressions
+ * ================================================================ *)
+
+count          ::= '"count"' ':' count-inner
+count-inner    ::= count-field | count-value
+count-field    ::= '{' field (',' where)? '}'
+count-value    ::= '{' value-lhs (',' '"name"' ':' STRING)? (',' where)? '}'
+where          ::= '"where"' ':' constraint
+
+(* ================================================================
+ * JSON values & template expressions
+ * ================================================================ *)
+
+string-value   ::= STRING | '"[' string-expr ']"'
+
+json-value     ::= STRING | NUMBER | BOOL | NULL
+                 | array | object
+                 | '"[' string-expr ']"'
+array          ::= '[' (json-value (',' json-value)*)? ']'
+object         ::= '{' (STRING ':' json-value (',' STRING ':' json-value)*)? '}'
+
+(* ================================================================
+ * ARM template expression sub-grammar
+ * ================================================================ *)
+
+string-expr    ::= NUMBER | STRING | '-' string-expr | complex-expr
+
+complex-expr   ::= IDENT
+                 | complex-expr '.' IDENT
+                 | complex-expr '(' (string-expr (',' string-expr)*)? ')'
+                 | complex-expr '[' string-expr ']'

src/languages/azure_policy/ast/mod.rs

@@ -87,7 +87,7 @@ pub enum EffectKind {
     DenyAction,
     Manual,
     /// An effect value that wasn't recognized (may be a parameterized expression).
-    /// Use [`EffectNode::raw`] to get the original text.
+    /// The original text can be retrieved from [`EffectNode::raw`].
     Other,
 }
 
@@ -283,13 +283,18 @@ pub struct PolicyDefinition {
     /// Optional `metadata` (kept as raw JSON).
     pub metadata: Option<JsonValue>,
 
-    /// Parameter definitions as an ordered list; lookups should match `ParameterDefinition::name`.
+    /// Parameter definitions as an ordered list; each entry includes its parameter name.
     pub parameters: Vec<ParameterDefinition>,
 
     /// The parsed `policyRule`.
     pub policy_rule: PolicyRule,
 
-    /// Any other top-level fields not handled above (e.g., `id`, `name`, `type`, `policyType`).
+    /// Any unrecognized fields collected during parsing.
+    ///
+    /// In the **wrapped** form this includes both envelope-level keys
+    /// (e.g., `id`, `name`, `type`) and unrecognized keys inside the
+    /// inner `properties` object. In the **unwrapped** form it contains
+    /// only unrecognized top-level keys.
     pub extra: Vec<ObjectEntry>,
 }
 

src/languages/azure_policy/parser/constraint.rs

@@ -18,18 +18,6 @@ use super::core::{CountInner, EntryValue, Parser};
 use super::error::ParseError;
 use super::parse_operator_kind;
 
-/// Set `slot` to `val`, returning a [`ParseError::DuplicateKey`] if it was already set.
-fn set_once<T>(slot: &mut Option<T>, val: T, key: &str, span: &Span) -> Result<(), ParseError> {
-    if slot.is_some() {
-        return Err(ParseError::DuplicateKey {
-            span: span.clone(),
-            key: String::from(key),
-        });
-    }
-    *slot = Some(val);
-    Ok(())
-}
-
 impl<'source> Parser<'source> {
     /// Parse a constraint (a JSON object: logical combinator or leaf condition).
     pub fn parse_constraint(&mut self) -> Result<Constraint, ParseError> {
@@ -191,7 +179,7 @@ impl<'source> Parser<'source> {
                             expected: "JSON value for 'field'",
                         });
                     };
-                    set_once(&mut field, (key_span.clone(), jv), &key, &key_span)?;
+                    Self::set_once(&mut field, (key_span.clone(), jv), &key, &key_span)?;
                 }
                 "value" => {
                     let EntryValue::Json(jv) = entry_value else {
@@ -200,7 +188,7 @@ impl<'source> Parser<'source> {
                             expected: "JSON value for 'value'",
                         });
                     };
-                    set_once(&mut value, (key_span.clone(), jv), &key, &key_span)?;
+                    Self::set_once(&mut value, (key_span.clone(), jv), &key, &key_span)?;
                 }
                 "count" => {
                     let EntryValue::CountInner(ci) = entry_value else {
@@ -209,7 +197,7 @@ impl<'source> Parser<'source> {
                             expected: "object for 'count'",
                         });
                     };
-                    set_once(&mut count, (key_span.clone(), ci), &key, &key_span)?;
+                    Self::set_once(&mut count, (key_span.clone(), ci), &key, &key_span)?;
                 }
                 _ => {
                     if let Some(op_kind) = parse_operator_kind(&key.to_lowercase()) {
@@ -288,19 +276,19 @@ impl<'source> Parser<'source> {
                 match key_lower.as_str() {
                     "field" => {
                         let jv = self.parse_json_value()?;
-                        set_once(&mut field, (key_span.clone(), jv), &key_lower, &key_span)?;
+                        Self::set_once(&mut field, (key_span.clone(), jv), &key_lower, &key_span)?;
                     }
                     "value" => {
                         let jv = self.parse_json_value()?;
-                        set_once(&mut value, (key_span.clone(), jv), &key_lower, &key_span)?;
+                        Self::set_once(&mut value, (key_span.clone(), jv), &key_lower, &key_span)?;
                     }
                     "name" => {
                         let jv = self.parse_json_value()?;
-                        set_once(&mut name, (key_span.clone(), jv), &key_lower, &key_span)?;
+                        Self::set_once(&mut name, (key_span.clone(), jv), &key_lower, &key_span)?;
                     }
                     "where" => {
                         let c = self.parse_constraint()?;
-                        set_once(&mut where_, c, &key_lower, &key_span)?;
+                        Self::set_once(&mut where_, c, &key_lower, &key_span)?;
                     }
                     _ => {
                         return Err(ParseError::UnrecognizedKey {

src/languages/azure_policy/parser/core.rs

@@ -346,6 +346,27 @@ impl<'source> Parser<'source> {
         })
     }
 
+    // ========================================================================
+    // Duplicate-key guard
+    // ========================================================================
+
+    /// Set `slot` to `val`, returning [`ParseError::DuplicateKey`] if already set.
+    pub(super) fn set_once<T>(
+        slot: &mut Option<T>,
+        val: T,
+        key: &str,
+        span: &Span,
+    ) -> Result<(), ParseError> {
+        if slot.is_some() {
+            return Err(ParseError::DuplicateKey {
+                span: span.clone(),
+                key: String::from(key),
+            });
+        }
+        *slot = Some(val);
+        Ok(())
+    }
+
     // ========================================================================
     // Conversion helpers
     // ========================================================================

src/languages/azure_policy/parser/mod.rs

@@ -1,27 +1,42 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
-//! Recursive-descent JSON parser for Azure Policy rule constraints.
+//! Custom recursive-descent JSON parser for Azure Policy rules.
 //!
 //! Parses Azure Policy JSON directly from [`Lexer`] tokens, building span-annotated
 //! AST nodes in a single pass. No intermediate `serde_json::Value` is created.
 //!
 //! The parser is policy-aware: when parsing JSON objects, it dispatches on key names
 //! (`allOf`, `anyOf`, `not`, `field`, `value`, `count`, operator names) to build
 //! the appropriate AST nodes.
+//!
+//! ## Usage
+//!
+//! ```ignore
+//! use regorus::Source;
+//! use regorus::languages::azure_policy::parser;
+//!
+//! let json = r#"{ "if": { "field": "type", "equals": "Microsoft.Compute/virtualMachines" },
+//!                 "then": { "effect": "deny" } }"#;
+//! let source = Source::from_contents("policy.json".into(), json.into())?;
+//! let rule = parser::parse_policy_rule(&source)?;
+//! ```
 
 mod constraint;
 mod core;
 mod error;
+mod policy_definition;
+mod policy_rule;
 
 pub(super) use self::core::json_unescape;
+
 pub use error::ParseError;
 
 use alloc::string::ToString as _;
 
 use crate::lexer::{Source, TokenKind};
 
-use super::ast::{Constraint, FieldKind, OperatorKind};
+use super::ast::{Constraint, FieldKind, OperatorKind, PolicyDefinition, PolicyRule};
 use super::expr::ExprParser;
 
 use self::core::Parser;
@@ -30,12 +45,56 @@ use self::core::Parser;
 // Public API
 // ============================================================================
 
+/// Parse an Azure Policy rule from a JSON source.
+///
+/// The source should contain a complete `policyRule` JSON object:
+/// ```json
+/// {
+///   "if": { "field": "type", "equals": "Microsoft.Compute/virtualMachines" },
+///   "then": { "effect": "deny" }
+/// }
+/// ```
+///
+/// Returns a span-annotated [`PolicyRule`] AST.
+pub fn parse_policy_rule(source: &Source) -> Result<PolicyRule, ParseError> {
+    let mut parser = Parser::new(source)?;
+    let rule = parser.parse_policy_rule()?;
+
+    if parser.tok.0 != TokenKind::Eof {
+        return Err(ParseError::UnexpectedToken {
+            span: parser.tok.1.clone(),
+            expected: "end of input",
+        });
+    }
+
+    Ok(rule)
+}
+
+/// Parse a full Azure Policy definition from a JSON source.
+///
+/// Accepts two forms:
+/// 1. **Wrapped**: `{ "properties": { "policyRule": ..., ... }, "id": ..., ... }`
+/// 2. **Unwrapped**: `{ "displayName": ..., "policyRule": ..., ... }`
+///
+/// Returns a [`PolicyDefinition`] with typed fields for known properties
+/// and a catch-all list of `extra` entries for everything else.
+pub fn parse_policy_definition(source: &Source) -> Result<PolicyDefinition, ParseError> {
+    let mut parser = Parser::new(source)?;
+    let defn = parser.parse_policy_definition()?;
+
+    if parser.tok.0 != TokenKind::Eof {
+        return Err(ParseError::UnexpectedToken {
+            span: parser.tok.1.clone(),
+            expected: "end of input",
+        });
+    }
+
+    Ok(defn)
+}
+
 /// Parse a standalone constraint from a JSON source.
 ///
-/// A constraint is one of:
-/// - Logical combinator: `{ "allOf": [...] }`, `{ "anyOf": [...] }`, `{ "not": {...} }`
-/// - Leaf condition: `{ "field": "...", "equals": "..." }`
-/// - Count condition: `{ "count": { "field": "..." }, "greater": 0 }`
+/// Useful for parsing just the `"if"` part of a policy rule.
 pub fn parse_constraint(source: &Source) -> Result<Constraint, ParseError> {
     let mut parser = Parser::new(source)?;
     let constraint = parser.parse_constraint()?;