@gate-forge/http-contract 0.1.0

package/dist/schema.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Canonical HTTP contract facts (ADR 0004 D1).
+ *
+ * A contract fact is one discovered HTTP surface: either a backend server
+ * route or a frontend API-client call. Facts are evidence, never decisions:
+ * consumption relationships exist only after the deterministic join (D3)
+ * runs, and endpoint semantics are decided exclusively by the classifier
+ * over linked facts.
+ *
+ * The zod schemas here are the normative definitions; detectors serialize
+ * facts as GPP/3 resources of kind `http.contract` whose attributes carry
+ * this payload (open attribute record, so the wire shape stays compatible).
+ */
+import { z } from 'zod';
+/** Wire schema version for the fact payload. */
+export declare const HTTP_CONTRACT_SCHEMA_VERSION = 1;
+/** Schema version field with the same strictness rules as core. */
+export declare const HttpContractSchemaVersionField: z.ZodLiteral<1>;
+/** Concrete HTTP methods a fact may declare. `ANY` is exposure-only. */
+export declare const HTTP_METHODS: readonly ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "ANY"];
+export declare const HttpMethodSchema: z.ZodEnum<{
+    GET: "GET";
+    HEAD: "HEAD";
+    POST: "POST";
+    PUT: "PUT";
+    PATCH: "PATCH";
+    DELETE: "DELETE";
+    OPTIONS: "OPTIONS";
+    ANY: "ANY";
+}>;
+export type HttpMethod = (typeof HTTP_METHODS)[number];
+/** Which side of the join the fact came from. */
+export declare const HttpContractRoles: readonly ["server-route", "frontend-call"];
+export declare const HttpContractRoleSchema: z.ZodEnum<{
+    "server-route": "server-route";
+    "frontend-call": "frontend-call";
+}>;
+export type HttpContractRole = (typeof HttpContractRoles)[number];
+/** Source location, identical in shape to the core Location schema. */
+export declare const HttpLocationSchema: z.ZodObject<{
+    file: z.ZodString;
+    line: z.ZodNumber;
+    col: z.ZodNumber;
+}, z.core.$strict>;
+export type HttpLocation = z.infer<typeof HttpLocationSchema>;
+/**
+ * One discovered HTTP surface. Strict: unknown fields are rejected so a
+ * detector cannot smuggle unversioned payloads through the join.
+ */
+export declare const HttpContractFactSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    role: z.ZodEnum<{
+        "server-route": "server-route";
+        "frontend-call": "frontend-call";
+    }>;
+    method: z.ZodEnum<{
+        GET: "GET";
+        HEAD: "HEAD";
+        POST: "POST";
+        PUT: "PUT";
+        PATCH: "PATCH";
+        DELETE: "DELETE";
+        OPTIONS: "OPTIONS";
+        ANY: "ANY";
+    }>;
+    normalizedPath: z.ZodString;
+    rawPath: z.ZodString;
+    framework: z.ZodString;
+    handlerSymbol: z.ZodOptional<z.ZodString>;
+    requestSchemaSymbols: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    responseSchemaSymbols: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    callsites: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    source: z.ZodObject<{
+        file: z.ZodString;
+        line: z.ZodNumber;
+        col: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type HttpContractFact = z.infer<typeof HttpContractFactSchema>;
+/** Resource kind used to carry facts through GPP/3 as evidence-only resources. */
+export declare const HTTP_CONTRACT_KIND = "http.contract";
+/** Resource kind emitted by the endpoint compiler for joined endpoints. */
+export declare const HTTP_ENDPOINT_KIND = "http.endpoint";
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,gDAAgD;AAChD,eAAO,MAAM,4BAA4B,IAAI,CAAC;AAE9C,mEAAmE;AACnE,eAAO,MAAM,8BAA8B,iBAEzC,CAAC;AAEH,wEAAwE;AACxE,eAAO,MAAM,YAAY,8EASf,CAAC;AAEX,eAAO,MAAM,gBAAgB;;;;;;;;;EAAuB,CAAC;AACrD,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD,iDAAiD;AACjD,eAAO,MAAM,iBAAiB,4CAA6C,CAAC;AAC5E,eAAO,MAAM,sBAAsB;;;EAA4B,CAAC;AAChE,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAElE,uEAAuE;AACvE,eAAO,MAAM,kBAAkB;;;;kBAMpB,CAAC;AACZ,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D;;;GAGG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAsBxB,CAAC;AAEZ,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,kFAAkF;AAClF,eAAO,MAAM,kBAAkB,kBAAkB,CAAC;AAElD,2EAA2E;AAC3E,eAAO,MAAM,kBAAkB,kBAAkB,CAAC"}

package/dist/schema.js

@@ -0,0 +1,75 @@
+/**
+ * Canonical HTTP contract facts (ADR 0004 D1).
+ *
+ * A contract fact is one discovered HTTP surface: either a backend server
+ * route or a frontend API-client call. Facts are evidence, never decisions:
+ * consumption relationships exist only after the deterministic join (D3)
+ * runs, and endpoint semantics are decided exclusively by the classifier
+ * over linked facts.
+ *
+ * The zod schemas here are the normative definitions; detectors serialize
+ * facts as GPP/3 resources of kind `http.contract` whose attributes carry
+ * this payload (open attribute record, so the wire shape stays compatible).
+ */
+import { z } from 'zod';
+/** Wire schema version for the fact payload. */
+export const HTTP_CONTRACT_SCHEMA_VERSION = 1;
+/** Schema version field with the same strictness rules as core. */
+export const HttpContractSchemaVersionField = z.literal(1, {
+    error: 'http contract schemaVersion must be exactly 1',
+});
+/** Concrete HTTP methods a fact may declare. `ANY` is exposure-only. */
+export const HTTP_METHODS = [
+    'GET',
+    'HEAD',
+    'POST',
+    'PUT',
+    'PATCH',
+    'DELETE',
+    'OPTIONS',
+    'ANY',
+];
+export const HttpMethodSchema = z.enum(HTTP_METHODS);
+/** Which side of the join the fact came from. */
+export const HttpContractRoles = ['server-route', 'frontend-call'];
+export const HttpContractRoleSchema = z.enum(HttpContractRoles);
+/** Source location, identical in shape to the core Location schema. */
+export const HttpLocationSchema = z
+    .object({
+    file: z.string().min(1),
+    line: z.number().int().min(1),
+    col: z.number().int().min(0),
+})
+    .strict();
+/**
+ * One discovered HTTP surface. Strict: unknown fields are rejected so a
+ * detector cannot smuggle unversioned payloads through the join.
+ */
+export const HttpContractFactSchema = z
+    .object({
+    schemaVersion: HttpContractSchemaVersionField,
+    role: HttpContractRoleSchema,
+    method: HttpMethodSchema,
+    /** Canonical positional path (ADR 0004 D2), e.g. `/api/v1/accounts/{}`. */
+    normalizedPath: z.string().min(1),
+    /** Exactly as written in source, before canonicalization. */
+    rawPath: z.string().min(1),
+    /** Producing framework/client id, e.g. `fastapi`, `fetch`, `axios`. */
+    framework: z.string().min(1),
+    /** Backend handler symbol (server-route facts only). */
+    handlerSymbol: z.string().min(1).optional(),
+    /** Request body/query/dependency schema symbols (server-route facts). */
+    requestSchemaSymbols: z.array(z.string().min(1)).min(1).optional(),
+    /** Response model symbols (server-route facts). */
+    responseSchemaSymbols: z.array(z.string().min(1)).min(1).optional(),
+    /** Frontend callsite identifiers (frontend-call facts only). */
+    callsites: z.array(z.string().min(1)).min(1).optional(),
+    /** Where the fact was found. */
+    source: HttpLocationSchema,
+})
+    .strict();
+/** Resource kind used to carry facts through GPP/3 as evidence-only resources. */
+export const HTTP_CONTRACT_KIND = 'http.contract';
+/** Resource kind emitted by the endpoint compiler for joined endpoints. */
+export const HTTP_ENDPOINT_KIND = 'http.endpoint';
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,gDAAgD;AAChD,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC;AAE9C,mEAAmE;AACnE,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE;IACzD,KAAK,EAAE,+CAA+C;CACvD,CAAC,CAAC;AAEH,wEAAwE;AACxE,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,KAAK;IACL,MAAM;IACN,MAAM;IACN,KAAK;IACL,OAAO;IACP,QAAQ;IACR,SAAS;IACT,KAAK;CACG,CAAC;AAEX,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;AAGrD,iDAAiD;AACjD,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,cAAc,EAAE,eAAe,CAAU,CAAC;AAC5E,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;AAGhE,uEAAuE;AACvE,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC;KAChC,MAAM,CAAC;IACN,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7B,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CAC7B,CAAC;KACD,MAAM,EAAE,CAAC;AAGZ;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC;KACpC,MAAM,CAAC;IACN,aAAa,EAAE,8BAA8B;IAC7C,IAAI,EAAE,sBAAsB;IAC5B,MAAM,EAAE,gBAAgB;IACxB,2EAA2E;IAC3E,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACjC,6DAA6D;IAC7D,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1B,uEAAuE;IACvE,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5B,wDAAwD;IACxD,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAC3C,yEAAyE;IACzE,oBAAoB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAClE,mDAAmD;IACnD,qBAAqB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACnE,gEAAgE;IAChE,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACvD,gCAAgC;IAChC,MAAM,EAAE,kBAAkB;CAC3B,CAAC;KACD,MAAM,EAAE,CAAC;AAIZ,kFAAkF;AAClF,MAAM,CAAC,MAAM,kBAAkB,GAAG,eAAe,CAAC;AAElD,2EAA2E;AAC3E,MAAM,CAAC,MAAM,kBAAkB,GAAG,eAAe,CAAC"}

package/dist/version.d.ts

@@ -0,0 +1,3 @@
+/** Package version for `@gate-forge/http-contract`. */
+export declare const HTTP_CONTRACT_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,uDAAuD;AACvD,eAAO,MAAM,qBAAqB,UAAU,CAAC"}

package/dist/version.js

@@ -0,0 +1,3 @@
+/** Package version for `@gate-forge/http-contract`. */
+export const HTTP_CONTRACT_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,uDAAuD;AACvD,MAAM,CAAC,MAAM,qBAAqB,GAAG,OAAO,CAAC"}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@gate-forge/http-contract",
+  "version": "0.1.0",
+  "license": "Apache-2.0",
+  "description": "Framework-neutral canonical HTTP contract: HttpContractFact schema, typed block codes, path/method normalization, and the deterministic frontend-call <-> server-route join engine (ADR 0004 D1-D4).",
+  "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"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "zod": "^4.1.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/umiddey/gateforge.git",
+    "directory": "packages/http-contract"
+  },
+  "bugs": {
+    "url": "https://github.com/umiddey/gateforge/issues"
+  },
+  "homepage": "https://github.com/umiddey/gateforge#readme"
+}