specforge-api 0.1.0__tar.gz

specforge_api-0.1.0/.gitignore

@@ -0,0 +1,40 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+.eggs/
+
+# Virtual Environments
+.venv/
+venv/
+env/
+ENV/
+
+# Testing & Coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# Frontend / Node
+frontend/node_modules/
+frontend/dist/
+frontend/.turbo/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# IDE & OS
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db

specforge_api-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SpecForge Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

specforge_api-0.1.0/PKG-INFO

@@ -0,0 +1,260 @@
+Metadata-Version: 2.5
+Name: specforge-api
+Version: 0.1.0
+Summary: The interactive API client and automated contract testing engine for Python.
+Project-URL: Homepage, https://github.com/specforge-api/specforge
+Project-URL: Documentation, https://github.com/specforge-api/specforge#readme
+Project-URL: Repository, https://github.com/specforge-api/specforge
+Project-URL: Issues, https://github.com/specforge-api/specforge/issues
+Author: SpecForge Team
+License: MIT License
+        
+        Copyright (c) 2026 SpecForge Contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: api-client,contract-testing,fastapi,fuzzing,openapi,pytest,swagger,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: all
+Requires-Dist: fastapi>=0.100.0; extra == 'all'
+Requires-Dist: flask>=2.0.0; extra == 'all'
+Requires-Dist: rich>=13.0.0; extra == 'all'
+Requires-Dist: typer>=0.9.0; extra == 'all'
+Provides-Extra: cli
+Requires-Dist: rich>=13.0.0; extra == 'cli'
+Requires-Dist: typer>=0.9.0; extra == 'cli'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.5.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100.0; extra == 'fastapi'
+Provides-Extra: flask
+Requires-Dist: flask>=2.0.0; extra == 'flask'
+Description-Content-Type: text/markdown
+
+# SpecForge ⚡
+
+[![PyPI version](https://img.shields.io/pypi/v/specforge-api.svg)](https://pypi.org/project/specforge-api/)
+[![Python versions](https://img.shields.io/pypi/pyversions/specforge-api.svg)](https://pypi.org/project/specforge-api/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+**The Interactive API Client & Automated Contract Testing Engine for Python.**
+
+A modern, drop-in Python library that replaces Swagger UI with a beautiful, responsive API workspace **and** automatically discovers boundary vulnerabilities, missing whitespace stripping, and unhandled 500 server crashes directly against your endpoints.
+
+---
+
+## 🚀 Why SpecForge?
+
+1. **Active Quality Gate, Not Just Passive Docs**: Traditional tools like Swagger UI only show the "happy path". SpecForge algorithmically analyzes your schema constraints and runs targeted boundary fuzzing right in your browser.
+2. **"Zero 500s" Invariant**: Verifies that edge-case inputs (e.g. `"   "`, empty strings, off-by-one numbers, malformed emails) return clean client errors (`422/400`), never unhandled server exceptions (`500`).
+3. **One-Click Pytest Exporter**: Discovered edge cases can be instantly exported into commit-ready `test_api_contracts.py` files with `@pytest.mark.parametrize`.
+4. **Zero Frontend Build Dependencies**: The interactive workspace is fully compiled and inlined into the Python package. No Node.js or npm needed on your machine.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install specforge-api
+```
+
+With framework extras:
+```bash
+pip install "specforge-api[fastapi]"   # FastAPI
+pip install "specforge-api[flask]"     # Flask
+pip install "specforge-api[all]"       # Full CLI & all framework adapters
+```
+
+---
+
+## ⚡ Quickstart
+
+### FastAPI
+
+```python
+from fastapi import FastAPI
+from specforge import SpecForge
+
+app = FastAPI(title="My API", version="1.0.0")
+
+# Mount SpecForge (auto-detects /openapi.json)
+SpecForge(app)
+
+@app.post("/users")
+def create_user(username: str, age: int):
+    return {"status": "created", "username": username}
+```
+
+Now open `http://localhost:8000/docs` in your browser. You get:
+- A modern, interactive dark/light mode API client (Try-It-Out, request history, multi-language code snippets).
+- An integrated **Boundary & Contract Testing Tab** to run automated fuzzing on all endpoints with one click.
+
+---
+
+### Flask
+
+```python
+from flask import Flask
+from specforge.flask import SpecForge
+
+app = Flask(__name__)
+
+# Register Blueprint
+SpecForge(app, spec_url="/api/spec.json", path="/docs")
+```
+
+---
+
+## 🧪 Schema-Aware Boundary Fuzzing
+
+SpecForge generates targeted test cases according to field types:
+
+| Field Type | Automated Test Coverage |
+|---|---|
+| **String** | Rejecting whitespace-only (`"   "`), empty strings (`""`), min/max bounds, Unicode 4-byte emojis, null bytes (`\x00`), format violations (email, uuid, datetime), and injection probes. |
+| **Number / Integer** | Boundary checks (`min - 1`, `max + 1`), negative values on unsigned fields, zero checks, float-into-integer pollution, and integer overflow. |
+| **Boolean** | Strict type testing vs loose coercion (`"true"`, `"yes"`, `1`, `0`, `null`). |
+| **Array** | Empty lists (`[]`), `minItems` / `maxItems` boundaries, and `uniqueItems: true` duplicates. |
+| **Object** | Combinatorial required field omission, extra unexpected keys (`additionalProperties: false`), and empty bodies. |
+
+---
+
+## 📁 Integrating Existing Project Tests
+
+If your repository already contains test suites (written in `pytest` or `unittest`), SpecForge can automatically index and display them in a dedicated **Project Tests** tab and link them directly to their corresponding API routes.
+
+### Quick Setup
+
+Pass `test_paths` when mounting SpecForge in your application:
+
+```python
+from fastapi import FastAPI
+from specforge import SpecForge
+
+app = FastAPI()
+
+# Mount SpecForge with existing project tests
+SpecForge(
+    app,
+    test_paths=["tests"],  # Can be directories or individual test files
+)
+```
+
+Now open `/docs` to see:
+- **📁 Project Tests Tab**: Browse all repository tests, file paths, line numbers, docstrings, and parameter matrices.
+- **Route Coverage Linking**: View your existing tests directly inside the API Explorer alongside SpecForge's automated boundary fuzzers.
+
+### Linking Tests to API Routes
+
+SpecForge associates existing tests with OpenAPI routes using two mechanisms:
+
+#### 1. Automatic HTTP Client Detection (Zero Configuration)
+If your test uses `TestClient`, `httpx`, or `requests` to call an API path, SpecForge automatically recognizes the route:
+```python
+def test_user_creation_underage(client):
+    """Rejects underage registrations."""
+    response = client.post("/api/v1/users", json={"username": "bob", "age": 16})
+    assert response.status_code == 422
+```
+
+#### 2. Explicit Pytest Marker (Recommended for Complex Tests)
+For tests with dynamic URLs or mocks, declare the endpoint explicitly:
+```python
+import pytest
+
+@pytest.mark.endpoint("POST", "/api/v1/users")
+def test_user_signup_pipeline():
+    """End-to-end user registration and event dispatch."""
+    ...
+```
+
+### 🔒 Security & Zero-Execution Guarantee
+
+SpecForge uses **Python Static Abstract Syntax Tree (AST) parsing** to discover tests:
+- **Zero Code Execution**: SpecForge **never** imports or executes your test files. Tests are analyzed purely as static syntax trees.
+- **No Side Effects**: Discovering tests will never trigger database operations, background tasks, or network calls.
+- **Path Sandboxing**: Scanned paths are strictly verified to remain within the project root directory, preventing any path traversal.
+
+---
+
+## 🛠️ CLI & CI/CD Pipeline
+
+Run headless contract fuzzing in your continuous integration pipeline:
+
+```bash
+specforge test http://localhost:8000/openapi.json --fail-on-500
+```
+
+---
+
+## 💻 Local Development & Testing Guide
+
+### 1. Run the Interactive Live Demo (Zero Dependencies)
+You can launch and explore SpecForge immediately using Python's standard library:
+```bash
+python examples/standalone_demo.py
+```
+Open **`http://localhost:8000/docs`** in your browser to:
+- Test API endpoints and inspect formatted JSON responses.
+- Click **"⚡ Run Boundary Test Suite"** to watch automated fuzzing of whitespace strings, negative numbers, and missing fields.
+- Click **"🐍 Export to Pytest"** to view and copy auto-generated test code.
+
+### 2. Run the Automated Unit Test Suite
+```bash
+pytest -v
+```
+
+### 3. Install in Another Project Locally (Editable Mode)
+To use this local version inside any other Python app on your machine without publishing to PyPI:
+```bash
+# In your other project's directory and virtualenv:
+pip install -e c:\Research-projects\specforge
+```
+*Any change you make in SpecForge source code will instantly reflect in your other application without reinstalling!*
+
+### 4. Build a Distribution Wheel (.whl)
+```bash
+pip install build
+python -m build
+# Outputs wheel file in dist/specforge-0.1.0-py3-none-any.whl
+```
+
+---
+
+## 📄 License
+
+SpecForge is licensed under the [MIT License](LICENSE).

specforge_api-0.1.0/README.md

@@ -0,0 +1,193 @@
+# SpecForge ⚡
+
+[![PyPI version](https://img.shields.io/pypi/v/specforge-api.svg)](https://pypi.org/project/specforge-api/)
+[![Python versions](https://img.shields.io/pypi/pyversions/specforge-api.svg)](https://pypi.org/project/specforge-api/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+**The Interactive API Client & Automated Contract Testing Engine for Python.**
+
+A modern, drop-in Python library that replaces Swagger UI with a beautiful, responsive API workspace **and** automatically discovers boundary vulnerabilities, missing whitespace stripping, and unhandled 500 server crashes directly against your endpoints.
+
+---
+
+## 🚀 Why SpecForge?
+
+1. **Active Quality Gate, Not Just Passive Docs**: Traditional tools like Swagger UI only show the "happy path". SpecForge algorithmically analyzes your schema constraints and runs targeted boundary fuzzing right in your browser.
+2. **"Zero 500s" Invariant**: Verifies that edge-case inputs (e.g. `"   "`, empty strings, off-by-one numbers, malformed emails) return clean client errors (`422/400`), never unhandled server exceptions (`500`).
+3. **One-Click Pytest Exporter**: Discovered edge cases can be instantly exported into commit-ready `test_api_contracts.py` files with `@pytest.mark.parametrize`.
+4. **Zero Frontend Build Dependencies**: The interactive workspace is fully compiled and inlined into the Python package. No Node.js or npm needed on your machine.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install specforge-api
+```
+
+With framework extras:
+```bash
+pip install "specforge-api[fastapi]"   # FastAPI
+pip install "specforge-api[flask]"     # Flask
+pip install "specforge-api[all]"       # Full CLI & all framework adapters
+```
+
+---
+
+## ⚡ Quickstart
+
+### FastAPI
+
+```python
+from fastapi import FastAPI
+from specforge import SpecForge
+
+app = FastAPI(title="My API", version="1.0.0")
+
+# Mount SpecForge (auto-detects /openapi.json)
+SpecForge(app)
+
+@app.post("/users")
+def create_user(username: str, age: int):
+    return {"status": "created", "username": username}
+```
+
+Now open `http://localhost:8000/docs` in your browser. You get:
+- A modern, interactive dark/light mode API client (Try-It-Out, request history, multi-language code snippets).
+- An integrated **Boundary & Contract Testing Tab** to run automated fuzzing on all endpoints with one click.
+
+---
+
+### Flask
+
+```python
+from flask import Flask
+from specforge.flask import SpecForge
+
+app = Flask(__name__)
+
+# Register Blueprint
+SpecForge(app, spec_url="/api/spec.json", path="/docs")
+```
+
+---
+
+## 🧪 Schema-Aware Boundary Fuzzing
+
+SpecForge generates targeted test cases according to field types:
+
+| Field Type | Automated Test Coverage |
+|---|---|
+| **String** | Rejecting whitespace-only (`"   "`), empty strings (`""`), min/max bounds, Unicode 4-byte emojis, null bytes (`\x00`), format violations (email, uuid, datetime), and injection probes. |
+| **Number / Integer** | Boundary checks (`min - 1`, `max + 1`), negative values on unsigned fields, zero checks, float-into-integer pollution, and integer overflow. |
+| **Boolean** | Strict type testing vs loose coercion (`"true"`, `"yes"`, `1`, `0`, `null`). |
+| **Array** | Empty lists (`[]`), `minItems` / `maxItems` boundaries, and `uniqueItems: true` duplicates. |
+| **Object** | Combinatorial required field omission, extra unexpected keys (`additionalProperties: false`), and empty bodies. |
+
+---
+
+## 📁 Integrating Existing Project Tests
+
+If your repository already contains test suites (written in `pytest` or `unittest`), SpecForge can automatically index and display them in a dedicated **Project Tests** tab and link them directly to their corresponding API routes.
+
+### Quick Setup
+
+Pass `test_paths` when mounting SpecForge in your application:
+
+```python
+from fastapi import FastAPI
+from specforge import SpecForge
+
+app = FastAPI()
+
+# Mount SpecForge with existing project tests
+SpecForge(
+    app,
+    test_paths=["tests"],  # Can be directories or individual test files
+)
+```
+
+Now open `/docs` to see:
+- **📁 Project Tests Tab**: Browse all repository tests, file paths, line numbers, docstrings, and parameter matrices.
+- **Route Coverage Linking**: View your existing tests directly inside the API Explorer alongside SpecForge's automated boundary fuzzers.
+
+### Linking Tests to API Routes
+
+SpecForge associates existing tests with OpenAPI routes using two mechanisms:
+
+#### 1. Automatic HTTP Client Detection (Zero Configuration)
+If your test uses `TestClient`, `httpx`, or `requests` to call an API path, SpecForge automatically recognizes the route:
+```python
+def test_user_creation_underage(client):
+    """Rejects underage registrations."""
+    response = client.post("/api/v1/users", json={"username": "bob", "age": 16})
+    assert response.status_code == 422
+```
+
+#### 2. Explicit Pytest Marker (Recommended for Complex Tests)
+For tests with dynamic URLs or mocks, declare the endpoint explicitly:
+```python
+import pytest
+
+@pytest.mark.endpoint("POST", "/api/v1/users")
+def test_user_signup_pipeline():
+    """End-to-end user registration and event dispatch."""
+    ...
+```
+
+### 🔒 Security & Zero-Execution Guarantee
+
+SpecForge uses **Python Static Abstract Syntax Tree (AST) parsing** to discover tests:
+- **Zero Code Execution**: SpecForge **never** imports or executes your test files. Tests are analyzed purely as static syntax trees.
+- **No Side Effects**: Discovering tests will never trigger database operations, background tasks, or network calls.
+- **Path Sandboxing**: Scanned paths are strictly verified to remain within the project root directory, preventing any path traversal.
+
+---
+
+## 🛠️ CLI & CI/CD Pipeline
+
+Run headless contract fuzzing in your continuous integration pipeline:
+
+```bash
+specforge test http://localhost:8000/openapi.json --fail-on-500
+```
+
+---
+
+## 💻 Local Development & Testing Guide
+
+### 1. Run the Interactive Live Demo (Zero Dependencies)
+You can launch and explore SpecForge immediately using Python's standard library:
+```bash
+python examples/standalone_demo.py
+```
+Open **`http://localhost:8000/docs`** in your browser to:
+- Test API endpoints and inspect formatted JSON responses.
+- Click **"⚡ Run Boundary Test Suite"** to watch automated fuzzing of whitespace strings, negative numbers, and missing fields.
+- Click **"🐍 Export to Pytest"** to view and copy auto-generated test code.
+
+### 2. Run the Automated Unit Test Suite
+```bash
+pytest -v
+```
+
+### 3. Install in Another Project Locally (Editable Mode)
+To use this local version inside any other Python app on your machine without publishing to PyPI:
+```bash
+# In your other project's directory and virtualenv:
+pip install -e c:\Research-projects\specforge
+```
+*Any change you make in SpecForge source code will instantly reflect in your other application without reinstalling!*
+
+### 4. Build a Distribution Wheel (.whl)
+```bash
+pip install build
+python -m build
+# Outputs wheel file in dist/specforge-0.1.0-py3-none-any.whl
+```
+
+---
+
+## 📄 License
+
+SpecForge is licensed under the [MIT License](LICENSE).

specforge_api-0.1.0/pyproject.toml

@@ -0,0 +1,100 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "specforge-api"
+version = "0.1.0"
+description = "The interactive API client and automated contract testing engine for Python."
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.9"
+authors = [
+    { name = "SpecForge Team" }
+]
+keywords = [
+    "openapi",
+    "swagger",
+    "fastapi",
+    "testing",
+    "contract-testing",
+    "fuzzing",
+    "api-client",
+    "pytest"
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Testing",
+    "Topic :: Internet :: WWW/HTTP :: HTTP Servers",
+]
+dependencies = [
+    "httpx>=0.24.0",
+    "pydantic>=2.0.0",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.100.0"]
+flask = ["flask>=2.0.0"]
+cli = ["typer>=0.9.0", "rich>=13.0.0"]
+all = [
+    "fastapi>=0.100.0",
+    "flask>=2.0.0",
+    "typer>=0.9.0",
+    "rich>=13.0.0"
+]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-asyncio>=0.21.0",
+    "ruff>=0.1.0",
+    "mypy>=1.5.0",
+    "types-pyyaml",
+]
+
+[project.scripts]
+specforge = "specforge.cli.main:cli_entrypoint"
+
+[project.urls]
+Homepage = "https://github.com/specforge-api/specforge"
+Documentation = "https://github.com/specforge-api/specforge#readme"
+Repository = "https://github.com/specforge-api/specforge"
+Issues = "https://github.com/specforge-api/specforge/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/specforge"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/README.md",
+    "/LICENSE",
+    "/pyproject.toml"
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+ignore = ["E501"]
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = false
+warn_unused_configs = true
+disallow_untyped_defs = false
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+asyncio_mode = "auto"

specforge_api-0.1.0/src/specforge/__init__.py

@@ -0,0 +1,23 @@
+"""SpecForge: The Interactive API Client & Automated Contract Testing Engine for Python."""
+
+from specforge.config import SpecForgeConfig
+from specforge.parser.openapi3 import OpenAPIParser
+from specforge.testing.exporters.pytest_export import PytestExporter
+from specforge.testing.planner import TestPlanner
+
+__version__ = "0.1.0"
+
+# Conditionally import FastAPI adapter if available
+try:
+    from specforge.adapters.fastapi import SpecForge
+except ImportError:
+    SpecForge = None  # type: ignore
+
+__all__ = [
+    "SpecForge",
+    "SpecForgeConfig",
+    "OpenAPIParser",
+    "TestPlanner",
+    "PytestExporter",
+    "__version__",
+]