@typra/emitter 0.2.5 → 0.2.6

package/README.md

@@ -11,9 +11,14 @@ ship runtime service implementations or product-specific contracts.
 ## Install
 
 ```powershell
-npm install --save-dev @typra/emitter @typespec/compiler
+npm install --save-dev @typra/emitter @typespec/compiler@1.10.0 @typespec/json-schema@1.10.0
 ```
 
+Typra currently validates against TypeSpec compiler and JSON schema emitter
+`1.10.0`. Unvalidated TypeSpec versions report a clear diagnostic during emit;
+set `allow-unsupported-typespec-version: true` only when you intentionally accept
+possible generated output churn.
+
 ## Configure TypeSpec
 
 Add the emitter to `tspconfig.yaml`:

package/dist/src/compatibility.d.ts

@@ -0,0 +1,32 @@
+import { EmitContext, NoTarget } from "@typespec/compiler";
+import { TypraEmitterOptions } from "./lib.js";
+export declare const SUPPORTED_TYPESPEC_COMPILER_VERSION = "1.10.0";
+export declare const SUPPORTED_TYPESPEC_JSON_SCHEMA_VERSION = "1.10.0";
+export interface ToolchainPackageMetadata {
+    name: string;
+    version: string;
+    supportedRange: string;
+    supported: boolean;
+}
+export interface ToolchainMetadata {
+    packages: ToolchainPackageMetadata[];
+}
+interface CompatibilityDiagnosticContext {
+    options: Pick<TypraEmitterOptions, "allow-unsupported-typespec-version">;
+    program: {
+        reportDiagnostic(diagnostic: {
+            code: string;
+            message: string;
+            severity: "error" | "warning";
+            target: typeof NoTarget;
+        }): void;
+    };
+}
+export declare function getToolchainMetadata(): ToolchainMetadata;
+export declare function buildToolchainMetadata(packages: Array<Omit<ToolchainPackageMetadata, "supported"> & Partial<Pick<ToolchainPackageMetadata, "supported">>>): ToolchainMetadata;
+export declare function reportTypeSpecCompatibility(context: EmitContext<TypraEmitterOptions>): ToolchainMetadata;
+export declare function shouldBlockUnsupportedTypeSpecToolchain(options: Pick<TypraEmitterOptions, "allow-unsupported-typespec-version">, toolchain: ToolchainMetadata): boolean;
+export declare function reportToolchainCompatibility(context: CompatibilityDiagnosticContext, toolchain: ToolchainMetadata): void;
+export declare function getUnsupportedTypeSpecPackages(toolchain: ToolchainMetadata): ToolchainPackageMetadata[];
+export declare function formatUnsupportedTypeSpecVersionMessage(unsupported: ToolchainPackageMetadata[], allowedUnsupportedVersion: boolean): string;
+export {};

package/dist/src/compatibility.js

@@ -0,0 +1,96 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { NoTarget } from "@typespec/compiler";
+export const SUPPORTED_TYPESPEC_COMPILER_VERSION = "1.10.0";
+export const SUPPORTED_TYPESPEC_JSON_SCHEMA_VERSION = "1.10.0";
+const require = createRequire(import.meta.url);
+export function getToolchainMetadata() {
+    const emitterVersion = resolveNearestPackageVersion("@typra/emitter", dirname(fileURLToPath(import.meta.url)));
+    return buildToolchainMetadata([
+        {
+            name: "@typespec/compiler",
+            version: resolveInstalledPackageVersion("@typespec/compiler"),
+            supportedRange: SUPPORTED_TYPESPEC_COMPILER_VERSION,
+        },
+        {
+            name: "@typespec/json-schema",
+            version: resolveInstalledPackageVersion("@typespec/json-schema"),
+            supportedRange: SUPPORTED_TYPESPEC_JSON_SCHEMA_VERSION,
+        },
+        {
+            name: "@typra/emitter",
+            version: emitterVersion,
+            supportedRange: emitterVersion,
+        },
+    ]);
+}
+export function buildToolchainMetadata(packages) {
+    return {
+        packages: packages
+            .map((entry) => ({
+            ...entry,
+            supported: entry.supported ?? isSupportedVersion(entry.version, entry.supportedRange),
+        }))
+            .sort((left, right) => left.name.localeCompare(right.name)),
+    };
+}
+export function reportTypeSpecCompatibility(context) {
+    const toolchain = getToolchainMetadata();
+    reportToolchainCompatibility(context, toolchain);
+    return toolchain;
+}
+export function shouldBlockUnsupportedTypeSpecToolchain(options, toolchain) {
+    return options["allow-unsupported-typespec-version"] !== true && getUnsupportedTypeSpecPackages(toolchain).length > 0;
+}
+export function reportToolchainCompatibility(context, toolchain) {
+    const unsupported = getUnsupportedTypeSpecPackages(toolchain);
+    if (unsupported.length === 0) {
+        return;
+    }
+    context.program.reportDiagnostic({
+        code: "typra-emitter-unsupported-typespec-version",
+        message: formatUnsupportedTypeSpecVersionMessage(unsupported, context.options["allow-unsupported-typespec-version"] === true),
+        severity: context.options["allow-unsupported-typespec-version"] === true ? "warning" : "error",
+        target: NoTarget,
+    });
+}
+export function getUnsupportedTypeSpecPackages(toolchain) {
+    return toolchain.packages.filter((entry) => (entry.name === "@typespec/compiler" || entry.name === "@typespec/json-schema") && !entry.supported);
+}
+export function formatUnsupportedTypeSpecVersionMessage(unsupported, allowedUnsupportedVersion) {
+    const actual = unsupported.map((entry) => `${entry.name}@${entry.version}`).join(", ");
+    const expected = unsupported.map((entry) => `${entry.name}@${entry.supportedRange}`).join(", ");
+    const action = allowedUnsupportedVersion
+        ? "Generation will continue because allow-unsupported-typespec-version is enabled."
+        : "Pin the TypeSpec toolchain to the supported versions, or set allow-unsupported-typespec-version: true to continue with a warning.";
+    return `@typra/emitter has only been validated with ${expected}; found ${actual}. ${action}`;
+}
+function isSupportedVersion(version, supportedRange) {
+    return version === supportedRange;
+}
+function resolveInstalledPackageVersion(packageName) {
+    try {
+        const packageEntry = require.resolve(packageName);
+        return resolveNearestPackageVersion(packageName, dirname(packageEntry));
+    }
+    catch {
+        return "unresolved";
+    }
+}
+function resolveNearestPackageVersion(expectedPackageName, startDir) {
+    let current = startDir;
+    while (current !== dirname(current)) {
+        const candidate = join(current, "package.json");
+        if (existsSync(candidate)) {
+            const metadata = JSON.parse(readFileSync(candidate, "utf8"));
+            if (metadata.name === expectedPackageName && typeof metadata.version === "string") {
+                return metadata.version;
+            }
+        }
+        current = dirname(current);
+    }
+    return "unresolved";
+}
+//# sourceMappingURL=compatibility.js.map

package/dist/src/contract-surface.d.ts

@@ -1,6 +1,7 @@
 import { EmitContext } from "@typespec/compiler";
 import { EmitTarget, TypraEmitterOptions } from "./lib.js";
 import { TypeNode } from "./ir/ast.js";
+import { ToolchainMetadata } from "./compatibility.js";
 export interface ExportSurfaceMethod {
     name: string;
     returns: string;
@@ -39,6 +40,7 @@ export interface TargetExportSurface {
 export interface ExportSurfaceSnapshot {
     emitter: "typra-emitter";
     version: 1;
+    toolchain: ToolchainMetadata;
     root: {
         object: string;
         namespace: string;
@@ -46,5 +48,5 @@ export interface ExportSurfaceSnapshot {
     };
     targets: TargetExportSurface[];
 }
-export declare function buildExportSurfaceSnapshot(rootObject: string, rootNamespace: string, rootAlias: string, targets: EmitTarget[], nodes: TypeNode[]): ExportSurfaceSnapshot;
+export declare function buildExportSurfaceSnapshot(rootObject: string, rootNamespace: string, rootAlias: string, targets: EmitTarget[], nodes: TypeNode[], toolchain?: ToolchainMetadata): ExportSurfaceSnapshot;
 export declare function emitExportSurfaceSnapshot(context: EmitContext<TypraEmitterOptions>, snapshot: ExportSurfaceSnapshot): Promise<void>;

package/dist/src/contract-surface.js

@@ -1,9 +1,11 @@
 import { emitFile, resolvePath } from "@typespec/compiler";
 import { toKebabCase, toSnakeCase } from "./ir/utilities.js";
-export function buildExportSurfaceSnapshot(rootObject, rootNamespace, rootAlias, targets, nodes) {
+import { getToolchainMetadata } from "./compatibility.js";
+export function buildExportSurfaceSnapshot(rootObject, rootNamespace, rootAlias, targets, nodes, toolchain = getToolchainMetadata()) {
     return {
         emitter: "typra-emitter",
         version: 1,
+        toolchain,
         root: {
             object: rootObject,
             namespace: rootNamespace,

package/dist/src/emitter.js

@@ -8,6 +8,7 @@ import { generateGo } from "./languages/go/driver.js";
 import { generateRust } from "./languages/rust/driver.js";
 import { emitGeneratedFile, emitGeneratedManifest } from "./cleanup/generated-file.js";
 import { buildExportSurfaceSnapshot, emitExportSurfaceSnapshot } from "./contract-surface.js";
+import { reportTypeSpecCompatibility, shouldBlockUnsupportedTypeSpecToolchain } from "./compatibility.js";
 /**
  * Filter nodes based on omit-models option.
  * Matches against model name (e.g., "AgentManifest") or fully qualified name (e.g., "Prompty.AgentManifest")
@@ -69,6 +70,10 @@ const generators = {
     rust: generateRust,
 };
 export async function $onEmit(context) {
+    const toolchain = reportTypeSpecCompatibility(context);
+    if (shouldBlockUnsupportedTypeSpecToolchain(context.options, toolchain)) {
+        return;
+    }
     const options = {
         emitterOutputDir: context.emitterOutputDir,
         ...context.options,
@@ -159,7 +164,7 @@ export async function $onEmit(context) {
         }
     }
     await emitGeneratedFile(context, resolvePath(context.emitterOutputDir, "json-ast", "model.json"), JSON.stringify(model.getSanitizedObject(), null, 2), { marker: false });
-    await emitExportSurfaceSnapshot(context, buildExportSurfaceSnapshot(rootObject, rootNamespace, rootAlias, targets, exportSurfaceNodes));
+    await emitExportSurfaceSnapshot(context, buildExportSurfaceSnapshot(rootObject, rootNamespace, rootAlias, targets, exportSurfaceNodes, toolchain));
     await emitGeneratedManifest(context);
 }
 //# sourceMappingURL=emitter.js.map

package/dist/src/lib.d.ts

@@ -18,6 +18,7 @@ export interface TypraEmitterOptions {
     "omit-models"?: string[];
     "schema-output-dir"?: string;
     "additional-roots"?: string[];
+    "allow-unsupported-typespec-version"?: boolean;
 }
 export declare const $lib: import("@typespec/compiler").TypeSpecLibrary<{
     [code: string]: import("@typespec/compiler").DiagnosticMessages;

package/dist/src/lib.js

@@ -82,6 +82,12 @@ const TypraEmitterOptionsSchema = {
             items: { type: "string" },
             nullable: true,
             description: "Additional root types to resolve and generate alongside the main root object. These types need not be referenced from the main root. Specified as fully-qualified names (e.g., 'Typra.Message')."
+        },
+        "allow-unsupported-typespec-version": {
+            type: "boolean",
+            nullable: true,
+            default: false,
+            description: "Allow generation with an unvalidated TypeSpec compiler/json-schema version. Unsupported versions report a warning instead of an error."
         }
     },
     required: ["root-object"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typra/emitter",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Generic TypeSpec emitter for generating multi-runtime model surfaces",
   "license": "MIT",
   "repository": {
@@ -40,15 +40,15 @@
     "fixtures/tspconfig.yaml"
   ],
   "peerDependencies": {
-    "@typespec/compiler": "latest",
-    "@typespec/json-schema": "latest"
+    "@typespec/compiler": "1.10.0",
+    "@typespec/json-schema": "1.10.0"
   },
   "devDependencies": {
     "@types/node": "^24.7.0",
     "@typescript-eslint/eslint-plugin": "^8.15.0",
     "@typescript-eslint/parser": "^8.15.0",
-    "@typespec/compiler": "latest",
-    "@typespec/json-schema": "^1.8.0",
+    "@typespec/compiler": "1.10.0",
+    "@typespec/json-schema": "1.10.0",
     "eslint": "^9.15.0",
     "markdownlint-cli": "^0.48.0",
     "prettier": "^3.3.3",