@gate-forge/pack-fastapi 0.1.0

package/dist/facts.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Post-canonicalization for the FastAPI detector.
+ *
+ * The Python scanner emits raw effective paths; this module is the single
+ * place where contract facts get their canonical `normalizedPath` (via
+ * `@gate-forge/http-contract`, so canonicalization has exactly one
+ * implementation across languages).
+ *
+ * Classification signals (dogfood remediation phase 4): NONE. The wrapper
+ * once minted `exposure: route` / `lifecycle.<op>` signals targeted at the
+ * PATH-DERIVED resource name (`pathDerivedResourceName`) — a guess that
+ * mostly names no discovered resource (route `/admin-bypasses` vs the real
+ * table), so the signals surfaced as STALE_SIGNAL_TARGET blockers while
+ * adding nothing: unknown exposure already defaults user-facing and unknown
+ * lifecycle operations already default enabled (ADR 0003 D5). Route→resource
+ * linkage belongs to the CLI endpoint compiler (schema-symbol/handler
+ * corroboration over these very facts' `requestSchemaSymbols`/
+ * `responseSchemaSymbols`/`handlerSymbol`, with typed
+ * ENDPOINT_RESOURCE_LINK_UNRESOLVED blocks for ambiguity). Core's
+ * STALE_SIGNAL_TARGET detection remains for genuinely stale authority
+ * signals (declaration markers, adapter bindings, read-only declarations)
+ * — this pack simply no longer produces false targets. The
+ * `classificationSignals` outcome field stays in the wire shape (protocol
+ * contract) and is always empty.
+ */
+import { type HttpContractFact, type HttpLocation } from '@gate-forge/http-contract';
+import type { ClassificationSignal } from '@gate-forge/core';
+/** Source location shape shared by facts, resources, and signals. */
+type Location = HttpLocation;
+/** Wire shape of one python-emitted contract resource (open attributes). */
+export interface ContractResource {
+    schemaVersion: 1;
+    kind: 'http.contract';
+    source: string;
+    location: Location;
+    detectorVersion: string;
+    attributes: Record<string, unknown>;
+    id: string;
+}
+export interface CanonicalizationOutcome {
+    /** Facts whose effective path canonicalized; `normalizedPath` filled in. */
+    facts: HttpContractFact[];
+    /** Raw resources kept for the graph's evidence-only channel. */
+    resources: ContractResource[];
+    /** Typed blocking entries for facts whose path could not canonicalize. */
+    unresolved: Array<{
+        code: string;
+        detail: string;
+        location: Location;
+    }>;
+    /** Exposure/lifecycle signals minted from the canonical facts. */
+    classificationSignals: ClassificationSignal[];
+}
+/**
+ * Canonicalizes python-emitted contract resources into typed facts.
+ *
+ * A fact whose effective path canonicalizes to a dynamic outcome becomes a
+ * blocking `HTTP_PATH_DYNAMIC` unresolved entry — never a dropped claim
+ * and never a guess. No classification signals are minted (phase 4; see
+ * the module doc). Facts and resources are returned in deterministic
+ * canonical order.
+ */
+export declare function canonicalizeFacts(resources: readonly ContractResource[]): CanonicalizationOutcome;
+export {};
+//# sourceMappingURL=facts.d.ts.map

package/dist/facts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"facts.d.ts","sourceRoot":"","sources":["../src/facts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAGL,KAAK,gBAAgB,EACrB,KAAK,YAAY,EAClB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAE7D,qEAAqE;AACrE,KAAK,QAAQ,GAAG,YAAY,CAAC;AAE7B,4EAA4E;AAC5E,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,CAAC,CAAC;IACjB,IAAI,EAAE,eAAe,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,QAAQ,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,uBAAuB;IACtC,4EAA4E;IAC5E,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B,gEAAgE;IAChE,SAAS,EAAE,gBAAgB,EAAE,CAAC;IAC9B,0EAA0E;IAC1E,UAAU,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,QAAQ,CAAA;KAAE,CAAC,CAAC;IACxE,kEAAkE;IAClE,qBAAqB,EAAE,oBAAoB,EAAE,CAAC;CAC/C;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,SAAS,gBAAgB,EAAE,GACrC,uBAAuB,CA0EzB"}

package/dist/facts.js

@@ -0,0 +1,109 @@
+/**
+ * Post-canonicalization for the FastAPI detector.
+ *
+ * The Python scanner emits raw effective paths; this module is the single
+ * place where contract facts get their canonical `normalizedPath` (via
+ * `@gate-forge/http-contract`, so canonicalization has exactly one
+ * implementation across languages).
+ *
+ * Classification signals (dogfood remediation phase 4): NONE. The wrapper
+ * once minted `exposure: route` / `lifecycle.<op>` signals targeted at the
+ * PATH-DERIVED resource name (`pathDerivedResourceName`) — a guess that
+ * mostly names no discovered resource (route `/admin-bypasses` vs the real
+ * table), so the signals surfaced as STALE_SIGNAL_TARGET blockers while
+ * adding nothing: unknown exposure already defaults user-facing and unknown
+ * lifecycle operations already default enabled (ADR 0003 D5). Route→resource
+ * linkage belongs to the CLI endpoint compiler (schema-symbol/handler
+ * corroboration over these very facts' `requestSchemaSymbols`/
+ * `responseSchemaSymbols`/`handlerSymbol`, with typed
+ * ENDPOINT_RESOURCE_LINK_UNRESOLVED blocks for ambiguity). Core's
+ * STALE_SIGNAL_TARGET detection remains for genuinely stale authority
+ * signals (declaration markers, adapter bindings, read-only declarations)
+ * — this pack simply no longer produces false targets. The
+ * `classificationSignals` outcome field stays in the wire shape (protocol
+ * contract) and is always empty.
+ */
+import { HTTP_PATH_DYNAMIC, normalizeHttpPath, } from '@gate-forge/http-contract';
+/**
+ * Canonicalizes python-emitted contract resources into typed facts.
+ *
+ * A fact whose effective path canonicalizes to a dynamic outcome becomes a
+ * blocking `HTTP_PATH_DYNAMIC` unresolved entry — never a dropped claim
+ * and never a guess. No classification signals are minted (phase 4; see
+ * the module doc). Facts and resources are returned in deterministic
+ * canonical order.
+ */
+export function canonicalizeFacts(resources) {
+    const facts = [];
+    const keptResources = [];
+    const unresolved = [];
+    // Phase 4: no classification signals are minted — the field stays in
+    // the wire shape (protocol contract) and is always empty.
+    const signals = [];
+    for (const resource of resources) {
+        if (resource.kind !== 'http.contract') {
+            keptResources.push(resource);
+            continue;
+        }
+        const attributes = resource.attributes;
+        const effectivePath = attributes['effectivePath'];
+        const method = attributes['method'];
+        if (typeof effectivePath !== 'string' || typeof method !== 'string') {
+            unresolved.push({
+                code: HTTP_PATH_DYNAMIC,
+                detail: `contract fact '${resource.id}' carries no provable effective path`,
+                location: resource.location,
+            });
+            continue;
+        }
+        const canonical = normalizeHttpPath(effectivePath);
+        if (!canonical.ok) {
+            unresolved.push({
+                code: HTTP_PATH_DYNAMIC,
+                detail: `route '${effectivePath}' in ${resource.source}: ${canonical.detail}`,
+                location: resource.location,
+            });
+            continue;
+        }
+        const fact = {
+            schemaVersion: 1,
+            role: 'server-route',
+            method: method,
+            normalizedPath: canonical.canonical,
+            rawPath: effectivePath,
+            framework: typeof attributes['framework'] === 'string' ? attributes['framework'] : 'fastapi',
+            handlerSymbol: typeof attributes['handlerSymbol'] === 'string'
+                ? attributes['handlerSymbol']
+                : undefined,
+            source: resource.location,
+        };
+        const responseModel = attributes['responseModel'];
+        if (typeof responseModel === 'string' && responseModel.length > 0) {
+            fact.responseSchemaSymbols = [responseModel];
+        }
+        const requestSchemas = attributes['requestSchemaSymbols'];
+        if (Array.isArray(requestSchemas)) {
+            const names = requestSchemas.filter((name) => typeof name === 'string' && name.length > 0);
+            if (names.length > 0)
+                fact.requestSchemaSymbols = names;
+        }
+        facts.push(fact);
+        keptResources.push({
+            ...resource,
+            attributes: { ...attributes, normalizedPath: canonical.canonical },
+        });
+    }
+    facts.sort((a, b) => compareText(JSON.stringify(a), JSON.stringify(b)));
+    keptResources.sort((a, b) => compareText(a.id, b.id));
+    unresolved.sort((a, b) => compareText(a.location.file, b.location.file) ||
+        (a.location.line || 0) - (b.location.line || 0) ||
+        compareText(a.code, b.code) ||
+        compareText(a.detail, b.detail));
+    return { facts, resources: keptResources, unresolved, classificationSignals: signals };
+}
+function compareText(a, b) {
+    if (a === b)
+        return 0;
+    return a < b ? -1 : 1;
+}
+//# sourceMappingURL=facts.js.map

package/dist/facts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"facts.js","sourceRoot":"","sources":["../src/facts.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `@gate-forge/pack-fastapi` — FastAPI server-route detector (ADR 0004,
+ * plan phase 2). The default export is the CLI in-process contract.
+ */
+export { createFastapiDetector, DEFAULT_COMMAND, DEFAULT_FASTAPI_SCAN_CONFIG, FASTAPI_SCAN_CONFIG_PATH, pythonEnvironment, readFastapiScanConfigOrNull, type FastapiDetector, type FastapiDetectorOptions, type FastapiScanConfig, } from './detector.js';
+export { PACK_PLUGIN_ID, PACK_VERSION } from './version.js';
+declare const _default: import("./detector.js").FastapiDetector;
+export default _default;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,2BAA2B,EAC3B,wBAAwB,EACxB,iBAAiB,EACjB,2BAA2B,EAC3B,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,GACvB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;;AAG5D,wBAAuC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * `@gate-forge/pack-fastapi` — FastAPI server-route detector (ADR 0004,
+ * plan phase 2). The default export is the CLI in-process contract.
+ */
+export { createFastapiDetector, DEFAULT_COMMAND, DEFAULT_FASTAPI_SCAN_CONFIG, FASTAPI_SCAN_CONFIG_PATH, pythonEnvironment, readFastapiScanConfigOrNull, } from './detector.js';
+export { PACK_PLUGIN_ID, PACK_VERSION } from './version.js';
+import { createFastapiDetector } from './detector.js';
+export default createFastapiDetector();
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,2BAA2B,EAC3B,wBAAwB,EACxB,iBAAiB,EACjB,2BAA2B,GAI5B,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAEtD,eAAe,qBAAqB,EAAE,CAAC"}

package/dist/version.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Pack identity constants. The GPP/3 handshake pins these values: the
+ * `.gateforge.yml` plugin entry MUST declare the same `id` and `version`
+ * (see the pack README).
+ */
+/** Plugin id every FastAPI pack contribution is pinned to. */
+export declare const PACK_PLUGIN_ID = "gateforge.pack-fastapi";
+/** Detector/pack version. Must match `python/gateforge_fastapi_detector/__init__.py`. */
+export declare const PACK_VERSION = "0.1.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,8DAA8D;AAC9D,eAAO,MAAM,cAAc,2BAA2B,CAAC;AAEvD,yFAAyF;AACzF,eAAO,MAAM,YAAY,UAAU,CAAC"}

package/dist/version.js

@@ -0,0 +1,10 @@
+/**
+ * Pack identity constants. The GPP/3 handshake pins these values: the
+ * `.gateforge.yml` plugin entry MUST declare the same `id` and `version`
+ * (see the pack README).
+ */
+/** Plugin id every FastAPI pack contribution is pinned to. */
+export const PACK_PLUGIN_ID = 'gateforge.pack-fastapi';
+/** Detector/pack version. Must match `python/gateforge_fastapi_detector/__init__.py`. */
+export const PACK_VERSION = '0.1.0';
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,8DAA8D;AAC9D,MAAM,CAAC,MAAM,cAAc,GAAG,wBAAwB,CAAC;AAEvD,yFAAyF;AACzF,MAAM,CAAC,MAAM,YAAY,GAAG,OAAO,CAAC"}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@gate-forge/pack-fastapi",
+  "version": "0.1.0",
+  "license": "Apache-2.0",
+  "description": "FastAPI server-route detector: Python AST scanner served over GPP/3 (pack-sqlalchemy pattern), emitting http.contract evidence facts with canonical effective paths plus exposure/lifecycle signals (ADR 0004 D1, plan phase 2).",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "README.md",
+    "dist",
+    "python"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@gate-forge/core": "^0.1.0",
+    "@gate-forge/http-contract": "^0.1.0",
+    "@gate-forge/plugin-protocol": "^0.1.0",
+    "zod": "^4.1.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/umiddey/gateforge.git",
+    "directory": "packages/pack-fastapi"
+  },
+  "bugs": {
+    "url": "https://github.com/umiddey/gateforge/issues"
+  },
+  "homepage": "https://github.com/umiddey/gateforge#readme"
+}

package/python/gateforge_fastapi_detector/__init__.py

@@ -0,0 +1,9 @@
+"""FastAPI route detection for Gateforge (GPP/3 plugin).
+
+The detector vocabulary is frozen in this module's docstring and mirrored
+by ``gateforge_fastapi_detector/scan.py`` (the implementation). See the
+pack README and ADR 0004 D1 for the contract-resource semantics.
+"""
+
+PLUGIN_ID = "gateforge.pack-fastapi"
+VERSION = "0.1.0"

package/python/gateforge_fastapi_detector/__main__.py

@@ -0,0 +1,99 @@
+"""GPP/3 serve entry for the Gateforge FastAPI detector.
+
+Runnable as a module so the CLI's subprocess transport can invoke it with
+``python3 -m gateforge_fastapi_detector``: handshake, one lock-step
+``discover`` per request, shutdown handshake — all through the reference
+client in @gate-forge/plugin-protocol (stdlib only).
+
+The module locates the ``gateforge_plugin`` client itself: when it is not
+importable from the environment (e.g. only this pack's ``python/`` dir is
+on ``PYTHONPATH`` in the monorepo layout), the sibling copy shipped by
+``packages/plugin-protocol/python`` is bootstrapped onto ``sys.path``.
+
+Usage:
+    python3 -m gateforge_fastapi_detector [root] [--import-roots <json>]
+    # root: scan root (default: process cwd, which the CLI sets to the
+    #       repo root); every discover path resolves under it.
+    # --import-roots: a JSON array of repo-root-relative directories that
+    #       act as Python import roots for ABSOLUTE imports (e.g.
+    #       '["backend"]' for the central-router-registry pattern). The
+    #       TypeScript wrapper passes the ``importRoots`` of
+    #       ``.gateforge/fastapi.json`` through this flag. Resolution is
+    #       fail-closed: an import matching more than one scanned file
+    #       under the roots is a typed unresolved entry, never a guess.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+try:  # installed / environment-provided client
+    from gateforge_plugin import ProtocolError, serve
+except ImportError:  # monorepo bootstrap: ../plugin-protocol/python
+    _protocol_py = Path(__file__).resolve().parents[3] / "plugin-protocol" / "python"
+    sys.path.insert(0, str(_protocol_py))
+    from gateforge_plugin import ProtocolError, serve  # noqa: E402
+
+from gateforge_fastapi_detector import PLUGIN_ID, VERSION
+
+_USAGE = (
+    "gateforge_fastapi_detector: usage: "
+    "python3 -m gateforge_fastapi_detector [root] [--import-roots <json-array>]"
+)
+
+
+def _parse_import_roots(raw: str) -> list[str]:
+    """Parses the ``--import-roots`` value: a JSON array of strings."""
+    try:
+        parsed = json.loads(raw)
+    except json.JSONDecodeError as error:
+        raise SystemExit(
+            f"gateforge_fastapi_detector: --import-roots must be a JSON array "
+            f"of repo-relative directories: {error.msg}"
+        ) from None
+    if not isinstance(parsed, list) or not all(isinstance(item, str) for item in parsed):
+        raise SystemExit(
+            "gateforge_fastapi_detector: --import-roots must be a JSON array "
+            "of repo-relative directories"
+        )
+    return parsed
+
+
+_scan_root: Path | None = None
+_import_roots: list[str] | None = None
+
+_args = sys.argv[1:]
+_index = 0
+while _index < len(_args):
+    _arg = _args[_index]
+    if _arg == "--import-roots":
+        _index += 1
+        if _index >= len(_args):
+            raise SystemExit("gateforge_fastapi_detector: --import-roots requires a JSON array value")
+        _import_roots = _parse_import_roots(_args[_index])
+    elif _arg.startswith("--import-roots="):
+        _import_roots = _parse_import_roots(_arg.split("=", 1)[1])
+    elif _arg.startswith("-"):
+        raise SystemExit(f"gateforge_fastapi_detector: unknown option {_arg!r}; {_USAGE}")
+    elif _scan_root is None:
+        _scan_root = Path(_arg).resolve()
+    else:
+        raise SystemExit(f"gateforge_fastapi_detector: unexpected argument {_arg!r}; {_USAGE}")
+    _index += 1
+
+
+def _discover(paths: list[str]) -> dict:
+    """GPP/3 discover handler: scans each repo-relative path in order."""
+    from gateforge_fastapi_detector import scan
+
+    return scan.scan(paths, _scan_root, _import_roots)
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(serve(PLUGIN_ID, VERSION, _discover))
+    except ProtocolError as error:
+        print(f"gateforge_fastapi_detector: {error}", file=sys.stderr)
+        raise SystemExit(4) from None