@formspec/build 0.1.0-alpha.16 → 0.1.0-alpha.17

package/dist/index.js

@@ -776,7 +776,12 @@ function applyCustomConstraint(schema, constraint, ctx) {
       `Cannot generate JSON Schema for custom constraint "${constraint.constraintId}" without a matching extension registration`
     );
   }
-  Object.assign(schema, registration.toJsonSchema(constraint.payload, ctx.vendorPrefix));
+  assignVendorPrefixedExtensionKeywords(
+    schema,
+    registration.toJsonSchema(constraint.payload, ctx.vendorPrefix),
+    ctx.vendorPrefix,
+    `custom constraint "${constraint.constraintId}"`
+  );
 }
 function applyCustomAnnotation(schema, annotation, ctx) {
   const registration = ctx.extensionRegistry?.findAnnotation(annotation.annotationId);
@@ -788,7 +793,22 @@ function applyCustomAnnotation(schema, annotation, ctx) {
   if (registration.toJsonSchema === void 0) {
     return;
   }
-  Object.assign(schema, registration.toJsonSchema(annotation.value, ctx.vendorPrefix));
+  assignVendorPrefixedExtensionKeywords(
+    schema,
+    registration.toJsonSchema(annotation.value, ctx.vendorPrefix),
+    ctx.vendorPrefix,
+    `custom annotation "${annotation.annotationId}"`
+  );
+}
+function assignVendorPrefixedExtensionKeywords(schema, extensionSchema, vendorPrefix, source) {
+  for (const [key, value] of Object.entries(extensionSchema)) {
+    if (!key.startsWith(`${vendorPrefix}-`)) {
+      throw new Error(
+        `Cannot apply ${source}: extension hooks may only emit "${vendorPrefix}-*" JSON Schema keywords`
+      );
+    }
+    schema[key] = value;
+  }
 }
 
 // src/json-schema/generator.ts
@@ -1041,7 +1061,10 @@ function getSchemaExtension(schema, key) {
 // src/extensions/registry.ts
 function createExtensionRegistry(extensions) {
   const typeMap = /* @__PURE__ */ new Map();
+  const typeNameMap = /* @__PURE__ */ new Map();
   const constraintMap = /* @__PURE__ */ new Map();
+  const constraintTagMap = /* @__PURE__ */ new Map();
+  const builtinBroadeningMap = /* @__PURE__ */ new Map();
   const annotationMap = /* @__PURE__ */ new Map();
   for (const ext of extensions) {
     if (ext.types !== void 0) {
@@ -1051,6 +1074,27 @@ function createExtensionRegistry(extensions) {
           throw new Error(`Duplicate custom type ID: "${qualifiedId}"`);
         }
         typeMap.set(qualifiedId, type);
+        for (const sourceTypeName of type.tsTypeNames ?? [type.typeName]) {
+          if (typeNameMap.has(sourceTypeName)) {
+            throw new Error(`Duplicate custom type source name: "${sourceTypeName}"`);
+          }
+          typeNameMap.set(sourceTypeName, {
+            extensionId: ext.extensionId,
+            registration: type
+          });
+        }
+        if (type.builtinConstraintBroadenings !== void 0) {
+          for (const broadening of type.builtinConstraintBroadenings) {
+            const key = `${qualifiedId}:${broadening.tagName}`;
+            if (builtinBroadeningMap.has(key)) {
+              throw new Error(`Duplicate built-in constraint broadening: "${key}"`);
+            }
+            builtinBroadeningMap.set(key, {
+              extensionId: ext.extensionId,
+              registration: broadening
+            });
+          }
+        }
       }
     }
     if (ext.constraints !== void 0) {
@@ -1062,6 +1106,17 @@ function createExtensionRegistry(extensions) {
         constraintMap.set(qualifiedId, constraint);
       }
     }
+    if (ext.constraintTags !== void 0) {
+      for (const tag of ext.constraintTags) {
+        if (constraintTagMap.has(tag.tagName)) {
+          throw new Error(`Duplicate custom constraint tag: "@${tag.tagName}"`);
+        }
+        constraintTagMap.set(tag.tagName, {
+          extensionId: ext.extensionId,
+          registration: tag
+        });
+      }
+    }
     if (ext.annotations !== void 0) {
       for (const annotation of ext.annotations) {
         const qualifiedId = `${ext.extensionId}/${annotation.annotationName}`;
@@ -1075,7 +1130,10 @@ function createExtensionRegistry(extensions) {
   return {
     extensions,
     findType: (typeId) => typeMap.get(typeId),
+    findTypeByName: (typeName) => typeNameMap.get(typeName),
     findConstraint: (constraintId) => constraintMap.get(constraintId),
+    findConstraintTag: (tagName) => constraintTagMap.get(tagName),
+    findBuiltinConstraintBroadening: (typeId, tagName) => builtinBroadeningMap.get(`${typeId}:${tagName}`),
     findAnnotation: (annotationId) => annotationMap.get(annotationId)
   };
 }
@@ -1261,7 +1319,7 @@ var LENGTH_CONSTRAINT_MAP = {
   maxItems: "maxItems"
 };
 var TAGS_REQUIRING_RAW_TEXT = /* @__PURE__ */ new Set(["pattern", "enumOptions", "defaultValue"]);
-function createFormSpecTSDocConfig() {
+function createFormSpecTSDocConfig(extensionTagNames = []) {
   const config = new TSDocConfiguration();
   for (const tagName of Object.keys(BUILTIN_CONSTRAINT_DEFINITIONS)) {
     config.addTagDefinition(
@@ -1281,14 +1339,34 @@ function createFormSpecTSDocConfig() {
       })
     );
   }
+  for (const tagName of extensionTagNames) {
+    config.addTagDefinition(
+      new TSDocTagDefinition({
+        tagName: "@" + tagName,
+        syntaxKind: TSDocTagSyntaxKind.BlockTag,
+        allowMultiple: true
+      })
+    );
+  }
   return config;
 }
-var sharedParser;
-function getParser() {
-  sharedParser ??= new TSDocParser(createFormSpecTSDocConfig());
-  return sharedParser;
-}
-function parseTSDocTags(node, file = "") {
+var parserCache = /* @__PURE__ */ new Map();
+function getParser(options) {
+  const extensionTagNames = [
+    ...options?.extensionRegistry?.extensions.flatMap(
+      (extension) => (extension.constraintTags ?? []).map((tag) => tag.tagName)
+    ) ?? []
+  ].sort();
+  const cacheKey = extensionTagNames.join("|");
+  const existing = parserCache.get(cacheKey);
+  if (existing) {
+    return existing;
+  }
+  const parser = new TSDocParser(createFormSpecTSDocConfig(extensionTagNames));
+  parserCache.set(cacheKey, parser);
+  return parser;
+}
+function parseTSDocTags(node, file = "", options) {
   const constraints = [];
   const annotations = [];
   let displayName;
@@ -1309,7 +1387,7 @@ function parseTSDocTags(node, file = "") {
       if (!commentText.startsWith("/**")) {
         continue;
       }
-      const parser = getParser();
+      const parser = getParser(options);
       const parserContext = parser.parseRange(
         TextRange.fromStringRange(sourceText, range.pos, range.end)
       );
@@ -1348,7 +1426,7 @@ function parseTSDocTags(node, file = "") {
         const expectedType = isBuiltinConstraintName(tagName) ? BUILTIN_CONSTRAINT_DEFINITIONS[tagName] : void 0;
         if (text === "" && expectedType !== "boolean") continue;
         const provenance = provenanceForComment(range, sourceFile, file, tagName);
-        const constraintNode = parseConstraintValue(tagName, text, provenance);
+        const constraintNode = parseConstraintValue(tagName, text, provenance, options);
         if (constraintNode) {
           constraints.push(constraintNode);
         }
@@ -1408,7 +1486,7 @@ function parseTSDocTags(node, file = "") {
       annotations.push(defaultValueNode);
       continue;
     }
-    const constraintNode = parseConstraintValue(tagName, text, provenance);
+    const constraintNode = parseConstraintValue(tagName, text, provenance, options);
     if (constraintNode) {
       constraints.push(constraintNode);
     }
@@ -1464,7 +1542,11 @@ function extractPlainText(node) {
   }
   return result;
 }
-function parseConstraintValue(tagName, text, provenance) {
+function parseConstraintValue(tagName, text, provenance, options) {
+  const customConstraint = parseExtensionConstraintValue(tagName, text, provenance, options);
+  if (customConstraint) {
+    return customConstraint;
+  }
   if (!isBuiltinConstraintName(tagName)) {
     return null;
   }
@@ -1569,6 +1651,83 @@ function parseConstraintValue(tagName, text, provenance) {
     provenance
   };
 }
+function parseExtensionConstraintValue(tagName, text, provenance, options) {
+  const pathResult = extractPathTarget(text);
+  const effectiveText = pathResult ? pathResult.remainingText : text;
+  const path3 = pathResult?.path;
+  const registry = options?.extensionRegistry;
+  if (registry === void 0) {
+    return null;
+  }
+  const directTag = registry.findConstraintTag(tagName);
+  if (directTag !== void 0) {
+    return makeCustomConstraintNode(
+      directTag.extensionId,
+      directTag.registration.constraintName,
+      directTag.registration.parseValue(effectiveText),
+      provenance,
+      path3,
+      registry
+    );
+  }
+  if (!isBuiltinConstraintName(tagName)) {
+    return null;
+  }
+  const broadenedTypeId = getBroadenedCustomTypeId(options?.fieldType);
+  if (broadenedTypeId === void 0) {
+    return null;
+  }
+  const broadened = registry.findBuiltinConstraintBroadening(broadenedTypeId, tagName);
+  if (broadened === void 0) {
+    return null;
+  }
+  return makeCustomConstraintNode(
+    broadened.extensionId,
+    broadened.registration.constraintName,
+    broadened.registration.parseValue(effectiveText),
+    provenance,
+    path3,
+    registry
+  );
+}
+function getBroadenedCustomTypeId(fieldType) {
+  if (fieldType?.kind === "custom") {
+    return fieldType.typeId;
+  }
+  if (fieldType?.kind !== "union") {
+    return void 0;
+  }
+  const customMembers = fieldType.members.filter(
+    (member) => member.kind === "custom"
+  );
+  if (customMembers.length !== 1) {
+    return void 0;
+  }
+  const nonCustomMembers = fieldType.members.filter((member) => member.kind !== "custom");
+  const allOtherMembersAreNull = nonCustomMembers.every(
+    (member) => member.kind === "primitive" && member.primitiveKind === "null"
+  );
+  const customMember = customMembers[0];
+  return allOtherMembersAreNull && customMember !== void 0 ? customMember.typeId : void 0;
+}
+function makeCustomConstraintNode(extensionId, constraintName, payload, provenance, path3, registry) {
+  const constraintId = `${extensionId}/${constraintName}`;
+  const registration = registry.findConstraint(constraintId);
+  if (registration === void 0) {
+    throw new Error(
+      `Custom TSDoc tag resolved to unregistered constraint "${constraintId}". Register the constraint before using its tag.`
+    );
+  }
+  return {
+    kind: "constraint",
+    constraintKind: "custom",
+    constraintId,
+    payload,
+    compositionRule: registration.compositionRule,
+    ...path3 && { path: path3 },
+    provenance
+  };
+}
 function parseDefaultValueValue(text, provenance) {
   const trimmed = text.trim();
   let value;
@@ -1629,12 +1788,12 @@ function getTagCommentText(tag) {
 }
 
 // src/analyzer/jsdoc-constraints.ts
-function extractJSDocConstraintNodes(node, file = "") {
-  const result = parseTSDocTags(node, file);
+function extractJSDocConstraintNodes(node, file = "", options) {
+  const result = parseTSDocTags(node, file, options);
   return [...result.constraints];
 }
-function extractJSDocAnnotationNodes(node, file = "") {
-  const result = parseTSDocTags(node, file);
+function extractJSDocAnnotationNodes(node, file = "", options) {
+  const result = parseTSDocTags(node, file, options);
   return [...result.annotations];
 }
 function extractDefaultValueAnnotation(initializer, file = "") {
@@ -1683,18 +1842,38 @@ var RESOLVING_TYPE_PLACEHOLDER = {
   properties: [],
   additionalProperties: true
 };
-function analyzeClassToIR(classDecl, checker, file = "") {
+function makeParseOptions(extensionRegistry, fieldType) {
+  if (extensionRegistry === void 0 && fieldType === void 0) {
+    return void 0;
+  }
+  return {
+    ...extensionRegistry !== void 0 && { extensionRegistry },
+    ...fieldType !== void 0 && { fieldType }
+  };
+}
+function analyzeClassToIR(classDecl, checker, file = "", extensionRegistry) {
   const name = classDecl.name?.text ?? "AnonymousClass";
   const fields = [];
   const fieldLayouts = [];
   const typeRegistry = {};
-  const annotations = extractJSDocAnnotationNodes(classDecl, file);
+  const annotations = extractJSDocAnnotationNodes(
+    classDecl,
+    file,
+    makeParseOptions(extensionRegistry)
+  );
   const visiting = /* @__PURE__ */ new Set();
   const instanceMethods = [];
   const staticMethods = [];
   for (const member of classDecl.members) {
     if (ts4.isPropertyDeclaration(member)) {
-      const fieldNode = analyzeFieldToIR(member, checker, file, typeRegistry, visiting);
+      const fieldNode = analyzeFieldToIR(
+        member,
+        checker,
+        file,
+        typeRegistry,
+        visiting,
+        extensionRegistry
+      );
       if (fieldNode) {
         fields.push(fieldNode);
         fieldLayouts.push({});
@@ -1721,15 +1900,26 @@ function analyzeClassToIR(classDecl, checker, file = "") {
     staticMethods
   };
 }
-function analyzeInterfaceToIR(interfaceDecl, checker, file = "") {
+function analyzeInterfaceToIR(interfaceDecl, checker, file = "", extensionRegistry) {
   const name = interfaceDecl.name.text;
   const fields = [];
   const typeRegistry = {};
-  const annotations = extractJSDocAnnotationNodes(interfaceDecl, file);
+  const annotations = extractJSDocAnnotationNodes(
+    interfaceDecl,
+    file,
+    makeParseOptions(extensionRegistry)
+  );
   const visiting = /* @__PURE__ */ new Set();
   for (const member of interfaceDecl.members) {
     if (ts4.isPropertySignature(member)) {
-      const fieldNode = analyzeInterfacePropertyToIR(member, checker, file, typeRegistry, visiting);
+      const fieldNode = analyzeInterfacePropertyToIR(
+        member,
+        checker,
+        file,
+        typeRegistry,
+        visiting,
+        extensionRegistry
+      );
       if (fieldNode) {
         fields.push(fieldNode);
       }
@@ -1746,7 +1936,7 @@ function analyzeInterfaceToIR(interfaceDecl, checker, file = "") {
     staticMethods: []
   };
 }
-function analyzeTypeAliasToIR(typeAlias, checker, file = "") {
+function analyzeTypeAliasToIR(typeAlias, checker, file = "", extensionRegistry) {
   if (!ts4.isTypeLiteralNode(typeAlias.type)) {
     const sourceFile = typeAlias.getSourceFile();
     const { line } = sourceFile.getLineAndCharacterOfPosition(typeAlias.getStart());
@@ -1759,11 +1949,22 @@ function analyzeTypeAliasToIR(typeAlias, checker, file = "") {
   const name = typeAlias.name.text;
   const fields = [];
   const typeRegistry = {};
-  const annotations = extractJSDocAnnotationNodes(typeAlias, file);
+  const annotations = extractJSDocAnnotationNodes(
+    typeAlias,
+    file,
+    makeParseOptions(extensionRegistry)
+  );
   const visiting = /* @__PURE__ */ new Set();
   for (const member of typeAlias.type.members) {
     if (ts4.isPropertySignature(member)) {
-      const fieldNode = analyzeInterfacePropertyToIR(member, checker, file, typeRegistry, visiting);
+      const fieldNode = analyzeInterfacePropertyToIR(
+        member,
+        checker,
+        file,
+        typeRegistry,
+        visiting,
+        extensionRegistry
+      );
       if (fieldNode) {
         fields.push(fieldNode);
       }
@@ -1782,7 +1983,7 @@ function analyzeTypeAliasToIR(typeAlias, checker, file = "") {
     }
   };
 }
-function analyzeFieldToIR(prop, checker, file, typeRegistry, visiting) {
+function analyzeFieldToIR(prop, checker, file, typeRegistry, visiting, extensionRegistry) {
   if (!ts4.isIdentifier(prop.name)) {
     return null;
   }
@@ -1790,14 +1991,26 @@ function analyzeFieldToIR(prop, checker, file, typeRegistry, visiting) {
   const tsType = checker.getTypeAtLocation(prop);
   const optional = prop.questionToken !== void 0;
   const provenance = provenanceForNode(prop, file);
-  let type = resolveTypeNode(tsType, checker, file, typeRegistry, visiting, prop);
+  let type = resolveTypeNode(
+    tsType,
+    checker,
+    file,
+    typeRegistry,
+    visiting,
+    prop,
+    extensionRegistry
+  );
   const constraints = [];
   if (prop.type) {
-    constraints.push(...extractTypeAliasConstraintNodes(prop.type, checker, file));
+    constraints.push(
+      ...extractTypeAliasConstraintNodes(prop.type, checker, file, extensionRegistry)
+    );
   }
-  constraints.push(...extractJSDocConstraintNodes(prop, file));
+  constraints.push(...extractJSDocConstraintNodes(prop, file, makeParseOptions(extensionRegistry, type)));
   let annotations = [];
-  annotations.push(...extractJSDocAnnotationNodes(prop, file));
+  annotations.push(
+    ...extractJSDocAnnotationNodes(prop, file, makeParseOptions(extensionRegistry, type))
+  );
   const defaultAnnotation = extractDefaultValueAnnotation(prop.initializer, file);
   if (defaultAnnotation && !annotations.some((a) => a.annotationKind === "defaultValue")) {
     annotations.push(defaultAnnotation);
@@ -1813,7 +2026,7 @@ function analyzeFieldToIR(prop, checker, file, typeRegistry, visiting) {
     provenance
   };
 }
-function analyzeInterfacePropertyToIR(prop, checker, file, typeRegistry, visiting) {
+function analyzeInterfacePropertyToIR(prop, checker, file, typeRegistry, visiting, extensionRegistry) {
   if (!ts4.isIdentifier(prop.name)) {
     return null;
   }
@@ -1821,14 +2034,26 @@ function analyzeInterfacePropertyToIR(prop, checker, file, typeRegistry, visitin
   const tsType = checker.getTypeAtLocation(prop);
   const optional = prop.questionToken !== void 0;
   const provenance = provenanceForNode(prop, file);
-  let type = resolveTypeNode(tsType, checker, file, typeRegistry, visiting, prop);
+  let type = resolveTypeNode(
+    tsType,
+    checker,
+    file,
+    typeRegistry,
+    visiting,
+    prop,
+    extensionRegistry
+  );
   const constraints = [];
   if (prop.type) {
-    constraints.push(...extractTypeAliasConstraintNodes(prop.type, checker, file));
+    constraints.push(
+      ...extractTypeAliasConstraintNodes(prop.type, checker, file, extensionRegistry)
+    );
   }
-  constraints.push(...extractJSDocConstraintNodes(prop, file));
+  constraints.push(...extractJSDocConstraintNodes(prop, file, makeParseOptions(extensionRegistry, type)));
   let annotations = [];
-  annotations.push(...extractJSDocAnnotationNodes(prop, file));
+  annotations.push(
+    ...extractJSDocAnnotationNodes(prop, file, makeParseOptions(extensionRegistry, type))
+  );
   ({ type, annotations } = applyEnumMemberDisplayNames(type, annotations));
   return {
     kind: "field",
@@ -1902,7 +2127,66 @@ function parseEnumMemberDisplayName(value) {
   if (label === "") return null;
   return { value: match[1], label };
 }
-function resolveTypeNode(type, checker, file, typeRegistry, visiting, sourceNode) {
+function resolveRegisteredCustomType(sourceNode, extensionRegistry, checker) {
+  if (sourceNode === void 0 || extensionRegistry === void 0) {
+    return null;
+  }
+  const typeNode = extractTypeNodeFromSource(sourceNode);
+  if (typeNode === void 0) {
+    return null;
+  }
+  return resolveRegisteredCustomTypeFromTypeNode(typeNode, extensionRegistry, checker);
+}
+function resolveRegisteredCustomTypeFromTypeNode(typeNode, extensionRegistry, checker) {
+  if (ts4.isParenthesizedTypeNode(typeNode)) {
+    return resolveRegisteredCustomTypeFromTypeNode(typeNode.type, extensionRegistry, checker);
+  }
+  const typeName = getTypeNodeRegistrationName(typeNode);
+  if (typeName === null) {
+    return null;
+  }
+  const registration = extensionRegistry.findTypeByName(typeName);
+  if (registration !== void 0) {
+    return {
+      kind: "custom",
+      typeId: `${registration.extensionId}/${registration.registration.typeName}`,
+      payload: null
+    };
+  }
+  if (ts4.isTypeReferenceNode(typeNode) && ts4.isIdentifier(typeNode.typeName)) {
+    const aliasDecl = checker.getSymbolAtLocation(typeNode.typeName)?.declarations?.find(ts4.isTypeAliasDeclaration);
+    if (aliasDecl !== void 0) {
+      return resolveRegisteredCustomTypeFromTypeNode(aliasDecl.type, extensionRegistry, checker);
+    }
+  }
+  return null;
+}
+function extractTypeNodeFromSource(sourceNode) {
+  if (ts4.isPropertyDeclaration(sourceNode) || ts4.isPropertySignature(sourceNode) || ts4.isParameter(sourceNode) || ts4.isTypeAliasDeclaration(sourceNode)) {
+    return sourceNode.type;
+  }
+  if (ts4.isTypeNode(sourceNode)) {
+    return sourceNode;
+  }
+  return void 0;
+}
+function getTypeNodeRegistrationName(typeNode) {
+  if (ts4.isTypeReferenceNode(typeNode)) {
+    return ts4.isIdentifier(typeNode.typeName) ? typeNode.typeName.text : typeNode.typeName.right.text;
+  }
+  if (ts4.isParenthesizedTypeNode(typeNode)) {
+    return getTypeNodeRegistrationName(typeNode.type);
+  }
+  if (typeNode.kind === ts4.SyntaxKind.BigIntKeyword || typeNode.kind === ts4.SyntaxKind.StringKeyword || typeNode.kind === ts4.SyntaxKind.NumberKeyword || typeNode.kind === ts4.SyntaxKind.BooleanKeyword) {
+    return typeNode.getText();
+  }
+  return null;
+}
+function resolveTypeNode(type, checker, file, typeRegistry, visiting, sourceNode, extensionRegistry) {
+  const customType = resolveRegisteredCustomType(sourceNode, extensionRegistry, checker);
+  if (customType) {
+    return customType;
+  }
   if (type.flags & ts4.TypeFlags.String) {
     return { kind: "primitive", primitiveKind: "string" };
   }
@@ -1931,26 +2215,50 @@ function resolveTypeNode(type, checker, file, typeRegistry, visiting, sourceNode
     };
   }
   if (type.isUnion()) {
-    return resolveUnionType(type, checker, file, typeRegistry, visiting, sourceNode);
+    return resolveUnionType(
+      type,
+      checker,
+      file,
+      typeRegistry,
+      visiting,
+      sourceNode,
+      extensionRegistry
+    );
   }
   if (checker.isArrayType(type)) {
-    return resolveArrayType(type, checker, file, typeRegistry, visiting);
+    return resolveArrayType(
+      type,
+      checker,
+      file,
+      typeRegistry,
+      visiting,
+      sourceNode,
+      extensionRegistry
+    );
   }
   if (isObjectType(type)) {
-    return resolveObjectType(type, checker, file, typeRegistry, visiting);
+    return resolveObjectType(type, checker, file, typeRegistry, visiting, extensionRegistry);
   }
   return { kind: "primitive", primitiveKind: "string" };
 }
-function resolveUnionType(type, checker, file, typeRegistry, visiting, sourceNode) {
+function resolveUnionType(type, checker, file, typeRegistry, visiting, sourceNode, extensionRegistry) {
   const typeName = getNamedTypeName(type);
   const namedDecl = getNamedTypeDeclaration(type);
   if (typeName && typeName in typeRegistry) {
     return { kind: "reference", name: typeName, typeArguments: [] };
   }
   const allTypes = type.types;
+  const unionMemberTypeNodes = extractUnionMemberTypeNodes(sourceNode, checker);
+  const nonNullSourceNodes = unionMemberTypeNodes.filter(
+    (memberTypeNode) => !isNullishTypeNode(resolveAliasedTypeNode(memberTypeNode, checker))
+  );
   const nonNullTypes = allTypes.filter(
-    (t) => !(t.flags & (ts4.TypeFlags.Null | ts4.TypeFlags.Undefined))
+    (memberType) => !(memberType.flags & (ts4.TypeFlags.Null | ts4.TypeFlags.Undefined))
   );
+  const nonNullMembers = nonNullTypes.map((memberType, index) => ({
+    memberType,
+    sourceNode: nonNullSourceNodes.length === nonNullTypes.length ? nonNullSourceNodes[index] : void 0
+  }));
   const hasNull = allTypes.some((t) => t.flags & ts4.TypeFlags.Null);
   const memberDisplayNames = /* @__PURE__ */ new Map();
   if (namedDecl) {
@@ -1967,7 +2275,7 @@ function resolveUnionType(type, checker, file, typeRegistry, visiting, sourceNod
     if (!typeName) {
       return result;
     }
-    const annotations = namedDecl ? extractJSDocAnnotationNodes(namedDecl, file) : void 0;
+    const annotations = namedDecl ? extractJSDocAnnotationNodes(namedDecl, file, makeParseOptions(extensionRegistry)) : void 0;
     typeRegistry[typeName] = {
       name: typeName,
       type: result,
@@ -2015,14 +2323,15 @@ function resolveUnionType(type, checker, file, typeRegistry, visiting, sourceNod
     } : enumNode;
     return registerNamed(result);
   }
-  if (nonNullTypes.length === 1 && nonNullTypes[0]) {
+  if (nonNullMembers.length === 1 && nonNullMembers[0]) {
     const inner = resolveTypeNode(
-      nonNullTypes[0],
+      nonNullMembers[0].memberType,
       checker,
       file,
       typeRegistry,
       visiting,
-      sourceNode
+      nonNullMembers[0].sourceNode ?? sourceNode,
+      extensionRegistry
     );
     const result = hasNull ? {
       kind: "union",
@@ -2030,21 +2339,38 @@ function resolveUnionType(type, checker, file, typeRegistry, visiting, sourceNod
     } : inner;
     return registerNamed(result);
   }
-  const members = nonNullTypes.map(
-    (t) => resolveTypeNode(t, checker, file, typeRegistry, visiting, sourceNode)
+  const members = nonNullMembers.map(
+    ({ memberType, sourceNode: memberSourceNode }) => resolveTypeNode(
+      memberType,
+      checker,
+      file,
+      typeRegistry,
+      visiting,
+      memberSourceNode ?? sourceNode,
+      extensionRegistry
+    )
   );
   if (hasNull) {
     members.push({ kind: "primitive", primitiveKind: "null" });
   }
   return registerNamed({ kind: "union", members });
 }
-function resolveArrayType(type, checker, file, typeRegistry, visiting) {
+function resolveArrayType(type, checker, file, typeRegistry, visiting, sourceNode, extensionRegistry) {
   const typeArgs = isTypeReference(type) ? type.typeArguments : void 0;
   const elementType = typeArgs?.[0];
-  const items = elementType ? resolveTypeNode(elementType, checker, file, typeRegistry, visiting) : { kind: "primitive", primitiveKind: "string" };
+  const elementSourceNode = extractArrayElementTypeNode(sourceNode, checker);
+  const items = elementType ? resolveTypeNode(
+    elementType,
+    checker,
+    file,
+    typeRegistry,
+    visiting,
+    elementSourceNode,
+    extensionRegistry
+  ) : { kind: "primitive", primitiveKind: "string" };
   return { kind: "array", items };
 }
-function tryResolveRecordType(type, checker, file, typeRegistry, visiting) {
+function tryResolveRecordType(type, checker, file, typeRegistry, visiting, extensionRegistry) {
   if (type.getProperties().length > 0) {
     return null;
   }
@@ -2052,7 +2378,15 @@ function tryResolveRecordType(type, checker, file, typeRegistry, visiting) {
   if (!indexInfo) {
     return null;
   }
-  const valueType = resolveTypeNode(indexInfo.type, checker, file, typeRegistry, visiting);
+  const valueType = resolveTypeNode(
+    indexInfo.type,
+    checker,
+    file,
+    typeRegistry,
+    visiting,
+    void 0,
+    extensionRegistry
+  );
   return { kind: "record", valueType };
 }
 function typeNodeContainsReference(type, targetName) {
@@ -2080,7 +2414,7 @@ function typeNodeContainsReference(type, targetName) {
     }
   }
 }
-function resolveObjectType(type, checker, file, typeRegistry, visiting) {
+function resolveObjectType(type, checker, file, typeRegistry, visiting, extensionRegistry) {
   const typeName = getNamedTypeName(type);
   const namedTypeName = typeName ?? void 0;
   const namedDecl = getNamedTypeDeclaration(type);
@@ -2111,7 +2445,14 @@ function resolveObjectType(type, checker, file, typeRegistry, visiting) {
       return { kind: "reference", name: namedTypeName, typeArguments: [] };
     }
   }
-  const recordNode = tryResolveRecordType(type, checker, file, typeRegistry, visiting);
+  const recordNode = tryResolveRecordType(
+    type,
+    checker,
+    file,
+    typeRegistry,
+    visiting,
+    extensionRegistry
+  );
   if (recordNode) {
     visiting.delete(type);
     if (namedTypeName !== void 0 && shouldRegisterNamedType) {
@@ -2120,7 +2461,7 @@ function resolveObjectType(type, checker, file, typeRegistry, visiting) {
         clearNamedTypeRegistration();
         return recordNode;
       }
-      const annotations = namedDecl ? extractJSDocAnnotationNodes(namedDecl, file) : void 0;
+      const annotations = namedDecl ? extractJSDocAnnotationNodes(namedDecl, file, makeParseOptions(extensionRegistry)) : void 0;
       typeRegistry[namedTypeName] = {
         name: namedTypeName,
         type: recordNode,
@@ -2132,7 +2473,14 @@ function resolveObjectType(type, checker, file, typeRegistry, visiting) {
     return recordNode;
   }
   const properties = [];
-  const fieldInfoMap = getNamedTypeFieldNodeInfoMap(type, checker, file, typeRegistry, visiting);
+  const fieldInfoMap = getNamedTypeFieldNodeInfoMap(
+    type,
+    checker,
+    file,
+    typeRegistry,
+    visiting,
+    extensionRegistry
+  );
   for (const prop of type.getProperties()) {
     const declaration = prop.valueDeclaration ?? prop.declarations?.[0];
     if (!declaration) continue;
@@ -2144,7 +2492,8 @@ function resolveObjectType(type, checker, file, typeRegistry, visiting) {
       file,
       typeRegistry,
       visiting,
-      declaration
+      declaration,
+      extensionRegistry
     );
     const fieldNodeInfo = fieldInfoMap?.get(prop.name);
     properties.push({
@@ -2163,7 +2512,7 @@ function resolveObjectType(type, checker, file, typeRegistry, visiting) {
     additionalProperties: true
   };
   if (namedTypeName !== void 0 && shouldRegisterNamedType) {
-    const annotations = namedDecl ? extractJSDocAnnotationNodes(namedDecl, file) : void 0;
+    const annotations = namedDecl ? extractJSDocAnnotationNodes(namedDecl, file, makeParseOptions(extensionRegistry)) : void 0;
     typeRegistry[namedTypeName] = {
       name: namedTypeName,
       type: objectNode,
@@ -2174,7 +2523,7 @@ function resolveObjectType(type, checker, file, typeRegistry, visiting) {
   }
   return objectNode;
 }
-function getNamedTypeFieldNodeInfoMap(type, checker, file, typeRegistry, visiting) {
+function getNamedTypeFieldNodeInfoMap(type, checker, file, typeRegistry, visiting, extensionRegistry) {
   const symbols = [type.getSymbol(), type.aliasSymbol].filter(
     (s) => s?.declarations != null && s.declarations.length > 0
   );
@@ -2186,7 +2535,14 @@ function getNamedTypeFieldNodeInfoMap(type, checker, file, typeRegistry, visitin
       const map = /* @__PURE__ */ new Map();
       for (const member of classDecl.members) {
         if (ts4.isPropertyDeclaration(member) && ts4.isIdentifier(member.name)) {
-          const fieldNode = analyzeFieldToIR(member, checker, file, typeRegistry, visiting);
+          const fieldNode = analyzeFieldToIR(
+            member,
+            checker,
+            file,
+            typeRegistry,
+            visiting,
+            extensionRegistry
+          );
           if (fieldNode) {
             map.set(fieldNode.name, {
               constraints: [...fieldNode.constraints],
@@ -2200,7 +2556,14 @@ function getNamedTypeFieldNodeInfoMap(type, checker, file, typeRegistry, visitin
     }
     const interfaceDecl = declarations.find(ts4.isInterfaceDeclaration);
     if (interfaceDecl) {
-      return buildFieldNodeInfoMap(interfaceDecl.members, checker, file, typeRegistry, visiting);
+      return buildFieldNodeInfoMap(
+        interfaceDecl.members,
+        checker,
+        file,
+        typeRegistry,
+        visiting,
+        extensionRegistry
+      );
     }
     const typeAliasDecl = declarations.find(ts4.isTypeAliasDeclaration);
     if (typeAliasDecl && ts4.isTypeLiteralNode(typeAliasDecl.type)) {
@@ -2209,17 +2572,68 @@ function getNamedTypeFieldNodeInfoMap(type, checker, file, typeRegistry, visitin
         checker,
         file,
         typeRegistry,
-        visiting
+        visiting,
+        extensionRegistry
       );
     }
   }
   return null;
 }
-function buildFieldNodeInfoMap(members, checker, file, typeRegistry, visiting) {
+function extractArrayElementTypeNode(sourceNode, checker) {
+  const typeNode = sourceNode === void 0 ? void 0 : extractTypeNodeFromSource(sourceNode);
+  if (typeNode === void 0) {
+    return void 0;
+  }
+  const resolvedTypeNode = resolveAliasedTypeNode(typeNode, checker);
+  if (ts4.isArrayTypeNode(resolvedTypeNode)) {
+    return resolvedTypeNode.elementType;
+  }
+  if (ts4.isTypeReferenceNode(resolvedTypeNode) && ts4.isIdentifier(resolvedTypeNode.typeName) && resolvedTypeNode.typeName.text === "Array" && resolvedTypeNode.typeArguments?.[0]) {
+    return resolvedTypeNode.typeArguments[0];
+  }
+  return void 0;
+}
+function extractUnionMemberTypeNodes(sourceNode, checker) {
+  const typeNode = sourceNode === void 0 ? void 0 : extractTypeNodeFromSource(sourceNode);
+  if (!typeNode) {
+    return [];
+  }
+  const resolvedTypeNode = resolveAliasedTypeNode(typeNode, checker);
+  return ts4.isUnionTypeNode(resolvedTypeNode) ? [...resolvedTypeNode.types] : [];
+}
+function resolveAliasedTypeNode(typeNode, checker, visited = /* @__PURE__ */ new Set()) {
+  if (ts4.isParenthesizedTypeNode(typeNode)) {
+    return resolveAliasedTypeNode(typeNode.type, checker, visited);
+  }
+  if (!ts4.isTypeReferenceNode(typeNode) || !ts4.isIdentifier(typeNode.typeName)) {
+    return typeNode;
+  }
+  const symbol = checker.getSymbolAtLocation(typeNode.typeName);
+  const aliasDecl = symbol?.declarations?.find(ts4.isTypeAliasDeclaration);
+  if (aliasDecl === void 0 || visited.has(aliasDecl)) {
+    return typeNode;
+  }
+  visited.add(aliasDecl);
+  return resolveAliasedTypeNode(aliasDecl.type, checker, visited);
+}
+function isNullishTypeNode(typeNode) {
+  if (typeNode.kind === ts4.SyntaxKind.NullKeyword || typeNode.kind === ts4.SyntaxKind.UndefinedKeyword) {
+    return true;
+  }
+  return ts4.isLiteralTypeNode(typeNode) && (typeNode.literal.kind === ts4.SyntaxKind.NullKeyword || typeNode.literal.kind === ts4.SyntaxKind.UndefinedKeyword);
+}
+function buildFieldNodeInfoMap(members, checker, file, typeRegistry, visiting, extensionRegistry) {
   const map = /* @__PURE__ */ new Map();
   for (const member of members) {
     if (ts4.isPropertySignature(member)) {
-      const fieldNode = analyzeInterfacePropertyToIR(member, checker, file, typeRegistry, visiting);
+      const fieldNode = analyzeInterfacePropertyToIR(
+        member,
+        checker,
+        file,
+        typeRegistry,
+        visiting,
+        extensionRegistry
+      );
       if (fieldNode) {
         map.set(fieldNode.name, {
           constraints: [...fieldNode.constraints],
@@ -2232,7 +2646,7 @@ function buildFieldNodeInfoMap(members, checker, file, typeRegistry, visiting) {
   return map;
 }
 var MAX_ALIAS_CHAIN_DEPTH = 8;
-function extractTypeAliasConstraintNodes(typeNode, checker, file, depth = 0) {
+function extractTypeAliasConstraintNodes(typeNode, checker, file, extensionRegistry, depth = 0) {
   if (!ts4.isTypeReferenceNode(typeNode)) return [];
   if (depth >= MAX_ALIAS_CHAIN_DEPTH) {
     const aliasName = typeNode.typeName.getText();
@@ -2245,8 +2659,29 @@ function extractTypeAliasConstraintNodes(typeNode, checker, file, depth = 0) {
   const aliasDecl = symbol.declarations.find(ts4.isTypeAliasDeclaration);
   if (!aliasDecl) return [];
   if (ts4.isTypeLiteralNode(aliasDecl.type)) return [];
-  const constraints = extractJSDocConstraintNodes(aliasDecl, file);
-  constraints.push(...extractTypeAliasConstraintNodes(aliasDecl.type, checker, file, depth + 1));
+  const aliasFieldType = resolveTypeNode(
+    checker.getTypeAtLocation(aliasDecl.type),
+    checker,
+    file,
+    {},
+    /* @__PURE__ */ new Set(),
+    aliasDecl.type,
+    extensionRegistry
+  );
+  const constraints = extractJSDocConstraintNodes(
+    aliasDecl,
+    file,
+    makeParseOptions(extensionRegistry, aliasFieldType)
+  );
+  constraints.push(
+    ...extractTypeAliasConstraintNodes(
+      aliasDecl.type,
+      checker,
+      file,
+      extensionRegistry,
+      depth + 1
+    )
+  );
   return constraints;
 }
 function provenanceForNode(node, file) {
@@ -2342,10 +2777,10 @@ function detectFormSpecReference(typeNode) {
 }
 
 // src/generators/class-schema.ts
-function generateClassSchemas(analysis, source) {
+function generateClassSchemas(analysis, source, options) {
   const ir = canonicalizeTSDoc(analysis, source);
   return {
-    jsonSchema: generateJsonSchemaFromIR(ir),
+    jsonSchema: generateJsonSchemaFromIR(ir, options),
     uiSchema: generateUiSchemaFromIR(ir)
   };
 }
@@ -2355,27 +2790,54 @@ function generateSchemasFromClass(options) {
   if (!classDecl) {
     throw new Error(`Class "${options.className}" not found in ${options.filePath}`);
   }
-  const analysis = analyzeClassToIR(classDecl, ctx.checker, options.filePath);
-  return generateClassSchemas(analysis, { file: options.filePath });
+  const analysis = analyzeClassToIR(
+    classDecl,
+    ctx.checker,
+    options.filePath,
+    options.extensionRegistry
+  );
+  return generateClassSchemas(
+    analysis,
+    { file: options.filePath },
+    {
+      extensionRegistry: options.extensionRegistry,
+      vendorPrefix: options.vendorPrefix
+    }
+  );
 }
 function generateSchemas(options) {
   const ctx = createProgramContext(options.filePath);
   const source = { file: options.filePath };
   const classDecl = findClassByName(ctx.sourceFile, options.typeName);
   if (classDecl) {
-    const analysis = analyzeClassToIR(classDecl, ctx.checker, options.filePath);
-    return generateClassSchemas(analysis, source);
+    const analysis = analyzeClassToIR(
+      classDecl,
+      ctx.checker,
+      options.filePath,
+      options.extensionRegistry
+    );
+    return generateClassSchemas(analysis, source, options);
   }
   const interfaceDecl = findInterfaceByName(ctx.sourceFile, options.typeName);
   if (interfaceDecl) {
-    const analysis = analyzeInterfaceToIR(interfaceDecl, ctx.checker, options.filePath);
-    return generateClassSchemas(analysis, source);
+    const analysis = analyzeInterfaceToIR(
+      interfaceDecl,
+      ctx.checker,
+      options.filePath,
+      options.extensionRegistry
+    );
+    return generateClassSchemas(analysis, source, options);
   }
   const typeAlias = findTypeAliasByName(ctx.sourceFile, options.typeName);
   if (typeAlias) {
-    const result = analyzeTypeAliasToIR(typeAlias, ctx.checker, options.filePath);
+    const result = analyzeTypeAliasToIR(
+      typeAlias,
+      ctx.checker,
+      options.filePath,
+      options.extensionRegistry
+    );
     if (result.ok) {
-      return generateClassSchemas(result.analysis, source);
+      return generateClassSchemas(result.analysis, source, options);
     }
     throw new Error(result.error);
   }
@@ -2387,7 +2849,7 @@ function generateSchemas(options) {
 // src/generators/mixed-authoring.ts
 function buildMixedAuthoringSchemas(options) {
   const { filePath, typeName, overlays, ...schemaOptions } = options;
-  const analysis = analyzeNamedType(filePath, typeName);
+  const analysis = analyzeNamedType(filePath, typeName, schemaOptions.extensionRegistry);
   const composedAnalysis = composeAnalysisWithOverlays(analysis, overlays);
   const ir = canonicalizeTSDoc(composedAnalysis, { file: filePath });
   return {
@@ -2395,20 +2857,20 @@ function buildMixedAuthoringSchemas(options) {
     uiSchema: generateUiSchemaFromIR(ir)
   };
 }
-function analyzeNamedType(filePath, typeName) {
+function analyzeNamedType(filePath, typeName, extensionRegistry) {
   const ctx = createProgramContext(filePath);
   const source = { file: filePath };
   const classDecl = findClassByName(ctx.sourceFile, typeName);
   if (classDecl !== null) {
-    return analyzeClassToIR(classDecl, ctx.checker, source.file);
+    return analyzeClassToIR(classDecl, ctx.checker, source.file, extensionRegistry);
   }
   const interfaceDecl = findInterfaceByName(ctx.sourceFile, typeName);
   if (interfaceDecl !== null) {
-    return analyzeInterfaceToIR(interfaceDecl, ctx.checker, source.file);
+    return analyzeInterfaceToIR(interfaceDecl, ctx.checker, source.file, extensionRegistry);
   }
   const typeAlias = findTypeAliasByName(ctx.sourceFile, typeName);
   if (typeAlias !== null) {
-    const result = analyzeTypeAliasToIR(typeAlias, ctx.checker, source.file);
+    const result = analyzeTypeAliasToIR(typeAlias, ctx.checker, source.file, extensionRegistry);
     if (result.ok) {
       return result.analysis;
     }
@@ -2487,7 +2949,7 @@ function assertSupportedOverlayField(baseField, overlayField) {
       `Mixed-authoring overlay for "${baseField.name}" cannot define constraints; keep constraints on the static model`
     );
   }
-  if (overlayField.required) {
+  if (overlayField.required && !baseField.required) {
     throw new Error(
       `Mixed-authoring overlay for "${baseField.name}" cannot change requiredness; keep requiredness on the static model`
     );
@@ -2577,7 +3039,7 @@ function mergeAnnotations(baseAnnotations, overlayAnnotations) {
   const overlayOnly = overlayAnnotations.filter(
     (annotation) => !baseKeys.has(annotationKey(annotation))
   );
-  return [...overlayOnly, ...baseAnnotations];
+  return [...baseAnnotations, ...overlayOnly];
 }
 function annotationKey(annotation) {
   return annotation.annotationKind === "custom" ? `${annotation.annotationKind}:${annotation.annotationId}` : annotation.annotationKind;