mirascope 2.0.0-alpha.0

package/dist/transform/index.d.cts

@@ -0,0 +1,89 @@
+import ts from 'typescript';
+import { J as JsonSchemaProperty, a as ToolParameterSchema } from '../tool-schema-Dh-RLHhC.cjs';
+export { MirascopeVitePluginOptions, default as vitePlugin } from './plugins/vite.cjs';
+export { MirascopeEsbuildPluginOptions, default as esbuildPlugin } from './plugins/esbuild.cjs';
+import '@rollup/plugin-typescript';
+import 'vite';
+import 'esbuild';
+
+/**
+ * TypeScript transformer for injecting schemas into tool and format definitions.
+ *
+ * This transformer finds calls to `defineTool<T>()`, `defineContextTool<T, DepsT>()`,
+ * and `defineFormat<T>()` and injects the `__schema` property with the JSON schema
+ * generated from type T.
+ */
+
+/**
+ * Create a TypeScript transformer that injects __schema into tool definitions.
+ *
+ * @param program - The TypeScript program.
+ * @returns A transformer factory.
+ */
+declare function createToolSchemaTransformer(program: ts.Program): ts.TransformerFactory<ts.SourceFile>;
+/**
+ * Default export for ts-patch and other transformer loaders.
+ */
+declare function transformer(program: ts.Program): ts.TransformerFactory<ts.SourceFile>;
+
+/**
+ * Convert TypeScript types to JSON Schema.
+ *
+ * Uses the TypeScript Compiler API to introspect types and generate
+ * JSON Schema representations suitable for LLM tool definitions.
+ */
+
+/**
+ * Context for type-to-schema conversion.
+ */
+interface ConversionContext {
+    /** The TypeScript type checker. */
+    checker: ts.TypeChecker;
+    /** Definitions for referenced types ($defs). */
+    definitions: Map<string, JsonSchemaProperty>;
+    /** Set of type names currently being processed (for cycle detection). */
+    processing: Set<string>;
+}
+/**
+ * Convert a TypeScript type to a JSON Schema property.
+ *
+ * @param type - The TypeScript type to convert.
+ * @param ctx - The conversion context.
+ * @returns The JSON Schema property.
+ */
+declare function typeToJsonSchema(type: ts.Type, ctx: ConversionContext): JsonSchemaProperty;
+/**
+ * Convert a TypeScript type to a ToolParameterSchema.
+ *
+ * This is the main entry point for converting tool argument types
+ * to the schema format expected by LLM providers.
+ *
+ * @param type - The TypeScript type to convert (should be an object type).
+ * @param checker - The TypeScript type checker.
+ * @returns The tool parameter schema.
+ */
+declare function typeToToolParameterSchema(type: ts.Type, checker: ts.TypeChecker): ToolParameterSchema;
+/**
+ * Create a ConversionContext for testing or manual use.
+ */
+declare function createConversionContext(checker: ts.TypeChecker): ConversionContext;
+
+/**
+ * Shared types for build system plugins.
+ */
+
+/**
+ * Common transformer configuration that can be passed to build plugins.
+ */
+interface TransformerConfig {
+    /**
+     * Additional transformers to run before the Mirascope transformer.
+     */
+    before?: ts.TransformerFactory<ts.SourceFile>[];
+    /**
+     * Additional transformers to run after the Mirascope transformer.
+     */
+    after?: ts.TransformerFactory<ts.SourceFile>[];
+}
+
+export { type TransformerConfig, createConversionContext, createToolSchemaTransformer, transformer, typeToJsonSchema, typeToToolParameterSchema };

package/dist/transform/index.d.ts

@@ -0,0 +1,89 @@
+import ts from 'typescript';
+import { J as JsonSchemaProperty, a as ToolParameterSchema } from '../tool-schema-Dh-RLHhC.js';
+export { MirascopeVitePluginOptions, default as vitePlugin } from './plugins/vite.js';
+export { MirascopeEsbuildPluginOptions, default as esbuildPlugin } from './plugins/esbuild.js';
+import '@rollup/plugin-typescript';
+import 'vite';
+import 'esbuild';
+
+/**
+ * TypeScript transformer for injecting schemas into tool and format definitions.
+ *
+ * This transformer finds calls to `defineTool<T>()`, `defineContextTool<T, DepsT>()`,
+ * and `defineFormat<T>()` and injects the `__schema` property with the JSON schema
+ * generated from type T.
+ */
+
+/**
+ * Create a TypeScript transformer that injects __schema into tool definitions.
+ *
+ * @param program - The TypeScript program.
+ * @returns A transformer factory.
+ */
+declare function createToolSchemaTransformer(program: ts.Program): ts.TransformerFactory<ts.SourceFile>;
+/**
+ * Default export for ts-patch and other transformer loaders.
+ */
+declare function transformer(program: ts.Program): ts.TransformerFactory<ts.SourceFile>;
+
+/**
+ * Convert TypeScript types to JSON Schema.
+ *
+ * Uses the TypeScript Compiler API to introspect types and generate
+ * JSON Schema representations suitable for LLM tool definitions.
+ */
+
+/**
+ * Context for type-to-schema conversion.
+ */
+interface ConversionContext {
+    /** The TypeScript type checker. */
+    checker: ts.TypeChecker;
+    /** Definitions for referenced types ($defs). */
+    definitions: Map<string, JsonSchemaProperty>;
+    /** Set of type names currently being processed (for cycle detection). */
+    processing: Set<string>;
+}
+/**
+ * Convert a TypeScript type to a JSON Schema property.
+ *
+ * @param type - The TypeScript type to convert.
+ * @param ctx - The conversion context.
+ * @returns The JSON Schema property.
+ */
+declare function typeToJsonSchema(type: ts.Type, ctx: ConversionContext): JsonSchemaProperty;
+/**
+ * Convert a TypeScript type to a ToolParameterSchema.
+ *
+ * This is the main entry point for converting tool argument types
+ * to the schema format expected by LLM providers.
+ *
+ * @param type - The TypeScript type to convert (should be an object type).
+ * @param checker - The TypeScript type checker.
+ * @returns The tool parameter schema.
+ */
+declare function typeToToolParameterSchema(type: ts.Type, checker: ts.TypeChecker): ToolParameterSchema;
+/**
+ * Create a ConversionContext for testing or manual use.
+ */
+declare function createConversionContext(checker: ts.TypeChecker): ConversionContext;
+
+/**
+ * Shared types for build system plugins.
+ */
+
+/**
+ * Common transformer configuration that can be passed to build plugins.
+ */
+interface TransformerConfig {
+    /**
+     * Additional transformers to run before the Mirascope transformer.
+     */
+    before?: ts.TransformerFactory<ts.SourceFile>[];
+    /**
+     * Additional transformers to run after the Mirascope transformer.
+     */
+    after?: ts.TransformerFactory<ts.SourceFile>[];
+}
+
+export { type TransformerConfig, createConversionContext, createToolSchemaTransformer, transformer, typeToJsonSchema, typeToToolParameterSchema };

package/dist/transform/index.js

@@ -0,0 +1,6 @@
+export { mirascope as esbuildPlugin } from '../chunk-2R5IW35Y.js';
+export { mirascope as vitePlugin } from '../chunk-RMNCGJYW.js';
+export { createConversionContext, createToolSchemaTransformer, transformer, typeToJsonSchema, typeToToolParameterSchema } from '../chunk-U4MFJ4DP.js';
+import '../chunk-NSBPE2FW.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/transform/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/transform/plugins/esbuild.cjs

@@ -0,0 +1,472 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var fs = require('fs');
+var path = require('path');
+var ts3 = require('typescript');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var fs__default = /*#__PURE__*/_interopDefault(fs);
+var path__default = /*#__PURE__*/_interopDefault(path);
+var ts3__default = /*#__PURE__*/_interopDefault(ts3);
+
+// src/transform/plugins/esbuild.ts
+function isArrayLikeType(type, checker) {
+  if (type.getFlags() & ts3__default.default.TypeFlags.Object) {
+    const objectType = type;
+    const objectFlags = objectType.objectFlags;
+    if (objectFlags & ts3__default.default.ObjectFlags.Reference) {
+      const typeRef = type;
+      const symbol = typeRef.symbol;
+      if (symbol && symbol.getName() === "Array") {
+        return true;
+      }
+      const target = typeRef.target;
+      if (target && target.symbol && target.symbol.getName() === "Array") {
+        return true;
+      }
+    }
+  }
+  const typeString = checker.typeToString(type);
+  if (typeString.endsWith("[]") || typeString.startsWith("Array<")) {
+    return true;
+  }
+  return false;
+}
+function typeToJsonSchema(type, ctx) {
+  const checker = ctx.checker;
+  if (type.isUnion()) {
+    return handleUnionType(type, ctx);
+  }
+  if (type.isIntersection()) {
+    return handleIntersectionType(type, ctx);
+  }
+  if (type.isLiteral()) {
+    return handleLiteralType(type);
+  }
+  const flags = type.getFlags();
+  if (flags & ts3__default.default.TypeFlags.BooleanLiteral) {
+    const intrinsicName = type.intrinsicName;
+    const isTrue = intrinsicName === "true";
+    return { type: "boolean", enum: [isTrue] };
+  }
+  if (flags & ts3__default.default.TypeFlags.String) {
+    return { type: "string" };
+  }
+  if (flags & ts3__default.default.TypeFlags.Number) {
+    return { type: "number" };
+  }
+  if (flags & ts3__default.default.TypeFlags.Null) {
+    return { type: "null" };
+  }
+  if (flags & ts3__default.default.TypeFlags.Undefined) {
+    return {};
+  }
+  if (checker.isArrayType(type) || isArrayLikeType(type, checker)) {
+    const typeRef = type;
+    const typeArgs = checker.getTypeArguments(typeRef);
+    if (typeArgs && typeArgs.length > 0) {
+      return {
+        type: "array",
+        items: typeToJsonSchema(typeArgs[0], ctx)
+      };
+    }
+    return { type: "array" };
+  }
+  if (flags & ts3__default.default.TypeFlags.Object) {
+    return handleObjectType(type, ctx);
+  }
+  return {};
+}
+function handleUnionType(type, ctx) {
+  const types = type.types;
+  const nonUndefinedTypes = types.filter(
+    (t) => !(t.getFlags() & ts3__default.default.TypeFlags.Undefined)
+  );
+  if (nonUndefinedTypes.length === 2 && nonUndefinedTypes.every((t) => t.getFlags() & ts3__default.default.TypeFlags.BooleanLiteral)) {
+    return { type: "boolean" };
+  }
+  if (nonUndefinedTypes.every(
+    (t) => t.isStringLiteral()
+  )) {
+    return {
+      type: "string",
+      enum: nonUndefinedTypes.map((t) => t.value)
+    };
+  }
+  if (nonUndefinedTypes.every(
+    (t) => t.isNumberLiteral()
+  )) {
+    return {
+      type: "number",
+      enum: nonUndefinedTypes.map((t) => t.value)
+    };
+  }
+  if (nonUndefinedTypes.length === 1) {
+    return typeToJsonSchema(nonUndefinedTypes[0], ctx);
+  }
+  return {
+    oneOf: nonUndefinedTypes.map((t) => typeToJsonSchema(t, ctx))
+  };
+}
+function handleIntersectionType(type, ctx) {
+  const allOf = type.types.map((t) => typeToJsonSchema(t, ctx));
+  if (allOf.every((s) => s.type === "object")) {
+    const merged = {
+      type: "object",
+      properties: {},
+      required: []
+    };
+    for (const schema of allOf) {
+      if (schema.properties) {
+        merged.properties = { ...merged.properties, ...schema.properties };
+      }
+      if (schema.required) {
+        merged.required = [
+          ...merged.required,
+          ...schema.required
+        ];
+      }
+    }
+    return merged;
+  }
+  return { allOf };
+}
+function handleLiteralType(type) {
+  if (type.isStringLiteral()) {
+    return { type: "string", enum: [type.value] };
+  }
+  if (type.isNumberLiteral()) {
+    return { type: "number", enum: [type.value] };
+  }
+  return {};
+}
+function handleObjectType(type, ctx) {
+  const checker = ctx.checker;
+  const properties = {};
+  const required = [];
+  const props = checker.getPropertiesOfType(type);
+  for (const prop of props) {
+    const propName = prop.getName();
+    const propType = checker.getTypeOfSymbol(prop);
+    const isOptional = (prop.getFlags() & ts3__default.default.SymbolFlags.Optional) !== 0;
+    const propSchema = typeToJsonSchema(propType, ctx);
+    const jsDocComment = prop.getDocumentationComment(checker);
+    if (jsDocComment.length > 0) {
+      const description = jsDocComment.map((c) => c.text).join("");
+      propSchema.description = description;
+    }
+    properties[propName] = propSchema;
+    if (!isOptional) {
+      required.push(propName);
+    }
+  }
+  return {
+    type: "object",
+    properties,
+    required: required.length > 0 ? required : void 0
+  };
+}
+function typeToToolParameterSchema(type, checker) {
+  const ctx = {
+    checker,
+    definitions: /* @__PURE__ */ new Map()};
+  const schema = typeToJsonSchema(type, ctx);
+  if (schema.type !== "object") {
+    throw new Error(
+      "Tool parameter type must be an object type, got: " + JSON.stringify(schema)
+    );
+  }
+  const result = {
+    type: "object",
+    properties: schema.properties ?? {},
+    required: schema.required ?? [],
+    additionalProperties: false
+  };
+  if (ctx.definitions.size > 0) {
+    result.$defs = Object.fromEntries(ctx.definitions);
+  }
+  return result;
+}
+
+// src/transform/transformer.ts
+var TOOL_FUNCTION_NAMES = /* @__PURE__ */ new Set(["defineTool", "defineContextTool"]);
+var FORMAT_FUNCTION_NAMES = /* @__PURE__ */ new Set(["defineFormat"]);
+function createToolSchemaTransformer(program) {
+  const checker = program.getTypeChecker();
+  return (context) => {
+    return (sourceFile) => {
+      const visitor = (node) => {
+        if (ts3__default.default.isCallExpression(node)) {
+          const toolTransformed = tryTransformToolCall(node, checker, context);
+          if (toolTransformed) {
+            return toolTransformed;
+          }
+          const formatTransformed = tryTransformFormatCall(
+            node,
+            checker,
+            context
+          );
+          if (formatTransformed) {
+            return formatTransformed;
+          }
+        }
+        return ts3__default.default.visitEachChild(node, visitor, context);
+      };
+      return ts3__default.default.visitNode(sourceFile, visitor);
+    };
+  };
+}
+function tryTransformToolCall(node, checker, context) {
+  const functionName = getFunctionName(node);
+  if (!functionName || !TOOL_FUNCTION_NAMES.has(functionName)) {
+    return void 0;
+  }
+  const typeArgs = node.typeArguments;
+  if (!typeArgs || typeArgs.length === 0) {
+    return void 0;
+  }
+  const argsTypeNode = typeArgs[0];
+  const argsType = checker.getTypeFromTypeNode(argsTypeNode);
+  let schema;
+  try {
+    schema = typeToToolParameterSchema(argsType, checker);
+  } catch {
+    return void 0;
+  }
+  const args = node.arguments;
+  const firstArg = args[0];
+  if (!firstArg || !ts3__default.default.isObjectLiteralExpression(firstArg)) {
+    return void 0;
+  }
+  const optionsObject = firstArg;
+  const hasSchema = optionsObject.properties.some(
+    (prop) => ts3__default.default.isPropertyAssignment(prop) && ts3__default.default.isIdentifier(prop.name) && prop.name.text === "__schema"
+  );
+  if (hasSchema) {
+    return void 0;
+  }
+  const schemaProperty = createSchemaProperty(schema, context.factory);
+  const newProperties = [...optionsObject.properties, schemaProperty];
+  const newOptionsObject = context.factory.updateObjectLiteralExpression(
+    optionsObject,
+    newProperties
+  );
+  const newArgs = [newOptionsObject, ...args.slice(1)];
+  return context.factory.updateCallExpression(
+    node,
+    node.expression,
+    node.typeArguments,
+    newArgs
+  );
+}
+function tryTransformFormatCall(node, checker, context) {
+  const functionName = getFunctionName(node);
+  if (!functionName || !FORMAT_FUNCTION_NAMES.has(functionName)) {
+    return void 0;
+  }
+  const typeArgs = node.typeArguments;
+  if (!typeArgs || typeArgs.length === 0) {
+    return void 0;
+  }
+  const outputTypeNode = typeArgs[0];
+  const outputType = checker.getTypeFromTypeNode(outputTypeNode);
+  const args = node.arguments;
+  const firstArg = args[0];
+  if (!firstArg) {
+    return void 0;
+  }
+  if (ts3__default.default.isObjectLiteralExpression(firstArg)) {
+    const formatSpecObject = firstArg;
+    const hasSchema = formatSpecObject.properties.some(
+      (prop) => ts3__default.default.isPropertyAssignment(prop) && ts3__default.default.isIdentifier(prop.name) && prop.name.text === "__schema"
+    );
+    if (hasSchema) {
+      return void 0;
+    }
+    let schema;
+    try {
+      schema = typeToToolParameterSchema(outputType, checker);
+    } catch {
+      return void 0;
+    }
+    const schemaProperty = createSchemaProperty(schema, context.factory);
+    const newProperties = [...formatSpecObject.properties, schemaProperty];
+    const newFormatSpecObject = context.factory.updateObjectLiteralExpression(
+      formatSpecObject,
+      newProperties
+    );
+    const newArgs = [newFormatSpecObject, ...args.slice(1)];
+    return context.factory.updateCallExpression(
+      node,
+      node.expression,
+      node.typeArguments,
+      newArgs
+    );
+  }
+  return void 0;
+}
+function getFunctionName(node) {
+  const expression = node.expression;
+  if (ts3__default.default.isIdentifier(expression)) {
+    return expression.text;
+  }
+  if (ts3__default.default.isPropertyAccessExpression(expression)) {
+    return expression.name.text;
+  }
+  return void 0;
+}
+function createSchemaProperty(schema, factory) {
+  return factory.createPropertyAssignment(
+    factory.createIdentifier("__schema"),
+    jsonToAst(schema, factory)
+  );
+}
+function jsonToAst(value, factory) {
+  if (value === null) {
+    return factory.createNull();
+  }
+  if (value === void 0) {
+    return factory.createIdentifier("undefined");
+  }
+  if (typeof value === "string") {
+    return factory.createStringLiteral(value);
+  }
+  if (typeof value === "number") {
+    return factory.createNumericLiteral(value);
+  }
+  if (typeof value === "boolean") {
+    return value ? factory.createTrue() : factory.createFalse();
+  }
+  if (Array.isArray(value)) {
+    return factory.createArrayLiteralExpression(
+      value.map((item) => jsonToAst(item, factory))
+    );
+  }
+  if (typeof value === "object") {
+    const properties = Object.entries(value).map(
+      ([key, val]) => factory.createPropertyAssignment(
+        factory.createIdentifier(key),
+        jsonToAst(val, factory)
+      )
+    );
+    return factory.createObjectLiteralExpression(properties, true);
+  }
+  return factory.createIdentifier("undefined");
+}
+
+// src/transform/plugins/esbuild.ts
+function mirascope(options = {}) {
+  const {
+    tsconfig = "./tsconfig.json",
+    filter = /\.(ts|tsx)$/,
+    compilerOptions: extraOptions = {}
+  } = options;
+  let cachedProgram;
+  let cachedTransformer;
+  let cachedConfigPath;
+  let cachedCompilerOptions;
+  return {
+    name: "mirascope",
+    setup(build) {
+      const cwd = process.cwd();
+      const configPath = path__default.default.resolve(cwd, tsconfig);
+      let parsedConfig;
+      if (fs__default.default.existsSync(configPath)) {
+        const configFile = ts3__default.default.readConfigFile(
+          configPath,
+          (path2) => ts3__default.default.sys.readFile(path2)
+        );
+        if (configFile.error) {
+          throw new Error(
+            `Error reading tsconfig.json: ${ts3__default.default.flattenDiagnosticMessageText(
+              configFile.error.messageText,
+              "\n"
+            )}`
+          );
+        }
+        parsedConfig = ts3__default.default.parseJsonConfigFileContent(
+          configFile.config,
+          ts3__default.default.sys,
+          path__default.default.dirname(configPath)
+        );
+      } else {
+        parsedConfig = ts3__default.default.parseJsonConfigFileContent({}, ts3__default.default.sys, cwd);
+      }
+      const compilerOptions = {
+        ...parsedConfig.options,
+        ...extraOptions,
+        // Required for transformation
+        noEmit: false,
+        sourceMap: false,
+        inlineSourceMap: false,
+        declaration: false,
+        declarationMap: false
+      };
+      build.onLoad(
+        { filter },
+        async (args) => {
+          const fileName = args.path;
+          const sourceText = await fs__default.default.promises.readFile(fileName, "utf-8");
+          if (!sourceText.includes("defineTool") && !sourceText.includes("defineContextTool")) {
+            return {
+              contents: sourceText,
+              loader: fileName.endsWith(".tsx") ? "tsx" : "ts"
+            };
+          }
+          if (!cachedProgram || cachedConfigPath !== configPath || cachedCompilerOptions !== compilerOptions) {
+            cachedProgram = ts3__default.default.createProgram([fileName], compilerOptions);
+            cachedTransformer = createToolSchemaTransformer(cachedProgram);
+            cachedConfigPath = configPath;
+            cachedCompilerOptions = compilerOptions;
+          }
+          const sourceFile = cachedProgram.getSourceFile(fileName);
+          if (!sourceFile) {
+            const singleFileProgram = ts3__default.default.createProgram(
+              [fileName],
+              compilerOptions
+            );
+            const transformer = createToolSchemaTransformer(singleFileProgram);
+            const sf = singleFileProgram.getSourceFile(fileName);
+            if (!sf) {
+              return {
+                errors: [
+                  {
+                    text: `Could not parse source file: ${fileName}`,
+                    location: null
+                  }
+                ]
+              };
+            }
+            const result2 = ts3__default.default.transform(sf, [transformer]);
+            const transformedSourceFile2 = result2.transformed[0];
+            const printer2 = ts3__default.default.createPrinter();
+            const outputText2 = transformedSourceFile2 ? printer2.printFile(transformedSourceFile2) : sourceText;
+            result2.dispose();
+            return {
+              contents: outputText2,
+              loader: fileName.endsWith(".tsx") ? "tsx" : "ts"
+            };
+          }
+          const result = ts3__default.default.transform(sourceFile, [cachedTransformer]);
+          const transformedSourceFile = result.transformed[0];
+          const printer = ts3__default.default.createPrinter();
+          const outputText = transformedSourceFile ? printer.printFile(transformedSourceFile) : sourceText;
+          result.dispose();
+          return {
+            contents: outputText,
+            loader: fileName.endsWith(".tsx") ? "tsx" : "ts"
+          };
+        }
+      );
+    }
+  };
+}
+var esbuild_default = mirascope;
+
+exports.default = esbuild_default;
+exports.mirascope = mirascope;
+//# sourceMappingURL=esbuild.cjs.map
+//# sourceMappingURL=esbuild.cjs.map