@zmdb/compiler 1.0.0-beta.1

package/src/protobuf/plan.ts

@@ -0,0 +1,244 @@
+import { type ObjectIR, type ProtoScalar, type ScalarIR, type TypeIR } from '@zmdb/schema/ir';
+
+type NumericMethod =
+  | 'uint32'
+  | 'int32'
+  | 'sint32'
+  | 'uint64'
+  | 'int64'
+  | 'sint64'
+  | 'fixed32'
+  | 'sfixed32'
+  | 'fixed64'
+  | 'sfixed64'
+  | 'float'
+  | 'double';
+
+export type ScalarZero = 'number' | 'bigint' | 'boolean' | 'string';
+
+export interface ScalarPlan<Zero extends string = ScalarZero> {
+  readonly kind: 'scalar';
+  readonly method: NumericMethod | 'bool' | 'string';
+  readonly wire: 0 | 1 | 2 | 5;
+  readonly zero: Zero;
+}
+
+export interface EnumPlan {
+  readonly kind: 'enum';
+  readonly helper: string;
+  readonly wire: 0;
+}
+
+export interface MessagePlan {
+  readonly kind: 'message';
+  readonly helper: string;
+  readonly wire: 2;
+}
+
+export interface TimestampPlan {
+  readonly kind: 'timestamp';
+  readonly helper: string;
+  readonly wire: 2;
+}
+
+export type AtomPlan<Zero extends string = ScalarZero> = ScalarPlan<Zero> | EnumPlan | MessagePlan | TimestampPlan;
+
+export interface FieldPlan<Atom> {
+  readonly atom: Atom;
+  readonly repeated: boolean;
+  readonly nullable: boolean;
+}
+
+export const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const THIRTY_TWO_BIT = new Set<ProtoScalar>(['int32', 'uint32', 'sint32', 'fixed32', 'sfixed32']);
+const SIXTY_FOUR_BIT = new Set<ProtoScalar>(['int64', 'uint64', 'sint64', 'fixed64', 'sfixed64']);
+const FLOATING = new Set<ProtoScalar>(['float', 'double']);
+
+type Refuse = (path: string, reason: string, source?: string) => undefined;
+
+export type FieldAtomIR = Extract<TypeIR, { kind: 'scalar' | 'object' | 'ref' }>;
+
+export function collectMessages(
+  node: TypeIR,
+  suggested: string,
+  register: (node: ObjectIR, suggested: string) => boolean,
+): void {
+  switch (node.kind) {
+    case 'object':
+      if (!register(node, suggested)) return;
+      for (const property of node.properties) {
+        collectMessages(property.type, `${suggested}${safeName(property.name)}`, register);
+      }
+      return;
+    case 'array':
+      collectMessages(node.element, suggested, register);
+      return;
+    case 'tuple':
+      for (const [index, element] of node.elements.entries()) {
+        collectMessages(element, `${suggested}${index + 1}`, register);
+      }
+      return;
+    case 'union':
+      for (const member of node.members) collectMessages(member, suggested, register);
+      return;
+    default:
+      return;
+  }
+}
+
+export function planField<Atom>(
+  node: TypeIR,
+  path: string,
+  atomPlan: (node: FieldAtomIR, path: string) => Atom | undefined,
+  enumeration: (path: string, values: readonly string[]) => Atom,
+  refuse: Refuse,
+): FieldPlan<Atom> | undefined {
+  if (node.kind === 'array') {
+    if (node.element.kind === 'array') {
+      return refuse(
+        path,
+        'a nested array would require `repeated repeated`, which proto3 cannot spell without an explicit wrapper message',
+      );
+    }
+    const element = planField(node.element, `${path}[]`, atomPlan, enumeration, refuse);
+    if (element === undefined) return undefined;
+    if (element.repeated || element.nullable) {
+      return refuse(path, 'a repeated protobuf element cannot itself be repeated or nullable');
+    }
+    return { atom: element.atom, repeated: true, nullable: false };
+  }
+
+  if (node.kind === 'union') {
+    const values = node.members.filter(member => member.kind !== 'null' && member.kind !== 'undefined');
+    const nullable = node.members.some(member => member.kind === 'null');
+    const literals = values.filter(member => member.kind === 'literal' && typeof member.value === 'string');
+    if (literals.length === values.length && literals.length > 0) {
+      const atom = enumeration(
+        path,
+        literals.map(member => (member.kind === 'literal' && typeof member.value === 'string' ? member.value : '')),
+      );
+      return { atom, repeated: false, nullable };
+    }
+
+    const [only] = values;
+    if (values.length === 1 && only !== undefined) {
+      const resolved = planField(only, path, atomPlan, enumeration, refuse);
+      return resolved === undefined ? undefined : { ...resolved, nullable: resolved.nullable || nullable };
+    }
+    if (values.some(member => member.kind === 'object')) {
+      return refuse(
+        path,
+        'a union of message types would require `oneof`, but union arms have no ProtoField<N> tag slot',
+      );
+    }
+    return refuse(path, 'this TypeScript union has no single protobuf field spelling');
+  }
+
+  switch (node.kind) {
+    case 'scalar':
+    case 'object':
+    case 'ref': {
+      const atom = atomPlan(node, path);
+      return atom === undefined ? undefined : { atom, repeated: false, nullable: false };
+    }
+    case 'literal':
+      return typeof node.value === 'string'
+        ? { atom: enumeration(path, [node.value]), repeated: false, nullable: false }
+        : refuse(path, 'a numeric or boolean literal has no protobuf wire constraint');
+    case 'tuple':
+      return refuse(path, 'a tuple has no protobuf field spelling; declare a numbered wrapper message');
+    case 'unknown':
+      return refuse(path, '`unknown` has no protobuf wire type');
+    case 'null':
+    case 'undefined':
+      return refuse(path, 'a protobuf field cannot contain only null or undefined');
+    case 'unsupported':
+      return refuse(path, node.reason, node.source);
+  }
+}
+
+export function planScalar(
+  node: ScalarIR,
+  path: string,
+  timestamp: () => string,
+  refuse: Refuse,
+): ScalarPlan | TimestampPlan | undefined {
+  const proto = node.proto;
+  switch (node.scalar) {
+    case 'number':
+    case 'integer':
+      if (proto === undefined) return scalar('double', 1, 'number');
+      if (THIRTY_TWO_BIT.has(proto) || FLOATING.has(proto)) return numeric(proto);
+      if (SIXTY_FOUR_BIT.has(proto)) {
+        return refuse(
+          path,
+          `Proto<'${proto}'> needs bigint because a TypeScript number cannot preserve every 64-bit integer`,
+        );
+      }
+      return refuse(path, `Proto<'${proto}'> is not a numeric protobuf scalar`);
+    case 'bigint':
+      if (proto === undefined) {
+        return refuse(path, 'an untagged bigint has no inferable protobuf width or signedness; add Proto<K>');
+      }
+      return SIXTY_FOUR_BIT.has(proto)
+        ? numeric(proto)
+        : refuse(path, `a bigint protobuf field needs an explicit 64-bit scalar, not Proto<'${proto}'>`);
+    case 'boolean':
+      if (proto === undefined || proto === 'bool') return scalar('bool', 0, 'boolean');
+      return refuse(path, `a boolean protobuf field cannot use Proto<'${proto}'>`);
+    case 'string':
+      if (proto === undefined || proto === 'string') return scalar('string', 2, 'string');
+      if (proto === 'bytes') {
+        return refuse(
+          path,
+          "Proto<'bytes'> needs Uint8Array, and the current reflection refuses typed-array data types",
+        );
+      }
+      return refuse(path, `a string protobuf field cannot use Proto<'${proto}'>`);
+    case 'date':
+      if (proto !== undefined) {
+        return refuse(path, `Date has the fixed google.protobuf.Timestamp mapping, not Proto<'${proto}'>`);
+      }
+      return { kind: 'timestamp', helper: timestamp(), wire: 2 };
+  }
+}
+
+function numeric(method: ProtoScalar): ScalarPlan {
+  switch (method) {
+    case 'int32':
+    case 'uint32':
+    case 'sint32':
+      return scalar(method, 0, 'number');
+    case 'int64':
+    case 'uint64':
+    case 'sint64':
+      return scalar(method, 0, 'bigint');
+    case 'fixed32':
+    case 'sfixed32':
+    case 'float':
+      return scalar(method, 5, 'number');
+    case 'fixed64':
+    case 'sfixed64':
+      return scalar(method, 1, 'bigint');
+    case 'double':
+      return scalar(method, 1, 'number');
+    case 'bool':
+    case 'string':
+    case 'bytes':
+      throw new Error(`non-numeric protobuf scalar ${method}`);
+  }
+}
+
+function scalar(method: ScalarPlan['method'], wire: ScalarPlan['wire'], zero: ScalarPlan['zero']): ScalarPlan {
+  return { kind: 'scalar', method, wire, zero };
+}
+
+export function isPacked<Zero extends string>(atom: AtomPlan<Zero>): atom is ScalarPlan<Zero> | EnumPlan {
+  return atom.kind === 'enum' || (atom.kind === 'scalar' && atom.method !== 'string');
+}
+
+export function safeName(raw: string): string {
+  const words = raw.split(/[^A-Za-z0-9_$]+/).filter(word => word.length > 0);
+  const joined = words.map(word => `${word.slice(0, 1).toUpperCase()}${word.slice(1)}`).join('');
+  return joined.length === 0 ? 'Message' : joined;
+}

package/src/reflect/callsites.ts

@@ -0,0 +1,198 @@
+// Finding the call sites the transformer replaces.
+//
+// The generic `findCallSites` helper remains text-based because reflection fixtures use
+// local probe functions. Production transformation uses `findOwnedCallSites` instead.
+// The five protobuf/gRPC calls resolve strictly to exports of `@zmdb/protobuf`, so a
+// local shadow, foreign same-named export, or old forwarding package is not a target.
+// Existing validator/schema calls retain their historical text-based forwarding support.
+
+import type { CallExpression, Node, SourceFile, TypeNode } from 'typescript/unstable/ast';
+import {
+  isCallExpression,
+  isIdentifier,
+  isImportDeclaration,
+  isPropertyAccessExpression,
+  isStringLiteral,
+} from 'typescript/unstable/ast/is';
+import { SymbolFlags, type Checker, type Symbol as TsSymbol } from 'typescript/unstable/sync';
+
+export const CALL_OWNERS: Readonly<Record<string, readonly string[]>> = Object.freeze({
+  is: ['@zmdb/validator', 'zmdb', 'zmdb/validator'],
+  isShallow: ['@zmdb/validator', 'zmdb/validator'],
+  assert: ['@zmdb/validator', 'zmdb', 'zmdb/validator'],
+  assertShallow: ['@zmdb/validator', 'zmdb/validator'],
+  equals: ['@zmdb/validator', 'zmdb/validator'],
+  assertEquals: ['@zmdb/validator', 'zmdb/validator'],
+  validate: ['@zmdb/validator', 'zmdb', 'zmdb/validator'],
+  validateShallow: ['@zmdb/validator', 'zmdb/validator'],
+  random: ['@zmdb/validator', 'zmdb/validator'],
+  toJsonSchema: ['@zmdb/schema/openapi', 'zmdb/schema'],
+  schemaOf: ['@zmdb/schema', 'zmdb', 'zmdb/schema'],
+  toolFor: ['@zmdb/ai'],
+  grpcDescriptor: ['@zmdb/protobuf'],
+  loadGrpcService: ['@zmdb/protobuf'],
+  protoDescriptor: ['@zmdb/protobuf'],
+  protoDecode: ['@zmdb/protobuf'],
+  protoEncode: ['@zmdb/protobuf'],
+});
+
+export const OWNED_CALLEES: ReadonlySet<string> = new Set(Object.keys(CALL_OWNERS));
+export const STRICT_OWNER_CALLEES: ReadonlySet<string> = new Set([
+  'grpcDescriptor',
+  'loadGrpcService',
+  'protoDescriptor',
+  'protoDecode',
+  'protoEncode',
+]);
+
+export interface CallSite {
+  /** The canonical exported name, even when the local import is aliased. */
+  readonly callee: string;
+  /** The local named-import binding, or the namespace binding for `ns.callee`. */
+  readonly binding: string;
+  /** The owner module whose export resolved to this call. */
+  readonly specifier?: string;
+  /** The single type argument. A call with none is not a call site. */
+  readonly typeArgument: TypeNode;
+  readonly node: CallExpression;
+}
+
+/** `is(...)` → `is`; `v.is(...)` → `is`; anything else → `undefined`. */
+function calleeName(call: CallExpression): { readonly callee: string; readonly binding: string } | undefined {
+  const target = call.expression;
+  if (isIdentifier(target)) return { callee: target.text, binding: target.text };
+  if (isPropertyAccessExpression(target) && isIdentifier(target.name) && isIdentifier(target.expression)) {
+    return { callee: target.name.text, binding: target.expression.text };
+  }
+  return undefined;
+}
+
+/**
+ * Every call to one of `callees` that carries a type argument, in source order.
+ *
+ * Source order matters downstream: the transformer rewrites by text offset, and
+ * rewriting back-to-front is what keeps earlier offsets valid.
+ */
+export function findCallSites(sourceFile: SourceFile, callees: ReadonlySet<string>): readonly CallSite[] {
+  const found: CallSite[] = [];
+
+  // `forEachChild` is a method on the node, not a free function: it is not among the
+  // exports of `typescript/unstable/ast`, which only offers the *visitor* (rewriting)
+  // half of the pair.
+  const visit = (node: Node): undefined => {
+    if (isCallExpression(node)) {
+      const typeArgument = node.typeArguments?.[0];
+      const named = calleeName(node);
+      if (typeArgument && named !== undefined && callees.has(named.callee)) {
+        found.push({ ...named, typeArgument, node });
+      }
+    }
+    node.forEachChild(visit);
+    return undefined;
+  };
+
+  sourceFile.forEachChild(visit);
+  return found;
+}
+
+function resolved(checker: Checker, symbol: TsSymbol | undefined): TsSymbol | undefined {
+  if (symbol === undefined) return undefined;
+  return (symbol.flags & SymbolFlags.Alias) === 0 ? symbol : checker.getAliasedSymbol(symbol);
+}
+
+function importedExports(
+  sourceFile: SourceFile,
+  checker: Checker,
+  callees: ReadonlySet<string>,
+  owners: Readonly<Record<string, readonly string[]>>,
+): ReadonlyMap<number, { readonly callee: string; readonly specifier: string }> {
+  const bySymbol = new Map<number, { readonly callee: string; readonly specifier: string }>();
+
+  for (const statement of sourceFile.statements) {
+    if (!isImportDeclaration(statement) || !isStringLiteral(statement.moduleSpecifier)) continue;
+    const specifier = statement.moduleSpecifier.text;
+    const candidates = [...callees].filter(callee => owners[callee]?.includes(specifier) === true);
+    if (candidates.length === 0) continue;
+
+    const module = checker.getSymbolAtLocation(statement.moduleSpecifier);
+    if (module === undefined) continue;
+    const exports = new Map(checker.getExportsOfModule(module).map(symbol => [symbol.name, symbol]));
+    for (const callee of candidates) {
+      const symbol = resolved(checker, exports.get(callee));
+      if (symbol !== undefined) bySymbol.set(symbol.id, { callee, specifier });
+    }
+  }
+
+  return bySymbol;
+}
+
+function callTarget(call: CallExpression): { readonly location: Node; readonly binding: string } | undefined {
+  const target = call.expression;
+  if (isIdentifier(target)) return { location: target, binding: target.text };
+  if (isPropertyAccessExpression(target) && isIdentifier(target.name) && isIdentifier(target.expression)) {
+    return { location: target.name, binding: target.expression.text };
+  }
+  return undefined;
+}
+
+export interface OwnedCallOptions {
+  /**
+   * Test-only escape for synthetic global declarations. Production callers leave
+   * this false; strict-owner calls then require a matching `CALL_OWNERS` import.
+   */
+  readonly allowUnbound?: boolean;
+}
+
+/**
+ * Calls whose resolved symbol is an allowed package export, plus legacy
+ * text-matched validator/schema calls that intentionally retain forwarding support.
+ *
+ * The canonical export table is built only from owner modules the file actually
+ * imports. Strict-owner calls therefore cannot match a foreign same-named function
+ * by structural type or text.
+ */
+export function findOwnedCallSites(
+  sourceFile: SourceFile,
+  checker: Checker,
+  callees: ReadonlySet<string>,
+  owners: Readonly<Record<string, readonly string[]>>,
+  options: OwnedCallOptions = {},
+): readonly CallSite[] {
+  if (options.allowUnbound === true) return findCallSites(sourceFile, callees);
+
+  const canonical = importedExports(sourceFile, checker, callees, owners);
+  const found: CallSite[] = [];
+
+  const visit = (node: Node): undefined => {
+    if (isCallExpression(node)) {
+      const typeArgument = node.typeArguments?.[0];
+      const target = callTarget(node);
+      if (typeArgument !== undefined && target !== undefined) {
+        const symbol = resolved(checker, checker.getSymbolAtLocation(target.location));
+        const owned = symbol === undefined ? undefined : canonical.get(symbol.id);
+        if (owned !== undefined) {
+          found.push({
+            callee: owned.callee,
+            binding: target.binding,
+            specifier: owned.specifier,
+            typeArgument,
+            node,
+          });
+        } else {
+          const named = calleeName(node);
+          if (named !== undefined && callees.has(named.callee) && !STRICT_OWNER_CALLEES.has(named.callee)) {
+            // Validator/schema calls retain their established forwarding support.
+            // The new protobuf boundary is deliberately stricter because those old
+            // owners are removed rather than kept as compatibility aliases.
+            found.push({ ...named, typeArgument, node });
+          }
+        }
+      }
+    }
+    node.forEachChild(visit);
+    return undefined;
+  };
+
+  sourceFile.forEachChild(visit);
+  return found;
+}