@openpkg-ts/sdk 0.54.11 → 0.55.0

package/dist/browser.js

@@ -21,7 +21,7 @@ import {
   toPagefindRecords,
   toSearchIndex,
   toSearchIndexJSON
-} from "./shared/chunk-7287tqkx.js";
+} from "./shared/chunk-pwvdnach.js";
 // src/core/spec-converters.ts
 function getLangForHighlight(lang) {
   const langMap = {

package/dist/index.d.ts

@@ -1333,7 +1333,7 @@ declare function getJSDocComment(node: ts4.Node, symbol?: ts4.Symbol, checker?:
 };
 declare function getSourceLocation(node: ts4.Node, sourceFile: ts4.SourceFile): SpecSource;
 /**
-* Get description for a destructured parameter property from JSDoc @param tags.
+* Get description for a parameter or destructured key from JSDoc @param tags.
 * Matches patterns like:
 * - @param paramName - exact match
 * - @param opts.paramName - dotted notation with alias

package/dist/index.js

@@ -25,7 +25,7 @@ import {
   toPagefindRecords,
   toSearchIndex,
   toSearchIndexJSON
-} from "./shared/chunk-7287tqkx.js";
+} from "./shared/chunk-pwvdnach.js";
 
 // src/primitives/diff.ts
 import {
@@ -2111,17 +2111,41 @@ function getSourceLocation(node, sourceFile) {
     line: line + 1
   };
 }
+function bindingPatternKind(decl) {
+  if (!decl)
+    return;
+  if (ts2.isObjectBindingPattern(decl.name))
+    return "object";
+  if (ts2.isArrayBindingPattern(decl.name))
+    return "array";
+  return;
+}
+function destructuredParamName(kind, taken, jsdocName) {
+  if (jsdocName && !taken.has(jsdocName))
+    return jsdocName;
+  const base = kind === "object" ? "options" : "args";
+  if (!taken.has(base))
+    return base;
+  let i = 2;
+  while (taken.has(`${base}${i}`))
+    i++;
+  return `${base}${i}`;
+}
+function jsdocParamTagName(tag) {
+  if (tag.tagName.text !== "param")
+    return "";
+  const paramTag = tag;
+  try {
+    return paramTag.name?.getText() ?? "";
+  } catch {
+    return paramTag.name?.text ?? "";
+  }
+}
 function getParamDescription(propertyName, jsdocTags, inferredAlias) {
   for (const tag of jsdocTags) {
     if (tag.tagName.text !== "param")
       continue;
-    const paramTag = tag;
-    let tagParamName = "";
-    try {
-      tagParamName = paramTag.name?.getText() ?? "";
-    } catch {
-      tagParamName = paramTag.name?.text ?? "";
-    }
+    const tagParamName = jsdocParamTagName(tag);
     const isMatch = tagParamName === propertyName || inferredAlias && tagParamName === `${inferredAlias}.${propertyName}` || tagParamName.endsWith(`.${propertyName}`);
     if (isMatch) {
       const comment = typeof tag.comment === "string" ? tag.comment : ts2.getTextOfJSDocComment(tag.comment);
@@ -3893,6 +3917,7 @@ function buildSchemaInternal(type, checker, ctx, typeNode) {
 function buildFunctionSchema(callSignatures, checker, ctx) {
   const buildSignatures = () => {
     const signatures = callSignatures.map((sig) => {
+      const taken = new Set(sig.getParameters().filter((p) => !bindingPatternKind(p.valueDeclaration)).map((p) => p.getName()));
       const params = sig.getParameters().flatMap((param) => {
         const decl = param.valueDeclaration;
         if (!decl)
@@ -3900,11 +3925,18 @@ function buildFunctionSchema(callSignatures, checker, ctx) {
         const paramType = checker.getTypeOfSymbolAtLocation(param, decl);
         const isOptional = !!decl?.questionToken || !!decl?.initializer;
         const effectiveType = isOptional ? stripUndefinedFromType(paramType, checker) : paramType;
+        const pattern = bindingPatternKind(decl);
+        let name = param.getName();
+        if (pattern) {
+          name = destructuredParamName(pattern, taken);
+          taken.add(name);
+        }
         return {
-          name: param.getName(),
+          name,
           schema: buildSchema(effectiveType, checker, ctx, decl.type),
           required: !isOptional && !decl.dotDotDotToken,
-          ...decl.dotDotDotToken ? { rest: true } : {}
+          ...decl.dotDotDotToken ? { rest: true } : {},
+          ...pattern ? { "x-ts-destructured": true } : {}
         };
       });
       const returnType = checker.getReturnTypeOfSignature(sig);
@@ -4505,121 +4537,185 @@ function extractParameters(signature, ctx) {
   const result = [];
   const signatureDecl = signature.getDeclaration();
   const jsdocTags = signatureDecl ? ts7.getJSDocTags(signatureDecl) : [];
+  const names = destructuredNames(signature.getParameters(), jsdocTags, checker);
   for (const param of signature.getParameters()) {
     const decl = param.valueDeclaration;
     if (!decl)
       continue;
     const defer = typeNodeDefersExpansion(decl.type, checker, ctx.program);
     const type = defer ? undefined : checker.getTypeOfSymbolAtLocation(param, decl);
-    if (decl && ts7.isObjectBindingPattern(decl.name)) {
-      const expandedParams = expandBindingPattern(decl, type ?? checker.getTypeOfSymbolAtLocation(param, decl), jsdocTags, ctx);
-      result.push(...expandedParams);
-    } else {
-      const isOptional = !!decl?.questionToken || !!decl?.initializer;
-      const isRest = !!decl.dotDotDotToken;
-      const paramName = param.getName();
-      const description = getParamDescription(paramName, jsdocTags);
-      const schema = defer ? buildSchemaFromTypeNode(decl.type, checker, ctx) : buildSchema(isOptional ? stripUndefinedFromType(type, checker) : type, checker, ctx, decl.type);
-      if (!defer && type) {
-        registerReferencedTypes(isOptional ? stripUndefinedFromType(type, checker) : type, ctx);
-      }
-      const paramResult = {
-        name: paramName,
-        schema,
-        required: !isOptional && !isRest,
-        ...isRest ? { rest: true } : {}
-      };
-      if (description) {
-        paramResult.description = description;
-        const inlineTags = parseInlineTags(description);
-        if (inlineTags)
-          paramResult.inlineTags = inlineTags;
-      }
-      if (decl.initializer) {
-        applyDefault(paramResult, decl.initializer);
-      }
-      result.push(paramResult);
-    }
-  }
-  return result;
-}
-function expandBindingPattern(paramDecl, paramType, jsdocTags, ctx) {
-  const { typeChecker: checker } = ctx;
-  const result = [];
-  const bindingPattern = paramDecl.name;
-  const allProperties = getEffectiveProperties(paramType, checker);
-  const inferredAlias = inferParamAlias(jsdocTags);
-  for (const element of bindingPattern.elements) {
-    if (!ts7.isBindingElement(element))
-      continue;
-    const propertyName = element.propertyName ? ts7.isIdentifier(element.propertyName) ? element.propertyName.text : element.propertyName.getText() : ts7.isIdentifier(element.name) ? element.name.text : element.name.getText();
-    const propSymbol = allProperties.get(propertyName);
-    if (!propSymbol)
-      continue;
-    const isOptional = !!(propSymbol.flags & ts7.SymbolFlags.Optional) || element.initializer !== undefined;
-    const propType = checker.getTypeOfSymbol(propSymbol);
-    const effectiveType = isOptional ? stripUndefinedFromType(propType, checker) : propType;
-    registerReferencedTypes(effectiveType, ctx);
-    const description = getParamDescription(propertyName, jsdocTags, inferredAlias);
-    const param = {
-      name: propertyName,
-      schema: buildSchema(effectiveType, checker, ctx, declaredTypeNode(propSymbol.valueDeclaration)),
-      required: !isOptional
+    const isOptional = !!decl.questionToken || !!decl.initializer;
+    const isRest = !!decl.dotDotDotToken;
+    const pattern = bindingPatternKind(decl);
+    const paramName = pattern ? names.get(param) ?? param.getName() : param.getName();
+    const description = getParamDescription(paramName, jsdocTags);
+    let schema = defer ? buildSchemaFromTypeNode(decl.type, checker, ctx) : buildSchema(isOptional ? stripUndefinedFromType(type, checker) : type, checker, ctx, decl.type);
+    if (!defer && type) {
+      registerReferencedTypes(isOptional ? stripUndefinedFromType(type, checker) : type, ctx);
+    }
+    if (pattern === "object") {
+      schema = resolvedObjectSchema(schema, param, decl, isOptional, ctx);
+    }
+    const paramResult = {
+      name: paramName,
+      schema,
+      required: !isOptional && !isRest,
+      ...isRest ? { rest: true } : {},
+      ...pattern ? { "x-ts-destructured": true } : {}
     };
     if (description) {
-      param.description = description;
+      paramResult.description = description;
       const inlineTags = parseInlineTags(description);
       if (inlineTags)
-        param.inlineTags = inlineTags;
+        paramResult.inlineTags = inlineTags;
     }
-    if (element.initializer) {
-      applyDefault(param, element.initializer);
+    if (decl.initializer) {
+      applyDefault(paramResult, decl.initializer);
+    }
+    if (pattern === "object") {
+      annotateBindingElements(decl.name, paramResult, jsdocTags);
     }
-    result.push(param);
+    result.push(paramResult);
   }
   return result;
 }
-function getEffectiveProperties(type, _checker) {
-  const properties = new Map;
-  if (type.isIntersection()) {
-    for (const subType of type.types) {
-      for (const prop of subType.getProperties()) {
-        properties.set(prop.getName(), prop);
-      }
+function destructuredNames(params, jsdocTags, checker) {
+  const names = new Map;
+  const taken = new Set;
+  const patterns = [];
+  for (const param of params) {
+    const decl = param.valueDeclaration;
+    const kind = bindingPatternKind(decl);
+    if (!kind || !decl) {
+      taken.add(param.getName());
+      continue;
     }
-  } else {
-    for (const prop of type.getProperties()) {
-      properties.set(prop.getName(), prop);
+    patterns.push({ symbol: param, decl, kind });
+  }
+  if (patterns.length === 0)
+    return names;
+  const tagNames = jsdocTags.map(jsdocParamTagName).filter((n) => n && !n.startsWith("__"));
+  if (tagNames.length === 0) {
+    for (const { symbol, kind } of patterns) {
+      const name = destructuredParamName(kind, taken);
+      taken.add(name);
+      names.set(symbol, name);
     }
+    return names;
   }
-  return properties;
-}
-function inferParamAlias(jsdocTags) {
-  const prefixes = [];
-  for (const tag of jsdocTags) {
-    if (tag.tagName.text !== "param")
+  const keys = new Set;
+  for (const { symbol, decl } of patterns) {
+    for (const element of decl.name.elements) {
+      const key = bindingElementKey(element);
+      if (key)
+        keys.add(key);
+    }
+    const type = checker.getTypeOfSymbolAtLocation(symbol, decl);
+    for (const prop of resolvedProperties(type, checker))
+      keys.add(prop.getName());
+  }
+  const candidates = [];
+  for (const tagName of tagNames) {
+    const [head, ...rest] = tagName.split(".");
+    if (taken.has(head))
       continue;
-    const tagText = typeof tag.comment === "string" ? tag.comment : ts7.getTextOfJSDocComment(tag.comment) ?? "";
-    const paramTag = tag;
-    const paramName = paramTag.name?.getText() ?? "";
-    if (paramName.includes(".")) {
-      const prefix = paramName.split(".")[0];
-      if (prefix && !prefix.startsWith("__")) {
-        prefixes.push(prefix);
-      }
-    } else if (tagText.includes(".")) {
-      const match = tagText.match(/^(\w+)\./);
-      if (match && !match[1].startsWith("__")) {
-        prefixes.push(match[1]);
-      }
+    if (rest.length === 0 && keys.has(head))
+      continue;
+    if (!candidates.includes(head))
+      candidates.push(head);
+  }
+  patterns.forEach(({ symbol, kind }, i) => {
+    const name = destructuredParamName(kind, taken, candidates[i]);
+    taken.add(name);
+    names.set(symbol, name);
+  });
+  return names;
+}
+function bindingElementKey(element) {
+  if (!ts7.isBindingElement(element) || element.dotDotDotToken)
+    return;
+  const key = element.propertyName ?? element.name;
+  if (ts7.isIdentifier(key))
+    return key.text;
+  if (ts7.isStringLiteral(key) || ts7.isNumericLiteral(key))
+    return key.text;
+  return;
+}
+function resolvedProperties(type, checker) {
+  const seen = new Map;
+  for (const arm of objectArms(type, checker)) {
+    for (const prop of armProperties(arm, checker)) {
+      if (!seen.has(prop.getName()))
+        seen.set(prop.getName(), prop);
     }
   }
-  if (prefixes.length === 0)
+  return [...seen.values()];
+}
+var PRIMITIVE_LIKE = ts7.TypeFlags.StringLike | ts7.TypeFlags.NumberLike | ts7.TypeFlags.BigIntLike | ts7.TypeFlags.BooleanLike | ts7.TypeFlags.ESSymbolLike | ts7.TypeFlags.Void | ts7.TypeFlags.Undefined | ts7.TypeFlags.Null;
+function objectArms(type, checker) {
+  const arms = type.isUnion() ? type.types : [type];
+  return arms.filter((arm) => !(arm.flags & PRIMITIVE_LIKE) && armProperties(arm, checker).length > 0);
+}
+function armProperties(arm, checker) {
+  const own = checker.getPropertiesOfType(arm);
+  return own.length > 0 ? own : checker.getPropertiesOfType(checker.getApparentType(arm));
+}
+function resolvedObjectSchema(schema, param, decl, isOptional, ctx) {
+  if (typeof schema !== "object" || schema === null || Array.isArray(schema))
+    return schema;
+  const current = schema;
+  if (current.properties || current.$ref)
+    return schema;
+  const { typeChecker: checker } = ctx;
+  const raw = checker.getTypeOfSymbolAtLocation(param, decl);
+  const type = isOptional ? stripUndefinedFromType(raw, checker) : raw;
+  const arms = objectArms(type, checker);
+  if (arms.length === 0)
+    return schema;
+  const props = resolvedProperties(type, checker);
+  const resolved = buildObjectSchema(props, checker, ctx, type);
+  if (arms.length > 1) {
+    const requiredInAll = new Set(props.map((p) => p.getName()));
+    for (const arm of arms) {
+      const armRequired = new Set(armProperties(arm, checker).filter((p) => !(p.flags & ts7.SymbolFlags.Optional)).map((p) => p.getName()));
+      for (const name of [...requiredInAll])
+        if (!armRequired.has(name))
+          requiredInAll.delete(name);
+    }
+    const required = resolved.required?.filter((n) => requiredInAll.has(n));
+    if (required?.length)
+      resolved.required = required;
+    else
+      delete resolved.required;
+  }
+  resolved["x-ts-type"] = renderTypeText(type, checker, decl);
+  return resolved;
+}
+function annotateBindingElements(pattern, param, jsdocTags) {
+  const schema = param.schema;
+  const properties = schema?.properties;
+  if (!properties)
     return;
-  const counts = new Map;
-  for (const p of prefixes)
-    counts.set(p, (counts.get(p) ?? 0) + 1);
-  return Array.from(counts.entries()).sort((a, b) => b[1] - a[1])[0]?.[0];
+  for (const element of pattern.elements) {
+    const propertyName = bindingElementKey(element);
+    if (!propertyName)
+      continue;
+    const prop = properties[propertyName];
+    if (!prop || typeof prop !== "object" || Array.isArray(prop))
+      continue;
+    const propSchema = prop;
+    const description = getParamDescription(propertyName, jsdocTags, param.name);
+    if (description && propSchema.description === undefined) {
+      propSchema.description = description;
+    }
+    if (element.initializer) {
+      const extracted = extractLiteralDefault(element.initializer);
+      if (extracted.literal)
+        propSchema.default = extracted.value;
+      else
+        propSchema["x-ts-default"] = extracted.text;
+    }
+  }
 }
 function extractLiteralDefault(initializer) {
   if (ts7.isStringLiteral(initializer)) {
@@ -6189,7 +6285,8 @@ function normalizeSignature(signature, options) {
       ...param.required !== undefined ? { required: param.required } : {},
       ...param.description ? { description: param.description } : {},
       ...param.default !== undefined ? { default: param.default } : {},
-      ...param.rest ? { rest: param.rest } : {}
+      ...param.rest ? { rest: param.rest } : {},
+      ...param["x-ts-destructured"] ? { "x-ts-destructured": true } : {}
     }));
   }
   if (signature.returns) {

package/dist/shared/{chunk-7287tqkx.js → chunk-pwvdnach.js}

@@ -97,7 +97,8 @@ function formatSchema(schema, options) {
     }
     if ("type" in schema && schema.type === "object") {
       if ("properties" in schema && schema.properties) {
-        const props = Object.entries(schema.properties).map(([k, v]) => `${k}: ${formatSchema(v, nextOpts)}`).join("; ");
+        const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+        const props = Object.entries(schema.properties).map(([k, v]) => `${k}${required.has(k) ? "" : "?"}: ${formatSchema(v, nextOpts)}`).join("; ");
         return `{ ${props} }`;
       }
       return "object";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpkg-ts/sdk",
-  "version": "0.54.11",
+  "version": "0.55.0",
   "description": "TypeScript API extraction SDK - programmatic primitives for OpenPkg specs",
   "keywords": [
     "openpkg",
@@ -43,7 +43,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@openpkg-ts/spec": "^0.54.9",
+    "@openpkg-ts/spec": "^0.55.0",
     "picomatch": "4.0.3",
     "typescript": "^5.0.0 || ^6.0.0"
   },