specforge-api 0.1.0__py3-none-any.whl

specforge/cli/main.py

@@ -0,0 +1,153 @@
+"""Command-line interface for SpecForge."""
+
+import argparse
+import json
+import sys
+import time
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from specforge.parser.openapi3 import OpenAPIParser
+from specforge.testing.exporters.pytest_export import PytestExporter
+from specforge.testing.invariants import TestStatus, evaluate_test_result
+from specforge.testing.planner import TestPlanner
+
+
+def fetch_spec(target: str) -> dict[str, Any]:
+    """Load OpenAPI JSON/YAML from a local file or remote HTTP URL."""
+    if target.startswith("http://") or target.startswith("https://"):
+        req = urllib.request.Request(target, headers={"User-Agent": "SpecForge-CLI"})
+        with urllib.request.urlopen(req) as response:
+            content = response.read().decode("utf-8")
+    else:
+        path = Path(target)
+        if not path.exists():
+            raise FileNotFoundError(f"Spec file not found at: {target}")
+        content = path.read_text(encoding="utf-8")
+
+    try:
+        return json.loads(content)
+    except json.JSONDecodeError:
+        import yaml  # type: ignore
+        return yaml.safe_load(content)
+
+
+def run_test_command(args: argparse.Namespace) -> int:
+    """Execute automated contract fuzzing against an API from the terminal."""
+    print("\n⚡ \033[1;36mSpecForge Contract & Boundary Testing Engine\033[0m")
+    print(f"Loading specification from: \033[33m{args.spec}\033[0m")
+
+    try:
+        raw_spec = fetch_spec(args.spec)
+    except Exception as e:
+        print(f"\033[1;31mError loading spec: {e}\033[0m")
+        return 1
+
+    parser = OpenAPIParser(raw_spec)
+    spec_model = parser.parse()
+    print(f"Parsed \033[32m{len(spec_model.operations)}\033[0m operations across API: {spec_model.title}\n")
+
+    all_test_cases = []
+    for op in spec_model.operations:
+        plan = TestPlanner.plan_operation_tests(op)
+        all_test_cases.extend(plan.test_cases)
+
+    print(f"Synthesized \033[1;35m{len(all_test_cases)}\033[0m boundary test cases.\n")
+    print("=" * 80)
+
+    base_url = args.base_url or (spec_model.servers[0] if spec_model.servers else "http://localhost:8000")
+    base_url = base_url.rstrip("/")
+
+    pass_count = 0
+    leak_count = 0
+    crash_count = 0
+    fail_count = 0
+
+    with httpx.Client(base_url=base_url, timeout=args.timeout) as client:
+        for _idx, tc in enumerate(all_test_cases, 1):
+            start = time.perf_counter()
+            kwargs: dict[str, Any] = {}
+            if tc.payload is not None:
+                kwargs["json"] = tc.payload
+            if tc.query_params:
+                kwargs["params"] = tc.query_params
+
+            try:
+                res = client.request(tc.method.upper(), tc.endpoint, **kwargs)
+                actual_status = res.status_code
+                resp_text = res.text
+            except Exception as e:
+                actual_status = 599
+                resp_text = str(e)
+
+            latency = (time.perf_counter() - start) * 1000
+            result = evaluate_test_result(tc, actual_status, resp_text, latency)
+
+            if result.status == TestStatus.PASS:
+                pass_count += 1
+                status_icon = "\033[32m[PASS]\033[0m"
+            elif result.status == TestStatus.CRASH_500:
+                crash_count += 1
+                status_icon = "\033[1;31m[CRASH 500]\033[0m"
+            elif result.status == TestStatus.WARN_LEAK:
+                leak_count += 1
+                status_icon = "\033[33m[LEAK 200]\033[0m"
+            else:
+                fail_count += 1
+                status_icon = f"\033[31m[{actual_status}]\033[0m"
+
+            print(
+                f"{status_icon} {tc.method.upper():<6} {tc.endpoint:<28} "
+                f"Field: {tc.field_name:<16} ({latency:4.0f}ms)"
+            )
+            if result.status == TestStatus.CRASH_500:
+                print(f"       \033[31m↳ {result.message}\033[0m")
+                print(f"       \033[90mReproduction:\033[0m {result.curl_command}")
+
+    print("=" * 80)
+    print("\n📊 \033[1mFinal Test Summary:\033[0m")
+    print(f"   Total Executed: {len(all_test_cases)}")
+    print(f"   \033[32mPassed (Clean 400/422):  {pass_count}\033[0m")
+    print(f"   \033[33mSchema Leaks (Accepted): {leak_count}\033[0m")
+    print(f"   \033[1;31mServer Crashes (500s):  {crash_count}\033[0m")
+
+    # Export to pytest if requested
+    if args.export_pytest:
+        out_path = Path(args.export_pytest)
+        code = PytestExporter.export(all_test_cases, base_url=base_url)
+        out_path.write_text(code, encoding="utf-8")
+        print(f"\n🐍 \033[32mExported Pytest suite to: {out_path.resolve()}\033[0m")
+
+    if args.fail_on_500 and crash_count > 0:
+        print(f"\n\033[1;31mFAILED: {crash_count} unhandled HTTP 500 server crashes detected!\033[0m")
+        return 1
+
+    return 0
+
+
+def cli_entrypoint() -> None:
+    """Main CLI entrypoint."""
+    parser = argparse.ArgumentParser(
+        prog="specforge",
+        description="SpecForge: Interactive API Client & Automated Contract Fuzzer",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # `specforge test` command
+    test_parser = subparsers.add_parser("test", help="Run automated boundary tests against an API")
+    test_parser.add_argument("spec", help="Path or URL to OpenAPI JSON/YAML spec")
+    test_parser.add_argument("--base-url", help="Target API base URL (e.g. http://localhost:8000)")
+    test_parser.add_argument("--timeout", type=float, default=10.0, help="HTTP request timeout in seconds")
+    test_parser.add_argument("--fail-on-500", action="store_true", default=True, help="Exit with code 1 on HTTP 500 crashes")
+    test_parser.add_argument("--export-pytest", help="File path to save generated pytest test suite")
+
+    args = parser.parse_args()
+    if args.command == "test":
+        sys.exit(run_test_command(args))
+
+
+if __name__ == "__main__":
+    cli_entrypoint()

specforge/config.py

@@ -0,0 +1,42 @@
+"""Configuration models for SpecForge."""
+
+from dataclasses import dataclass, field
+from typing import Any, Literal, Optional
+
+
+@dataclass
+class SpecForgeConfig:
+    """Master configuration for SpecForge documentation and testing studio."""
+
+    title: str = "SpecForge API Studio"
+    path: str = "/docs"
+    spec_url: Optional[str] = None
+    theme: Literal["dark", "light", "auto"] = "dark"
+    enable_tests: bool = True
+    allow_mutation_fuzzing: bool = True
+    fail_on_500: bool = True
+    fail_on_leak: bool = True
+    max_string_fuzz_length: int = 1000
+    timeout_seconds: float = 10.0
+    headers: dict[str, str] = field(default_factory=dict)
+    custom_css: Optional[str] = None
+    logo_url: Optional[str] = None
+    export_pytest: bool = True
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert configuration to dictionary for injection into frontend client."""
+        return {
+            "title": self.title,
+            "path": self.path,
+            "spec_url": self.spec_url,
+            "theme": self.theme,
+            "enable_tests": self.enable_tests,
+            "allow_mutation_fuzzing": self.allow_mutation_fuzzing,
+            "fail_on_500": self.fail_on_500,
+            "fail_on_leak": self.fail_on_leak,
+            "max_string_fuzz_length": self.max_string_fuzz_length,
+            "timeout_seconds": self.timeout_seconds,
+            "headers": self.headers,
+            "logo_url": self.logo_url,
+            "export_pytest": self.export_pytest,
+        }

specforge/parser/models.py

@@ -0,0 +1,131 @@
+"""Normalized internal models for OpenAPI specs and schemas."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class ParameterLocation(str, Enum):
+    QUERY = "query"
+    PATH = "path"
+    HEADER = "header"
+    COOKIE = "cookie"
+
+
+@dataclass
+class JSONSchema:
+    """Represents a normalized JSON Schema / OpenAPI Schema object."""
+
+    type: str | list[str] | None = None
+    format: str | None = None
+    title: str | None = None
+    description: str | None = None
+    default: Any | None = None
+    example: Any | None = None
+    enum: list[Any] | None = None
+
+    # String constraints
+    min_length: int | None = None
+    max_length: int | None = None
+    pattern: str | None = None
+
+    # Numeric constraints
+    minimum: int | float | None = None
+    maximum: int | float | None = None
+    exclusive_minimum: int | float | bool | None = None
+    exclusive_maximum: int | float | bool | None = None
+    multiple_of: int | float | None = None
+
+    # Array constraints
+    items: JSONSchema | None = None
+    min_items: int | None = None
+    max_items: int | None = None
+    unique_items: bool | None = None
+
+    # Object constraints
+    properties: dict[str, JSONSchema] = field(default_factory=dict)
+    required: list[str] = field(default_factory=list)
+    additional_properties: bool | JSONSchema = True
+
+    # Polymorphism / Nullability
+    nullable: bool = False
+    all_of: list[JSONSchema] = field(default_factory=list)
+    any_of: list[JSONSchema] = field(default_factory=list)
+    one_of: list[JSONSchema] = field(default_factory=list)
+
+    raw_schema: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class Parameter:
+    """Represents an API operation parameter (query, path, header, or cookie)."""
+
+    name: str
+    location: ParameterLocation
+    required: bool = False
+    description: str | None = None
+    schema: JSONSchema | None = None
+    example: Any | None = None
+
+
+@dataclass
+class RequestBody:
+    """Represents an operation's HTTP request body definition."""
+
+    description: str | None = None
+    required: bool = False
+    content_type: str = "application/json"
+    schema: JSONSchema | None = None
+    example: Any | None = None
+
+
+@dataclass
+class ResponseDefinition:
+    """Represents an expected HTTP response definition."""
+
+    status_code: str
+    description: str = ""
+    content_type: str = "application/json"
+    schema: JSONSchema | None = None
+
+
+@dataclass
+class Operation:
+    """Represents an HTTP endpoint operation (e.g. POST /users)."""
+
+    method: str  # "get", "post", "put", "delete", "patch", etc.
+    path: str
+    operation_id: str | None = None
+    summary: str | None = None
+    description: str | None = None
+    tags: list[str] = field(default_factory=list)
+    parameters: list[Parameter] = field(default_factory=list)
+    request_body: RequestBody | None = None
+    responses: dict[str, ResponseDefinition] = field(default_factory=dict)
+
+    @property
+    def key(self) -> str:
+        """Unique identifier key for this operation."""
+        return f"{self.method.upper()} {self.path}"
+
+
+@dataclass
+class OpenAPISpec:
+    """Normalized container for an entire API specification."""
+
+    title: str = "API Documentation"
+    version: str = "1.0.0"
+    description: str = ""
+    servers: list[str] = field(default_factory=list)
+    operations: list[Operation] = field(default_factory=list)
+    raw_spec: dict[str, Any] = field(default_factory=dict)
+
+    def get_operation(self, method: str, path: str) -> Operation | None:
+        """Find an operation by method and path."""
+        target_method = method.lower()
+        for op in self.operations:
+            if op.method.lower() == target_method and op.path == path:
+                return op
+        return None

specforge/parser/openapi3.py

@@ -0,0 +1,285 @@
+"""OpenAPI 3.x and Swagger 2.0 parser that outputs normalized OpenAPISpec models."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from specforge.parser.models import (
+    JSONSchema,
+    OpenAPISpec,
+    Operation,
+    Parameter,
+    ParameterLocation,
+    RequestBody,
+    ResponseDefinition,
+)
+from specforge.parser.resolver import RefResolver
+
+
+class OpenAPIParser:
+    """Parses raw OpenAPI dictionaries into structured, dereferenced OpenAPISpec objects."""
+
+    def __init__(self, raw_spec: dict[str, Any]):
+        self.raw_spec = raw_spec
+        self.resolver = RefResolver(raw_spec)
+
+    def parse(self) -> OpenAPISpec:
+        """Execute full parsing of the OpenAPI specification."""
+        info = self.raw_spec.get("info", {})
+        title = info.get("title", "API Documentation")
+        version = info.get("version", "1.0.0")
+        description = info.get("description", "")
+
+        servers: list[str] = []
+        if "servers" in self.raw_spec and isinstance(self.raw_spec["servers"], list):
+            for s in self.raw_spec["servers"]:
+                if isinstance(s, dict) and "url" in s:
+                    servers.append(s["url"])
+        elif "host" in self.raw_spec:
+            # Swagger 2.0 fallback
+            schemes = self.raw_spec.get("schemes", ["http"])
+            host = self.raw_spec["host"]
+            base_path = self.raw_spec.get("basePath", "")
+            servers.append(f"{schemes[0]}://{host}{base_path}")
+
+        operations: list[Operation] = []
+        paths = self.raw_spec.get("paths", {})
+
+        for path, path_item in paths.items():
+            if not isinstance(path_item, dict):
+                continue
+
+            # Path-level parameters
+            path_params = path_item.get("parameters", [])
+
+            for method, op_data in path_item.items():
+                if method.lower() not in (
+                    "get", "post", "put", "delete", "patch", "options", "head", "trace"
+                ):
+                    continue
+                if not isinstance(op_data, dict):
+                    continue
+
+                operation = self._parse_operation(path, method.lower(), op_data, path_params)
+                operations.append(operation)
+
+        return OpenAPISpec(
+            title=title,
+            version=version,
+            description=description,
+            servers=servers,
+            operations=operations,
+            raw_spec=self.raw_spec,
+        )
+
+    def _parse_operation(
+        self,
+        path: str,
+        method: str,
+        op_data: dict[str, Any],
+        path_level_params: list[Any],
+    ) -> Operation:
+        """Parse a single operation item."""
+        summary = op_data.get("summary")
+        description = op_data.get("description")
+        operation_id = op_data.get("operationId")
+        tags = op_data.get("tags", [])
+
+        # Merge path-level and operation-level parameters
+        merged_params_raw = list(path_level_params) + op_data.get("parameters", [])
+        parameters: list[Parameter] = []
+
+        for p_raw in merged_params_raw:
+            derefed_param = self.resolver.dereference(p_raw)
+            if not isinstance(derefed_param, dict) or "name" not in derefed_param:
+                continue
+
+            param_loc_str = derefed_param.get("in", "query")
+            try:
+                param_loc = ParameterLocation(param_loc_str)
+            except ValueError:
+                param_loc = ParameterLocation.QUERY
+
+            schema_raw = derefed_param.get("schema", {})
+            param_schema = self._parse_schema(schema_raw) if schema_raw else None
+
+            parameters.append(
+                Parameter(
+                    name=derefed_param["name"],
+                    location=param_loc,
+                    required=derefed_param.get("required", False),
+                    description=derefed_param.get("description"),
+                    schema=param_schema,
+                    example=derefed_param.get("example"),
+                )
+            )
+
+        # Parse request body (OpenAPI 3.x)
+        request_body: RequestBody | None = None
+        if "requestBody" in op_data:
+            rb_raw = self.resolver.dereference(op_data["requestBody"])
+            if isinstance(rb_raw, dict):
+                content = rb_raw.get("content", {})
+                content_type = "application/json"
+                body_schema_raw = None
+
+                if "application/json" in content:
+                    content_type = "application/json"
+                    body_schema_raw = content["application/json"].get("schema")
+                elif content:
+                    content_type = next(iter(content.keys()))
+                    body_schema_raw = content[content_type].get("schema")
+
+                parsed_schema = (
+                    self._parse_schema(body_schema_raw) if body_schema_raw else None
+                )
+                request_body = RequestBody(
+                    description=rb_raw.get("description"),
+                    required=rb_raw.get("required", False),
+                    content_type=content_type,
+                    schema=parsed_schema,
+                )
+
+        # Parse responses
+        responses: dict[str, ResponseDefinition] = {}
+        for status_code, resp_raw in op_data.get("responses", {}).items():
+            derefed_resp = self.resolver.dereference(resp_raw)
+            if not isinstance(derefed_resp, dict):
+                continue
+
+            resp_desc = derefed_resp.get("description", "")
+            resp_content = derefed_resp.get("content", {})
+            resp_schema = None
+            resp_content_type = "application/json"
+
+            if "application/json" in resp_content:
+                resp_schema_raw = resp_content["application/json"].get("schema")
+                if resp_schema_raw:
+                    resp_schema = self._parse_schema(resp_schema_raw)
+            elif resp_content:
+                resp_content_type = next(iter(resp_content.keys()))
+                resp_schema_raw = resp_content[resp_content_type].get("schema")
+                if resp_schema_raw:
+                    resp_schema = self._parse_schema(resp_schema_raw)
+
+            responses[str(status_code)] = ResponseDefinition(
+                status_code=str(status_code),
+                description=resp_desc,
+                content_type=resp_content_type,
+                schema=resp_schema,
+            )
+
+        return Operation(
+            method=method,
+            path=path,
+            operation_id=operation_id,
+            summary=summary,
+            description=description,
+            tags=tags,
+            parameters=parameters,
+            request_body=request_body,
+            responses=responses,
+        )
+
+    def _parse_schema(self, schema_raw: Any) -> JSONSchema:
+        """Convert a raw dereferenced schema dictionary into a typed JSONSchema."""
+        derefed = self.resolver.dereference(schema_raw)
+        if not isinstance(derefed, dict):
+            return JSONSchema(raw_schema={})
+
+        schema_type = derefed.get("type")
+        format_val = derefed.get("format")
+        title = derefed.get("title")
+        description = derefed.get("description")
+        default = derefed.get("default")
+        example = derefed.get("example")
+        enum = derefed.get("enum")
+
+        # String constraints
+        min_length = derefed.get("minLength")
+        max_length = derefed.get("maxLength")
+        pattern = derefed.get("pattern")
+
+        # Numeric constraints
+        minimum = derefed.get("minimum")
+        maximum = derefed.get("maximum")
+        exclusive_minimum = derefed.get("exclusiveMinimum")
+        exclusive_maximum = derefed.get("exclusiveMaximum")
+        multiple_of = derefed.get("multipleOf")
+
+        # Array constraints
+        items_schema = None
+        if "items" in derefed:
+            items_schema = self._parse_schema(derefed["items"])
+        min_items = derefed.get("minItems")
+        max_items = derefed.get("maxItems")
+        unique_items = derefed.get("uniqueItems")
+
+        # Object constraints
+        properties: dict[str, JSONSchema] = {}
+        for prop_name, prop_raw in derefed.get("properties", {}).items():
+            properties[prop_name] = self._parse_schema(prop_raw)
+
+        required = derefed.get("required", [])
+        if not isinstance(required, list):
+            required = []
+
+        additional_properties_raw = derefed.get("additionalProperties", True)
+        additional_properties: bool | JSONSchema
+        if isinstance(additional_properties_raw, dict):
+            additional_properties = self._parse_schema(additional_properties_raw)
+        else:
+            additional_properties = bool(additional_properties_raw)
+
+        nullable = bool(derefed.get("nullable", False))
+
+        # Handle allOf merging if present
+        all_of: list[JSONSchema] = []
+        if "allOf" in derefed and isinstance(derefed["allOf"], list):
+            all_of = [self._parse_schema(item) for item in derefed["allOf"]]
+            # Inherit properties from allOf members
+            for parent_schema in all_of:
+                for k, v in parent_schema.properties.items():
+                    if k not in properties:
+                        properties[k] = v
+                for req_item in parent_schema.required:
+                    if req_item not in required:
+                        required.append(req_item)
+
+        any_of: list[JSONSchema] = []
+        if "anyOf" in derefed and isinstance(derefed["anyOf"], list):
+            any_of = [self._parse_schema(item) for item in derefed["anyOf"]]
+
+        one_of: list[JSONSchema] = []
+        if "oneOf" in derefed and isinstance(derefed["oneOf"], list):
+            one_of = [self._parse_schema(item) for item in derefed["oneOf"]]
+
+        return JSONSchema(
+            type=schema_type,
+            format=format_val,
+            title=title,
+            description=description,
+            default=default,
+            example=example,
+            enum=enum,
+            min_length=min_length,
+            max_length=max_length,
+            pattern=pattern,
+            minimum=minimum,
+            maximum=maximum,
+            exclusive_minimum=exclusive_minimum,
+            exclusive_maximum=exclusive_maximum,
+            multiple_of=multiple_of,
+            items=items_schema,
+            min_items=min_items,
+            max_items=max_items,
+            unique_items=unique_items,
+            properties=properties,
+            required=required,
+            additional_properties=additional_properties,
+            nullable=nullable,
+            all_of=all_of,
+            any_of=any_of,
+            one_of=one_of,
+            raw_schema=derefed,
+        )