@formspec/build 0.1.0-alpha.47 → 0.1.0-alpha.49

package/dist/cli.js

@@ -2469,6 +2469,90 @@ function supportsConstraintCapability(type, checker, capability) {
   }
   return false;
 }
+function stripHintNullishUnion(type) {
+  if (!type.isUnion()) {
+    return type;
+  }
+  const nonNullish = type.types.filter(
+    (member) => (member.flags & (ts.TypeFlags.Null | ts.TypeFlags.Undefined)) === 0
+  );
+  if (nonNullish.length === 1 && nonNullish[0] !== void 0) {
+    return nonNullish[0];
+  }
+  return type;
+}
+function isCallableType(type) {
+  return type.getCallSignatures().length > 0 || type.getConstructSignatures().length > 0;
+}
+function isUserEmittableHintProperty(property, declaration) {
+  if (property.name.startsWith("__")) {
+    return false;
+  }
+  if ("name" in declaration && declaration.name !== void 0) {
+    const name = declaration.name;
+    if (ts.isComputedPropertyName(name) || ts.isPrivateIdentifier(name)) {
+      return false;
+    }
+    if (!ts.isIdentifier(name) && !ts.isStringLiteral(name) && !ts.isNumericLiteral(name)) {
+      return false;
+    }
+  }
+  return true;
+}
+function collectObjectSubfieldCandidates(type, checker, capability) {
+  const out = [];
+  const visit = (current, prefix, depth) => {
+    if (depth > MAX_HINT_DEPTH) {
+      return;
+    }
+    const stripped = stripHintNullishUnion(current);
+    if (isCallableType(stripped)) {
+      return;
+    }
+    if (!hasTypeSemanticCapability(stripped, checker, "object-like")) {
+      return;
+    }
+    for (const property of stripped.getProperties()) {
+      const declaration = property.valueDeclaration ?? property.declarations?.[0];
+      if (declaration === void 0) {
+        continue;
+      }
+      if (!isUserEmittableHintProperty(property, declaration)) {
+        continue;
+      }
+      const propertyType = checker.getTypeOfSymbolAtLocation(property, declaration);
+      const path5 = [...prefix, property.name];
+      if (supportsConstraintCapability(propertyType, checker, capability)) {
+        out.push(path5.join("."));
+        continue;
+      }
+      const strippedPropertyType = stripHintNullishUnion(propertyType);
+      if (!isCallableType(strippedPropertyType) && hasTypeSemanticCapability(strippedPropertyType, checker, "object-like")) {
+        visit(strippedPropertyType, path5, depth + 1);
+      }
+    }
+  };
+  visit(type, [], 0);
+  return out;
+}
+function buildPathTargetHint(subjectType, checker, capability, tagName, argumentText) {
+  if (!hasTypeSemanticCapability(subjectType, checker, "object-like")) {
+    return null;
+  }
+  const candidates = collectObjectSubfieldCandidates(subjectType, checker, capability);
+  const primary = candidates[0];
+  if (primary === void 0) {
+    return null;
+  }
+  const argText = argumentText?.trim() ?? "";
+  const renderExample = (path5) => argText === "" ? `@${tagName} :${path5}` : `@${tagName} :${path5} ${argText}`;
+  if (candidates.length === 1) {
+    return `Hint: use a path target to constrain a subfield, e.g. ${renderExample(primary)}`;
+  }
+  const shown = candidates.slice(0, MAX_HINT_CANDIDATES);
+  const overflow = candidates.length > MAX_HINT_CANDIDATES ? ", \u2026" : "";
+  return `Hint: use a path target to constrain a subfield (candidates: ${shown.join(", ")}${overflow}), e.g. ${renderExample(primary)}`;
+}
 function makeDiagnostic(code, message, provenance) {
   return {
     code,
@@ -2636,10 +2720,18 @@ function buildCompilerBackedConstraintDiagnostics(node, sourceFile, tagName, par
     const requiredCapability = definition.capabilities[0];
     if (requiredCapability !== void 0 && !supportsConstraintCapability(subjectType, checker, requiredCapability)) {
       const actualType = checker.typeToString(subjectType, node, SYNTHETIC_TYPE_FORMAT_FLAGS);
+      const baseMessage = `Target "${node.getText(sourceFile)}": constraint "${tagName}" is only valid on ${capabilityLabel(requiredCapability)} targets, but field type is "${actualType}"`;
+      const hint = buildPathTargetHint(
+        subjectType,
+        checker,
+        requiredCapability,
+        tagName,
+        parsedTag?.argumentText
+      );
       return [
         makeDiagnostic(
           "TYPE_MISMATCH",
-          `Target "${node.getText(sourceFile)}": constraint "${tagName}" is only valid on ${capabilityLabel(requiredCapability)} targets, but field type is "${actualType}"`,
+          hint === null ? baseMessage : `${baseMessage}. ${hint}`,
           provenance
         )
       ];
@@ -3015,11 +3107,13 @@ function getTagCommentText(tag) {
   }
   return ts.getTextOfJSDocComment(tag.comment);
 }
-var SYNTHETIC_TYPE_FORMAT_FLAGS, parseResultCache;
+var SYNTHETIC_TYPE_FORMAT_FLAGS, MAX_HINT_CANDIDATES, MAX_HINT_DEPTH, parseResultCache;
 var init_tsdoc_parser = __esm({
   "src/analyzer/tsdoc-parser.ts"() {
     "use strict";
     SYNTHETIC_TYPE_FORMAT_FLAGS = ts.TypeFormatFlags.NoTruncation | ts.TypeFormatFlags.UseAliasDefinedOutsideCurrentScope;
+    MAX_HINT_CANDIDATES = 5;
+    MAX_HINT_DEPTH = 3;
     parseResultCache = /* @__PURE__ */ new Map();
   }
 });
@@ -4303,6 +4397,9 @@ function resolveTypeNode(type, checker, file, typeRegistry, visiting, sourceNode
   if (type.flags & ts3.TypeFlags.Undefined) {
     return { kind: "primitive", primitiveKind: "null" };
   }
+  if (type.flags & ts3.TypeFlags.Void) {
+    return { kind: "primitive", primitiveKind: "null" };
+  }
   if (type.isStringLiteral()) {
     return {
       kind: "enum",
@@ -6296,7 +6393,13 @@ function toStandaloneJsonSchema(root, typeRegistry, resolved) {
   const syntheticField = {
     kind: "field",
     name: "__result",
-    ...syntheticFieldMetadata !== void 0 && { metadata: syntheticFieldMetadata },
+    metadata: {
+      ...syntheticFieldMetadata,
+      // Pin apiName so metadata-policy transforms (e.g. toStripeApiCase)
+      // cannot rename this synthetic wrapper field. The lookup below
+      // expects "__result" in the output schema properties.
+      apiName: { value: "__result", source: "explicit" }
+    },
     type: root.type,
     required: true,
     constraints: [],
@@ -6539,7 +6642,20 @@ function unwrapPromiseType(checker, type) {
   if (!("getAwaitedType" in checker) || typeof checker.getAwaitedType !== "function") {
     return type;
   }
-  return checker.getAwaitedType(type) ?? type;
+  const awaited = checker.getAwaitedType(type) ?? type;
+  if (awaited === type && looksLikePromiseType(checker, type)) {
+    throw new Error(
+      `FormSpec could not unwrap the awaited type from "${checker.typeToString(type)}". This usually indicates the TypeScript compiler host cannot resolve its default lib files (for example "lib.es2015.promise.d.ts"). Ensure the program is configured with the standard library available to \`ts.createProgram\`.`
+    );
+  }
+  return awaited;
+}
+function looksLikePromiseType(checker, type) {
+  const symbolName = type.getSymbol()?.getName();
+  if (symbolName === "Promise" || symbolName === "PromiseLike") {
+    return true;
+  }
+  return /^(?:Promise|PromiseLike)\b/.test(checker.typeToString(type));
 }
 function unwrapPromiseTypeNode(typeNode) {
   if (typeNode === void 0) {