@sembl/compiler 0.1.0 → 0.2.1

package/dist/cli/index.js

@@ -1,8 +1,4 @@
 #!/usr/bin/env node
-import {
-  emitSchemas,
-  extractSchemas
-} from "../chunk-Y4FKH2ZU.js";
 
 // src/cli/index.ts
 import { Command } from "commander";
@@ -10,6 +6,459 @@ import { Command } from "commander";
 // src/cli/commands/extract.ts
 import { resolve } from "path";
 import { glob } from "glob";
+
+// src/extractor/ast-extractor.ts
+import { Project, ScriptTarget } from "ts-morph";
+
+// src/extractor/decorator-parser.ts
+import {
+  Node,
+  SyntaxKind
+} from "ts-morph";
+var CONSTRAINT_KEYS = {
+  maxLength: "number",
+  minLength: "number",
+  minimum: "number",
+  maximum: "number",
+  minItems: "number",
+  maxItems: "number",
+  pattern: "string"
+};
+function getDecoratorStringArg(decorator) {
+  if (!decorator.isDecoratorFactory()) {
+    return void 0;
+  }
+  const args = decorator.getArguments();
+  if (args.length === 0) {
+    return void 0;
+  }
+  const arg = args[0];
+  const text = arg.getText();
+  if (text.startsWith('"') && text.endsWith('"') || text.startsWith("'") && text.endsWith("'")) {
+    return text.slice(1, -1);
+  }
+  if (text.startsWith("`") && text.endsWith("`")) {
+    return text.slice(1, -1);
+  }
+  return void 0;
+}
+function parseSchemaDecorator(classDecl) {
+  const decorator = classDecl.getDecorator("Schema");
+  if (!decorator) {
+    return void 0;
+  }
+  return getDecoratorStringArg(decorator);
+}
+function parseDescribeDecorator(propDecl) {
+  const decorator = propDecl.getDecorator("Describe");
+  if (!decorator) {
+    return void 0;
+  }
+  return getDecoratorStringArg(decorator);
+}
+function readNumberLiteral(node) {
+  if (Node.isNumericLiteral(node)) {
+    return node.getLiteralValue();
+  }
+  if (Node.isPrefixUnaryExpression(node)) {
+    const operand = node.getOperand();
+    if (Node.isNumericLiteral(operand)) {
+      const operator = node.getOperatorToken();
+      if (operator === SyntaxKind.MinusToken) {
+        return -operand.getLiteralValue();
+      }
+      if (operator === SyntaxKind.PlusToken) {
+        return operand.getLiteralValue();
+      }
+    }
+  }
+  return void 0;
+}
+function readStringLiteral(node) {
+  if (Node.isStringLiteral(node) || Node.isNoSubstitutionTemplateLiteral(node)) {
+    return node.getLiteralValue();
+  }
+  return void 0;
+}
+function readConstraintEntry(property, constraints, scope) {
+  if (!Node.isPropertyAssignment(property)) {
+    scope.context.warn(
+      scope,
+      `@Constrain entry \`${property.getText()}\` is not a \`key: value\` pair of compile-time constants and cannot be read from source. Skipping it.`
+    );
+    return false;
+  }
+  const nameNode = property.getNameNode();
+  if (!Node.isIdentifier(nameNode) && !Node.isStringLiteral(nameNode)) {
+    scope.context.warn(
+      scope,
+      `@Constrain key \`${nameNode.getText()}\` is computed and cannot be read from source. Skipping it.`
+    );
+    return false;
+  }
+  const key = nameNode.getText().replace(/^["']|["']$/g, "");
+  if (!Object.prototype.hasOwnProperty.call(CONSTRAINT_KEYS, key)) {
+    scope.context.warn(
+      scope,
+      `@Constrain key "${key}" is not a FieldConstraints property. Expected one of: ${Object.keys(CONSTRAINT_KEYS).join(", ")}. Skipping it.`
+    );
+    return false;
+  }
+  const expected = CONSTRAINT_KEYS[key];
+  const initializer = property.getInitializerOrThrow();
+  const value = expected === "number" ? readNumberLiteral(initializer) : readStringLiteral(initializer);
+  if (value === void 0) {
+    scope.context.warn(
+      scope,
+      `@Constrain value for "${key}" is \`${initializer.getText()}\`, which is not a ${expected} literal the compiler can read from source. Skipping it.`
+    );
+    return false;
+  }
+  constraints[key] = value;
+  return true;
+}
+function parseConstrainDecorator(propDecl, scope) {
+  const decorator = propDecl.getDecorator("Constrain");
+  if (!decorator) {
+    return void 0;
+  }
+  const args = decorator.isDecoratorFactory() ? decorator.getArguments() : [];
+  const argument = args[0];
+  if (argument === void 0 || !Node.isObjectLiteralExpression(argument)) {
+    scope.context.warn(
+      scope,
+      `@Constrain expects an inline object literal of compile-time constants, but ${argument === void 0 ? "it was called with no argument" : `was given \`${argument.getText()}\``}. Ignoring the decorator.`
+    );
+    return void 0;
+  }
+  const constraints = {};
+  let accepted = 0;
+  for (const property of argument.getProperties()) {
+    if (readConstraintEntry(property, constraints, scope)) {
+      accepted += 1;
+    }
+  }
+  return accepted > 0 ? constraints : void 0;
+}
+function parseValuesFromDecorator(propDecl, scope) {
+  const decorator = propDecl.getDecorator("ValuesFrom");
+  if (!decorator) {
+    return void 0;
+  }
+  const sourceId = getDecoratorStringArg(decorator);
+  if (sourceId === void 0) {
+    scope.context.warn(
+      scope,
+      `@ValuesFrom expects a string literal naming the enum source, which the caller resolves at coercion time. Ignoring the decorator.`
+    );
+    return void 0;
+  }
+  return sourceId;
+}
+
+// src/extractor/extraction-context.ts
+import { createHash } from "crypto";
+function createExtractionContext() {
+  const warnings = [];
+  const synthesizedSchemas = {};
+  const nestedReferences = [];
+  return {
+    warnings,
+    synthesizedSchemas,
+    warn(scope, message) {
+      warnings.push(`${scope.className}.${scope.propertyPath}: ${message}`);
+    },
+    registerSynthesizedSchema(schema) {
+      synthesizedSchemas[schema.id] = schema;
+    },
+    recordNestedReference(scope, nestedSchemaId, typeText) {
+      nestedReferences.push({
+        className: scope.className,
+        propertyPath: scope.propertyPath,
+        nestedSchemaId,
+        typeText
+      });
+    },
+    reportUnresolvedNestedSchemas(knownSchemaIds) {
+      for (const reference of nestedReferences) {
+        if (knownSchemaIds.has(reference.nestedSchemaId)) {
+          continue;
+        }
+        warnings.push(
+          `${reference.className}.${reference.propertyPath}: type \`${reference.typeText}\` resolves to nested schema "${reference.nestedSchemaId}", which is not a @Schema-decorated class in this extraction. It will emit as an object with no properties. Decorate it with @Schema if it is yours to change, or use a type the contract supports \u2014 a \`Date\`, for instance, extracts as an ISO-8601 string.`
+        );
+      }
+    }
+  };
+}
+function synthesizedSchemaId(scope, structuralSignature) {
+  const path = `${scope.className}_${scope.propertyPath}`.replace(
+    /[^A-Za-z0-9_]/g,
+    "_"
+  );
+  const digest = createHash("sha256").update(structuralSignature).digest("hex").slice(0, 8);
+  return `${path}__${digest}`;
+}
+
+// src/extractor/type-resolver.ts
+function reportUnsupported(type, scope, reason) {
+  scope.context.warn(
+    scope,
+    `unsupported type \`${type.getText(scope.node)}\` \u2014 ${reason}. Falling back to string.`
+  );
+  return { kind: "string" };
+}
+function resolveInlineObjectType(type, scope) {
+  const properties = type.getProperties();
+  if (properties.length === 0) {
+    const isMap = type.getStringIndexType() !== void 0 || type.getNumberIndexType() !== void 0;
+    return reportUnsupported(
+      type,
+      scope,
+      isMap ? "a map with an index signature has no FieldType equivalent, so its entries cannot be described to the model; declare a @Schema class with the keys you expect, or take the value as a JSON string and parse it yourself" : "an object type with no properties has nothing to extract"
+    );
+  }
+  const fields = properties.map((property) => {
+    const name = property.getName();
+    return {
+      name,
+      // Members of an inline type carry no @Describe, so the owning field's
+      // description is the only semantics the model gets for them.
+      description: "",
+      type: resolveFieldType(property.getTypeAtLocation(scope.node), {
+        ...scope,
+        propertyPath: `${scope.propertyPath}.${name}`
+      }),
+      required: !property.isOptional()
+    };
+  });
+  const id = synthesizedSchemaId(
+    scope,
+    JSON.stringify(fields.map((f) => [f.name, f.required, f.type]))
+  );
+  scope.context.registerSynthesizedSchema({
+    id,
+    description: `Inline object type declared at ${scope.className}.${scope.propertyPath}.`,
+    fields
+  });
+  return { kind: "object", nestedSchemaId: id };
+}
+function resolveFieldType(type, scope) {
+  if (type.isUnion()) {
+    const members = type.getUnionTypes().filter((t) => !t.isUndefined() && !t.isNull());
+    if (members.length === 1) {
+      return resolveFieldType(members[0], scope);
+    }
+    if (members.length === 0) {
+      return reportUnsupported(type, scope, "there is no value type to extract");
+    }
+    if (members.every((t) => t.isStringLiteral())) {
+      return {
+        kind: "enum",
+        values: members.map((t) => t.getLiteralValue())
+      };
+    }
+    if (members.every((t) => t.isBoolean() || t.isBooleanLiteral())) {
+      return { kind: "boolean" };
+    }
+    if (members.every((t) => t.isNumber() || t.isNumberLiteral())) {
+      return { kind: "number" };
+    }
+    return reportUnsupported(
+      type,
+      scope,
+      "a union mixing several kinds of value has no single FieldType; split it into separate fields, or narrow it to one kind"
+    );
+  }
+  if (type.isString() || type.isStringLiteral()) {
+    return { kind: "string" };
+  }
+  if (type.isNumber() || type.isNumberLiteral()) {
+    return { kind: "number" };
+  }
+  if (type.isBoolean() || type.isBooleanLiteral()) {
+    return { kind: "boolean" };
+  }
+  if (type.isArray()) {
+    const elementType = type.getArrayElementTypeOrThrow();
+    return { kind: "array", items: resolveFieldType(elementType, scope) };
+  }
+  if (type.isEnum()) {
+    const members = type.getUnionTypes().map((t) => t.getLiteralValue()).filter((v) => typeof v === "string");
+    if (members.length > 0) {
+      return { kind: "enum", values: members };
+    }
+    return reportUnsupported(
+      type,
+      scope,
+      "its members are not string values, so they cannot be offered to the model as an enum"
+    );
+  }
+  if (type.isObject()) {
+    const symbol = type.getSymbol() ?? type.getAliasSymbol();
+    const typeName = symbol?.getName();
+    if (typeName && typeName !== "__type" && typeName !== "Object") {
+      scope.context.recordNestedReference(
+        scope,
+        typeName,
+        type.getText(scope.node)
+      );
+      return { kind: "object", nestedSchemaId: typeName };
+    }
+    return resolveInlineObjectType(type, scope);
+  }
+  return reportUnsupported(
+    type,
+    scope,
+    "it maps to none of string, number, boolean, array, enum, or a @Schema class"
+  );
+}
+
+// src/extractor/class-visitor.ts
+function describeKind(type) {
+  return type.kind === "array" ? `${describeKind(type.items)}[]` : type.kind;
+}
+function applyValuesFrom(type, sourceId, scope) {
+  if (type.kind === "string") {
+    return { kind: "dynamicEnum", sourceId };
+  }
+  if (type.kind === "array" && type.items.kind === "string") {
+    return { kind: "array", items: { kind: "dynamicEnum", sourceId } };
+  }
+  scope.context.warn(
+    scope,
+    `@ValuesFrom("${sourceId}") applies to a string or string[] field, but this field resolved to ${describeKind(type)}. Leaving the type unchanged.`
+  );
+  return type;
+}
+function visitClass(classDecl, context) {
+  const description = parseSchemaDecorator(classDecl);
+  if (description === void 0) {
+    return void 0;
+  }
+  const className = classDecl.getName();
+  if (!className) {
+    return void 0;
+  }
+  const fields = [];
+  for (const prop of classDecl.getProperties()) {
+    const fieldDescription = parseDescribeDecorator(prop);
+    if (fieldDescription === void 0) {
+      continue;
+    }
+    const name = prop.getName();
+    const isOptional = prop.hasQuestionToken();
+    const scope = {
+      className,
+      propertyPath: name,
+      node: prop,
+      context
+    };
+    let type = resolveFieldType(prop.getType(), scope);
+    const sourceId = parseValuesFromDecorator(prop, scope);
+    if (sourceId !== void 0) {
+      type = applyValuesFrom(type, sourceId, scope);
+    }
+    const constraints = parseConstrainDecorator(prop, scope);
+    fields.push({
+      name,
+      description: fieldDescription,
+      type,
+      required: !isOptional,
+      ...constraints !== void 0 ? { constraints } : {}
+    });
+  }
+  return {
+    id: className,
+    description,
+    fields
+  };
+}
+
+// src/extractor/ast-extractor.ts
+function extractSchemas(options) {
+  const project = new Project({
+    tsConfigFilePath: options.tsconfigPath,
+    skipAddingFilesFromTsConfig: true,
+    compilerOptions: {
+      experimentalDecorators: true,
+      strict: true,
+      // Without a target the default lib is ES5, so anything newer — `Map`,
+      // `Set` — resolves to `any` and lands in the unsupported-type warning as
+      // "any", naming a type the author never wrote.
+      target: ScriptTarget.ES2022
+    }
+  });
+  for (const pattern of options.filePatterns) {
+    project.addSourceFilesAtPaths(pattern);
+  }
+  const context = createExtractionContext();
+  const schemas = {};
+  for (const sourceFile of project.getSourceFiles()) {
+    for (const classDecl of sourceFile.getClasses()) {
+      const schema = visitClass(classDecl, context);
+      if (schema) {
+        schemas[schema.id] = schema;
+      }
+    }
+  }
+  for (const [id, schema] of Object.entries(context.synthesizedSchemas)) {
+    schemas[id] = schema;
+  }
+  context.reportUnresolvedNestedSchemas(new Set(Object.keys(schemas)));
+  return { schemas, warnings: [...context.warnings] };
+}
+
+// src/generator/schema-emitter.ts
+import { mkdirSync, writeFileSync } from "fs";
+import { join } from "path";
+function schemaToSource(schema) {
+  const json = JSON.stringify(schema, null, 2);
+  return `// Auto-generated by sembl extract \u2014 do not edit
+import type { RuntimeSchema } from "@sembl/core";
+
+export const ${schema.id}Schema: RuntimeSchema = ${json};
+`;
+}
+function emitSchemas(bundle, outputDir) {
+  mkdirSync(outputDir, { recursive: true });
+  const emittedFiles = [];
+  const schemaIds = [];
+  for (const [id, schema] of Object.entries(bundle.schemas)) {
+    const fileName = `${id}.schema.ts`;
+    const filePath = join(outputDir, fileName);
+    writeFileSync(filePath, schemaToSource(schema), "utf-8");
+    emittedFiles.push(filePath);
+    schemaIds.push(id);
+  }
+  const indexLines = [
+    "// Auto-generated by sembl extract \u2014 do not edit",
+    'import type { SchemaBundle } from "@sembl/core";',
+    ""
+  ];
+  for (const id of schemaIds) {
+    indexLines.push(`import { ${id}Schema } from "./${id}.schema.js";`);
+  }
+  indexLines.push("");
+  indexLines.push("export const bundle: SchemaBundle = {");
+  indexLines.push("  schemas: {");
+  for (const id of schemaIds) {
+    indexLines.push(`    ${id}: ${id}Schema,`);
+  }
+  indexLines.push("  },");
+  indexLines.push("};");
+  indexLines.push("");
+  for (const id of schemaIds) {
+    indexLines.push(`export { ${id}Schema } from "./${id}.schema.js";`);
+  }
+  indexLines.push("");
+  const indexPath = join(outputDir, "index.ts");
+  writeFileSync(indexPath, indexLines.join("\n"), "utf-8");
+  emittedFiles.push(indexPath);
+  return emittedFiles;
+}
+
+// src/cli/commands/extract.ts
 async function extractCommand(options) {
   const inputDir = resolve(options.input);
   const outputDir = resolve(options.output);
@@ -60,9 +509,83 @@ async function extractCommand(options) {
   };
 }
 
+// src/cli/commands/eval.ts
+import { pathToFileURL } from "url";
+import { resolve as resolve2, join as join2 } from "path";
+import {
+  runEval,
+  loadFixtures,
+  loadReport,
+  saveReport,
+  diffReports,
+  formatReport,
+  replayOrRecord
+} from "@sembl/testing";
+async function loadConfig(path) {
+  const url = pathToFileURL(resolve2(path)).href;
+  const mod = await import(url);
+  const config = mod.default ?? mod;
+  if (!config.schema || typeof config.schema !== "object" || !("id" in config.schema)) {
+    throw new Error(`${path} must export a \`schema\` (a RuntimeSchema or defineSchema result)`);
+  }
+  if (!config.provider || typeof config.provider.complete !== "function") {
+    throw new Error(`${path} must export a \`provider\``);
+  }
+  return config;
+}
+async function evalCommand(options) {
+  let config;
+  let fixtures;
+  try {
+    config = await loadConfig(options.config);
+    fixtures = loadFixtures(options.fixtures);
+  } catch (error) {
+    console.error(`sembl eval: ${error instanceof Error ? error.message : String(error)}`);
+    return { exitCode: 1 };
+  }
+  if (fixtures.length === 0) {
+    console.error(`sembl eval: no fixtures found in ${resolve2(options.fixtures)}`);
+    return { exitCode: 1 };
+  }
+  const provider = options.replay ? replayOrRecord(resolve2(options.replay), config.provider) : config.provider;
+  const out = options.out ?? join2(resolve2(options.fixtures), ".sembl-eval", "last-run.json");
+  const previous = loadReport(out);
+  const report = await runEval({
+    ...config.coerceOptions,
+    schema: config.schema,
+    bundle: config.bundle,
+    enumResolver: config.enumResolver,
+    prices: config.prices,
+    provider,
+    fixtures,
+    mode: options.mode,
+    provenance: options.provenance,
+    concurrency: options.concurrency
+  });
+  const diff = previous ? diffReports(previous, report) : void 0;
+  console.log(formatReport(report, diff));
+  saveReport(report, out);
+  console.log(`
+Report written to ${out}${previous ? " (deltas are against the previous run)" : ""}`);
+  const below = (value, floor) => floor !== void 0 && (value === null || value < floor);
+  let exitCode = 0;
+  if (below(report.totals.recall, options.minRecall)) {
+    console.error(`sembl eval: recall ${fmt(report.totals.recall)} is below --min-recall ${options.minRecall}`);
+    exitCode = 1;
+  }
+  if (below(report.totals.precision, options.minPrecision)) {
+    console.error(`sembl eval: precision ${fmt(report.totals.precision)} is below --min-precision ${options.minPrecision}`);
+    exitCode = 1;
+  }
+  return { report, diff, exitCode };
+}
+function fmt(value) {
+  return value === null ? "n/a" : value.toFixed(2);
+}
+
 // src/cli/index.ts
 var program = new Command();
-program.name("sembl").description("SEMBL schema compiler \u2014 extract runtime schemas from decorated TypeScript classes").version("0.1.0");
+program.name("sembl").description("SEMBL schema compiler \u2014 extract runtime schemas from decorated TypeScript classes").version("0.2.1");
 program.command("extract").description("Extract @Schema-decorated classes into RuntimeSchema files").requiredOption("-i, --input <path>", "Input directory containing decorated schema classes").requiredOption("-o, --output <path>", "Output directory for generated .schema.ts files").option("--tsconfig <path>", "Path to tsconfig.json").option("--strict", "Exit non-zero if extraction produced any warnings").action(async (options) => {
   const result = await extractCommand({
     input: options.input,
@@ -72,5 +595,20 @@ program.command("extract").description("Extract @Schema-decorated classes into R
   });
   process.exitCode = result.exitCode;
 });
+program.command("eval").description("Run fixtures through a schema and report per-field precision and recall").requiredOption("-c, --config <path>", "JS module exporting { schema, provider, \u2026 }").requiredOption("-f, --fixtures <dir>", "Directory of fixture JSON files").option("-o, --out <file>", "Where to write the report (default: <fixtures>/.sembl-eval/last-run.json)").option("--mode <mode>", "coerce or partialCoerce", "coerce").option("--provenance", "Ask for provenance and show confidence on mismatches").option("--concurrency <n>", "Fixtures to run at once", "1").option("--replay <dir>", "Replay recordings from this directory; record misses through the provider").option("--min-recall <fraction>", "Fail when overall recall is below this").option("--min-precision <fraction>", "Fail when overall precision is below this").action(async (options) => {
+  const mode = options.mode === "partialCoerce" ? "partialCoerce" : "coerce";
+  const result = await evalCommand({
+    config: options.config,
+    fixtures: options.fixtures,
+    out: options.out,
+    mode,
+    provenance: options.provenance,
+    concurrency: Number(options.concurrency),
+    replay: options.replay,
+    minRecall: options.minRecall !== void 0 ? Number(options.minRecall) : void 0,
+    minPrecision: options.minPrecision !== void 0 ? Number(options.minPrecision) : void 0
+  });
+  process.exitCode = result.exitCode;
+});
 program.parse();
 //# sourceMappingURL=index.js.map