🔄 Merge pull request Ambro17#20 from Ambro17/add-change-to-validation-result-object

✨ Enrich validation response with rule name and original change object to enable allowlist feature

Author: Ambro17

docs/changes/field.html

@@ -26,7 +26,7 @@ <h1 class="title">Module <code>schemadiff.changes.field</code></h1>
 <summary>
 <span>Expand source code</span>
 </summary>
-<pre><code class="python">from graphql import is_non_null_type
+<pre><code class="python">from graphql import is_non_null_type, GraphQLField
 
 from schemadiff.changes import Change, Criticality, is_safe_type_change
 
@@ -99,13 +99,14 @@ <h1 class="title">Module <code>schemadiff.changes.field</code></h1>
 
 
 class FieldArgumentAdded(Change):
-    def __init__(self, parent, field_name, argument_name, arg_type):
+    def __init__(self, parent, field_name: str, field: GraphQLField, argument_name, arg_type):
         self.criticality = Criticality.safe(&#39;Adding an optional argument is a safe change&#39;)\
                            if not is_non_null_type(arg_type.type)\
                            else Criticality.breaking(&#34;Adding a required argument to an existing field is a breaking &#34;
                                                    &#34;change because it will break existing uses of this field&#34;)
         self.parent = parent
         self.field_name = field_name
+        self.field = field
         self.argument_name = argument_name
         self.arg_type = arg_type
 
@@ -154,7 +155,7 @@ <h2 class="section-title" id="header-classes">Classes</h2>
 <dl>
 <dt id="schemadiff.changes.field.FieldArgumentAdded"><code class="flex name class">
 <span>class <span class="ident">FieldArgumentAdded</span></span>
-<span>(</span><span>parent, field_name, argument_name, arg_type)</span>
+<span>(</span><span>parent, field_name: str, field: graphql.type.definition.GraphQLField, argument_name, arg_type)</span>
 </code></dt>
 <dd>
 <div class="desc"><p>Common interface of all schema changes</p>
@@ -166,13 +167,14 @@ <h2 class="section-title" id="header-classes">Classes</h2>
 <span>Expand source code</span>
 </summary>
 <pre><code class="python">class FieldArgumentAdded(Change):
-    def __init__(self, parent, field_name, argument_name, arg_type):
+    def __init__(self, parent, field_name: str, field: GraphQLField, argument_name, arg_type):
         self.criticality = Criticality.safe(&#39;Adding an optional argument is a safe change&#39;)\
                            if not is_non_null_type(arg_type.type)\
                            else Criticality.breaking(&#34;Adding a required argument to an existing field is a breaking &#34;
                                                    &#34;change because it will break existing uses of this field&#34;)
         self.parent = parent
         self.field_name = field_name
+        self.field = field
         self.argument_name = argument_name
         self.arg_type = arg_type
 

docs/changes/object.html

@@ -26,16 +26,19 @@ <h1 class="title">Module <code>schemadiff.changes.object</code></h1>
 <summary>
 <span>Expand source code</span>
 </summary>
-<pre><code class="python">from schemadiff.changes import Change, Criticality
+<pre><code class="python">from graphql import GraphQLField, GraphQLObjectType
+
+from schemadiff.changes import Change, Criticality
 
 
 class ObjectTypeFieldAdded(Change):
 
     criticality = Criticality.safe()
 
-    def __init__(self, parent, field_name):
+    def __init__(self, parent: GraphQLObjectType, field_name, field: GraphQLField):
         self.parent = parent
         self.field_name = field_name
+        self.field = field
         self.description = parent.fields[field_name].description
 
     @property
@@ -82,7 +85,7 @@ <h2 class="section-title" id="header-classes">Classes</h2>
 <dl>
 <dt id="schemadiff.changes.object.ObjectTypeFieldAdded"><code class="flex name class">
 <span>class <span class="ident">ObjectTypeFieldAdded</span></span>
-<span>(</span><span>parent, field_name)</span>
+<span>(</span><span>parent: graphql.type.definition.GraphQLObjectType, field_name, field: graphql.type.definition.GraphQLField)</span>
 </code></dt>
 <dd>
 <div class="desc"><p>Common interface of all schema changes</p>
@@ -97,9 +100,10 @@ <h2 class="section-title" id="header-classes">Classes</h2>
 
     criticality = Criticality.safe()
 
-    def __init__(self, parent, field_name):
+    def __init__(self, parent: GraphQLObjectType, field_name, field: GraphQLField):
         self.parent = parent
         self.field_name = field_name
+        self.field = field
         self.description = parent.fields[field_name].description
 
     @property

docs/index.html

@@ -34,7 +34,7 @@ <h1 class="title">Package <code>schemadiff</code></h1>
 from schemadiff.diff.schema import Schema
 from schemadiff.schema_loader import SchemaLoader
 from schemadiff.formatting import print_diff, format_diff
-from schemadiff.validation import validate_diff
+from schemadiff.validation import validate_changes
 
 
 SDL = str  # Alias for string describing schema through schema definition language
@@ -67,7 +67,7 @@ <h1 class="title">Package <code>schemadiff</code></h1>
     &#39;diff_from_file&#39;,
     &#39;format_diff&#39;,
     &#39;print_diff&#39;,
-    &#39;validate_diff&#39;,
+    &#39;validate_changes&#39;,
     &#39;Change&#39;,
 ]</code></pre>
 </details>
@@ -182,13 +182,13 @@ <h2 id="returns">Returns</h2>
     print(format_diff(changes))</code></pre>
 </details>
 </dd>
-<dt id="schemadiff.validate_diff"><code class="name flex">
-<span>def <span class="ident">validate_diff</span></span>(<span>diff, rules: List[str]) ‑> bool</span>
+<dt id="schemadiff.validate_changes"><code class="name flex">
+<span>def <span class="ident">validate_changes</span></span>(<span>diff: List[<a title="schemadiff.changes.Change" href="changes/index.html#schemadiff.changes.Change">Change</a>], rules: List[str], allowed_changes: Dict[str, Any] = None) ‑> <a title="schemadiff.validation.ValidationResult" href="validation.html#schemadiff.validation.ValidationResult">ValidationResult</a></span>
 </code></dt>
 <dd>
-<div class="desc"><p>Given a diff between schemas and a list of rules
-names, it looks up for all rules matching the list
-and evaluates the changes against that list.</p>
+<div class="desc"><p>Given a list of changes between schemas and a list of rules,
+it runs all rules against the changes, to detect invalid changes.
+It also admits an allowlist of accepted invalid changes to document exceptions to the rules</p>
 <h2 id="returns">Returns</h2>
 <dl>
 <dt><code>bool</code></dt>
@@ -199,24 +199,30 @@ <h2 id="returns">Returns</h2>
 <summary>
 <span>Expand source code</span>
 </summary>
-<pre><code class="python">def validate_diff(diff, rules: List[str]) -&gt; bool:
-    &#34;&#34;&#34;Given a diff between schemas and a list of rules
-    names, it looks up for all rules matching the list
-    and evaluates the changes against that list.
+<pre><code class="python">def validate_changes(diff: List[Change], rules: List[str], allowed_changes: Dict[str, Any] = None) -&gt; ValidationResult:
+    &#34;&#34;&#34;Given a list of changes between schemas and a list of rules,
+    it runs all rules against the changes, to detect invalid changes.
+    It also admits an allowlist of accepted invalid changes to document exceptions to the rules
 
     Returns:
         bool: True if there is at least one restricted change,
             False otherwise.
     &#34;&#34;&#34;
-    is_restricted = False
+    allowed_changes = allowed_changes or {}
+    is_valid = True
+    errors = []
     rules = ValidationRule.get_subclasses_by_names(rules)
     for change in diff:
         for rule in rules:
             if not rule(change).is_valid():
+                if change.checksum() in allowed_changes:
+                    continue
+
                 change.restricted = rule(change).message
-                is_restricted = True
+                is_valid = False
+                errors.append(ValidationError(rule.name, change.restricted, change))
 
-    return is_restricted</code></pre>
+    return ValidationResult(is_valid, errors)</code></pre>
 </details>
 </dd>
 </dl>
@@ -497,7 +503,7 @@ <h1>Index</h1>
 <li><code><a title="schemadiff.diff_from_file" href="#schemadiff.diff_from_file">diff_from_file</a></code></li>
 <li><code><a title="schemadiff.format_diff" href="#schemadiff.format_diff">format_diff</a></code></li>
 <li><code><a title="schemadiff.print_diff" href="#schemadiff.print_diff">print_diff</a></code></li>
-<li><code><a title="schemadiff.validate_diff" href="#schemadiff.validate_diff">validate_diff</a></code></li>
+<li><code><a title="schemadiff.validate_changes" href="#schemadiff.validate_changes">validate_changes</a></code></li>
 </ul>
 </li>
 <li><h3><a href="#header-classes">Classes</a></h3>