@sembl/compiler 0.1.0 → 0.2.1

package/dist/index.d.cts

@@ -0,0 +1,220 @@
+import { SchemaBundle, RuntimeSchema, FieldConstraints, FieldType, Provider, EnumResolver, CoerceOptions } from '@sembl/core';
+import { Node, ClassDeclaration, PropertyDeclaration, Type } from 'ts-morph';
+import { EvalReport, EvalDiff, TokenPrices } from '@sembl/testing';
+
+/**
+ * Annotation extracted from a @Schema decorator.
+ */
+interface SchemaAnnotation {
+    /** Class name */
+    className: string;
+    /** Description string from @Schema(description) */
+    description: string;
+}
+/**
+ * Annotation extracted from a @Describe decorator on a property.
+ */
+interface FieldAnnotation {
+    /** Property name */
+    name: string;
+    /** Description string from @Describe(description) */
+    description: string;
+    /** Raw TypeScript type text */
+    rawType: string;
+    /** Whether the property is optional (?:) */
+    optional: boolean;
+}
+/**
+ * Configuration for the compiler.
+ */
+interface CompilerConfig {
+    /** Glob patterns for input source files */
+    inputPatterns: string[];
+    /** Output directory for generated schema files */
+    outputDir: string;
+    /** Optional tsconfig path */
+    tsconfigPath?: string;
+}
+/**
+ * Result of extracting schemas from source files.
+ *
+ * Extends `SchemaBundle` so it can be handed straight to the emitter, and adds
+ * the diagnostics raised on the way — a field whose type the schema contract
+ * cannot express still emits, so the warnings are what tell the caller the
+ * output does not match the source.
+ */
+interface ExtractionResult extends SchemaBundle {
+    /** Any warnings generated during extraction, in discovery order */
+    warnings: string[];
+}
+
+interface ExtractOptions {
+    /** Glob patterns for source files */
+    filePatterns: string[];
+    /** Optional tsconfig.json path */
+    tsconfigPath?: string;
+}
+/**
+ * Extract all @Schema-decorated classes from the given source files.
+ *
+ * Returns the schemas alongside any warnings raised while resolving them —
+ * unsupported field types, annotations that could not be read. Extraction
+ * never throws on a bad field, so the warnings are the only signal that the
+ * emitted schemas are not what the source described.
+ */
+declare function extractSchemas(options: ExtractOptions): ExtractionResult;
+
+/**
+ * Emit a SchemaBundle as a set of individual .schema.ts files
+ * plus a bundle index file.
+ */
+declare function emitSchemas(bundle: SchemaBundle, outputDir: string): string[];
+
+/**
+ * Where a field sits in the source, carried through type resolution and
+ * decorator parsing.
+ *
+ * Every diagnostic names the class and the property, because a warning that
+ * only says "unsupported type" sends the reader hunting through the whole
+ * input directory for it.
+ */
+interface FieldScope {
+    /** Name of the @Schema class that owns the field. */
+    className: string;
+    /** Property name, dotted through synthesized inline objects. */
+    propertyPath: string;
+    /**
+     * Declaration the type was read from. Members of an anonymous object type
+     * have no declaration of their own to resolve against, so they are typed
+     * relative to this node.
+     */
+    node: Node;
+    /** Collector for diagnostics and synthesized schemas. */
+    context: ExtractionContext;
+}
+/**
+ * Accumulates everything an extraction produces beyond the schemas themselves:
+ * diagnostics, schemas synthesized for anonymous object types, and the nested
+ * schema references that can only be validated once all files are visited.
+ */
+interface ExtractionContext {
+    /** Diagnostics raised so far, in discovery order. */
+    readonly warnings: readonly string[];
+    /** Schemas synthesized for anonymous inline object types, keyed by id. */
+    readonly synthesizedSchemas: Readonly<Record<string, RuntimeSchema>>;
+    /** Record a diagnostic against a field. */
+    warn(scope: FieldScope, message: string): void;
+    /** Add a schema synthesized for an inline object type. */
+    registerSynthesizedSchema(schema: RuntimeSchema): void;
+    /** Note that a field points at `nestedSchemaId`, to be checked later. */
+    recordNestedReference(scope: FieldScope, nestedSchemaId: string, typeText: string): void;
+    /**
+     * Warn about every recorded reference whose target is not among
+     * `knownSchemaIds`. Call once, after all classes have been visited.
+     */
+    reportUnresolvedNestedSchemas(knownSchemaIds: ReadonlySet<string>): void;
+}
+/**
+ * Create an empty {@link ExtractionContext} for a single extraction run.
+ */
+declare function createExtractionContext(): ExtractionContext;
+/**
+ * Derive the id of a schema synthesized from an anonymous object type.
+ *
+ * The id becomes a filename and an exported binding in the generated output
+ * (`<id>.schema.ts`, `<id>Schema`), so it has to be a valid identifier. The
+ * path prefix keeps generated files traceable back to the declaration they
+ * came from; the digest of the resolved shape makes the id collision-resistant
+ * against a hand-written @Schema class and stable across runs and machines —
+ * it is derived from the resolved fields, never from absolute source paths.
+ */
+declare function synthesizedSchemaId(scope: FieldScope, structuralSignature: string): string;
+
+/**
+ * Visit a class declaration and extract a RuntimeSchema if it has @Schema decorator.
+ * Returns undefined if the class is not decorated with @Schema.
+ *
+ * Diagnostics and schemas synthesized for inline object types are collected
+ * into `context` rather than thrown, so one questionable field does not stop
+ * the rest of the extraction.
+ */
+declare function visitClass(classDecl: ClassDeclaration, context: ExtractionContext): RuntimeSchema | undefined;
+
+/**
+ * Extract the @Schema description from a class declaration.
+ * Returns undefined if the class doesn't have a @Schema decorator.
+ */
+declare function parseSchemaDecorator(classDecl: ClassDeclaration): string | undefined;
+/**
+ * Extract the @Describe description from a property declaration.
+ * Returns undefined if the property doesn't have a @Describe decorator.
+ */
+declare function parseDescribeDecorator(propDecl: PropertyDeclaration): string | undefined;
+/**
+ * Extract the @Constrain bounds from a property declaration.
+ *
+ * The decorator's argument has to be an inline object literal: decorators are
+ * never evaluated, so a value that is not written out in source cannot be
+ * resolved. Unreadable and unknown entries are warned about and skipped
+ * individually, so one bad bound does not discard the rest.
+ *
+ * Returns undefined if there is no @Constrain decorator, or if nothing in it
+ * could be read.
+ */
+declare function parseConstrainDecorator(propDecl: PropertyDeclaration, scope: FieldScope): FieldConstraints | undefined;
+/**
+ * Extract the enum source id from a property's @ValuesFrom decorator.
+ *
+ * Returns undefined if there is no @ValuesFrom decorator, or if its argument
+ * is not a string literal.
+ */
+declare function parseValuesFromDecorator(propDecl: PropertyDeclaration, scope: FieldScope): string | undefined;
+
+/**
+ * Resolve a TypeScript type to a FieldType descriptor.
+ *
+ * Maps TS types to the schema type system: string, number, boolean, array,
+ * object, enum. Anything the contract cannot express is reported through
+ * `scope.context` rather than quietly coerced.
+ */
+declare function resolveFieldType(type: Type, scope: FieldScope): FieldType;
+
+interface EvalCommandOptions {
+    /** A JS module exporting the schema and provider to evaluate with. */
+    config: string;
+    /** Directory of fixture JSON files. */
+    fixtures: string;
+    /** Where to write the report; defaults to `<fixtures>/.sembl-eval/last-run.json`. */
+    out?: string;
+    mode?: "coerce" | "partialCoerce";
+    provenance?: boolean;
+    concurrency?: number;
+    /** Replay recordings from this directory, recording misses through the provider. */
+    replay?: string;
+    /** Exit non-zero when overall recall lands below this fraction. */
+    minRecall?: number;
+    /** Exit non-zero when overall precision lands below this fraction. */
+    minPrecision?: number;
+}
+/**
+ * What an eval config module exports. Written as a plain JS module so the
+ * CLI can `import()` it without a TypeScript loader; a TS project can point
+ * at its build output, or keep the config in `.mjs`.
+ */
+interface EvalConfig {
+    schema: RuntimeSchema;
+    provider: Provider;
+    bundle?: SchemaBundle;
+    enumResolver?: EnumResolver;
+    prices?: TokenPrices;
+    /** Any other coercion options: `onInvalidField`, `maxRepairAttempts`, `maxInputChars`, … */
+    coerceOptions?: Partial<Omit<CoerceOptions, "schema" | "provider" | "bundle" | "enumResolver">>;
+}
+interface EvalCommandResult {
+    report?: EvalReport;
+    diff?: EvalDiff;
+    exitCode: number;
+}
+declare function evalCommand(options: EvalCommandOptions): Promise<EvalCommandResult>;
+
+export { type CompilerConfig, type EvalCommandOptions, type EvalCommandResult, type EvalConfig, type ExtractOptions, type ExtractionContext, type ExtractionResult, type FieldAnnotation, type FieldScope, type SchemaAnnotation, createExtractionContext, emitSchemas, evalCommand, extractSchemas, parseConstrainDecorator, parseDescribeDecorator, parseSchemaDecorator, parseValuesFromDecorator, resolveFieldType, synthesizedSchemaId, visitClass };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-import { SchemaBundle, RuntimeSchema, FieldConstraints, FieldType } from '@sembl/core';
+import { SchemaBundle, RuntimeSchema, FieldConstraints, FieldType, Provider, EnumResolver, CoerceOptions } from '@sembl/core';
 import { Node, ClassDeclaration, PropertyDeclaration, Type } from 'ts-morph';
+import { EvalReport, EvalDiff, TokenPrices } from '@sembl/testing';
 
 /**
  * Annotation extracted from a @Schema decorator.
@@ -178,4 +179,42 @@ declare function parseValuesFromDecorator(propDecl: PropertyDeclaration, scope:
  */
 declare function resolveFieldType(type: Type, scope: FieldScope): FieldType;
 
-export { type CompilerConfig, type ExtractOptions, type ExtractionContext, type ExtractionResult, type FieldAnnotation, type FieldScope, type SchemaAnnotation, createExtractionContext, emitSchemas, extractSchemas, parseConstrainDecorator, parseDescribeDecorator, parseSchemaDecorator, parseValuesFromDecorator, resolveFieldType, synthesizedSchemaId, visitClass };
+interface EvalCommandOptions {
+    /** A JS module exporting the schema and provider to evaluate with. */
+    config: string;
+    /** Directory of fixture JSON files. */
+    fixtures: string;
+    /** Where to write the report; defaults to `<fixtures>/.sembl-eval/last-run.json`. */
+    out?: string;
+    mode?: "coerce" | "partialCoerce";
+    provenance?: boolean;
+    concurrency?: number;
+    /** Replay recordings from this directory, recording misses through the provider. */
+    replay?: string;
+    /** Exit non-zero when overall recall lands below this fraction. */
+    minRecall?: number;
+    /** Exit non-zero when overall precision lands below this fraction. */
+    minPrecision?: number;
+}
+/**
+ * What an eval config module exports. Written as a plain JS module so the
+ * CLI can `import()` it without a TypeScript loader; a TS project can point
+ * at its build output, or keep the config in `.mjs`.
+ */
+interface EvalConfig {
+    schema: RuntimeSchema;
+    provider: Provider;
+    bundle?: SchemaBundle;
+    enumResolver?: EnumResolver;
+    prices?: TokenPrices;
+    /** Any other coercion options: `onInvalidField`, `maxRepairAttempts`, `maxInputChars`, … */
+    coerceOptions?: Partial<Omit<CoerceOptions, "schema" | "provider" | "bundle" | "enumResolver">>;
+}
+interface EvalCommandResult {
+    report?: EvalReport;
+    diff?: EvalDiff;
+    exitCode: number;
+}
+declare function evalCommand(options: EvalCommandOptions): Promise<EvalCommandResult>;
+
+export { type CompilerConfig, type EvalCommandOptions, type EvalCommandResult, type EvalConfig, type ExtractOptions, type ExtractionContext, type ExtractionResult, type FieldAnnotation, type FieldScope, type SchemaAnnotation, createExtractionContext, emitSchemas, evalCommand, extractSchemas, parseConstrainDecorator, parseDescribeDecorator, parseSchemaDecorator, parseValuesFromDecorator, resolveFieldType, synthesizedSchemaId, visitClass };