@c4a/extract-contract 0.7.9 → 0.7.10-alpha.2

package/index.d.ts

@@ -0,0 +1,584 @@
+import { z } from 'zod';
+
+export interface ContractLocator {
+	path: string;
+	line: number;
+	column: number;
+	qualified_item_path: string;
+}
+export interface ContractEndpoint {
+	endpoint_ref: string;
+	protocol: "openapi" | "graphql";
+	path_or_type: string;
+	locator: ContractLocator;
+}
+export interface ContractOperation {
+	operation_ref: string;
+	protocol: "openapi" | "graphql";
+	operation_kind: string;
+	name: string;
+	parent: string;
+	deprecated: boolean;
+	fields?: ContractField[];
+	locator: ContractLocator;
+}
+export interface ContractType {
+	type_ref: string;
+	protocol: "openapi" | "graphql";
+	kind: string;
+	name: string;
+	extension: boolean;
+	field_names: string[];
+	fields?: ContractField[];
+	locator: ContractLocator;
+}
+interface ContractField {
+	name: string;
+	type: string;
+	optional: boolean;
+	location?: string;
+	defaultValue?: string;
+	description?: string;
+	fields?: ContractField[];
+	constraints?: Record<string, unknown>;
+}
+export interface ContractReference {
+	reference_ref: string;
+	protocol: "openapi" | "graphql";
+	target_path: string;
+	target_item_path: string;
+	locator: ContractLocator;
+}
+export interface ContractDiagnostic {
+	code: "contract-source-unsupported" | "graphql-extension-base-ambiguous" | "graphql-extension-base-missing" | "graphql-schema-definition-ambiguous" | "graphql-type-definition-ambiguous" | "openapi-external-ref-cycle" | "openapi-ref-base-uri-unsupported" | "openapi-ref-missing" | "openapi-ref-out-of-scope" | "openapi-ref-pointer-missing" | "openapi-ref-target-unsupported";
+	severity: "warning" | "error";
+	locator: ContractLocator;
+	detail: string;
+}
+export interface ContractDocumentCatalog {
+	path: string;
+	format: "openapi" | "openapi-fragment" | "graphql" | "excluded";
+	version: string | null;
+	disposition: "analyzed" | "unsupported" | "excluded";
+	endpoints: ContractEndpoint[];
+	operations: ContractOperation[];
+	types: ContractType[];
+	references: ContractReference[];
+	diagnostics: ContractDiagnostic[];
+}
+/**
+ * Parses one registered contract scope. GraphQL files in one invocation are
+ * treated as one schema scope so extensions can resolve to an exact base.
+ */
+export declare function parseContractSources(files: Readonly<Record<string, string>>): ContractDocumentCatalog[];
+/** Discover local dependencies with the same syntax and scope rules as parsing.
+ * The caller supplies captured file access; this helper never reads or fetches. */
+export declare function openApiSourceDependencies(path: string, source: string): string[];
+declare const indexerEvidenceAdapterResultSchema: z.ZodEffects<z.ZodObject<{
+	protocol: z.ZodLiteral<"context.indexer.evidence-adapter-result/v1">;
+	adapter: z.ZodObject<{
+		id: z.ZodEffects<z.ZodString, string, string>;
+		package: z.ZodString;
+		export: z.ZodString;
+		version: z.ZodString;
+		digest: z.ZodString;
+	}, "strict", z.ZodTypeAny, {
+		version: string;
+		package: string;
+		id: string;
+		digest: string;
+		export: string;
+	}, {
+		version: string;
+		package: string;
+		id: string;
+		digest: string;
+		export: string;
+	}>;
+	authorized_scope: z.ZodObject<{
+		source_ref: z.ZodString;
+		module_refs: z.ZodArray<z.ZodString, "many">;
+		scope_digest: z.ZodString;
+	}, "strict", z.ZodTypeAny, {
+		source_ref: string;
+		module_refs: string[];
+		scope_digest: string;
+	}, {
+		source_ref: string;
+		module_refs: string[];
+		scope_digest: string;
+	}>;
+	input_digest: z.ZodString;
+	precedence: z.ZodNumber;
+	files: z.ZodArray<z.ZodEffects<z.ZodObject<{
+		file_ref: z.ZodString;
+		source_ref: z.ZodString;
+		module_ref: z.ZodNullable<z.ZodString>;
+		normalized_path: z.ZodEffects<z.ZodString, string, string>;
+		role: z.ZodEnum<[
+			"primary-owner",
+			"enricher"
+		]>;
+		coverage_tier: z.ZodEnum<[
+			"ast-catalog",
+			"lightweight-evidence"
+		]>;
+		disposition: z.ZodEnum<[
+			"analyzed",
+			"unsupported",
+			"excluded"
+		]>;
+		facts: z.ZodArray<z.ZodObject<{
+			fact_ref: z.ZodString;
+			kind: z.ZodEffects<z.ZodString, string, string>;
+			locator: z.ZodObject<{
+				source_ref: z.ZodString;
+				module_ref: z.ZodNullable<z.ZodString>;
+				normalized_path: z.ZodEffects<z.ZodString, string, string>;
+				qualified_item_path: z.ZodString;
+				signature_digest: z.ZodString;
+			}, "strict", z.ZodTypeAny, {
+				source_ref: string;
+				module_ref: string | null;
+				normalized_path: string;
+				qualified_item_path: string;
+				signature_digest: string;
+			}, {
+				source_ref: string;
+				module_ref: string | null;
+				normalized_path: string;
+				qualified_item_path: string;
+				signature_digest: string;
+			}>;
+			payload_digest: z.ZodString;
+			denominator: z.ZodEnum<[
+				"none",
+				"eligible-file",
+				"loc",
+				"symbol",
+				"protocol-item"
+			]>;
+		}, "strict", z.ZodTypeAny, {
+			kind: string;
+			fact_ref: string;
+			locator: {
+				source_ref: string;
+				module_ref: string | null;
+				normalized_path: string;
+				qualified_item_path: string;
+				signature_digest: string;
+			};
+			payload_digest: string;
+			denominator: "symbol" | "none" | "eligible-file" | "loc" | "protocol-item";
+		}, {
+			kind: string;
+			fact_ref: string;
+			locator: {
+				source_ref: string;
+				module_ref: string | null;
+				normalized_path: string;
+				qualified_item_path: string;
+				signature_digest: string;
+			};
+			payload_digest: string;
+			denominator: "symbol" | "none" | "eligible-file" | "loc" | "protocol-item";
+		}>, "many">;
+	}, "strict", z.ZodTypeAny, {
+		disposition: "excluded" | "analyzed" | "unsupported";
+		source_ref: string;
+		module_ref: string | null;
+		normalized_path: string;
+		file_ref: string;
+		role: "primary-owner" | "enricher";
+		coverage_tier: "ast-catalog" | "lightweight-evidence";
+		facts: {
+			kind: string;
+			fact_ref: string;
+			locator: {
+				source_ref: string;
+				module_ref: string | null;
+				normalized_path: string;
+				qualified_item_path: string;
+				signature_digest: string;
+			};
+			payload_digest: string;
+			denominator: "symbol" | "none" | "eligible-file" | "loc" | "protocol-item";
+		}[];
+	}, {
+		disposition: "excluded" | "analyzed" | "unsupported";
+		source_ref: string;
+		module_ref: string | null;
+		normalized_path: string;
+		file_ref: string;
+		role: "primary-owner" | "enricher";
+		coverage_tier: "ast-catalog" | "lightweight-evidence";
+		facts: {
+			kind: string;
+			fact_ref: string;
+			locator: {
+				source_ref: string;
+				module_ref: string | null;
+				normalized_path: string;
+				qualified_item_path: string;
+				signature_digest: string;
+			};
+			payload_digest: string;
+			denominator: "symbol" | "none" | "eligible-file" | "loc" | "protocol-item";
+		}[];
+	}>, {
+		disposition: "excluded" | "analyzed" | "unsupported";
+		source_ref: string;
+		module_ref: string | null;
+		normalized_path: string;
+		file_ref: string;
+		role: "primary-owner" | "enricher";
+		coverage_tier: "ast-catalog" | "lightweight-evidence";
+		facts: {
+			kind: string;
+			fact_ref: string;
+			locator: {
+				source_ref: string;
+				module_ref: string | null;
+				normalized_path: string;
+				qualified_item_path: string;
+				signature_digest: string;
+			};
+			payload_digest: string;
+			denominator: "symbol" | "none" | "eligible-file" | "loc" | "protocol-item";
+		}[];
+	}, {
+		disposition: "excluded" | "analyzed" | "unsupported";
+		source_ref: string;
+		module_ref: string | null;
+		normalized_path: string;
+		file_ref: string;
+		role: "primary-owner" | "enricher";
+		coverage_tier: "ast-catalog" | "lightweight-evidence";
+		facts: {
+			kind: string;
+			fact_ref: string;
+			locator: {
+				source_ref: string;
+				module_ref: string | null;
+				normalized_path: string;
+				qualified_item_path: string;
+				signature_digest: string;
+			};
+			payload_digest: string;
+			denominator: "symbol" | "none" | "eligible-file" | "loc" | "protocol-item";
+		}[];
+	}>, "many">;
+	diagnostics: z.ZodArray<z.ZodObject<{
+		code: z.ZodEffects<z.ZodString, string, string>;
+		fact_ref: z.ZodOptional<z.ZodString>;
+		severity: z.ZodEnum<[
+			"info",
+			"warning",
+			"error"
+		]>;
+		detail_digest: z.ZodString;
+	}, "strict", z.ZodTypeAny, {
+		code: string;
+		severity: "warning" | "error" | "info";
+		detail_digest: string;
+		fact_ref?: string | undefined;
+	}, {
+		code: string;
+		severity: "warning" | "error" | "info";
+		detail_digest: string;
+		fact_ref?: string | undefined;
+	}>, "many">;
+	toolchain: z.ZodArray<z.ZodEffects<z.ZodObject<{
+		step: z.ZodEffects<z.ZodString, string, string>;
+		package: z.ZodString;
+		export: z.ZodString;
+		version: z.ZodString;
+		digest: z.ZodString;
+		capabilities: z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">;
+		input_digest: z.ZodString;
+		output_digest: z.ZodString;
+	}, "strict", z.ZodTypeAny, {
+		version: string;
+		package: string;
+		digest: string;
+		export: string;
+		step: string;
+		capabilities: string[];
+		input_digest: string;
+		output_digest: string;
+	}, {
+		version: string;
+		package: string;
+		digest: string;
+		export: string;
+		step: string;
+		capabilities: string[];
+		input_digest: string;
+		output_digest: string;
+	}>, {
+		version: string;
+		package: string;
+		digest: string;
+		export: string;
+		step: string;
+		capabilities: string[];
+		input_digest: string;
+		output_digest: string;
+	}, {
+		version: string;
+		package: string;
+		digest: string;
+		export: string;
+		step: string;
+		capabilities: string[];
+		input_digest: string;
+		output_digest: string;
+	}>, "many">;
+	output_digest: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+	input_digest: string;
+	output_digest: string;
+	protocol: "context.indexer.evidence-adapter-result/v1";
+	adapter: {
+		version: string;
+		package: string;
+		id: string;
+		digest: string;
+		export: string;
+	};
+	authorized_scope: {
+		source_ref: string;
+		module_refs: string[];
+		scope_digest: string;
+	};
+	precedence: number;
+	files: {
+		disposition: "excluded" | "analyzed" | "unsupported";
+		source_ref: string;
+		module_ref: string | null;
+		normalized_path: string;
+		file_ref: string;
+		role: "primary-owner" | "enricher";
+		coverage_tier: "ast-catalog" | "lightweight-evidence";
+		facts: {
+			kind: string;
+			fact_ref: string;
+			locator: {
+				source_ref: string;
+				module_ref: string | null;
+				normalized_path: string;
+				qualified_item_path: string;
+				signature_digest: string;
+			};
+			payload_digest: string;
+			denominator: "symbol" | "none" | "eligible-file" | "loc" | "protocol-item";
+		}[];
+	}[];
+	diagnostics: {
+		code: string;
+		severity: "warning" | "error" | "info";
+		detail_digest: string;
+		fact_ref?: string | undefined;
+	}[];
+	toolchain: {
+		version: string;
+		package: string;
+		digest: string;
+		export: string;
+		step: string;
+		capabilities: string[];
+		input_digest: string;
+		output_digest: string;
+	}[];
+}, {
+	input_digest: string;
+	output_digest: string;
+	protocol: "context.indexer.evidence-adapter-result/v1";
+	adapter: {
+		version: string;
+		package: string;
+		id: string;
+		digest: string;
+		export: string;
+	};
+	authorized_scope: {
+		source_ref: string;
+		module_refs: string[];
+		scope_digest: string;
+	};
+	precedence: number;
+	files: {
+		disposition: "excluded" | "analyzed" | "unsupported";
+		source_ref: string;
+		module_ref: string | null;
+		normalized_path: string;
+		file_ref: string;
+		role: "primary-owner" | "enricher";
+		coverage_tier: "ast-catalog" | "lightweight-evidence";
+		facts: {
+			kind: string;
+			fact_ref: string;
+			locator: {
+				source_ref: string;
+				module_ref: string | null;
+				normalized_path: string;
+				qualified_item_path: string;
+				signature_digest: string;
+			};
+			payload_digest: string;
+			denominator: "symbol" | "none" | "eligible-file" | "loc" | "protocol-item";
+		}[];
+	}[];
+	diagnostics: {
+		code: string;
+		severity: "warning" | "error" | "info";
+		detail_digest: string;
+		fact_ref?: string | undefined;
+	}[];
+	toolchain: {
+		version: string;
+		package: string;
+		digest: string;
+		export: string;
+		step: string;
+		capabilities: string[];
+		input_digest: string;
+		output_digest: string;
+	}[];
+}>, {
+	input_digest: string;
+	output_digest: string;
+	protocol: "context.indexer.evidence-adapter-result/v1";
+	adapter: {
+		version: string;
+		package: string;
+		id: string;
+		digest: string;
+		export: string;
+	};
+	authorized_scope: {
+		source_ref: string;
+		module_refs: string[];
+		scope_digest: string;
+	};
+	precedence: number;
+	files: {
+		disposition: "excluded" | "analyzed" | "unsupported";
+		source_ref: string;
+		module_ref: string | null;
+		normalized_path: string;
+		file_ref: string;
+		role: "primary-owner" | "enricher";
+		coverage_tier: "ast-catalog" | "lightweight-evidence";
+		facts: {
+			kind: string;
+			fact_ref: string;
+			locator: {
+				source_ref: string;
+				module_ref: string | null;
+				normalized_path: string;
+				qualified_item_path: string;
+				signature_digest: string;
+			};
+			payload_digest: string;
+			denominator: "symbol" | "none" | "eligible-file" | "loc" | "protocol-item";
+		}[];
+	}[];
+	diagnostics: {
+		code: string;
+		severity: "warning" | "error" | "info";
+		detail_digest: string;
+		fact_ref?: string | undefined;
+	}[];
+	toolchain: {
+		version: string;
+		package: string;
+		digest: string;
+		export: string;
+		step: string;
+		capabilities: string[];
+		input_digest: string;
+		output_digest: string;
+	}[];
+}, {
+	input_digest: string;
+	output_digest: string;
+	protocol: "context.indexer.evidence-adapter-result/v1";
+	adapter: {
+		version: string;
+		package: string;
+		id: string;
+		digest: string;
+		export: string;
+	};
+	authorized_scope: {
+		source_ref: string;
+		module_refs: string[];
+		scope_digest: string;
+	};
+	precedence: number;
+	files: {
+		disposition: "excluded" | "analyzed" | "unsupported";
+		source_ref: string;
+		module_ref: string | null;
+		normalized_path: string;
+		file_ref: string;
+		role: "primary-owner" | "enricher";
+		coverage_tier: "ast-catalog" | "lightweight-evidence";
+		facts: {
+			kind: string;
+			fact_ref: string;
+			locator: {
+				source_ref: string;
+				module_ref: string | null;
+				normalized_path: string;
+				qualified_item_path: string;
+				signature_digest: string;
+			};
+			payload_digest: string;
+			denominator: "symbol" | "none" | "eligible-file" | "loc" | "protocol-item";
+		}[];
+	}[];
+	diagnostics: {
+		code: string;
+		severity: "warning" | "error" | "info";
+		detail_digest: string;
+		fact_ref?: string | undefined;
+	}[];
+	toolchain: {
+		version: string;
+		package: string;
+		digest: string;
+		export: string;
+		step: string;
+		capabilities: string[];
+		input_digest: string;
+		output_digest: string;
+	}[];
+}>;
+type IndexerEvidenceAdapterResult = z.infer<typeof indexerEvidenceAdapterResultSchema>;
+type IndexerEvidenceAdapterFactPayloadValue = null | boolean | number | string | IndexerEvidenceAdapterFactPayloadValue[] | {
+	[key: string]: IndexerEvidenceAdapterFactPayloadValue;
+};
+interface IndexerEvidenceAdapterFactPayload {
+	fact_ref: string;
+	payload: IndexerEvidenceAdapterFactPayloadValue;
+}
+interface IndexerEvidenceAdapterMaterialization {
+	result: IndexerEvidenceAdapterResult;
+	fact_payloads: IndexerEvidenceAdapterFactPayload[];
+}
+export interface ContractEvidenceAdapterInvocation {
+	adapter: IndexerEvidenceAdapterResult["adapter"];
+	authorized_scope: IndexerEvidenceAdapterResult["authorized_scope"];
+	input_digest: string;
+	precedence: number;
+	module_refs?: Readonly<Record<string, string | null>>;
+	role?: "primary-owner" | "enricher";
+}
+/** Parses caller-registered contract text and emits only the common Evidence ABI. */
+export declare function contractSourcesToEvidenceAdapterResult(files: Readonly<Record<string, string>>, invocation: ContractEvidenceAdapterInvocation): IndexerEvidenceAdapterResult;
+export declare function contractSourcesToEvidenceAdapterMaterialization(files: Readonly<Record<string, string>>, invocation: ContractEvidenceAdapterInvocation): IndexerEvidenceAdapterMaterialization;
+export declare const CONTRACT_EVIDENCE_ADAPTER_EXPORT = "contractSourcesToEvidenceAdapterMaterialization";
+
+export {};

package/index.js

@@ -21825,6 +21825,26 @@ function refTarget(importer, raw) {
   const targetPath = posix.normalize(posix.join(posix.dirname(importer), rawPath));
   return portablePath(targetPath) ? { targetPath, pointer, external: true } : null;
 }
+function openApiSourceDependencies(path, source) {
+  if (!/\.(?:json|ya?ml)$/iu.test(path))
+    return [];
+  if (!portablePath(path))
+    throw new TypeError(`contract source path is not portable: ${path}`);
+  const parsed = parseYaml(path, source);
+  if (parsed.parseError)
+    throw new TypeError(`${path}: ${parsed.parseError}`);
+  const dependencies = new Set;
+  for (const ref of collectRefs(parsed)) {
+    if (ref.underBaseId && !ref.raw.startsWith("#"))
+      throw new TypeError(`${path}: reference under $id requires an explicit registered URI mapping: ${ref.raw}`);
+    const target = refTarget(path, ref.raw);
+    if (!target)
+      throw new TypeError(`${path}: reference leaves registered source scope: ${ref.raw}`);
+    if (target.external)
+      dependencies.add(target.targetPath);
+  }
+  return [...dependencies];
+}
 function cycleMembers(graph) {
   const cycles = new Set;
   const visiting = new Set;
@@ -27146,6 +27166,7 @@ function contractSourcesToEvidenceAdapterMaterialization(files, invocation) {
 var CONTRACT_EVIDENCE_ADAPTER_EXPORT = "contractSourcesToEvidenceAdapterMaterialization";
 export {
   parseContractSources,
+  openApiSourceDependencies,
   contractSourcesToEvidenceAdapterResult,
   contractSourcesToEvidenceAdapterMaterialization,
   CONTRACT_EVIDENCE_ADAPTER_EXPORT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c4a/extract-contract",
-  "version": "0.7.9",
+  "version": "0.7.10-alpha.2",
   "type": "module",
   "description": "OpenAPI and GraphQL contract catalog adapter for Context",
   "license": "MIT",
@@ -20,7 +20,9 @@
   },
   "dependencies": {
     "graphql": "^16.14.2",
-    "yaml": "^2.8.2"
+    "yaml": "^2.8.2",
+    "zod": "^3.23.8"
   },
-  "main": "./index.js"
+  "main": "./index.js",
+  "types": "./index.d.ts"
 }