@varavel/vdl-plugin-sdk 0.0.0 → 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,373 @@
+//#region src/runtime.d.ts
+declare global {
+  const console: {
+    log(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+  };
+} //# sourceMappingURL=runtime.d.ts.map
+//#endregion
+//#region src/types/types.d.ts
+/**
+ * Underlying storage kind used by an enum
+ */
+type EnumValueType = "string" | "int";
+declare const EnumValueTypeList: EnumValueType[];
+declare function isEnumValueType(value: unknown): value is EnumValueType;
+/**
+ * Kind discriminator for LiteralValue.
+ *
+ * LiteralValue is used for fully resolved literal data in:
+ *
+ * - constant values
+ * - annotation arguments
+ */
+type LiteralKind = "string" | "int" | "float" | "bool" | "object" | "array";
+declare const LiteralKindList: LiteralKind[];
+declare function isLiteralKind(value: unknown): value is LiteralKind;
+/**
+ * Primitive scalar type names
+ */
+type PrimitiveType = "string" | "int" | "float" | "bool" | "datetime";
+declare const PrimitiveTypeList: PrimitiveType[];
+declare function isPrimitiveType(value: unknown): value is PrimitiveType;
+/**
+ * Kind discriminator for TypeRef
+ */
+type TypeKind = "primitive" | "type" | "enum" | "array" | "map" | "object";
+declare const TypeKindList: TypeKind[];
+declare function isTypeKind(value: unknown): value is TypeKind;
+/**
+ * Annotation Annotation metadata preserved in IR.
+ *
+ * `name` is the annotation identifier without the `@` prefix.
+ * `argument`, when present, is fully resolved as a LiteralValue.
+ */
+type Annotation = {
+  position: Position;
+  name: string;
+  argument?: LiteralValue;
+};
+declare function hydrateAnnotation(input: Annotation): Annotation;
+declare function validateAnnotation(input: unknown, path?: string): string | null;
+/**
+ * ConstantDef Fully resolved constant definition.
+ *
+ * `typeRef` is explicit or inferred by analysis.
+ * `value` contains the fully resolved literal payload.
+ */
+type ConstantDef = {
+  position: Position;
+  name: string;
+  doc?: string;
+  annotations: Annotation[];
+  typeRef: TypeRef;
+  value: LiteralValue;
+};
+declare function hydrateConstantDef(input: ConstantDef): ConstantDef;
+declare function validateConstantDef(input: unknown, path?: string): string | null;
+/**
+ * EnumDef Flattened enum definition.
+ *
+ * All enum spreads are already expanded into `members`.
+ */
+type EnumDef = {
+  position: Position;
+  name: string;
+  doc?: string;
+  annotations: Annotation[];
+  enumType: EnumValueType;
+  members: EnumMember[];
+};
+declare function hydrateEnumDef(input: EnumDef): EnumDef;
+declare function validateEnumDef(input: unknown, path?: string): string | null;
+/**
+ * EnumMember Enum member definition
+ */
+type EnumMember = {
+  position: Position;
+  name: string;
+  value: LiteralValue;
+  doc?: string;
+  annotations: Annotation[];
+};
+declare function hydrateEnumMember(input: EnumMember): EnumMember;
+declare function validateEnumMember(input: unknown, path?: string): string | null;
+/**
+ * Field Flattened object/type field definition
+ */
+type Field = {
+  position: Position;
+  name: string;
+  doc?: string;
+  optional: boolean;
+  annotations: Annotation[];
+  typeRef: TypeRef;
+};
+declare function hydrateField(input: Field): Field;
+declare function validateField(input: unknown, path?: string): string | null;
+/**
+ * IrSchema IrSchema is the generator-facing representation of a VDL program.
+ *
+ * This model is intentionally "flat" and "resolved":
+ *
+ * - spreads are already expanded
+ * - references are already resolved
+ * - collections are in deterministic order
+ *
+ * A code generator should be able to consume IrSchema directly, without needing
+ * to re-run parser or semantic-analysis logic.
+ */
+type IrSchema = {
+  entryPoint: string;
+  constants: ConstantDef[];
+  enums: EnumDef[];
+  types: TypeDef[];
+  docs: TopLevelDoc[];
+};
+declare function hydrateIrSchema(input: IrSchema): IrSchema;
+declare function validateIrSchema(input: unknown, path?: string): string | null;
+/**
+ * LiteralValue Fully resolved literal value.
+ *
+ * The selected payload is determined by `kind`:
+ *
+ * - `string` -> `stringValue`
+ * - `int` -> `intValue`
+ * - `float` -> `floatValue`
+ * - `bool` -> `boolValue`
+ * - `object` -> `objectEntries`
+ * - `array` -> `arrayItems`
+ */
+type LiteralValue = {
+  position: Position;
+  kind: LiteralKind;
+  stringValue?: string;
+  intValue?: number;
+  floatValue?: number;
+  boolValue?: boolean;
+  objectEntries?: ObjectEntry[];
+  arrayItems?: LiteralValue[];
+};
+declare function hydrateLiteralValue(input: LiteralValue): LiteralValue;
+declare function validateLiteralValue(input: unknown, path?: string): string | null;
+/**
+ * ObjectEntry Key/value pair inside an object LiteralValue payload
+ */
+type ObjectEntry = {
+  position: Position;
+  key: string;
+  value: LiteralValue;
+};
+declare function hydrateObjectEntry(input: ObjectEntry): ObjectEntry;
+declare function validateObjectEntry(input: unknown, path?: string): string | null;
+/**
+ * PluginInput PluginInput represents the data payload sent to a plugin.
+ *
+ * The plugin receives this as a single argument containing the complete
+ * Intermediate Representation of the VDL schema along with any user-defined
+ * configuration options from `vdl.config.vdl`.
+ */
+type PluginInput = {
+  version: string;
+  ir: IrSchema;
+  options: Record<string, string>;
+};
+declare function hydratePluginInput(input: PluginInput): PluginInput;
+declare function validatePluginInput(input: unknown, path?: string): string | null;
+/**
+ * PluginOutput PluginOutput represents the response payload returned by the `plugin` function.
+ *
+ * After processing the input schema, the plugin outputs this object containing
+ * all files to be generated or errors to be displayed to the user.
+ *
+ * If there are no errors and at least one file is returned, VDL will write each
+ * file to the specified path within the output directory. If there are errors,
+ * VDL will display them to the user and not write any files.
+ */
+type PluginOutput = {
+  files?: PluginOutputFile[];
+  errors?: PluginOutputError[];
+};
+declare function hydratePluginOutput(input: PluginOutput): PluginOutput;
+declare function validatePluginOutput(input: unknown, path?: string): string | null;
+/**
+ * PluginOutputError A structured error reported by the plugin.
+ */
+type PluginOutputError = {
+  message: string;
+  position?: Position;
+};
+declare function hydratePluginOutputError(input: PluginOutputError): PluginOutputError;
+declare function validatePluginOutputError(input: unknown, path?: string): string | null;
+/**
+ * PluginOutputFile PluginOutputFile represents a single generated file produced by the plugin.
+ *
+ * This abstraction allows plugins to generate multiple files from a single
+ * invocation, enabling patterns like one-file-per-type or splitting large
+ * outputs across multiple modules.
+ */
+type PluginOutputFile = {
+  path: string;
+  content: string;
+};
+declare function hydratePluginOutputFile(input: PluginOutputFile): PluginOutputFile;
+declare function validatePluginOutputFile(_input: unknown, _path?: string): string | null;
+/**
+ * Position It represents a position within a file and is used for error
+ * reporting, diagnostics, plugins, and tooling support.
+ */
+type Position = {
+  file: string;
+  line: number;
+  column: number;
+};
+declare function hydratePosition(input: Position): Position;
+declare function validatePosition(_input: unknown, _path?: string): string | null;
+/**
+ * TopLevelDoc Standalone documentation block.
+ *
+ * Used for top-level docstrings that are not attached to a type/enum/constant.
+ */
+type TopLevelDoc = {
+  position: Position;
+  content: string;
+};
+declare function hydrateTopLevelDoc(input: TopLevelDoc): TopLevelDoc;
+declare function validateTopLevelDoc(input: unknown, path?: string): string | null;
+/**
+ * TypeDef Flattened type definition.
+ *
+ * All spreads are already expanded. The unified `typeRef` describes what this
+ * type IS, a primitive, custom reference, map, array, or object with fields.
+ */
+type TypeDef = {
+  position: Position;
+  name: string;
+  doc?: string;
+  annotations: Annotation[];
+  typeRef: TypeRef;
+};
+declare function hydrateTypeDef(input: TypeDef): TypeDef;
+declare function validateTypeDef(input: unknown, path?: string): string | null;
+/**
+ * TypeRef Normalized type reference used by fields and constants.
+ *
+ * `kind` selects which payload fields are meaningful. Generators should inspect
+ * `kind` first, then read the related payload fields.
+ */
+type TypeRef = {
+  kind: TypeKind;
+  primitiveName?: PrimitiveType;
+  typeName?: string;
+  enumName?: string;
+  enumType?: EnumValueType;
+  arrayType?: TypeRef;
+  arrayDims?: number;
+  mapType?: TypeRef;
+  objectFields?: Field[];
+};
+declare function hydrateTypeRef(input: TypeRef): TypeRef;
+declare function validateTypeRef(input: unknown, path?: string): string | null;
+//#endregion
+//#region src/define-plugin.d.ts
+/**
+ * Defines a VDL plugin handler function.
+ *
+ * @param input - The input data for the plugin containing the IR and other relevant information.
+ * @returns The output data from the plugin containing the generated files and any errors.
+ */
+type VdlPluginHandler = (input: PluginInput) => PluginOutput;
+/**
+ * Defines a VDL plugin by wrapping the provided handler function. This is a helper function
+ * that can be used to create plugins in a more concise way.
+ *
+ * Example usage:
+ * ```typescript
+ * import { definePlugin } from "@varavel/vdl-plugin-sdk";
+ *
+ * export const generate = definePlugin((input) => {
+ *  // Plugin logic goes here
+ *  return {
+ *    files: [],
+ *    errors: []
+ *  };
+ * });
+ * ```
+ *
+ * @param handler - The plugin handler function that contains the logic for processing the input and generating the output.
+ * @returns The same handler function, which can be exported as the plugin's main entry point.
+ */
+declare function definePlugin(handler: VdlPluginHandler): VdlPluginHandler;
+//#endregion
+//#region src/utils/annotations.d.ts
+/**
+ * Returns the first annotation that matches the provided name.
+ */
+declare function getAnnotation(annotations: Annotation[] | undefined, name: string): Annotation | undefined;
+/**
+ * Returns the raw literal argument stored in an annotation.
+ *
+ * VDL annotations currently expose a single literal argument.
+ * Pair this helper with `unwrapLiteral` when you need a plain JavaScript value.
+ */
+declare function getAnnotationArgs(annotations: Annotation[] | undefined, name: string): LiteralValue | undefined;
+//#endregion
+//#region src/utils/literals.d.ts
+/**
+ * Native JavaScript value produced by `unwrapLiteral`.
+ *
+ * `undefined` is preserved when a literal is missing its kind-specific payload.
+ * `null` is returned for unknown literal kinds to keep the resolver non-throwing.
+ */
+type UnwrappedLiteral = string | number | boolean | null | undefined | UnwrappedLiteral[] | {
+  [key: string]: UnwrappedLiteral;
+};
+/**
+ * Resolves a `LiteralValue` into its native JavaScript representation.
+ *
+ * Pass a generic when you already know the expected shape.
+ * Omit it to get `unknown` and narrow the result yourself.
+ *
+ * The generic only affects TypeScript types. It does not validate the runtime value.
+ */
+declare function unwrapLiteral<T = unknown>(value: LiteralValue): T;
+//#endregion
+//#region src/utils/options.d.ts
+/**
+ * Returns a string option or the provided fallback when the key is missing.
+ */
+declare function getOptionString(options: Record<string, string> | undefined, key: string, defaultValue: string): string;
+/**
+ * Returns a boolean option using common truthy and falsy string values.
+ *
+ * Accepted truthy values: `true`, `1`, `yes`, `on`, `enable`, `enabled`, `y`.
+ *
+ * Accepted falsy values: `false`, `0`, `no`, `off`, `disable`, `disabled`, `n`.
+ *
+ * Invalid values fall back to the provided default.
+ */
+declare function getOptionBool(options: Record<string, string> | undefined, key: string, defaultValue: boolean): boolean;
+/**
+ * Returns a numeric option or the provided fallback when parsing fails.
+ *
+ * Empty, invalid, and non-finite values fall back to the default.
+ */
+declare function getOptionNumber(options: Record<string, string> | undefined, key: string, defaultValue: number): number;
+/**
+ * Returns a string array option from a separator-delimited value.
+ *
+ * Empty items are removed and each entry is trimmed.
+ *
+ * Missing values return the provided default.
+ *
+ * @example
+ * // For options: { "features": "feature1, feature2, feature3" }
+ * getOptionArray(options, "features", [], ",")
+ * // returns ["feature1", "feature2", "feature3"]
+ */
+declare function getOptionArray(options: Record<string, string> | undefined, key: string, defaultValue?: string[], separator?: string): string[];
+//#endregion
+export { Annotation, ConstantDef, EnumDef, EnumMember, EnumValueType, EnumValueTypeList, Field, IrSchema, LiteralKind, LiteralKindList, LiteralValue, ObjectEntry, PluginInput, PluginOutput, PluginOutputError, PluginOutputFile, Position, PrimitiveType, PrimitiveTypeList, TopLevelDoc, TypeDef, TypeKind, TypeKindList, TypeRef, UnwrappedLiteral, VdlPluginHandler, definePlugin, getAnnotation, getAnnotationArgs, getOptionArray, getOptionBool, getOptionNumber, getOptionString, hydrateAnnotation, hydrateConstantDef, hydrateEnumDef, hydrateEnumMember, hydrateField, hydrateIrSchema, hydrateLiteralValue, hydrateObjectEntry, hydratePluginInput, hydratePluginOutput, hydratePluginOutputError, hydratePluginOutputFile, hydratePosition, hydrateTopLevelDoc, hydrateTypeDef, hydrateTypeRef, isEnumValueType, isLiteralKind, isPrimitiveType, isTypeKind, unwrapLiteral, validateAnnotation, validateConstantDef, validateEnumDef, validateEnumMember, validateField, validateIrSchema, validateLiteralValue, validateObjectEntry, validatePluginInput, validatePluginOutput, validatePluginOutputError, validatePluginOutputFile, validatePosition, validateTopLevelDoc, validateTypeDef, validateTypeRef };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/runtime.ts","../src/types/types.ts","../src/define-plugin.ts","../src/utils/annotations.ts","../src/utils/literals.ts","../src/utils/options.ts"],"mappings":"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"}

package/dist/{ir.js → index.js}

@@ -1,4 +1,29 @@
-//#region src/ir.ts
+//#region src/define-plugin.ts
+/**
+* Defines a VDL plugin by wrapping the provided handler function. This is a helper function
+* that can be used to create plugins in a more concise way.
+*
+* Example usage:
+* ```typescript
+* import { definePlugin } from "@varavel/vdl-plugin-sdk";
+*
+* export const generate = definePlugin((input) => {
+*  // Plugin logic goes here
+*  return {
+*    files: [],
+*    errors: []
+*  };
+* });
+* ```
+*
+* @param handler - The plugin handler function that contains the logic for processing the input and generating the output.
+* @returns The same handler function, which can be exported as the plugin's main entry point.
+*/
+function definePlugin(handler) {
+	return handler;
+}
+//#endregion
+//#region src/types/types.ts
 const EnumValueTypeList = ["string", "int"];
 function isEnumValueType(value) {
 	return EnumValueTypeList.includes(value);
@@ -285,6 +310,72 @@ function validateObjectEntry(input, path = "ObjectEntry") {
 	}
 	return null;
 }
+function hydratePluginInput(input) {
+	return {
+		version: input.version,
+		ir: hydrateIrSchema(input.ir),
+		options: input.options
+	};
+}
+function validatePluginInput(input, path = "PluginInput") {
+	if (input === null || input === void 0 || typeof input !== "object") return `${path}: expected object, got ${typeof input}`;
+	const obj = input;
+	if (obj.ir === void 0 || obj.ir === null) return `${path}.ir: required field is missing`;
+	{
+		const err = validateIrSchema(obj.ir, `${path}.ir`);
+		if (err !== null) return err;
+	}
+	return null;
+}
+function hydratePluginOutput(input) {
+	return {
+		files: input.files ? input.files.map((el) => hydratePluginOutputFile(el)) : input.files,
+		errors: input.errors ? input.errors.map((el) => hydratePluginOutputError(el)) : input.errors
+	};
+}
+function validatePluginOutput(input, path = "PluginOutput") {
+	if (input === null || input === void 0 || typeof input !== "object") return `${path}: expected object, got ${typeof input}`;
+	const obj = input;
+	if (obj.files !== void 0 && obj.files !== null) {
+		if (!Array.isArray(obj.files)) return `${path}.files: expected array, got ${typeof obj.files}`;
+		for (let i = 0; i < obj.files.length; i++) {
+			const err = validatePluginOutputFile(obj.files[i], `${path}.files[${i}]`);
+			if (err !== null) return err;
+		}
+	}
+	if (obj.errors !== void 0 && obj.errors !== null) {
+		if (!Array.isArray(obj.errors)) return `${path}.errors: expected array, got ${typeof obj.errors}`;
+		for (let i = 0; i < obj.errors.length; i++) {
+			const err = validatePluginOutputError(obj.errors[i], `${path}.errors[${i}]`);
+			if (err !== null) return err;
+		}
+	}
+	return null;
+}
+function hydratePluginOutputError(input) {
+	return {
+		message: input.message,
+		position: input.position ? hydratePosition(input.position) : input.position
+	};
+}
+function validatePluginOutputError(input, path = "PluginOutputError") {
+	if (input === null || input === void 0 || typeof input !== "object") return `${path}: expected object, got ${typeof input}`;
+	const obj = input;
+	if (obj.position !== void 0 && obj.position !== null) {
+		const err = validatePosition(obj.position, `${path}.position`);
+		if (err !== null) return err;
+	}
+	return null;
+}
+function hydratePluginOutputFile(input) {
+	return {
+		path: input.path,
+		content: input.content
+	};
+}
+function validatePluginOutputFile(_input, _path = "PluginOutputFile") {
+	return null;
+}
 function hydratePosition(input) {
 	return {
 		file: input.file,
@@ -383,6 +474,131 @@ function validateTypeRef(input, path = "TypeRef") {
 	return null;
 }
 //#endregion
-export { EnumValueTypeList, LiteralKindList, PrimitiveTypeList, TypeKindList, hydrateAnnotation, hydrateConstantDef, hydrateEnumDef, hydrateEnumMember, hydrateField, hydrateIrSchema, hydrateLiteralValue, hydrateObjectEntry, hydratePosition, hydrateTopLevelDoc, hydrateTypeDef, hydrateTypeRef, isEnumValueType, isLiteralKind, isPrimitiveType, isTypeKind, validateAnnotation, validateConstantDef, validateEnumDef, validateEnumMember, validateField, validateIrSchema, validateLiteralValue, validateObjectEntry, validatePosition, validateTopLevelDoc, validateTypeDef, validateTypeRef };
+//#region src/utils/annotations.ts
+/**
+* Returns the first annotation that matches the provided name.
+*/
+function getAnnotation(annotations, name) {
+	if (!annotations) return void 0;
+	return annotations.find((anno) => anno.name === name);
+}
+/**
+* Returns the raw literal argument stored in an annotation.
+*
+* VDL annotations currently expose a single literal argument.
+* Pair this helper with `unwrapLiteral` when you need a plain JavaScript value.
+*/
+function getAnnotationArgs(annotations, name) {
+	const anno = getAnnotation(annotations, name);
+	return anno === null || anno === void 0 ? void 0 : anno.argument;
+}
+//#endregion
+//#region src/utils/literals.ts
+/**
+* Resolves a `LiteralValue` into its native JavaScript representation.
+*
+* Pass a generic when you already know the expected shape.
+* Omit it to get `unknown` and narrow the result yourself.
+*
+* The generic only affects TypeScript types. It does not validate the runtime value.
+*/
+function unwrapLiteral(value) {
+	return unwrapLiteralValue(value);
+}
+/**
+* Performs the recursive literal resolution used by `unwrapLiteral`.
+*/
+function unwrapLiteralValue(value) {
+	switch (value.kind) {
+		case "string": return value.stringValue;
+		case "int": return value.intValue;
+		case "float": return value.floatValue;
+		case "bool": return value.boolValue;
+		case "object": {
+			var _value$objectEntries;
+			const resolvedObject = {};
+			const entries = (_value$objectEntries = value.objectEntries) !== null && _value$objectEntries !== void 0 ? _value$objectEntries : [];
+			for (const entry of entries) resolvedObject[entry.key] = unwrapLiteralValue(entry.value);
+			return resolvedObject;
+		}
+		case "array":
+			var _value$arrayItems;
+			return ((_value$arrayItems = value.arrayItems) !== null && _value$arrayItems !== void 0 ? _value$arrayItems : []).map((item) => unwrapLiteralValue(item));
+		default: return null;
+	}
+}
+//#endregion
+//#region src/utils/options.ts
+/**
+* Returns a string option or the provided fallback when the key is missing.
+*/
+function getOptionString(options, key, defaultValue) {
+	const value = options === null || options === void 0 ? void 0 : options[key];
+	return value === void 0 ? defaultValue : value;
+}
+/**
+* Returns a boolean option using common truthy and falsy string values.
+*
+* Accepted truthy values: `true`, `1`, `yes`, `on`, `enable`, `enabled`, `y`.
+*
+* Accepted falsy values: `false`, `0`, `no`, `off`, `disable`, `disabled`, `n`.
+*
+* Invalid values fall back to the provided default.
+*/
+function getOptionBool(options, key, defaultValue) {
+	const value = options === null || options === void 0 ? void 0 : options[key];
+	if (value === void 0) return defaultValue;
+	switch (value.trim().toLowerCase()) {
+		case "true":
+		case "1":
+		case "yes":
+		case "on":
+		case "enable":
+		case "enabled":
+		case "y": return true;
+		case "false":
+		case "0":
+		case "no":
+		case "off":
+		case "disable":
+		case "disabled":
+		case "n": return false;
+		default: return defaultValue;
+	}
+}
+/**
+* Returns a numeric option or the provided fallback when parsing fails.
+*
+* Empty, invalid, and non-finite values fall back to the default.
+*/
+function getOptionNumber(options, key, defaultValue) {
+	const value = options === null || options === void 0 ? void 0 : options[key];
+	if (value === void 0) return defaultValue;
+	const trimmedValue = value.trim();
+	if (trimmedValue === "") return defaultValue;
+	const parsedValue = Number(trimmedValue);
+	return Number.isFinite(parsedValue) ? parsedValue : defaultValue;
+}
+/**
+* Returns a string array option from a separator-delimited value.
+*
+* Empty items are removed and each entry is trimmed.
+*
+* Missing values return the provided default.
+*
+* @example
+* // For options: { "features": "feature1, feature2, feature3" }
+* getOptionArray(options, "features", [], ",")
+* // returns ["feature1", "feature2", "feature3"]
+*/
+function getOptionArray(options, key, defaultValue = [], separator = ",") {
+	const value = options === null || options === void 0 ? void 0 : options[key];
+	if (value === void 0) return defaultValue;
+	const trimmedValue = value.trim();
+	if (trimmedValue === "") return [];
+	return trimmedValue.split(separator).map((item) => item.trim()).filter((item) => item.length > 0);
+}
+//#endregion
+export { EnumValueTypeList, LiteralKindList, PrimitiveTypeList, TypeKindList, definePlugin, getAnnotation, getAnnotationArgs, getOptionArray, getOptionBool, getOptionNumber, getOptionString, hydrateAnnotation, hydrateConstantDef, hydrateEnumDef, hydrateEnumMember, hydrateField, hydrateIrSchema, hydrateLiteralValue, hydrateObjectEntry, hydratePluginInput, hydratePluginOutput, hydratePluginOutputError, hydratePluginOutputFile, hydratePosition, hydrateTopLevelDoc, hydrateTypeDef, hydrateTypeRef, isEnumValueType, isLiteralKind, isPrimitiveType, isTypeKind, unwrapLiteral, validateAnnotation, validateConstantDef, validateEnumDef, validateEnumMember, validateField, validateIrSchema, validateLiteralValue, validateObjectEntry, validatePluginInput, validatePluginOutput, validatePluginOutputError, validatePluginOutputFile, validatePosition, validateTopLevelDoc, validateTypeDef, validateTypeRef };
 
-//# sourceMappingURL=ir.js.map
+//# sourceMappingURL=index.js.map