forge-doctor-api 0.2.0__tar.gz

forge_doctor_api-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Edgar Sócrates Caria
+
+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.

forge_doctor_api-0.2.0/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: forge-doctor-api
+Version: 0.2.0
+Summary: Deterministic, offline-first, evidence-first API architecture intelligence engine.
+License: MIT
+License-File: LICENSE
+Author: Edgar Sócrates Caria
+Requires-Python: >=3.11
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Provides-Extra: graphql
+Provides-Extra: mcp
+Requires-Dist: graphql-core (>=3.2,<4) ; extra == "graphql"
+Requires-Dist: mcp (>=2.0,<3) ; extra == "mcp"
+Requires-Dist: pyyaml (>=6.0)
+Requires-Dist: rich (>=15.0.0)
+Requires-Dist: typer (>=0.12)
+Description-Content-Type: text/markdown
+
+
+> Instalação portátil: [`docs/installation/quickstart.md`](docs/installation/quickstart.md) — clone → setup → install. Delegação agêntica: [forge.agentic.json](forge.agentic.json) (SpecialistAgenticManifest/v1).
+> Docs: [commands](docs/reference/commands.md) · [skills](docs/reference/skills.md) · [agents](docs/reference/agents.md) · [tutorial](docs/tutorials/first-run.md) · [economy](docs/economy.md) · [troubleshooting](docs/installation/troubleshooting.md)
+<p align="center">
+  <img src="docs/assets/logo.png" alt="Forge Doctor API" width="440">
+</p>
+
+# Forge Doctor API
+
+Deterministic, offline-first, evidence-first engine for API architecture
+intelligence.
+
+Forge Doctor ("the Doctor") inspects API projects — contracts, source
+code, configuration, and exported runtime artifacts — and produces
+structured, evidence-bearing findings. It never calls a model, never
+fetches a URL, and never guesses: anything it cannot establish from
+local evidence is surfaced as an explicit `UnknownFact`.
+
+Status: `0.2.0` — the full deterministic surface is implemented (scan,
+diff, diagnose, inventory, lab, handoff). This is **not** a stable public
+API commitment; interfaces may still change before 1.0.
+
+## Design principles
+
+| Principle | What it means in practice |
+|---|---|
+| Deterministic | Same inputs → byte-identical findings, ordering, and exports. No LLM calls anywhere. |
+| Offline-first | Zero network access. Host interaction happens only through `ProjectContext`. Tests hard-block sockets. |
+| Evidence-first | Every finding carries `Evidence` (file + line + summary) and a `Confidence` (`HIGH`/`MEDIUM`/`LOW`/`UNKNOWN`). |
+| Low false positives | Passive/absence-of-evidence cases are emitted as *candidates*, never as verdicts. |
+| Explicit unknowns | Missing files, unresolvable references, dynamic code → `UnknownFact` records, not silence. |
+| Portable | Pure Python, no platform-specific imports; supports Python 3.11/3.12/3.13 on Linux/Windows/macOS. |
+
+The Doctor is the **deterministic** half of the Forge product family:
+it observes and classifies. Agentic code generation lives in `api-forge`
+(a separate project); this repository has no dependency on it.
+
+## Installation
+
+```bash
+pip install .            # runtime deps: typer, rich, pyyaml
+pip install .[graphql]   # optional: graphql-core for GraphQL parsing
+```
+
+Requirements: Python >= 3.11. For development:
+
+```bash
+pip install pytest ruff mypy types-PyYAML build
+python -m pytest -q
+python -m ruff check .
+python -m mypy src
+```
+
+### Portable install (Forge contract)
+
+The checkout also carries the Forge family's portable-installation
+contract — clone once, setup once:
+
+```bash
+./setup.sh          # or .\setup.ps1 — venv + wheel + ~/.forge registry
+```
+
+Installing the Forge into a *consumer* project (managed `.mcp.json` key +
+`AGENTS.md` marker block, sha256-ledgered) is deliberately a **checkout
+script**, not a `forge-doctor-api` verb: the package boundary bans
+`os`/`subprocess` imports across `src/` and the 0.2.0 RC window forbids
+new CLI commands. Same verbs, same receipts as sibling forges:
+
+```bash
+python scripts/forge_install.py install --dry-run   # plan only
+python scripts/forge_install.py install --yes       # apply to a repo
+python scripts/forge_install.py status|doctor|repair
+python scripts/forge_install.py uninstall [--purge]
+python scripts/forge_install.py update|mcp-verify
+
+# Optional local web UI over the same real services (127.0.0.1, session token)
+python scripts/forge_portal.py [--no-browser] [--port N] [--root DIR]
+```
+
+`theforge install auto` delegates here automatically via the
+`install_command` field in `forge.json`.
+
+## Quickstart
+
+```bash
+# Full deterministic scan of a project directory
+forge-doctor-api scan ./my-service
+
+# Scan + CI gate: fail on new breaking changes vs a baseline contract
+forge-doctor-api scan ./my-service --fail-on breaking --baseline ./last-release
+
+# Emit SARIF for GitHub code scanning, or a compact agent-readable format
+forge-doctor-api scan . --format sarif --out results.sarif
+forge-doctor-api scan . --format agent
+```
+
+Exit codes: `0` scan ran and gate passed · `1` gate failed ·
+`2` usage/misconfiguration error.
+
+## Command tour
+
+```text
+forge-doctor-api scan TARGET        all pipelines + optional §178 gate
+forge-doctor-api inventory TARGET   fleet answers over a workspace or repo
+forge-doctor-api diff OLD NEW       semantic contract diff + typed events
+forge-doctor-api diff OLD NEW --pr  + PR-intel summary and blast radius
+forge-doctor-api fingerprint FILE   semantic fingerprint of a contract
+forge-doctor-api graph TARGET       merged contract/route/client graph
+forge-doctor-api blast-radius O N   operation → clients → services impact
+forge-doctor-api diagnose TARGET    root-cause episodes from evidence
+forge-doctor-api explain DIR TOKEN  evidence chain for one finding
+forge-doctor-api lab [labs]         Forge Lab corpus: precision/recall
+forge-doctor-api contract diff O N  contract-level diff
+forge-doctor-api contract compat …  compatibility classification
+forge-doctor-api runtime requests   per-request execution table
+forge-doctor-api runtime baseline   performance baselines per endpoint
+forge-doctor-api runtime regress…   regressions vs baseline
+forge-doctor-api security inspect   passive security evidence + findings
+forge-doctor-api reliability inspect  timeouts/retries/idempotency/SLOs
+forge-doctor-api reliability path     hop-by-hop effective policy
+```
+
+`--help` on any command lists its options. See
+[docs/cli.md](docs/cli.md) for the full reference.
+
+## What it understands
+
+- **Contracts**: OpenAPI 3.x (YAML/JSON), AsyncAPI, GraphQL SDL +
+  introspection, gRPC `.proto`.
+- **Source**: FastAPI route discovery, client call-site extraction
+  (Python/JS/TS), GraphQL client queries (`gql` tagged literals).
+- **Config**: timeouts, retries, rate limits, idempotency headers,
+  authentication/CORS/mTLS/TLS evidence, gateway routes, ownership
+  files, policy files.
+- **Runtime**: OTLP/OTEL JSON traces, access-log records — ingested as
+  compact per-request summaries (raw spans are not retained).
+
+From those inputs it produces: OAS/ASYNC/GQL/GRPC contract checks,
+contract-drift and semantic compatibility diffs, client impact and blast
+radius, versioning/deprecation analysis, observability + performance
+regression findings, reliability checks (retry amplification, SLO
+budgets), passive OWASP API Top-10 candidates, policy violations, an API
+digital twin, root-cause diagnosis, safe-fix classification, multi-repo
+workspace analysis, fleet intelligence, migration portability
+assessments, and compact handoff bundles for agentic tools.
+
+## Documentation
+
+- [docs/architecture.md](docs/architecture.md) — pipeline layout, models, determinism contract
+- [docs/cli.md](docs/cli.md) — every command, option, and exit code
+- [docs/output-formats.md](docs/output-formats.md) — console/JSON/JSONL/SARIF/agent + CI gate
+- [docs/checks.md](docs/checks.md) — finding model, namespaces, confidence semantics
+- [docs/compatibility.md](docs/compatibility.md) — cross-protocol diff taxonomy, decision tables, client-impact coverage
+- [docs/runtime-evidence.md](docs/runtime-evidence.md) — trace/log ingestion, history, perf & SLOs
+- [docs/runtime-scale.md](docs/runtime-scale.md) — streaming bounds, memory curve, perf budget gate, snapshot formats
+- [docs/policies.md](docs/policies.md) — policy files, inheritance, exceptions, ownership
+- [docs/workspace-fleet.md](docs/workspace-fleet.md) — multi-repo manifests + inventory
+- [docs/knowledge-packs.md](docs/knowledge-packs.md) — versioned knowledge data + plugin SDK
+- [docs/migration.md](docs/migration.md) — portability assessments + decision briefs
+- [docs/handoff.md](docs/handoff.md) — `ApiHandoffBundle`, `DoctorApi`, Forger routing
+- [docs/infrastructure.md](docs/infrastructure.md) — gateway/mesh declared config + Kubernetes/IaC evidence
+- [docs/cache.md](docs/cache.md) — declared cache policies, layers, invalidation risk
+- [docs/lab.md](docs/lab.md) — Forge Lab corpus, ground truth, precision/recall
+- [docs/output-contract.md](docs/output-contract.md) — v1 export schemas (json/jsonl/sarif/agent/report) + evolution rules
+- [docs/forger-boundary.md](docs/forger-boundary.md) — Doctor ↔ API Forge ↔ The Forger typed boundary
+- [docs/release-policy.md](docs/release-policy.md) — versioning, public surfaces, release checklist, SBOM
+- [docs/release-v0.1.md](docs/release-v0.1.md) — quality gate, packaging, hermetic proofs
+- [docs/roadmap.md](docs/roadmap.md) — shipped coverage vs planned waves
+- [docs/adr/](docs/adr/) — architecture decision records
+- [docs/development.md](docs/development.md) — repo layout, test/lint/typecheck, adding a check
+
+## Repository layout
+
+```text
+src/forge_doctor_api/   engine (analyzers, checks, models, CLI)
+tests/                  pytest suite (offline-blocked sockets)
+labs/                   Forge Lab corpus: golden + adversarial fixtures
+factory/                Loop Factory specs, run records, quality gate
+.github/workflows/      doctor-scan.yml CI gate
+docs/                   documentation
+```
+
+## Graph Studio
+
+`forge-doctor-api graph . --view|--ui` projects the service graph through
+`forge/ForgeGraphView/v1` and serves the embedded local explorer (declinable at
+install via `--components`). Full docs: `the-forge/docs/graph-studio/`.
+

forge_doctor_api-0.2.0/README.md

@@ -0,0 +1,187 @@
+
+> Instalação portátil: [`docs/installation/quickstart.md`](docs/installation/quickstart.md) — clone → setup → install. Delegação agêntica: [forge.agentic.json](forge.agentic.json) (SpecialistAgenticManifest/v1).
+> Docs: [commands](docs/reference/commands.md) · [skills](docs/reference/skills.md) · [agents](docs/reference/agents.md) · [tutorial](docs/tutorials/first-run.md) · [economy](docs/economy.md) · [troubleshooting](docs/installation/troubleshooting.md)
+<p align="center">
+  <img src="docs/assets/logo.png" alt="Forge Doctor API" width="440">
+</p>
+
+# Forge Doctor API
+
+Deterministic, offline-first, evidence-first engine for API architecture
+intelligence.
+
+Forge Doctor ("the Doctor") inspects API projects — contracts, source
+code, configuration, and exported runtime artifacts — and produces
+structured, evidence-bearing findings. It never calls a model, never
+fetches a URL, and never guesses: anything it cannot establish from
+local evidence is surfaced as an explicit `UnknownFact`.
+
+Status: `0.2.0` — the full deterministic surface is implemented (scan,
+diff, diagnose, inventory, lab, handoff). This is **not** a stable public
+API commitment; interfaces may still change before 1.0.
+
+## Design principles
+
+| Principle | What it means in practice |
+|---|---|
+| Deterministic | Same inputs → byte-identical findings, ordering, and exports. No LLM calls anywhere. |
+| Offline-first | Zero network access. Host interaction happens only through `ProjectContext`. Tests hard-block sockets. |
+| Evidence-first | Every finding carries `Evidence` (file + line + summary) and a `Confidence` (`HIGH`/`MEDIUM`/`LOW`/`UNKNOWN`). |
+| Low false positives | Passive/absence-of-evidence cases are emitted as *candidates*, never as verdicts. |
+| Explicit unknowns | Missing files, unresolvable references, dynamic code → `UnknownFact` records, not silence. |
+| Portable | Pure Python, no platform-specific imports; supports Python 3.11/3.12/3.13 on Linux/Windows/macOS. |
+
+The Doctor is the **deterministic** half of the Forge product family:
+it observes and classifies. Agentic code generation lives in `api-forge`
+(a separate project); this repository has no dependency on it.
+
+## Installation
+
+```bash
+pip install .            # runtime deps: typer, rich, pyyaml
+pip install .[graphql]   # optional: graphql-core for GraphQL parsing
+```
+
+Requirements: Python >= 3.11. For development:
+
+```bash
+pip install pytest ruff mypy types-PyYAML build
+python -m pytest -q
+python -m ruff check .
+python -m mypy src
+```
+
+### Portable install (Forge contract)
+
+The checkout also carries the Forge family's portable-installation
+contract — clone once, setup once:
+
+```bash
+./setup.sh          # or .\setup.ps1 — venv + wheel + ~/.forge registry
+```
+
+Installing the Forge into a *consumer* project (managed `.mcp.json` key +
+`AGENTS.md` marker block, sha256-ledgered) is deliberately a **checkout
+script**, not a `forge-doctor-api` verb: the package boundary bans
+`os`/`subprocess` imports across `src/` and the 0.2.0 RC window forbids
+new CLI commands. Same verbs, same receipts as sibling forges:
+
+```bash
+python scripts/forge_install.py install --dry-run   # plan only
+python scripts/forge_install.py install --yes       # apply to a repo
+python scripts/forge_install.py status|doctor|repair
+python scripts/forge_install.py uninstall [--purge]
+python scripts/forge_install.py update|mcp-verify
+
+# Optional local web UI over the same real services (127.0.0.1, session token)
+python scripts/forge_portal.py [--no-browser] [--port N] [--root DIR]
+```
+
+`theforge install auto` delegates here automatically via the
+`install_command` field in `forge.json`.
+
+## Quickstart
+
+```bash
+# Full deterministic scan of a project directory
+forge-doctor-api scan ./my-service
+
+# Scan + CI gate: fail on new breaking changes vs a baseline contract
+forge-doctor-api scan ./my-service --fail-on breaking --baseline ./last-release
+
+# Emit SARIF for GitHub code scanning, or a compact agent-readable format
+forge-doctor-api scan . --format sarif --out results.sarif
+forge-doctor-api scan . --format agent
+```
+
+Exit codes: `0` scan ran and gate passed · `1` gate failed ·
+`2` usage/misconfiguration error.
+
+## Command tour
+
+```text
+forge-doctor-api scan TARGET        all pipelines + optional §178 gate
+forge-doctor-api inventory TARGET   fleet answers over a workspace or repo
+forge-doctor-api diff OLD NEW       semantic contract diff + typed events
+forge-doctor-api diff OLD NEW --pr  + PR-intel summary and blast radius
+forge-doctor-api fingerprint FILE   semantic fingerprint of a contract
+forge-doctor-api graph TARGET       merged contract/route/client graph
+forge-doctor-api blast-radius O N   operation → clients → services impact
+forge-doctor-api diagnose TARGET    root-cause episodes from evidence
+forge-doctor-api explain DIR TOKEN  evidence chain for one finding
+forge-doctor-api lab [labs]         Forge Lab corpus: precision/recall
+forge-doctor-api contract diff O N  contract-level diff
+forge-doctor-api contract compat …  compatibility classification
+forge-doctor-api runtime requests   per-request execution table
+forge-doctor-api runtime baseline   performance baselines per endpoint
+forge-doctor-api runtime regress…   regressions vs baseline
+forge-doctor-api security inspect   passive security evidence + findings
+forge-doctor-api reliability inspect  timeouts/retries/idempotency/SLOs
+forge-doctor-api reliability path     hop-by-hop effective policy
+```
+
+`--help` on any command lists its options. See
+[docs/cli.md](docs/cli.md) for the full reference.
+
+## What it understands
+
+- **Contracts**: OpenAPI 3.x (YAML/JSON), AsyncAPI, GraphQL SDL +
+  introspection, gRPC `.proto`.
+- **Source**: FastAPI route discovery, client call-site extraction
+  (Python/JS/TS), GraphQL client queries (`gql` tagged literals).
+- **Config**: timeouts, retries, rate limits, idempotency headers,
+  authentication/CORS/mTLS/TLS evidence, gateway routes, ownership
+  files, policy files.
+- **Runtime**: OTLP/OTEL JSON traces, access-log records — ingested as
+  compact per-request summaries (raw spans are not retained).
+
+From those inputs it produces: OAS/ASYNC/GQL/GRPC contract checks,
+contract-drift and semantic compatibility diffs, client impact and blast
+radius, versioning/deprecation analysis, observability + performance
+regression findings, reliability checks (retry amplification, SLO
+budgets), passive OWASP API Top-10 candidates, policy violations, an API
+digital twin, root-cause diagnosis, safe-fix classification, multi-repo
+workspace analysis, fleet intelligence, migration portability
+assessments, and compact handoff bundles for agentic tools.
+
+## Documentation
+
+- [docs/architecture.md](docs/architecture.md) — pipeline layout, models, determinism contract
+- [docs/cli.md](docs/cli.md) — every command, option, and exit code
+- [docs/output-formats.md](docs/output-formats.md) — console/JSON/JSONL/SARIF/agent + CI gate
+- [docs/checks.md](docs/checks.md) — finding model, namespaces, confidence semantics
+- [docs/compatibility.md](docs/compatibility.md) — cross-protocol diff taxonomy, decision tables, client-impact coverage
+- [docs/runtime-evidence.md](docs/runtime-evidence.md) — trace/log ingestion, history, perf & SLOs
+- [docs/runtime-scale.md](docs/runtime-scale.md) — streaming bounds, memory curve, perf budget gate, snapshot formats
+- [docs/policies.md](docs/policies.md) — policy files, inheritance, exceptions, ownership
+- [docs/workspace-fleet.md](docs/workspace-fleet.md) — multi-repo manifests + inventory
+- [docs/knowledge-packs.md](docs/knowledge-packs.md) — versioned knowledge data + plugin SDK
+- [docs/migration.md](docs/migration.md) — portability assessments + decision briefs
+- [docs/handoff.md](docs/handoff.md) — `ApiHandoffBundle`, `DoctorApi`, Forger routing
+- [docs/infrastructure.md](docs/infrastructure.md) — gateway/mesh declared config + Kubernetes/IaC evidence
+- [docs/cache.md](docs/cache.md) — declared cache policies, layers, invalidation risk
+- [docs/lab.md](docs/lab.md) — Forge Lab corpus, ground truth, precision/recall
+- [docs/output-contract.md](docs/output-contract.md) — v1 export schemas (json/jsonl/sarif/agent/report) + evolution rules
+- [docs/forger-boundary.md](docs/forger-boundary.md) — Doctor ↔ API Forge ↔ The Forger typed boundary
+- [docs/release-policy.md](docs/release-policy.md) — versioning, public surfaces, release checklist, SBOM
+- [docs/release-v0.1.md](docs/release-v0.1.md) — quality gate, packaging, hermetic proofs
+- [docs/roadmap.md](docs/roadmap.md) — shipped coverage vs planned waves
+- [docs/adr/](docs/adr/) — architecture decision records
+- [docs/development.md](docs/development.md) — repo layout, test/lint/typecheck, adding a check
+
+## Repository layout
+
+```text
+src/forge_doctor_api/   engine (analyzers, checks, models, CLI)
+tests/                  pytest suite (offline-blocked sockets)
+labs/                   Forge Lab corpus: golden + adversarial fixtures
+factory/                Loop Factory specs, run records, quality gate
+.github/workflows/      doctor-scan.yml CI gate
+docs/                   documentation
+```
+
+## Graph Studio
+
+`forge-doctor-api graph . --view|--ui` projects the service graph through
+`forge/ForgeGraphView/v1` and serves the embedded local explorer (declinable at
+install via `--components`). Full docs: `the-forge/docs/graph-studio/`.

forge_doctor_api-0.2.0/pyproject.toml

@@ -0,0 +1,93 @@
+[project]
+name = "forge-doctor-api"
+version = "0.2.0"
+description = "Deterministic, offline-first, evidence-first API architecture intelligence engine."
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{ name = "Edgar Sócrates Caria" }]
+license = { text = "MIT" }
+classifiers = [
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "typer>=0.12",
+    "rich>=15.0.0",
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+graphql = ["graphql-core>=3.2,<4"]
+mcp = ["mcp>=2.0,<3"]
+
+[project.scripts]
+forge-doctor-api = "forge_doctor_api.cli:main"
+
+[tool.poetry]
+packages = [{ include = "forge_doctor_api", from = "src" }]
+
+[tool.poetry.group.dev.dependencies]
+pytest = ">=8.0"
+ruff = ">=0.6"
+mypy = ">=2.3.1"
+types-PyYAML = ">=6.0"
+
+[build-system]
+requires = ["poetry-core>=2.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "-ra --basetemp=.pytest-tmp"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests"]
+extend-exclude = ["factory", "docs", ".claude", "labs"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "SIM", "RUF", "DTZ"]
+
+[tool.ruff.lint.per-file-ignores]
+# Vendored Graph Studio kit (canonical: the-forge/src/theforge)
+"src/forge_doctor_api/_graphview.py" = ["ALL"]
+"src/forge_doctor_api/_graphstudio.py" = ["ALL"]
+# Vendored Forge UI kit (canonical: the-forge/src/theforge/ui)
+"src/forge_doctor_api/ui/**/*.py" = ["ALL"]
+# Vendored shared sources — canonical copies in the-forge are the lint target.
+"scripts/forge_installkit.py" = ["ALL"]
+"scripts/forge_bootstrap.py" = ["ALL"]
+# Vendored portal server — canonical copy in forge-portal/portal_core.
+"scripts/_forge_portal.py" = ["ALL"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+mypy_path = "src"
+packages = ["forge_doctor_api"]
+
+[[tool.mypy.overrides]]
+# Optional extras are absent under a minimal install — mypy must still
+# pass there (TYPE_CHECKING imports resolve as missing by design).
+module = ["mcp", "mcp.*", "graphql", "graphql.*"]
+follow_imports = "skip"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = ["forge_doctor_api.handoff.mcp_server"]
+disallow_untyped_decorators = false
+
+[[tool.mypy.overrides]]
+# Vendored upstream surfaces (byte-parity with the-forge, same convention
+# as api-forge's `_installkit`/`tui.*`): canonical copy is the typecheck
+# target; kept byte-identical here outside `strict`.
+module = [
+    "forge_doctor_api._graphview",
+    "forge_doctor_api._graphstudio",
+    "forge_doctor_api.ui.*",
+]
+ignore_errors = true

forge_doctor_api-0.2.0/src/forge_doctor_api/__init__.py

@@ -0,0 +1,69 @@
+"""Forge Doctor API: deterministic API architecture intelligence.
+
+Public surface (stable): `Doctor` facade, `DoctorReport`, core models
+and the handoff bundle. Everything else is internal and may move —
+import from here, not from deep module paths.
+"""
+
+from forge_doctor_api.core.context import ProjectContext
+from forge_doctor_api.core.discovery import ArtifactInventory
+from forge_doctor_api.core.models import (
+    Confidence,
+    Evidence,
+    EvidenceKind,
+    Finding,
+    Model,
+    Severity,
+    SourceLocation,
+    UnknownFact,
+)
+from forge_doctor_api.core.plan import AnalysisPlan
+from forge_doctor_api.core.report import DomainSummary
+from forge_doctor_api.handoff.bundle import assemble_bundle
+from forge_doctor_api.handoff.model import ApiHandoffBundle
+from forge_doctor_api.handoff.protocol import (
+    ForgeHandoff,
+    ForgeReceipt,
+    ForgeRef,
+    ForgeRequest,
+    ForgeResult,
+)
+from forge_doctor_api.report import DoctorReport
+from forge_doctor_api.sdk import (
+    SDK_VERSION,
+    Doctor,
+    DoctorError,
+    FindingNotFoundError,
+    ProjectUnreadableError,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "SDK_VERSION",
+    "AnalysisPlan",
+    "ApiHandoffBundle",
+    "ArtifactInventory",
+    "Confidence",
+    "Doctor",
+    "DoctorError",
+    "DoctorReport",
+    "DomainSummary",
+    "Evidence",
+    "EvidenceKind",
+    "Finding",
+    "FindingNotFoundError",
+    "ForgeHandoff",
+    "ForgeReceipt",
+    "ForgeRef",
+    "ForgeRequest",
+    "ForgeResult",
+    "Model",
+    "ProjectContext",
+    "ProjectUnreadableError",
+    "Severity",
+    "SourceLocation",
+    "UnknownFact",
+    "__version__",
+    "assemble_bundle",
+]

forge_doctor_api-0.2.0/src/forge_doctor_api/__main__.py

@@ -0,0 +1,3 @@
+from forge_doctor_api.cli import main
+
+main()