@contractspec/module.workspace 1.44.0

package/dist/analysis/snapshot/snapshot.d.ts

@@ -0,0 +1,18 @@
+import { ContractSnapshot, SnapshotOptions } from "./types.js";
+
+//#region src/analysis/snapshot/snapshot.d.ts
+
+/**
+ * Generate a contract snapshot from spec source files.
+ *
+ * @param specs - Array of { path, content } for each spec file
+ * @param options - Snapshot generation options
+ * @returns Canonical contract snapshot
+ */
+declare function generateSnapshot(specs: {
+  path: string;
+  content: string;
+}[], options?: SnapshotOptions): ContractSnapshot;
+//#endregion
+export { generateSnapshot };
+//# sourceMappingURL=snapshot.d.ts.map

package/dist/analysis/snapshot/snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","names":[],"sources":["../../../src/analysis/snapshot/snapshot.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;iBA2BgB,gBAAA;;;eAEL,kBACR"}

package/dist/analysis/snapshot/snapshot.js

@@ -0,0 +1,163 @@
+import { scanSpecSource } from "../spec-scan.js";
+import { computeHash, sortFields, sortSpecs } from "./normalizer.js";
+
+//#region src/analysis/snapshot/snapshot.ts
+/**
+* Contract snapshot generation.
+*
+* Generates canonical, deterministic snapshots from spec source files
+* for comparison and impact detection.
+*/
+/**
+* Generate a contract snapshot from spec source files.
+*
+* @param specs - Array of { path, content } for each spec file
+* @param options - Snapshot generation options
+* @returns Canonical contract snapshot
+*/
+function generateSnapshot(specs, options = {}) {
+	const snapshots = [];
+	for (const { path, content } of specs) {
+		const scanned = scanSpecSource(content, path);
+		if (options.types && !options.types.includes(scanned.specType)) continue;
+		if (scanned.specType === "operation" && scanned.key && scanned.version !== void 0) {
+			const opSnapshot = createOperationSnapshot(scanned, content);
+			if (opSnapshot) snapshots.push(opSnapshot);
+		} else if (scanned.specType === "event" && scanned.key && scanned.version !== void 0) {
+			const eventSnapshot = createEventSnapshot(scanned, content);
+			if (eventSnapshot) snapshots.push(eventSnapshot);
+		}
+	}
+	const sortedSpecs = sortSpecs(snapshots);
+	const hash = computeHash({ specs: sortedSpecs });
+	return {
+		version: 1,
+		generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		specs: sortedSpecs,
+		hash
+	};
+}
+/**
+* Create an operation snapshot from scanned spec data.
+*/
+function createOperationSnapshot(scanned, content) {
+	if (!scanned.key || scanned.version === void 0) return null;
+	const io = extractIoFromSource(content);
+	const http = extractHttpBinding(content);
+	return {
+		type: "operation",
+		key: scanned.key,
+		version: scanned.version,
+		kind: scanned.kind === "command" || scanned.kind === "query" ? scanned.kind : "command",
+		stability: scanned.stability ?? "experimental",
+		http: http ?? void 0,
+		io,
+		authLevel: extractAuthLevel(content),
+		emittedEvents: scanned.emittedEvents
+	};
+}
+/**
+* Create an event snapshot from scanned spec data.
+*/
+function createEventSnapshot(scanned, content) {
+	if (!scanned.key || scanned.version === void 0) return null;
+	const payload = extractPayloadFromSource(content);
+	return {
+		type: "event",
+		key: scanned.key,
+		version: scanned.version,
+		stability: scanned.stability ?? "experimental",
+		payload
+	};
+}
+/**
+* Extract IO schema from source code.
+* This is a heuristic extraction - not full Zod introspection.
+*/
+function extractIoFromSource(content) {
+	const input = extractSchemaFields(content, "input");
+	const output = extractSchemaFields(content, "output");
+	return {
+		input: sortFields(input),
+		output: sortFields(output)
+	};
+}
+/**
+* Extract payload schema from event source code.
+*/
+function extractPayloadFromSource(content) {
+	return sortFields(extractSchemaFields(content, "payload"));
+}
+/**
+* Extract schema fields from a specific section of the source.
+*/
+function extractSchemaFields(content, section) {
+	const fields = {};
+	const sectionPattern = new RegExp(`${section}\\s*:\\s*z\\.object\\(\\{([^}]+)\\}`, "s");
+	const sectionMatch = content.match(sectionPattern);
+	if (!sectionMatch?.[1]) return fields;
+	const sectionContent = sectionMatch[1];
+	const fieldPattern = /(\w+)\s*:\s*z\.(\w+)\((.*?)\)/g;
+	let match;
+	while ((match = fieldPattern.exec(sectionContent)) !== null) {
+		const [, fieldName, zodType] = match;
+		if (!fieldName || !zodType) continue;
+		const isOptional = sectionContent.includes(`${fieldName}:`) && sectionContent.slice(sectionContent.indexOf(`${fieldName}:`)).includes(".optional()");
+		const isNullable = sectionContent.includes(`${fieldName}:`) && sectionContent.slice(sectionContent.indexOf(`${fieldName}:`)).includes(".nullable()");
+		fields[fieldName] = {
+			name: fieldName,
+			type: mapZodTypeToFieldType(zodType),
+			required: !isOptional,
+			nullable: isNullable
+		};
+	}
+	return fields;
+}
+/**
+* Map Zod type to FieldType.
+*/
+function mapZodTypeToFieldType(zodType) {
+	return {
+		string: "string",
+		number: "number",
+		boolean: "boolean",
+		object: "object",
+		array: "array",
+		enum: "enum",
+		union: "union",
+		literal: "literal",
+		date: "date",
+		coerce: "unknown"
+	}[zodType] ?? "unknown";
+}
+/**
+* Extract HTTP binding from source code.
+*/
+function extractHttpBinding(content) {
+	const methodMatch = content.match(/method\s*:\s*['"](\w+)['"]/);
+	const pathMatch = content.match(/path\s*:\s*['"]([^'"]+)['"]/);
+	if (methodMatch?.[1] && pathMatch?.[1]) {
+		const method = methodMatch[1].toUpperCase();
+		if ([
+			"GET",
+			"POST",
+			"PUT",
+			"PATCH",
+			"DELETE"
+		].includes(method)) return {
+			method,
+			path: pathMatch[1]
+		};
+	}
+	return null;
+}
+/**
+* Extract auth level from source code.
+*/
+function extractAuthLevel(content) {
+	return content.match(/auth\s*:\s*['"](\w+)['"]/)?.[1];
+}
+
+//#endregion
+export { generateSnapshot };
+//# sourceMappingURL=snapshot.js.map

package/dist/analysis/snapshot/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","names":["snapshots: SpecSnapshot[]","fields: Record<string, FieldSnapshot>"],"sources":["../../../src/analysis/snapshot/snapshot.ts"],"sourcesContent":["/**\n * Contract snapshot generation.\n *\n * Generates canonical, deterministic snapshots from spec source files\n * for comparison and impact detection.\n */\n\nimport { scanSpecSource } from '../spec-scan';\nimport { computeHash, sortSpecs, sortFields } from './normalizer';\nimport type {\n  ContractSnapshot,\n  EventSnapshot,\n  FieldSnapshot,\n  FieldType,\n  IoSnapshot,\n  OperationSnapshot,\n  SnapshotOptions,\n  SpecSnapshot,\n} from './types';\n\n/**\n * Generate a contract snapshot from spec source files.\n *\n * @param specs - Array of { path, content } for each spec file\n * @param options - Snapshot generation options\n * @returns Canonical contract snapshot\n */\nexport function generateSnapshot(\n  specs: { path: string; content: string }[],\n  options: SnapshotOptions = {}\n): ContractSnapshot {\n  const snapshots: SpecSnapshot[] = [];\n\n  for (const { path, content } of specs) {\n    const scanned = scanSpecSource(content, path);\n\n    // Filter by types if specified\n    if (\n      options.types &&\n      !options.types.includes(scanned.specType as 'operation' | 'event')\n    ) {\n      continue;\n    }\n\n    if (\n      scanned.specType === 'operation' &&\n      scanned.key &&\n      scanned.version !== undefined\n    ) {\n      const opSnapshot = createOperationSnapshot(scanned, content);\n      if (opSnapshot) {\n        snapshots.push(opSnapshot);\n      }\n    } else if (\n      scanned.specType === 'event' &&\n      scanned.key &&\n      scanned.version !== undefined\n    ) {\n      const eventSnapshot = createEventSnapshot(scanned, content);\n      if (eventSnapshot) {\n        snapshots.push(eventSnapshot);\n      }\n    }\n  }\n\n  const sortedSpecs = sortSpecs(snapshots);\n  const hash = computeHash({ specs: sortedSpecs });\n\n  return {\n    version: 1,\n    generatedAt: new Date().toISOString(),\n    specs: sortedSpecs,\n    hash,\n  };\n}\n\n/**\n * Create an operation snapshot from scanned spec data.\n */\nfunction createOperationSnapshot(\n  scanned: ReturnType<typeof scanSpecSource>,\n  content: string\n): OperationSnapshot | null {\n  if (!scanned.key || scanned.version === undefined) {\n    return null;\n  }\n\n  const io = extractIoFromSource(content);\n  const http = extractHttpBinding(content);\n\n  return {\n    type: 'operation',\n    key: scanned.key,\n    version: scanned.version,\n    kind:\n      scanned.kind === 'command' || scanned.kind === 'query'\n        ? scanned.kind\n        : 'command',\n    stability: scanned.stability ?? 'experimental',\n    http: http ?? undefined,\n    io,\n    authLevel: extractAuthLevel(content),\n    emittedEvents: scanned.emittedEvents,\n  };\n}\n\n/**\n * Create an event snapshot from scanned spec data.\n */\nfunction createEventSnapshot(\n  scanned: ReturnType<typeof scanSpecSource>,\n  content: string\n): EventSnapshot | null {\n  if (!scanned.key || scanned.version === undefined) {\n    return null;\n  }\n\n  const payload = extractPayloadFromSource(content);\n\n  return {\n    type: 'event',\n    key: scanned.key,\n    version: scanned.version,\n    stability: scanned.stability ?? 'experimental',\n    payload,\n  };\n}\n\n/**\n * Extract IO schema from source code.\n * This is a heuristic extraction - not full Zod introspection.\n */\nfunction extractIoFromSource(content: string): IoSnapshot {\n  const input = extractSchemaFields(content, 'input');\n  const output = extractSchemaFields(content, 'output');\n\n  return {\n    input: sortFields(input) as Record<string, FieldSnapshot>,\n    output: sortFields(output) as Record<string, FieldSnapshot>,\n  };\n}\n\n/**\n * Extract payload schema from event source code.\n */\nfunction extractPayloadFromSource(\n  content: string\n): Record<string, FieldSnapshot> {\n  const fields = extractSchemaFields(content, 'payload');\n  return sortFields(fields) as Record<string, FieldSnapshot>;\n}\n\n/**\n * Extract schema fields from a specific section of the source.\n */\nfunction extractSchemaFields(\n  content: string,\n  section: 'input' | 'output' | 'payload'\n): Record<string, FieldSnapshot> {\n  const fields: Record<string, FieldSnapshot> = {};\n\n  // Look for z.object({ ... }) patterns within the section\n  const sectionPattern = new RegExp(\n    `${section}\\\\s*:\\\\s*z\\\\.object\\\\(\\\\{([^}]+)\\\\}`,\n    's'\n  );\n  const sectionMatch = content.match(sectionPattern);\n\n  if (!sectionMatch?.[1]) {\n    return fields;\n  }\n\n  const sectionContent = sectionMatch[1];\n\n  // Match field definitions: fieldName: z.string(), z.number(), etc.\n  const fieldPattern = /(\\w+)\\s*:\\s*z\\.(\\w+)\\((.*?)\\)/g;\n  let match;\n\n  while ((match = fieldPattern.exec(sectionContent)) !== null) {\n    const [, fieldName, zodType] = match;\n    if (!fieldName || !zodType) continue;\n\n    const isOptional =\n      sectionContent.includes(`${fieldName}:`) &&\n      sectionContent\n        .slice(sectionContent.indexOf(`${fieldName}:`))\n        .includes('.optional()');\n    const isNullable =\n      sectionContent.includes(`${fieldName}:`) &&\n      sectionContent\n        .slice(sectionContent.indexOf(`${fieldName}:`))\n        .includes('.nullable()');\n\n    fields[fieldName] = {\n      name: fieldName,\n      type: mapZodTypeToFieldType(zodType),\n      required: !isOptional,\n      nullable: isNullable,\n    };\n  }\n\n  return fields;\n}\n\n/**\n * Map Zod type to FieldType.\n */\nfunction mapZodTypeToFieldType(zodType: string): FieldType {\n  const mapping: Record<string, FieldType> = {\n    string: 'string',\n    number: 'number',\n    boolean: 'boolean',\n    object: 'object',\n    array: 'array',\n    enum: 'enum',\n    union: 'union',\n    literal: 'literal',\n    date: 'date',\n    coerce: 'unknown',\n  };\n  return mapping[zodType] ?? 'unknown';\n}\n\n/**\n * Extract HTTP binding from source code.\n */\nfunction extractHttpBinding(content: string): {\n  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';\n  path: string;\n} | null {\n  // Look for http: { method: 'X', path: 'Y' } pattern\n  const methodMatch = content.match(/method\\s*:\\s*['\"](\\w+)['\"]/);\n  const pathMatch = content.match(/path\\s*:\\s*['\"]([^'\"]+)['\"]/);\n\n  if (methodMatch?.[1] && pathMatch?.[1]) {\n    const method = methodMatch[1].toUpperCase();\n    if (['GET', 'POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) {\n      return {\n        method: method as 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',\n        path: pathMatch[1],\n      };\n    }\n  }\n\n  return null;\n}\n\n/**\n * Extract auth level from source code.\n */\nfunction extractAuthLevel(content: string): string | undefined {\n  const authMatch = content.match(/auth\\s*:\\s*['\"](\\w+)['\"]/);\n  return authMatch?.[1];\n}\n"],"mappings":"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"}

package/dist/analysis/snapshot/types.d.ts

@@ -0,0 +1,80 @@
+//#region src/analysis/snapshot/types.d.ts
+/**
+ * Canonical contract snapshot types.
+ *
+ * These types define the normalized, deterministic representation
+ * of contracts for comparison and impact detection.
+ */
+/** Field type in a schema */
+type FieldType = 'string' | 'number' | 'boolean' | 'object' | 'array' | 'enum' | 'union' | 'literal' | 'date' | 'unknown';
+/** Schema field definition */
+interface FieldSnapshot {
+  name: string;
+  type: FieldType;
+  required: boolean;
+  nullable: boolean;
+  description?: string;
+  enumValues?: string[];
+  literalValue?: unknown;
+  items?: FieldSnapshot;
+  properties?: Record<string, FieldSnapshot>;
+  unionTypes?: FieldSnapshot[];
+}
+/** IO schema snapshot */
+interface IoSnapshot {
+  input: Record<string, FieldSnapshot>;
+  output: Record<string, FieldSnapshot>;
+}
+/** HTTP binding snapshot */
+interface HttpBindingSnapshot {
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  path: string;
+}
+/** Operation snapshot */
+interface OperationSnapshot {
+  type: 'operation';
+  key: string;
+  version: number;
+  kind: 'command' | 'query';
+  stability: string;
+  http?: HttpBindingSnapshot;
+  io: IoSnapshot;
+  authLevel?: string;
+  emittedEvents?: {
+    key: string;
+    version: number;
+  }[];
+}
+/** Event payload snapshot */
+interface EventSnapshot {
+  type: 'event';
+  key: string;
+  version: number;
+  stability: string;
+  payload: Record<string, FieldSnapshot>;
+}
+/** Spec snapshot union type */
+type SpecSnapshot = OperationSnapshot | EventSnapshot;
+/** Full contract snapshot for a workspace */
+interface ContractSnapshot {
+  /** Schema version for forward compatibility */
+  version: 1;
+  /** Generation timestamp (ISO 8601) */
+  generatedAt: string;
+  /** Git commit SHA if available */
+  commitSha?: string;
+  /** All specs in the workspace */
+  specs: SpecSnapshot[];
+  /** Content hash for quick comparison */
+  hash: string;
+}
+/** Options for snapshot generation */
+interface SnapshotOptions {
+  /** Glob pattern for spec discovery */
+  pattern?: string;
+  /** Include only specific spec types */
+  types?: ('operation' | 'event')[];
+}
+//#endregion
+export { ContractSnapshot, EventSnapshot, FieldSnapshot, FieldType, HttpBindingSnapshot, IoSnapshot, OperationSnapshot, SnapshotOptions, SpecSnapshot };
+//# sourceMappingURL=types.d.ts.map

package/dist/analysis/snapshot/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/analysis/snapshot/types.ts"],"sourcesContent":[],"mappings":";;AAQA;AAaA;;;;;AAUe,KAvBH,SAAA,GAuBG,QAAA,GAAA,QAAA,GAAA,SAAA,GAAA,QAAA,GAAA,OAAA,GAAA,MAAA,GAAA,OAAA,GAAA,SAAA,GAAA,MAAA,GAAA,SAAA;;AAIE,UAdA,aAAA,CAcU;EACH,IAAA,EAAA,MAAA;EAAf,IAAA,EAbD,SAaC;EACgB,QAAA,EAAA,OAAA;EAAf,QAAA,EAAA,OAAA;EAAM,WAAA,CAAA,EAAA,MAAA;EAIC,UAAA,CAAA,EAAA,MAAA,EAAA;EAMA,YAAA,CAAA,EAAA,OAAiB;EAajB,KAAA,CAAA,EA/BP,aA+BoB;EASlB,UAAA,CAAA,EAvCG,MAuCS,CAAA,MAAA,EAvCM,aAuCH,CAAA;EAGV,UAAA,CAAA,EAzCF,aAyCkB,EAAA;AAcjC;;UAnDiB,UAAA;SACR,eAAe;UACd,eAAe;;;UAIR,mBAAA;;;;;UAMA,iBAAA;;;;;;SAMR;MACH;;;;;;;;UAMW,aAAA;;;;;WAKN,eAAe;;;KAId,YAAA,GAAe,oBAAoB;;UAG9B,gBAAA;;;;;;;;SAQR;;;;;UAMQ,eAAA"}

package/dist/analysis/spec-scan.d.ts

@@ -0,0 +1,34 @@
+import { AnalyzedSpecType, RefInfo, SpecScanResult } from "../types/analysis-types.js";
+
+//#region src/analysis/spec-scan.d.ts
+
+/**
+ * Infer spec type from file path based on naming conventions.
+ * Supports all contract types from @contractspec/lib.contracts.
+ */
+declare function inferSpecTypeFromFilePath(filePath: string): AnalyzedSpecType;
+/**
+ * Scan spec source code to extract metadata without executing it.
+ */
+declare function scanSpecSource(code: string, filePath: string): SpecScanResult;
+/**
+ * Extract emitted event refs from operation spec source.
+ * Looks for sideEffects.emits array entries.
+ */
+declare function extractEmittedEvents(code: string): RefInfo[] | undefined;
+/**
+ * Extract policy refs from operation spec source.
+ */
+declare function extractPolicyRefs(code: string): RefInfo[] | undefined;
+/**
+ * Extract test spec refs.
+ */
+declare function extractTestRefs(code: string): RefInfo[] | undefined;
+/**
+ * Scan spec source code to extract ALL specs from a file.
+ * This function finds multiple spec definitions in a single file.
+ */
+declare function scanAllSpecsFromSource(code: string, filePath: string): SpecScanResult[];
+//#endregion
+export { extractEmittedEvents, extractPolicyRefs, extractTestRefs, inferSpecTypeFromFilePath, scanAllSpecsFromSource, scanSpecSource };
+//# sourceMappingURL=spec-scan.d.ts.map

package/dist/analysis/spec-scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-scan.d.ts","names":[],"sources":["../../src/analysis/spec-scan.ts"],"sourcesContent":[],"mappings":";;;;AAoHA;AAgCA;AA0BA;AAoMA;iBAjWgB,yBAAA,oBAA6C;;;;iBA8C7C,cAAA,kCAAgD;;;;;iBAqDhD,oBAAA,gBAAoC;;;;iBAgCpC,iBAAA,gBAAiC;;;;iBA0BjC,eAAA,gBAA+B;;;;;iBAoM/B,sBAAA,kCAGb"}

package/dist/analysis/spec-scan.js

@@ -0,0 +1,349 @@
+//#region src/analysis/spec-scan.ts
+/**
+* Infer spec type from file path based on naming conventions.
+* Supports all contract types from @contractspec/lib.contracts.
+*/
+function inferSpecTypeFromFilePath(filePath) {
+	if (filePath.includes(".operations.") || filePath.includes("/operations/") || filePath.includes(".operation.") || filePath.includes("/operation/")) return "operation";
+	if (filePath.includes(".event.") || filePath.includes("/events/") || filePath.endsWith("/events.ts")) return "event";
+	if (filePath.includes(".presentation.") || filePath.includes("/presentations/") || filePath.endsWith("/presentations.ts")) return "presentation";
+	if (filePath.includes(".feature.")) return "feature";
+	if (filePath.includes(".capability.")) return "capability";
+	if (filePath.includes(".data-view.")) return "data-view";
+	if (filePath.includes(".form.")) return "form";
+	if (filePath.includes(".migration.")) return "migration";
+	if (filePath.includes(".workflow.")) return "workflow";
+	if (filePath.includes(".experiment.")) return "experiment";
+	if (filePath.includes(".integration.")) return "integration";
+	if (filePath.includes(".knowledge.")) return "knowledge";
+	if (filePath.includes(".telemetry.")) return "telemetry";
+	if (filePath.includes(".app-config.")) return "app-config";
+	if (filePath.includes(".policy.")) return "policy";
+	if (filePath.includes(".test-spec.")) return "test-spec";
+	return "unknown";
+}
+/**
+* Scan spec source code to extract metadata without executing it.
+*/
+function scanSpecSource(code, filePath) {
+	const specType = inferSpecTypeFromFilePath(filePath);
+	const key = matchStringField(code, "key");
+	const description = matchStringField(code, "description");
+	const stabilityRaw = matchStringField(code, "stability");
+	const stability = isStability(stabilityRaw) ? stabilityRaw : void 0;
+	const owners = matchStringArrayField(code, "owners");
+	const tags = matchStringArrayField(code, "tags");
+	const version = matchNumberField(code, "version");
+	const kind = inferOperationKind(code);
+	const hasMeta = /meta\s*:\s*{/.test(code);
+	const hasIo = /\bio\s*:\s*{/.test(code);
+	const hasPolicy = /\bpolicy\s*:\s*{/.test(code);
+	const hasPayload = /\bpayload\s*:\s*{/.test(code);
+	const hasContent = /\bcontent\s*:\s*{/.test(code);
+	const hasDefinition = /\bdefinition\s*:\s*{/.test(code);
+	const emittedEvents = specType === "operation" ? extractEmittedEvents(code) : void 0;
+	const policyRefs = specType === "operation" ? extractPolicyRefs(code) : void 0;
+	const testRefs = extractTestRefs(code);
+	return {
+		filePath,
+		specType,
+		key: key ?? void 0,
+		description: description ?? void 0,
+		stability,
+		owners,
+		tags,
+		version: version ?? void 0,
+		kind,
+		hasMeta,
+		hasIo,
+		hasPolicy,
+		hasPayload,
+		hasContent,
+		hasDefinition,
+		emittedEvents,
+		policyRefs,
+		testRefs
+	};
+}
+/**
+* Extract emitted event refs from operation spec source.
+* Looks for sideEffects.emits array entries.
+*/
+function extractEmittedEvents(code) {
+	const events = [];
+	const inlinePattern = /\{\s*key:\s*['"]([^'"]+)['"]\s*,\s*version:\s*(\d+)/g;
+	let match;
+	while ((match = inlinePattern.exec(code)) !== null) if (match[1] && match[2]) events.push({
+		key: match[1],
+		version: Number(match[2])
+	});
+	const refPattern = /\{\s*ref:\s*(\w+)/g;
+	while ((match = refPattern.exec(code)) !== null) if (match[1] && !match[1].startsWith("when")) {}
+	return events.length > 0 ? events : void 0;
+}
+/**
+* Extract policy refs from operation spec source.
+*/
+function extractPolicyRefs(code) {
+	const policies = [];
+	const policyPattern = /\{\s*key:\s*['"]([^'"]+)['"]\s*,\s*version:\s*(\d+)/g;
+	const policySectionMatch = code.match(/policies\s*:\s*\[([\s\S]*?)\]/);
+	if (policySectionMatch?.[1]) {
+		let match;
+		while ((match = policyPattern.exec(policySectionMatch[1])) !== null) if (match[1] && match[2]) policies.push({
+			key: match[1],
+			version: Number(match[2])
+		});
+	}
+	return policies.length > 0 ? policies : void 0;
+}
+/**
+* Extract test spec refs.
+*/
+function extractTestRefs(code) {
+	const tests = [];
+	const testsSectionMatch = code.match(/tests\s*:\s*\[([\s\S]*?)\]/);
+	if (testsSectionMatch?.[1]) {
+		const refPattern = /\{\s*key:\s*['"]([^'"]+)['"]\s*,\s*version:\s*(\d+)/g;
+		let match;
+		while ((match = refPattern.exec(testsSectionMatch[1])) !== null) if (match[1] && match[2]) tests.push({
+			key: match[1],
+			version: Number(match[2])
+		});
+	}
+	return tests.length > 0 ? tests : void 0;
+}
+function matchStringField(code, field) {
+	const regex = /* @__PURE__ */ new RegExp(`${escapeRegex(field)}\\s*:\\s*['"]([^'"]+)['"]`);
+	return code.match(regex)?.[1] ?? null;
+}
+function matchNumberField(code, field) {
+	const regex = /* @__PURE__ */ new RegExp(`${escapeRegex(field)}\\s*:\\s*(\\d+)`);
+	const match = code.match(regex);
+	if (!match?.[1]) return null;
+	const parsed = Number(match[1]);
+	return Number.isFinite(parsed) ? parsed : null;
+}
+function matchStringArrayField(code, field) {
+	const regex = /* @__PURE__ */ new RegExp(`${escapeRegex(field)}\\s*:\\s*\\[([\\s\\S]*?)\\]`);
+	const match = code.match(regex);
+	if (!match?.[1]) return void 0;
+	const inner = match[1];
+	const items = Array.from(inner.matchAll(/['"]([^'"]+)['"]/g)).map((m) => m[1]).filter((value) => typeof value === "string" && value.length > 0);
+	return items.length > 0 ? items : void 0;
+}
+function isStability(value) {
+	return value === "experimental" || value === "beta" || value === "stable" || value === "deprecated";
+}
+function escapeRegex(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+* Infer operation kind from source code.
+* First checks for defineCommand/defineQuery usage (which set kind automatically),
+* then falls back to explicit kind field.
+*/
+function inferOperationKind(code) {
+	if (/defineCommand\s*\(/.test(code)) return "command";
+	if (/defineQuery\s*\(/.test(code)) return "query";
+	const kindRaw = matchStringField(code, "kind");
+	return kindRaw === "command" || kindRaw === "query" ? kindRaw : "unknown";
+}
+/**
+* Infer operation kind from a specific code block.
+*/
+function inferOperationKindFromBlock(block) {
+	if (/defineCommand\s*\(/.test(block)) return "command";
+	if (/defineQuery\s*\(/.test(block)) return "query";
+	const kindRaw = matchStringField(block, "kind");
+	return kindRaw === "command" || kindRaw === "query" ? kindRaw : "unknown";
+}
+/**
+* Extract key and version from a meta block.
+*/
+function extractMetaFromBlock(block) {
+	const key = matchStringField(block, "key");
+	const version = matchNumberField(block, "version");
+	if (key && version !== null) return {
+		key,
+		version
+	};
+	return null;
+}
+/**
+* Define function patterns for all spec types.
+*/
+const DEFINE_FUNCTION_PATTERNS = [
+	{
+		pattern: /defineCommand\s*\(\s*\{/g,
+		type: "operation"
+	},
+	{
+		pattern: /defineQuery\s*\(\s*\{/g,
+		type: "operation"
+	},
+	{
+		pattern: /defineEvent\s*\(\s*\{/g,
+		type: "event"
+	},
+	{
+		pattern: /:\s*PresentationSpec\s*=\s*\{/g,
+		type: "presentation"
+	},
+	{
+		pattern: /:\s*PresentationSpec\s*=\s*\{/g,
+		type: "presentation"
+	},
+	{
+		pattern: /:\s*PresentationDescriptor\s*=\s*\{/g,
+		type: "presentation"
+	},
+	{
+		pattern: /definePresentation\s*\(\s*\{/g,
+		type: "presentation"
+	},
+	{
+		pattern: /defineCapability\s*\(\s*\{/g,
+		type: "capability"
+	},
+	{
+		pattern: /defineWorkflow\s*\(\s*\{/g,
+		type: "workflow"
+	},
+	{
+		pattern: /defineExperiment\s*\(\s*\{/g,
+		type: "experiment"
+	},
+	{
+		pattern: /defineIntegration\s*\(\s*\{/g,
+		type: "integration"
+	},
+	{
+		pattern: /defineKnowledge\s*\(\s*\{/g,
+		type: "knowledge"
+	},
+	{
+		pattern: /defineTelemetry\s*\(\s*\{/g,
+		type: "telemetry"
+	},
+	{
+		pattern: /defineAppConfig\s*\(\s*\{/g,
+		type: "app-config"
+	},
+	{
+		pattern: /definePolicy\s*\(\s*\{/g,
+		type: "policy"
+	},
+	{
+		pattern: /defineTestSpec\s*\(\s*\{/g,
+		type: "test-spec"
+	},
+	{
+		pattern: /defineDataView\s*\(\s*\{/g,
+		type: "data-view"
+	},
+	{
+		pattern: /defineForm\s*\(\s*\{/g,
+		type: "form"
+	},
+	{
+		pattern: /defineMigration\s*\(\s*\{/g,
+		type: "migration"
+	}
+];
+/**
+* Find matching closing brace for an opening brace.
+* Returns the index of the closing brace or -1 if not found.
+*/
+function findMatchingBrace(code, startIndex) {
+	let depth = 0;
+	let inString = false;
+	let stringChar = "";
+	for (let i = startIndex; i < code.length; i++) {
+		const char = code[i];
+		const prevChar = i > 0 ? code[i - 1] : "";
+		if ((char === "\"" || char === "'" || char === "`") && prevChar !== "\\") {
+			if (!inString) {
+				inString = true;
+				stringChar = char;
+			} else if (char === stringChar) inString = false;
+			continue;
+		}
+		if (inString) continue;
+		if (char === "{") depth++;
+		else if (char === "}") {
+			depth--;
+			if (depth === 0) return i;
+		}
+	}
+	return -1;
+}
+/**
+* Scan spec source code to extract ALL specs from a file.
+* This function finds multiple spec definitions in a single file.
+*/
+function scanAllSpecsFromSource(code, filePath) {
+	const results = [];
+	const baseSpecType = inferSpecTypeFromFilePath(filePath);
+	const processedPositions = /* @__PURE__ */ new Set();
+	for (const { pattern, type } of DEFINE_FUNCTION_PATTERNS) {
+		pattern.lastIndex = 0;
+		let match;
+		while ((match = pattern.exec(code)) !== null) {
+			const startPos = match.index;
+			if (processedPositions.has(startPos)) continue;
+			processedPositions.add(startPos);
+			const openBracePos = code.indexOf("{", startPos);
+			if (openBracePos === -1) continue;
+			const closeBracePos = findMatchingBrace(code, openBracePos);
+			if (closeBracePos === -1) continue;
+			const block = code.slice(openBracePos, closeBracePos + 1);
+			const meta = extractMetaFromBlock(block);
+			if (!meta) continue;
+			const description = matchStringField(block, "description");
+			const stabilityRaw = matchStringField(block, "stability");
+			const stability = isStability(stabilityRaw) ? stabilityRaw : void 0;
+			const owners = matchStringArrayField(block, "owners");
+			const tags = matchStringArrayField(block, "tags");
+			const hasMeta = /meta\s*:\s*{/.test(block);
+			const hasIo = /\bio\s*:\s*{/.test(block);
+			const hasPolicy = /\bpolicy\s*:\s*{/.test(block);
+			const hasPayload = /\bpayload\s*:\s*{/.test(block);
+			const hasContent = /\bcontent\s*:\s*{/.test(block);
+			const hasDefinition = /\bdefinition\s*:\s*{/.test(block);
+			const kind = type === "operation" ? inferOperationKindFromBlock(block) : "unknown";
+			const emittedEvents = type === "operation" ? extractEmittedEvents(block) : void 0;
+			const policyRefs = type === "operation" ? extractPolicyRefs(block) : void 0;
+			const testRefs = extractTestRefs(block);
+			results.push({
+				filePath,
+				specType: type,
+				key: meta.key,
+				version: meta.version,
+				description: description ?? void 0,
+				stability,
+				owners,
+				tags,
+				kind,
+				hasMeta,
+				hasIo,
+				hasPolicy,
+				hasPayload,
+				hasContent,
+				hasDefinition,
+				emittedEvents,
+				policyRefs,
+				testRefs
+			});
+		}
+	}
+	if (results.length === 0 && baseSpecType !== "unknown") {
+		const fallback = scanSpecSource(code, filePath);
+		if (fallback.key && fallback.version !== void 0) results.push(fallback);
+	}
+	return results;
+}
+
+//#endregion
+export { extractEmittedEvents, extractPolicyRefs, extractTestRefs, inferSpecTypeFromFilePath, scanAllSpecsFromSource, scanSpecSource };
+//# sourceMappingURL=spec-scan.js.map