specforge-api 0.1.0__py3-none-any.whl

specforge/parser/resolver.py

@@ -0,0 +1,101 @@
+"""JSON Pointer & $ref reference resolver with circular reference protection."""
+
+from typing import Any, Optional
+
+
+class RefResolver:
+    """Resolves JSON Reference ($ref) pointers within an OpenAPI specification."""
+
+    def __init__(self, root_spec: dict[str, Any], max_depth: int = 25):
+        self.root_spec = root_spec
+        self.max_depth = max_depth
+
+    def resolve_pointer(self, ref: str) -> dict[str, Any]:
+        """Resolve a local JSON Pointer string like '#/components/schemas/User'.
+
+        Raises ValueError if the reference cannot be located.
+        """
+        if not ref.startswith("#/"):
+            raise ValueError(f"External references are not supported: {ref}")
+
+        parts = ref[2:].split("/")
+        current: Any = self.root_spec
+
+        for part in parts:
+            # Unescape JSON pointer tokens (~1 for /, ~0 for ~)
+            part = part.replace("~1", "/").replace("~0", "~")
+            if isinstance(current, dict) and part in current:
+                current = current[part]
+            elif isinstance(current, list) and part.isdigit() and int(part) < len(current):
+                current = current[int(part)]
+            else:
+                raise ValueError(f"Could not resolve $ref pointer part '{part}' in '{ref}'")
+
+        if not isinstance(current, dict):
+            return {"type": "object", "value": current}
+        return current
+
+    def dereference(
+        self,
+        schema: Any,
+        visited_refs: Optional[set[str]] = None,
+        depth: int = 0,
+    ) -> Any:
+        """Recursively dereferences schemas, protecting against infinite cyclic references."""
+        if visited_refs is None:
+            visited_refs = set()
+
+        if depth > self.max_depth:
+            return {"type": "object", "description": "[Recursion depth exceeded]"}
+
+        if not isinstance(schema, dict):
+            if isinstance(schema, list):
+                return [self.dereference(item, visited_refs, depth + 1) for item in schema]
+            return schema
+
+        # Check for $ref
+        if "$ref" in schema:
+            ref_path = schema["$ref"]
+            if ref_path in visited_refs:
+                # Cycle detected! Return a stub to avoid infinite recursion
+                model_name = ref_path.split("/")[-1]
+                return {
+                    "type": "object",
+                    "description": f"[Circular reference to {model_name}]",
+                    "_is_cycle": True,
+                }
+
+            resolved = self.resolve_pointer(ref_path)
+            new_visited = visited_refs.copy()
+            new_visited.add(ref_path)
+
+            # Dereference the target schema
+            dereferenced_target = self.dereference(resolved, new_visited, depth + 1)
+
+            # Merge any local overrides in the original schema (e.g. description, nullable)
+            merged = dict(dereferenced_target)
+            for k, v in schema.items():
+                if k != "$ref":
+                    merged[k] = v
+            return merged
+
+        # Otherwise, recursively dereference dictionary keys
+        result: dict[str, Any] = {}
+        for key, val in schema.items():
+            if key in ("properties", "patternProperties") and isinstance(val, dict):
+                result[key] = {
+                    prop_name: self.dereference(prop_schema, visited_refs, depth + 1)
+                    for prop_name, prop_schema in val.items()
+                }
+            elif key == "items":
+                result[key] = self.dereference(val, visited_refs, depth + 1)
+            elif key in ("allOf", "anyOf", "oneOf") and isinstance(val, list):
+                result[key] = [self.dereference(item, visited_refs, depth + 1) for item in val]
+            elif isinstance(val, dict):
+                result[key] = self.dereference(val, visited_refs, depth + 1)
+            elif isinstance(val, list):
+                result[key] = [self.dereference(item, visited_refs, depth + 1) for item in val]
+            else:
+                result[key] = val
+
+        return result

specforge/testing/exporters/pytest_export.py

@@ -0,0 +1,89 @@
+"""Pytest code generator for SpecForge test plans."""
+
+import json
+
+from specforge.testing.invariants import TestCase
+
+
+class PytestExporter:
+    """Compiles SpecForge TestCases into ready-to-run pytest code."""
+
+    @classmethod
+    def export(
+        cls,
+        test_cases: list[TestCase],
+        base_url: str = "http://localhost:8000",
+        module_name: str = "test_api_contracts.py",
+    ) -> str:
+        """Generate clean, formatted pytest code."""
+        cases_repr: list[str] = []
+
+        for tc in test_cases:
+            payload_json = json.dumps(tc.payload) if tc.payload is not None else "None"
+            query_json = json.dumps(tc.query_params) if tc.query_params else "None"
+            desc_escaped = tc.description.replace('"', '\\"')
+
+            case_str = (
+                f'    (\n'
+                f'        "{tc.endpoint}",\n'
+                f'        "{tc.method.upper()}",\n'
+                f'        {payload_json},\n'
+                f'        {query_json},\n'
+                f'        {tc.expected_status},\n'
+                f'        {tc.is_negative_test},\n'
+                f'        "{desc_escaped}",\n'
+                f'    ),'
+            )
+            cases_repr.append(case_str)
+
+        cases_block = "\n".join(cases_repr)
+
+        code = f'''# Auto-generated by SpecForge
+# Contract Boundary & Invariant Test Suite
+import pytest
+import httpx
+
+BASE_URL = "{base_url}"
+
+@pytest.mark.parametrize(
+    "endpoint,method,payload,query_params,expected_status,is_negative,description",
+    [
+{cases_block}
+    ]
+)
+def test_specforge_contract_boundaries(
+    endpoint: str,
+    method: str,
+    payload,
+    query_params,
+    expected_status: int,
+    is_negative: bool,
+    description: str,
+):
+    """Execute boundary test and assert Zero-500s invariant and contract validation."""
+    with httpx.Client(base_url=BASE_URL, timeout=10.0) as client:
+        kwargs = {{}}
+        if payload is not None:
+            kwargs["json"] = payload
+        if query_params is not None:
+            kwargs["params"] = query_params
+
+        response = client.request(method, endpoint, **kwargs)
+
+        # Invariant 1: Server must NEVER crash with HTTP 500 on client inputs
+        assert response.status_code != 500, (
+            f"CRITICAL 500 SERVER CRASH: '{{description}}' triggered an unhandled exception!"
+        )
+
+        # Invariant 2: Negative tests must be cleanly rejected with 400 or 422
+        if is_negative:
+            assert response.status_code in (400, 422), (
+                f"SCHEMA LEAK on '{{description}}': expected 400/422 rejection, "
+                f"got HTTP {{response.status_code}}. Response: {{response.text}}"
+            )
+        else:
+            assert 200 <= response.status_code < 300, (
+                f"Happy path failed on '{{description}}': got HTTP {{response.status_code}}."
+            )
+'''
+        return code

specforge/testing/fuzzers/array_fuzzer.py

@@ -0,0 +1,56 @@
+"""Array field mutation test generator."""
+
+from typing import Any
+
+from specforge.parser.models import JSONSchema
+
+
+class ArrayFuzzer:
+    """Generates boundary and mutation payloads for array schema fields."""
+
+    @classmethod
+    def generate_mutations(
+        cls,
+        field_name: str,
+        schema: JSONSchema,
+        valid_example: Any = None,
+    ) -> list[tuple[str, str, Any, str]]:
+        """Generate mutations for array field."""
+        mutations: list[tuple[str, str, Any, str]] = []
+
+        # 1. Empty array check when minItems >= 1
+        if schema.min_items is not None and schema.min_items > 0:
+            mutations.append((
+                "Boundary: Empty Array",
+                f"Reject empty list [] for '{field_name}' (requires at least {schema.min_items})",
+                [],
+                "Boundary",
+            ))
+
+        # 2. Exceeding maxItems
+        if schema.max_items is not None:
+            mutations.append((
+                "Boundary: Exceeds Max Items",
+                f"Reject array with {schema.max_items + 1} items (> max {schema.max_items}) for '{field_name}'",
+                ["item"] * (schema.max_items + 1),
+                "Boundary",
+            ))
+
+        # 3. Unique items enforcement
+        if schema.unique_items:
+            mutations.append((
+                "Integrity: Duplicate Items",
+                f"Reject duplicate items in uniqueItems list for '{field_name}'",
+                ["duplicate", "duplicate"],
+                "Integrity",
+            ))
+
+        # 4. Type inversion: Primitive string instead of array
+        mutations.append((
+            "Type: Scalar String Instead of Array",
+            f"Reject single string scalar instead of array for '{field_name}'",
+            "not_an_array_string",
+            "Type",
+        ))
+
+        return mutations

specforge/testing/fuzzers/boolean_fuzzer.py

@@ -0,0 +1,38 @@
+"""Boolean field mutation test generator."""
+
+from typing import Any
+
+from specforge.parser.models import JSONSchema
+
+
+class BooleanFuzzer:
+    """Generates boundary and mutation payloads for boolean schema fields."""
+
+    @classmethod
+    def generate_mutations(
+        cls,
+        field_name: str,
+        schema: JSONSchema,
+        valid_example: bool = True,
+    ) -> list[tuple[str, str, Any, str]]:
+        """Generate mutations for boolean field."""
+        return [
+            (
+                "Type: String 'yes' for Boolean",
+                f"Reject ambiguous string 'yes' for boolean field '{field_name}'",
+                "yes",
+                "Type",
+            ),
+            (
+                "Type: Numeric 1 for Boolean",
+                f"Reject numeric integer 1 for strict boolean field '{field_name}'",
+                1,
+                "Type",
+            ),
+            (
+                "Type: Invalid String for Boolean",
+                f"Reject arbitrary string 'not_a_bool' for boolean '{field_name}'",
+                "not_a_bool",
+                "Type",
+            ),
+        ]

specforge/testing/fuzzers/numeric_fuzzer.py

@@ -0,0 +1,92 @@
+"""Numeric and integer field boundary test generator."""
+
+from typing import Any
+
+from specforge.parser.models import JSONSchema
+
+
+class NumericFuzzer:
+    """Generates boundary and mutation payloads for integer and number schema fields."""
+
+    @classmethod
+    def generate_mutations(
+        cls,
+        field_name: str,
+        schema: JSONSchema,
+        valid_example: float = 10,
+    ) -> list[tuple[str, str, Any, str]]:
+        """Generate a list of mutations for a numeric field.
+
+        Returns tuples of: (mutation_name, description, mutated_value, category)
+        """
+        mutations: list[tuple[str, str, Any, str]] = []
+        is_integer = (
+            schema.type == "integer"
+            or (isinstance(schema.type, list) and "integer" in schema.type)
+        )
+
+        # 1. Minimum boundary
+        if schema.minimum is not None:
+            subtractor = 1 if is_integer else 0.01
+            mutations.append((
+                "Boundary: Below Minimum",
+                f"Reject value {schema.minimum - subtractor} (< min {schema.minimum}) for '{field_name}'",
+                schema.minimum - subtractor,
+                "Boundary",
+            ))
+
+        # 2. Maximum boundary
+        if schema.maximum is not None:
+            adder = 1 if is_integer else 0.01
+            mutations.append((
+                "Boundary: Exceeds Maximum",
+                f"Reject value {schema.maximum + adder} (> max {schema.maximum}) for '{field_name}'",
+                schema.maximum + adder,
+                "Boundary",
+            ))
+
+        # 3. Negative value check (if minimum is non-negative)
+        if schema.minimum is not None and schema.minimum >= 0:
+            mutations.append((
+                "Boundary: Negative Number",
+                f"Reject negative number (-1) for positive field '{field_name}'",
+                -1,
+                "Boundary",
+            ))
+
+        # 4. Zero check (if minimum is strictly positive)
+        if schema.minimum is not None and schema.minimum > 0:
+            mutations.append((
+                "Boundary: Zero Value",
+                f"Reject 0 for field with minimum {schema.minimum} '{field_name}'",
+                0,
+                "Boundary",
+            ))
+
+        # 5. Float into integer field
+        if is_integer:
+            mutations.append((
+                "Type: Float in Integer Field",
+                f"Reject non-integer float (42.5) for integer field '{field_name}'",
+                42.5,
+                "Type",
+            ))
+
+        # 6. Integer range overflow
+        if is_integer:
+            mutations.append((
+                "Overflow: 32-bit Integer Limit",
+                f"Handle 32-bit integer overflow (2,147,483,648) for '{field_name}'",
+                2147483648,
+                "Overflow",
+            ))
+
+        # 7. Type inversion: String representation of number
+        mutations.append((
+            "Type: String Instead of Number",
+            f"Reject string representation '100' for numeric field '{field_name}'",
+            "100",
+            "Type",
+        ))
+
+        return mutations

specforge/testing/fuzzers/object_fuzzer.py

@@ -0,0 +1,99 @@
+"""Object schema mutation and required field omission generator."""
+
+import copy
+from typing import Any
+
+from specforge.parser.models import JSONSchema
+
+
+class ObjectFuzzer:
+    """Generates mutations for object schemas (request bodies and nested objects)."""
+
+    @classmethod
+    def generate_valid_baseline(cls, schema: JSONSchema) -> dict[str, Any]:
+        """Generate a valid baseline dictionary conforming to the schema."""
+        baseline: dict[str, Any] = {}
+
+        for prop_name, prop_schema in schema.properties.items():
+            if prop_schema.example is not None:
+                baseline[prop_name] = prop_schema.example
+            elif prop_schema.default is not None:
+                baseline[prop_name] = prop_schema.default
+            elif prop_schema.enum:
+                baseline[prop_name] = prop_schema.enum[0]
+            elif prop_schema.type == "string":
+                if prop_schema.format == "email":
+                    baseline[prop_name] = "user@example.com"
+                elif prop_schema.format == "uuid":
+                    baseline[prop_name] = "123e4567-e89b-12d3-a456-426614174000"
+                elif prop_schema.format in ("date-time", "date"):
+                    baseline[prop_name] = "2026-01-01T12:00:00Z"
+                else:
+                    baseline[prop_name] = f"sample_{prop_name}"
+            elif prop_schema.type == "integer":
+                min_val = prop_schema.minimum if prop_schema.minimum is not None else 1
+                baseline[prop_name] = int(min_val)
+            elif prop_schema.type == "number":
+                min_val = prop_schema.minimum if prop_schema.minimum is not None else 1.0
+                baseline[prop_name] = float(min_val)
+            elif prop_schema.type == "boolean":
+                baseline[prop_name] = True
+            elif prop_schema.type == "array":
+                baseline[prop_name] = []
+            elif prop_schema.type == "object":
+                baseline[prop_name] = cls.generate_valid_baseline(prop_schema)
+            else:
+                baseline[prop_name] = "valid_value"
+
+        return baseline
+
+    @classmethod
+    def generate_object_mutations(
+        cls,
+        schema: JSONSchema,
+        baseline_payload: dict[str, Any],
+    ) -> list[tuple[str, str, Any, str]]:
+        """Generate object-level mutations (omissions, unexpected properties, type inversion)."""
+        mutations: list[tuple[str, str, Any, str]] = []
+
+        # 1. Combinatorial omission of required fields
+        for req_field in schema.required:
+            if req_field in baseline_payload:
+                omitted_payload = copy.deepcopy(baseline_payload)
+                del omitted_payload[req_field]
+                mutations.append((
+                    f"Structure: Omit Required Field '{req_field}'",
+                    f"Reject payload missing required property '{req_field}'",
+                    omitted_payload,
+                    "Structure",
+                ))
+
+        # 2. Completely empty dictionary when required fields exist
+        if schema.required:
+            mutations.append((
+                "Structure: Empty Object Payload",
+                "Reject completely empty object {} when required properties exist",
+                {},
+                "Structure",
+            ))
+
+        # 3. Unexpected property injection when additionalProperties is False
+        if schema.additional_properties is False:
+            extra_payload = copy.deepcopy(baseline_payload)
+            extra_payload["__unexpected_field__"] = "invalid"
+            mutations.append((
+                "Structure: Unexpected Additional Property",
+                "Reject unlisted property when additionalProperties is false",
+                extra_payload,
+                "Structure",
+            ))
+
+        # 4. Type inversion: Primitive scalar instead of object dictionary
+        mutations.append((
+            "Type: String Instead of Object",
+            "Reject string primitive instead of JSON dictionary object",
+            "invalid_raw_string_payload",
+            "Type",
+        ))
+
+        return mutations

specforge/testing/fuzzers/string_fuzzer.py

@@ -0,0 +1,157 @@
+"""String field boundary and negative test generator."""
+
+from typing import Any
+
+from specforge.parser.models import JSONSchema
+
+
+class StringFuzzer:
+    """Generates boundary and mutation payloads for string schema fields."""
+
+    @classmethod
+    def generate_mutations(
+        cls,
+        field_name: str,
+        schema: JSONSchema,
+        valid_example: str = "valid_sample",
+    ) -> list[tuple[str, str, Any, str]]:
+        """Generate a list of mutations for a string field.
+
+        Returns tuples of: (mutation_name, description, mutated_value, category)
+        """
+        mutations: list[tuple[str, str, Any, str]] = []
+
+        # 1. Whitespace Fuzzing
+        mutations.append((
+            "Whitespace: Single Space",
+            f"Reject single space string for '{field_name}'",
+            " ",
+            "Whitespace",
+        ))
+        mutations.append((
+            "Whitespace: Multi-Space Only",
+            f"Reject multiple whitespace-only string for '{field_name}'",
+            "     ",
+            "Whitespace",
+        ))
+        mutations.append((
+            "Whitespace: Tabs and Newlines",
+            f"Reject tab and newline whitespace for '{field_name}'",
+            "\t\n\r  ",
+            "Whitespace",
+        ))
+
+        # 2. Empty String
+        if schema.min_length is None or schema.min_length > 0:
+            mutations.append((
+                "Boundary: Empty String",
+                f"Reject empty string for '{field_name}'",
+                "",
+                "Boundary",
+            ))
+
+        # 3. Min/Max Length Boundaries
+        if schema.min_length is not None and schema.min_length > 1:
+            mutations.append((
+                "Boundary: Below Min Length",
+                f"Reject string of length {schema.min_length - 1} (< min {schema.min_length}) for '{field_name}'",
+                "a" * (schema.min_length - 1),
+                "Boundary",
+            ))
+
+        if schema.max_length is not None:
+            mutations.append((
+                "Boundary: Exceeds Max Length",
+                f"Reject string of length {schema.max_length + 1} (> max {schema.max_length}) for '{field_name}'",
+                "a" * (schema.max_length + 1),
+                "Boundary",
+            ))
+        else:
+            # Test buffer DoS guardrails
+            mutations.append((
+                "Buffer: Large String (5000 chars)",
+                f"Safely handle 5,000-character payload for '{field_name}'",
+                "x" * 5000,
+                "Buffer",
+            ))
+
+        # 4. Unicode & Special Characters
+        mutations.append((
+            "Unicode: 4-Byte Emojis",
+            f"Verify 4-byte UTF-8 emoji support (no crash) for '{field_name}'",
+            "🚀✨🔥💡",
+            "Unicode",
+        ))
+        mutations.append((
+            "Unicode: Null Byte Injection",
+            f"Reject or escape null byte injection in '{field_name}'",
+            "admin\x00root",
+            "Security",
+        ))
+
+        # 5. Format-Specific Fuzzing
+        if schema.format == "email":
+            mutations.append((
+                "Format: Missing At Symbol",
+                f"Reject malformed email without '@' in '{field_name}'",
+                "plainaddress_without_at",
+                "Format",
+            ))
+            mutations.append((
+                "Format: Missing Domain",
+                f"Reject incomplete email '@domain.com' in '{field_name}'",
+                "@domain.com",
+                "Format",
+            ))
+        elif schema.format == "uuid":
+            mutations.append((
+                "Format: Malformed UUID",
+                f"Reject invalid UUID string in '{field_name}'",
+                "not-a-valid-uuid-12345",
+                "Format",
+            ))
+        elif schema.format in ("date-time", "date"):
+            mutations.append((
+                "Format: Impossible Date",
+                f"Reject invalid date (Feb 31st) in '{field_name}'",
+                "2026-02-31T00:00:00Z",
+                "Format",
+            ))
+            mutations.append((
+                "Format: Non-ISO Date String",
+                f"Reject non-ISO date string in '{field_name}'",
+                "Tomorrow morning",
+                "Format",
+            ))
+        elif schema.format == "uri":
+            mutations.append((
+                "Format: Missing URI Protocol",
+                f"Reject URI missing scheme (http/https) in '{field_name}'",
+                "www.example.com/no-protocol",
+                "Format",
+            ))
+
+        # 6. Injection Probes (Safety heuristics)
+        mutations.append((
+            "Security: Basic SQL Injection Probe",
+            f"Safely validate/escape SQL injection probe in '{field_name}'",
+            "' OR '1'='1",
+            "Security",
+        ))
+        mutations.append((
+            "Security: XSS Script Tag Probe",
+            f"Safely validate/escape script tag in '{field_name}'",
+            "<script>alert(1)</script>",
+            "Security",
+        ))
+
+        # 7. Pattern Non-Compliance
+        if schema.pattern:
+            mutations.append((
+                "Pattern: Non-Matching String",
+                f"Reject string violating pattern '{schema.pattern}' for '{field_name}'",
+                "__INVALID_PATTERN_VIOLATION__!",
+                "Pattern",
+            ))
+
+        return mutations