@formspec/build 0.1.0-alpha.27 → 0.1.0-alpha.28

package/dist/index.js

@@ -1212,6 +1212,9 @@ import * as path from "path";
 
 // src/analyzer/class-analyzer.ts
 import * as ts3 from "typescript";
+import {
+  parseCommentBlock as parseCommentBlock2
+} from "@formspec/analysis/internal";
 
 // src/analyzer/jsdoc-constraints.ts
 import * as ts2 from "typescript";
@@ -2159,9 +2162,17 @@ function analyzeClassToIR(classDecl, checker, file = "", extensionRegistry) {
       }
     }
   }
+  const specializedFields = applyDeclarationDiscriminatorToFields(
+    fields,
+    classDecl,
+    classType,
+    checker,
+    file,
+    diagnostics
+  );
   return {
     name,
-    fields,
+    fields: specializedFields,
     fieldLayouts,
     typeRegistry,
     ...annotations.length > 0 && { annotations },
@@ -2201,10 +2212,18 @@ function analyzeInterfaceToIR(interfaceDecl, checker, file = "", extensionRegist
       }
     }
   }
-  const fieldLayouts = fields.map(() => ({}));
+  const specializedFields = applyDeclarationDiscriminatorToFields(
+    fields,
+    interfaceDecl,
+    interfaceType,
+    checker,
+    file,
+    diagnostics
+  );
+  const fieldLayouts = specializedFields.map(() => ({}));
   return {
     name,
-    fields,
+    fields: specializedFields,
     fieldLayouts,
     typeRegistry,
     ...annotations.length > 0 && { annotations },
@@ -2253,12 +2272,20 @@ function analyzeTypeAliasToIR(typeAlias, checker, file = "", extensionRegistry)
       }
     }
   }
+  const specializedFields = applyDeclarationDiscriminatorToFields(
+    fields,
+    typeAlias,
+    aliasType,
+    checker,
+    file,
+    diagnostics
+  );
   return {
     ok: true,
     analysis: {
       name,
-      fields,
-      fieldLayouts: fields.map(() => ({})),
+      fields: specializedFields,
+      fieldLayouts: specializedFields.map(() => ({})),
       typeRegistry,
       ...annotations.length > 0 && { annotations },
       ...diagnostics.length > 0 && { diagnostics },
@@ -2267,6 +2294,396 @@ function analyzeTypeAliasToIR(typeAlias, checker, file = "", extensionRegistry)
     }
   };
 }
+function makeAnalysisDiagnostic(code, message, primaryLocation, relatedLocations = []) {
+  return {
+    code,
+    message,
+    severity: "error",
+    primaryLocation,
+    relatedLocations
+  };
+}
+function getLeadingParsedTags(node) {
+  const sourceFile = node.getSourceFile();
+  const sourceText = sourceFile.getFullText();
+  const commentRanges = ts3.getLeadingCommentRanges(sourceText, node.getFullStart());
+  if (commentRanges === void 0) {
+    return [];
+  }
+  const parsedTags = [];
+  for (const range of commentRanges) {
+    if (range.kind !== ts3.SyntaxKind.MultiLineCommentTrivia) {
+      continue;
+    }
+    const commentText = sourceText.slice(range.pos, range.end);
+    if (!commentText.startsWith("/**")) {
+      continue;
+    }
+    parsedTags.push(...parseCommentBlock2(commentText, { offset: range.pos }).tags);
+  }
+  return parsedTags;
+}
+function findDiscriminatorProperty(node, fieldName) {
+  if (ts3.isClassDeclaration(node)) {
+    for (const member of node.members) {
+      if (ts3.isPropertyDeclaration(member) && ts3.isIdentifier(member.name) && member.name.text === fieldName) {
+        return member;
+      }
+    }
+    return null;
+  }
+  if (ts3.isInterfaceDeclaration(node)) {
+    for (const member of node.members) {
+      if (ts3.isPropertySignature(member) && ts3.isIdentifier(member.name) && member.name.text === fieldName) {
+        return member;
+      }
+    }
+    return null;
+  }
+  if (ts3.isTypeLiteralNode(node.type)) {
+    for (const member of node.type.members) {
+      if (ts3.isPropertySignature(member) && ts3.isIdentifier(member.name) && member.name.text === fieldName) {
+        return member;
+      }
+    }
+  }
+  return null;
+}
+function isLocalTypeParameterName(node, typeParameterName) {
+  return node.typeParameters?.some((typeParameter) => typeParameter.name.text === typeParameterName) ?? false;
+}
+function isNullishSemanticType(type) {
+  if (type.flags & (ts3.TypeFlags.Null | ts3.TypeFlags.Undefined | ts3.TypeFlags.Void | ts3.TypeFlags.Unknown | ts3.TypeFlags.Any)) {
+    return true;
+  }
+  return type.isUnion() && type.types.some((member) => isNullishSemanticType(member));
+}
+function isStringLikeSemanticType(type) {
+  if (type.flags & ts3.TypeFlags.StringLike) {
+    return true;
+  }
+  if (type.isUnion()) {
+    return type.types.length > 0 && type.types.every((member) => isStringLikeSemanticType(member));
+  }
+  return false;
+}
+function extractDiscriminatorDirective(node, file, diagnostics) {
+  const discriminatorTags = getLeadingParsedTags(node).filter(
+    (tag) => tag.normalizedTagName === "discriminator"
+  );
+  if (discriminatorTags.length === 0) {
+    return null;
+  }
+  const [firstTag, ...duplicateTags] = discriminatorTags;
+  for (const _duplicateTag of duplicateTags) {
+    diagnostics.push(
+      makeAnalysisDiagnostic(
+        "DUPLICATE_TAG",
+        'Duplicate "@discriminator" tag. Only one discriminator declaration is allowed per declaration.',
+        provenanceForNode(node, file)
+      )
+    );
+  }
+  if (firstTag === void 0) {
+    return null;
+  }
+  const firstTarget = firstTag.target;
+  if (firstTarget?.path === null || firstTarget?.valid !== true) {
+    diagnostics.push(
+      makeAnalysisDiagnostic(
+        "INVALID_TAG_ARGUMENT",
+        'Tag "@discriminator" requires a direct path target like ":kind".',
+        provenanceForNode(node, file)
+      )
+    );
+    return null;
+  }
+  if (firstTarget.path.segments.length !== 1) {
+    diagnostics.push(
+      makeAnalysisDiagnostic(
+        "INVALID_TAG_ARGUMENT",
+        'Tag "@discriminator" only supports direct property targets in v1; nested paths are out of scope.',
+        provenanceForNode(node, file)
+      )
+    );
+    return null;
+  }
+  const typeParameterName = firstTag.argumentText.trim();
+  if (!/^[A-Za-z_$][\w$]*$/u.test(typeParameterName)) {
+    diagnostics.push(
+      makeAnalysisDiagnostic(
+        "INVALID_TAG_ARGUMENT",
+        'Tag "@discriminator" requires a local type parameter name as its source operand.',
+        provenanceForNode(node, file)
+      )
+    );
+    return null;
+  }
+  return {
+    fieldName: firstTarget.path.segments[0] ?? firstTarget.rawText,
+    typeParameterName,
+    provenance: provenanceForNode(node, file)
+  };
+}
+function validateDiscriminatorDirective(node, checker, file, diagnostics) {
+  const directive = extractDiscriminatorDirective(node, file, diagnostics);
+  if (directive === null) {
+    return null;
+  }
+  if (!isLocalTypeParameterName(node, directive.typeParameterName)) {
+    diagnostics.push(
+      makeAnalysisDiagnostic(
+        "INVALID_TAG_ARGUMENT",
+        `Tag "@discriminator" references "${directive.typeParameterName}", but the source operand must be a type parameter declared on the same declaration.`,
+        directive.provenance
+      )
+    );
+    return null;
+  }
+  const propertyDecl = findDiscriminatorProperty(node, directive.fieldName);
+  if (propertyDecl === null) {
+    diagnostics.push(
+      makeAnalysisDiagnostic(
+        "UNKNOWN_PATH_TARGET",
+        `Tag "@discriminator" targets "${directive.fieldName}", but no direct property with that name exists on this declaration.`,
+        directive.provenance
+      )
+    );
+    return null;
+  }
+  if (propertyDecl.questionToken !== void 0) {
+    diagnostics.push(
+      makeAnalysisDiagnostic(
+        "TYPE_MISMATCH",
+        `Discriminator field "${directive.fieldName}" must be required; optional discriminator fields are not supported.`,
+        directive.provenance,
+        [provenanceForNode(propertyDecl, file)]
+      )
+    );
+    return null;
+  }
+  const propertyType = checker.getTypeAtLocation(propertyDecl);
+  if (isNullishSemanticType(propertyType)) {
+    diagnostics.push(
+      makeAnalysisDiagnostic(
+        "TYPE_MISMATCH",
+        `Discriminator field "${directive.fieldName}" must not be nullable.`,
+        directive.provenance,
+        [provenanceForNode(propertyDecl, file)]
+      )
+    );
+    return null;
+  }
+  if (!isStringLikeSemanticType(propertyType)) {
+    diagnostics.push(
+      makeAnalysisDiagnostic(
+        "TYPE_MISMATCH",
+        `Discriminator field "${directive.fieldName}" must be string-like.`,
+        directive.provenance,
+        [provenanceForNode(propertyDecl, file)]
+      )
+    );
+    return null;
+  }
+  return directive;
+}
+function getConcreteTypeArgumentForDiscriminator(node, subjectType, checker, typeParameterName) {
+  const typeParameterIndex = node.typeParameters?.findIndex(
+    (typeParameter) => typeParameter.name.text === typeParameterName
+  ) ?? -1;
+  if (typeParameterIndex < 0) {
+    return null;
+  }
+  const referenceTypeArguments = (isTypeReference(subjectType) ? subjectType.typeArguments : void 0) ?? subjectType.aliasTypeArguments;
+  if (referenceTypeArguments?.[typeParameterIndex] !== void 0) {
+    return referenceTypeArguments[typeParameterIndex] ?? null;
+  }
+  const localTypeParameter = node.typeParameters?.[typeParameterIndex];
+  return localTypeParameter === void 0 ? null : checker.getTypeAtLocation(localTypeParameter);
+}
+function extractDeclarationApiName(node) {
+  for (const tag of getLeadingParsedTags(node)) {
+    if (tag.normalizedTagName !== "apiName") {
+      continue;
+    }
+    if (tag.target === null && tag.argumentText.trim() !== "") {
+      return tag.argumentText.trim();
+    }
+    if (tag.target?.kind === "variant" && tag.target.rawText === "singular") {
+      const value = tag.argumentText.trim();
+      if (value !== "") {
+        return value;
+      }
+    }
+  }
+  return null;
+}
+function inferJsonFacingName(name) {
+  return name.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2").replace(/[-\s]+/g, "_").toLowerCase();
+}
+function resolveNamedDiscriminatorDeclaration(type, checker, seen = /* @__PURE__ */ new Set()) {
+  if (seen.has(type)) {
+    return null;
+  }
+  seen.add(type);
+  const symbol = type.aliasSymbol ?? type.getSymbol();
+  if (symbol !== void 0) {
+    const aliased = symbol.flags & ts3.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : void 0;
+    const targetSymbol = aliased ?? symbol;
+    const declaration = targetSymbol.declarations?.find(
+      (candidate) => ts3.isClassDeclaration(candidate) || ts3.isInterfaceDeclaration(candidate) || ts3.isTypeAliasDeclaration(candidate) || ts3.isEnumDeclaration(candidate)
+    );
+    if (declaration !== void 0) {
+      if (ts3.isTypeAliasDeclaration(declaration) && ts3.isTypeReferenceNode(declaration.type) && checker.getTypeFromTypeNode(declaration.type) !== type) {
+        return resolveNamedDiscriminatorDeclaration(
+          checker.getTypeFromTypeNode(declaration.type),
+          checker,
+          seen
+        );
+      }
+      return declaration;
+    }
+  }
+  return null;
+}
+function resolveDiscriminatorValue(boundType, checker, provenance, diagnostics) {
+  if (boundType === null) {
+    diagnostics.push(
+      makeAnalysisDiagnostic(
+        "INVALID_TAG_ARGUMENT",
+        "Discriminator resolution failed because no concrete type argument is available for the referenced type parameter.",
+        provenance
+      )
+    );
+    return null;
+  }
+  if (boundType.isStringLiteral()) {
+    return boundType.value;
+  }
+  if (boundType.isUnion()) {
+    const nonNullMembers = boundType.types.filter(
+      (member) => !(member.flags & (ts3.TypeFlags.Null | ts3.TypeFlags.Undefined))
+    );
+    if (nonNullMembers.every((member) => member.isStringLiteral())) {
+      diagnostics.push(
+        makeAnalysisDiagnostic(
+          "INVALID_TAG_ARGUMENT",
+          "Discriminator resolution for unions of string literals is out of scope for v1.",
+          provenance
+        )
+      );
+      return null;
+    }
+  }
+  const declaration = resolveNamedDiscriminatorDeclaration(boundType, checker);
+  if (declaration !== null) {
+    return extractDeclarationApiName(declaration) ?? inferJsonFacingName(getDeclarationName(declaration));
+  }
+  diagnostics.push(
+    makeAnalysisDiagnostic(
+      "INVALID_TAG_ARGUMENT",
+      "Discriminator resolution could not derive a JSON-facing discriminator value from the referenced type argument.",
+      provenance
+    )
+  );
+  return null;
+}
+function getDeclarationName(node) {
+  if (ts3.isClassDeclaration(node) || ts3.isInterfaceDeclaration(node) || ts3.isTypeAliasDeclaration(node) || ts3.isEnumDeclaration(node)) {
+    return node.name?.text ?? "anonymous";
+  }
+  return "anonymous";
+}
+function applyDeclarationDiscriminatorToFields(fields, node, subjectType, checker, file, diagnostics) {
+  const directive = validateDiscriminatorDirective(node, checker, file, diagnostics);
+  if (directive === null) {
+    return [...fields];
+  }
+  const discriminatorValue = resolveDiscriminatorValue(
+    getConcreteTypeArgumentForDiscriminator(
+      node,
+      subjectType,
+      checker,
+      directive.typeParameterName
+    ),
+    checker,
+    directive.provenance,
+    diagnostics
+  );
+  if (discriminatorValue === null) {
+    return [...fields];
+  }
+  return fields.map(
+    (field) => field.name === directive.fieldName ? {
+      ...field,
+      type: {
+        kind: "enum",
+        members: [{ value: discriminatorValue }]
+      }
+    } : field
+  );
+}
+function buildInstantiatedReferenceName(baseName, typeArguments, checker) {
+  const renderedArguments = typeArguments.map(
+    (typeArgument) => checker.typeToString(typeArgument).replace(/[^A-Za-z0-9]+/g, "_").replace(/^_+|_+$/g, "")
+  ).filter((value) => value !== "");
+  return renderedArguments.length === 0 ? baseName : `${baseName}__${renderedArguments.join("__")}`;
+}
+function extractReferenceTypeArguments(type, checker, file, typeRegistry, visiting, sourceNode, extensionRegistry, diagnostics) {
+  const typeNode = sourceNode === void 0 ? void 0 : extractTypeNodeFromSource(sourceNode);
+  if (typeNode === void 0) {
+    return [];
+  }
+  const resolvedTypeNode = resolveAliasedTypeNode(typeNode, checker);
+  if (!ts3.isTypeReferenceNode(resolvedTypeNode) || resolvedTypeNode.typeArguments === void 0) {
+    return [];
+  }
+  return resolvedTypeNode.typeArguments.map((argumentNode) => {
+    const argumentType = checker.getTypeFromTypeNode(argumentNode);
+    return {
+      tsType: argumentType,
+      typeNode: resolveTypeNode(
+        argumentType,
+        checker,
+        file,
+        typeRegistry,
+        visiting,
+        argumentNode,
+        extensionRegistry,
+        diagnostics
+      )
+    };
+  });
+}
+function applyDiscriminatorToObjectProperties(properties, node, subjectType, checker, file, diagnostics) {
+  const directive = validateDiscriminatorDirective(node, checker, file, diagnostics);
+  if (directive === null) {
+    return properties;
+  }
+  const discriminatorValue = resolveDiscriminatorValue(
+    getConcreteTypeArgumentForDiscriminator(
+      node,
+      subjectType,
+      checker,
+      directive.typeParameterName
+    ),
+    checker,
+    directive.provenance,
+    diagnostics
+  );
+  if (discriminatorValue === null) {
+    return properties;
+  }
+  return properties.map(
+    (property) => property.name === directive.fieldName ? {
+      ...property,
+      type: {
+        kind: "enum",
+        members: [{ value: discriminatorValue }]
+      }
+    } : property
+  );
+}
 function analyzeFieldToIR(prop, checker, file, typeRegistry, visiting, diagnostics, hostType, extensionRegistry) {
   if (!ts3.isIdentifier(prop.name)) {
     return null;
@@ -2555,6 +2972,7 @@ function resolveTypeNode(type, checker, file, typeRegistry, visiting, sourceNode
       file,
       typeRegistry,
       visiting,
+      sourceNode,
       extensionRegistry,
       diagnostics
     );
@@ -2818,35 +3236,60 @@ function typeNodeContainsReference(type, targetName) {
     }
   }
 }
-function resolveObjectType(type, checker, file, typeRegistry, visiting, extensionRegistry, diagnostics) {
+function resolveObjectType(type, checker, file, typeRegistry, visiting, sourceNode, extensionRegistry, diagnostics) {
+  const collectedDiagnostics = diagnostics ?? [];
   const typeName = getNamedTypeName(type);
   const namedTypeName = typeName ?? void 0;
   const namedDecl = getNamedTypeDeclaration(type);
-  const shouldRegisterNamedType = namedTypeName !== void 0 && !(namedTypeName === "Record" && namedDecl?.getSourceFile().fileName !== file);
+  const referenceTypeArguments = extractReferenceTypeArguments(
+    type,
+    checker,
+    file,
+    typeRegistry,
+    visiting,
+    sourceNode,
+    extensionRegistry,
+    collectedDiagnostics
+  );
+  const instantiatedTypeName = namedTypeName !== void 0 && referenceTypeArguments.length > 0 ? buildInstantiatedReferenceName(
+    namedTypeName,
+    referenceTypeArguments.map((argument) => argument.tsType),
+    checker
+  ) : void 0;
+  const registryTypeName = instantiatedTypeName ?? namedTypeName;
+  const shouldRegisterNamedType = registryTypeName !== void 0 && !(registryTypeName === "Record" && namedDecl?.getSourceFile().fileName !== file);
   const clearNamedTypeRegistration = () => {
-    if (namedTypeName === void 0 || !shouldRegisterNamedType) {
+    if (registryTypeName === void 0 || !shouldRegisterNamedType) {
       return;
     }
-    Reflect.deleteProperty(typeRegistry, namedTypeName);
+    Reflect.deleteProperty(typeRegistry, registryTypeName);
   };
   if (visiting.has(type)) {
-    if (namedTypeName !== void 0 && shouldRegisterNamedType) {
-      return { kind: "reference", name: namedTypeName, typeArguments: [] };
+    if (registryTypeName !== void 0 && shouldRegisterNamedType) {
+      return {
+        kind: "reference",
+        name: registryTypeName,
+        typeArguments: referenceTypeArguments.map((argument) => argument.typeNode)
+      };
     }
     return { kind: "object", properties: [], additionalProperties: false };
   }
-  if (namedTypeName !== void 0 && shouldRegisterNamedType && !typeRegistry[namedTypeName]) {
-    typeRegistry[namedTypeName] = {
-      name: namedTypeName,
+  if (registryTypeName !== void 0 && shouldRegisterNamedType && !typeRegistry[registryTypeName]) {
+    typeRegistry[registryTypeName] = {
+      name: registryTypeName,
       type: RESOLVING_TYPE_PLACEHOLDER,
       provenance: provenanceForDeclaration(namedDecl, file)
     };
   }
   visiting.add(type);
-  if (namedTypeName !== void 0 && shouldRegisterNamedType && typeRegistry[namedTypeName]?.type !== void 0) {
-    if (typeRegistry[namedTypeName].type !== RESOLVING_TYPE_PLACEHOLDER) {
+  if (registryTypeName !== void 0 && shouldRegisterNamedType && typeRegistry[registryTypeName]?.type !== void 0) {
+    if (typeRegistry[registryTypeName].type !== RESOLVING_TYPE_PLACEHOLDER) {
       visiting.delete(type);
-      return { kind: "reference", name: namedTypeName, typeArguments: [] };
+      return {
+        kind: "reference",
+        name: registryTypeName,
+        typeArguments: referenceTypeArguments.map((argument) => argument.typeNode)
+      };
     }
   }
   const recordNode = tryResolveRecordType(
@@ -2856,24 +3299,28 @@ function resolveObjectType(type, checker, file, typeRegistry, visiting, extensio
     typeRegistry,
     visiting,
     extensionRegistry,
-    diagnostics
+    collectedDiagnostics
   );
   if (recordNode) {
     visiting.delete(type);
-    if (namedTypeName !== void 0 && shouldRegisterNamedType) {
-      const isRecursiveRecord = typeNodeContainsReference(recordNode.valueType, namedTypeName);
+    if (registryTypeName !== void 0 && shouldRegisterNamedType) {
+      const isRecursiveRecord = typeNodeContainsReference(recordNode.valueType, registryTypeName);
       if (!isRecursiveRecord) {
         clearNamedTypeRegistration();
         return recordNode;
       }
       const annotations = namedDecl ? extractJSDocAnnotationNodes(namedDecl, file, makeParseOptions(extensionRegistry)) : void 0;
-      typeRegistry[namedTypeName] = {
-        name: namedTypeName,
+      typeRegistry[registryTypeName] = {
+        name: registryTypeName,
         type: recordNode,
         ...annotations !== void 0 && annotations.length > 0 && { annotations },
         provenance: provenanceForDeclaration(namedDecl, file)
       };
-      return { kind: "reference", name: namedTypeName, typeArguments: [] };
+      return {
+        kind: "reference",
+        name: registryTypeName,
+        typeArguments: referenceTypeArguments.map((argument) => argument.typeNode)
+      };
     }
     return recordNode;
   }
@@ -2884,7 +3331,7 @@ function resolveObjectType(type, checker, file, typeRegistry, visiting, extensio
     file,
     typeRegistry,
     visiting,
-    diagnostics ?? [],
+    collectedDiagnostics,
     extensionRegistry
   );
   for (const prop of type.getProperties()) {
@@ -2900,7 +3347,7 @@ function resolveObjectType(type, checker, file, typeRegistry, visiting, extensio
       visiting,
       declaration,
       extensionRegistry,
-      diagnostics
+      collectedDiagnostics
     );
     const fieldNodeInfo = fieldInfoMap?.get(prop.name);
     properties.push({
@@ -2915,18 +3362,29 @@ function resolveObjectType(type, checker, file, typeRegistry, visiting, extensio
   visiting.delete(type);
   const objectNode = {
     kind: "object",
-    properties,
+    properties: namedDecl !== void 0 && (ts3.isClassDeclaration(namedDecl) || ts3.isInterfaceDeclaration(namedDecl) || ts3.isTypeAliasDeclaration(namedDecl)) ? applyDiscriminatorToObjectProperties(
+      properties,
+      namedDecl,
+      type,
+      checker,
+      file,
+      collectedDiagnostics
+    ) : properties,
     additionalProperties: true
   };
-  if (namedTypeName !== void 0 && shouldRegisterNamedType) {
+  if (registryTypeName !== void 0 && shouldRegisterNamedType) {
     const annotations = namedDecl ? extractJSDocAnnotationNodes(namedDecl, file, makeParseOptions(extensionRegistry)) : void 0;
-    typeRegistry[namedTypeName] = {
-      name: namedTypeName,
+    typeRegistry[registryTypeName] = {
+      name: registryTypeName,
       type: objectNode,
       ...annotations !== void 0 && annotations.length > 0 && { annotations },
       provenance: provenanceForDeclaration(namedDecl, file)
     };
-    return { kind: "reference", name: namedTypeName, typeArguments: [] };
+    return {
+      kind: "reference",
+      name: registryTypeName,
+      typeArguments: referenceTypeArguments.map((argument) => argument.typeNode)
+    };
   }
   return objectNode;
 }