@openpkg-ts/sdk 0.33.0 → 0.34.0

package/dist/shared/chunk-91b592v7.js

@@ -0,0 +1,552 @@
+// src/core/query-builder.ts
+class QueryBuilder {
+  spec;
+  predicates = [];
+  constructor(spec) {
+    this.spec = spec;
+  }
+  byKind(...kinds) {
+    if (kinds.length > 0) {
+      this.predicates.push((exp) => kinds.includes(exp.kind));
+    }
+    return this;
+  }
+  byName(pattern) {
+    if (typeof pattern === "string") {
+      this.predicates.push((exp) => exp.name === pattern);
+    } else {
+      this.predicates.push((exp) => pattern.test(exp.name));
+    }
+    return this;
+  }
+  byTag(...tags) {
+    if (tags.length > 0) {
+      this.predicates.push((exp) => {
+        const expTags = exp.tags?.map((t) => t.name) ?? [];
+        return tags.some((tag) => expTags.includes(tag));
+      });
+    }
+    return this;
+  }
+  deprecated(include) {
+    if (include !== undefined) {
+      this.predicates.push((exp) => (exp.deprecated ?? false) === include);
+    }
+    return this;
+  }
+  withDescription() {
+    this.predicates.push((exp) => Boolean(exp.description?.trim()));
+    return this;
+  }
+  search(term) {
+    const lower = term.toLowerCase();
+    this.predicates.push((exp) => exp.name.toLowerCase().includes(lower) || (exp.description?.toLowerCase().includes(lower) ?? false));
+    return this;
+  }
+  where(predicate) {
+    this.predicates.push(predicate);
+    return this;
+  }
+  byModule(modulePath) {
+    this.predicates.push((exp) => exp.source?.file?.includes(modulePath) ?? false);
+    return this;
+  }
+  matches(exp) {
+    return this.predicates.every((p) => p(exp));
+  }
+  find() {
+    return this.spec.exports.filter((exp) => this.matches(exp));
+  }
+  first() {
+    return this.spec.exports.find((exp) => this.matches(exp));
+  }
+  count() {
+    return this.spec.exports.filter((exp) => this.matches(exp)).length;
+  }
+  ids() {
+    return this.find().map((exp) => exp.id);
+  }
+  toSpec() {
+    return {
+      ...this.spec,
+      exports: this.find(),
+      types: this.spec.types ? [...this.spec.types] : undefined
+    };
+  }
+}
+function query(spec) {
+  return new QueryBuilder(spec);
+}
+
+// src/core/diagnostics.ts
+function hasDeprecatedTag(exp) {
+  if (exp.deprecated === true)
+    return true;
+  return exp.tags?.some((t) => t.name === "deprecated" || t.name === "@deprecated") ?? false;
+}
+function getDeprecationMessage(exp) {
+  const tag = exp.tags?.find((t) => t.name === "deprecated" || t.name === "@deprecated");
+  if (tag?.text.trim()) {
+    return tag.text.trim();
+  }
+  return;
+}
+function findMissingParamDocs(exp) {
+  const missing = [];
+  for (const sig of exp.signatures ?? []) {
+    for (const param of sig.parameters ?? []) {
+      if (!param.description?.trim()) {
+        missing.push(param.name);
+      }
+    }
+  }
+  return missing;
+}
+function checkMemberDescriptions(exp, members) {
+  const items = [];
+  for (const member of members) {
+    if (!member.description?.trim() && member.name) {
+      items.push({
+        exportId: exp.id,
+        exportName: exp.name,
+        issue: "member missing description",
+        member: member.name
+      });
+    }
+  }
+  return items;
+}
+function analyzeSpec(spec) {
+  const missingDescriptions = [];
+  const deprecatedNoReason = [];
+  const missingParamDocs = [];
+  for (const exp of spec.exports) {
+    if (!exp.description?.trim()) {
+      missingDescriptions.push({
+        exportId: exp.id,
+        exportName: exp.name,
+        issue: "missing description"
+      });
+    }
+    if (exp.members) {
+      missingDescriptions.push(...checkMemberDescriptions(exp, exp.members));
+    }
+    if (hasDeprecatedTag(exp) && !getDeprecationMessage(exp)) {
+      deprecatedNoReason.push({
+        exportId: exp.id,
+        exportName: exp.name,
+        issue: "deprecated without reason"
+      });
+    }
+    const missingParams = findMissingParamDocs(exp);
+    for (const param of missingParams) {
+      missingParamDocs.push({
+        exportId: exp.id,
+        exportName: exp.name,
+        issue: "param missing description",
+        param
+      });
+    }
+  }
+  return {
+    missingDescriptions,
+    deprecatedNoReason,
+    missingParamDocs
+  };
+}
+
+// src/core/format.ts
+function getMemberBadges(member) {
+  const badges = [];
+  const visibility = member.visibility ?? "public";
+  if (visibility !== "public") {
+    badges.push(visibility);
+  }
+  const flags = member.flags;
+  if (flags?.static)
+    badges.push("static");
+  if (flags?.readonly)
+    badges.push("readonly");
+  if (flags?.async)
+    badges.push("async");
+  if (flags?.abstract)
+    badges.push("abstract");
+  return badges;
+}
+function formatBadges(badges) {
+  return badges.join(" ");
+}
+
+// src/core/query.ts
+function formatFunctionSchema(schema) {
+  const sigs = schema["x-ts-signatures"];
+  if (!sigs?.length)
+    return "(...args: unknown[]) => unknown";
+  const sig = sigs[0];
+  const params = formatParameters(sig);
+  const ret = sig.returns ? formatSchema(sig.returns.schema) : "void";
+  return `${params} => ${ret}`;
+}
+function formatSchema(schema, options) {
+  if (!schema)
+    return "unknown";
+  if (typeof schema === "string")
+    return schema;
+  const withPackage = (typeStr) => {
+    if (options?.includePackage && typeof schema === "object" && "x-ts-package" in schema) {
+      const pkg = schema["x-ts-package"];
+      return `${typeStr} (from ${pkg})`;
+    }
+    return typeStr;
+  };
+  if (typeof schema === "object" && schema !== null) {
+    if ("x-ts-type" in schema && typeof schema["x-ts-type"] === "string") {
+      const tsType = schema["x-ts-type"];
+      if (tsType === "function" || schema["x-ts-function"]) {
+        return withPackage(formatFunctionSchema(schema));
+      }
+      return withPackage(tsType);
+    }
+    if ("x-ts-function" in schema && schema["x-ts-function"]) {
+      return withPackage(formatFunctionSchema(schema));
+    }
+    if ("x-ts-type-predicate" in schema) {
+      const pred = schema["x-ts-type-predicate"];
+      return `${pred.parameterName} is ${formatSchema(pred.type, options)}`;
+    }
+    if ("$ref" in schema && typeof schema.$ref === "string") {
+      const baseName = schema.$ref.replace("#/types/", "");
+      if ("x-ts-type-arguments" in schema && Array.isArray(schema["x-ts-type-arguments"])) {
+        const args = schema["x-ts-type-arguments"].map((s) => formatSchema(s, options)).join(", ");
+        return withPackage(`${baseName}<${args}>`);
+      }
+      return withPackage(baseName);
+    }
+    if ("anyOf" in schema && Array.isArray(schema.anyOf)) {
+      const threshold = options?.collapseUnionThreshold;
+      const members = schema.anyOf;
+      if (threshold && members.length > threshold) {
+        const shown = members.slice(0, 3);
+        const remaining = members.length - 3;
+        const shownStr = shown.map((s) => formatSchema(s, options)).join(" | ");
+        return `${shownStr} | ... (${remaining} more)`;
+      }
+      return members.map((s) => formatSchema(s, options)).join(" | ");
+    }
+    if ("allOf" in schema && Array.isArray(schema.allOf)) {
+      return schema.allOf.map((s) => formatSchema(s, options)).join(" & ");
+    }
+    if ("type" in schema && schema.type === "array") {
+      const items = "items" in schema ? formatSchema(schema.items, options) : "unknown";
+      return `${items}[]`;
+    }
+    if ("type" in schema && schema.type === "tuple" && "items" in schema) {
+      const items = schema.items.map((s) => formatSchema(s, options)).join(", ");
+      return `[${items}]`;
+    }
+    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, options)}`).join("; ");
+        return `{ ${props} }`;
+      }
+      return "object";
+    }
+    if ("type" in schema && typeof schema.type === "string") {
+      return withPackage(schema.type);
+    }
+  }
+  return "unknown";
+}
+function formatTypeParameters(typeParams) {
+  if (!typeParams?.length)
+    return "";
+  const params = typeParams.map((tp) => {
+    let str = "";
+    if ("const" in tp && tp.const)
+      str += "const ";
+    if (tp.variance === "in")
+      str += "in ";
+    else if (tp.variance === "out")
+      str += "out ";
+    else if (tp.variance === "inout")
+      str += "in out ";
+    str += tp.name;
+    if (tp.constraint)
+      str += ` extends ${tp.constraint}`;
+    if (tp.default)
+      str += ` = ${tp.default}`;
+    return str;
+  });
+  return `<${params.join(", ")}>`;
+}
+function formatParameters(sig) {
+  if (!sig?.parameters?.length)
+    return "()";
+  const params = sig.parameters.map((p) => {
+    const optional = p.required === false ? "?" : "";
+    const rest = p.rest ? "..." : "";
+    const type = formatSchema(p.schema);
+    return `${rest}${p.name}${optional}: ${type}`;
+  });
+  return `(${params.join(", ")})`;
+}
+function formatReturnType(sig) {
+  if (!sig?.returns)
+    return "void";
+  return formatSchema(sig.returns.schema);
+}
+function buildSignatureString(exp, sigIndex = 0) {
+  const sig = exp.signatures?.[sigIndex];
+  const typeParams = formatTypeParameters(exp.typeParameters || sig?.typeParameters);
+  switch (exp.kind) {
+    case "function": {
+      const params = formatParameters(sig);
+      const returnType = formatReturnType(sig);
+      return `function ${exp.name}${typeParams}${params}: ${returnType}`;
+    }
+    case "class": {
+      const ext = exp.extends ? ` extends ${exp.extends}` : "";
+      const impl = exp.implements?.length ? ` implements ${exp.implements.join(", ")}` : "";
+      return `class ${exp.name}${typeParams}${ext}${impl}`;
+    }
+    case "interface": {
+      const ext = exp.extends ? ` extends ${exp.extends}` : "";
+      return `interface ${exp.name}${typeParams}${ext}`;
+    }
+    case "type": {
+      const typeValue = typeof exp.type === "string" ? exp.type : formatSchema(exp.schema);
+      return `type ${exp.name}${typeParams} = ${typeValue}`;
+    }
+    case "enum": {
+      return `enum ${exp.name}`;
+    }
+    case "variable": {
+      const typeValue = typeof exp.type === "string" ? exp.type : formatSchema(exp.schema);
+      return `const ${exp.name}: ${typeValue}`;
+    }
+    default:
+      return exp.name;
+  }
+}
+function resolveTypeRef(ref, spec) {
+  const id = ref.replace("#/types/", "");
+  return spec.types?.find((t) => t.id === id);
+}
+function isMethod(member) {
+  return !!member.signatures?.length;
+}
+function isProperty(member) {
+  return !member.signatures?.length;
+}
+function getMethods(members) {
+  return members?.filter(isMethod) ?? [];
+}
+function getProperties(members) {
+  return members?.filter(isProperty) ?? [];
+}
+function groupByVisibility(members) {
+  const groups = {
+    public: [],
+    protected: [],
+    private: []
+  };
+  for (const member of members ?? []) {
+    const visibility = member.visibility ?? "public";
+    groups[visibility].push(member);
+  }
+  return groups;
+}
+function sortByName(items) {
+  return [...items].sort((a, b) => a.name.localeCompare(b.name));
+}
+function formatConditionalType(condType) {
+  const check = formatSchema(condType.checkType);
+  const ext = formatSchema(condType.extendsType);
+  const trueT = formatSchema(condType.trueType);
+  const falseT = formatSchema(condType.falseType);
+  return `${check} extends ${ext} ? ${trueT} : ${falseT}`;
+}
+function formatMappedType(mappedType) {
+  const keyStr = formatSchema(mappedType.keyType);
+  const valueStr = formatSchema(mappedType.valueType);
+  let readonlyMod = "";
+  if (mappedType.readonly === true || mappedType.readonly === "add") {
+    readonlyMod = "readonly ";
+  } else if (mappedType.readonly === "remove") {
+    readonlyMod = "-readonly ";
+  }
+  let optionalMod = "";
+  if (mappedType.optional === true || mappedType.optional === "add") {
+    optionalMod = "?";
+  } else if (mappedType.optional === "remove") {
+    optionalMod = "-?";
+  }
+  return `{ ${readonlyMod}[${keyStr}]${optionalMod}: ${valueStr} }`;
+}
+
+// src/core/search.ts
+var defaultSlugify = (name) => name.toLowerCase().replace(/[^a-z0-9]+/g, "-");
+function extractKeywords(exp, options = {}) {
+  const keywords = new Set;
+  keywords.add(exp.name);
+  keywords.add(exp.name.toLowerCase());
+  const camelParts = exp.name.split(/(?=[A-Z])/);
+  for (const part of camelParts) {
+    if (part.length > 2)
+      keywords.add(part.toLowerCase());
+  }
+  if (exp.tags) {
+    for (const tag of exp.tags) {
+      keywords.add(tag.name.replace("@", ""));
+      const tagWords = tag.text.split(/\s+/);
+      for (const word of tagWords) {
+        if (word.length > 2)
+          keywords.add(word.toLowerCase());
+      }
+    }
+  }
+  if (exp.description) {
+    const descWords = exp.description.toLowerCase().split(/\W+/).filter((w) => w.length > 2);
+    for (const word of descWords) {
+      keywords.add(word);
+    }
+  }
+  if (options.includeMembers && exp.members) {
+    for (const member of exp.members) {
+      if (member.name) {
+        keywords.add(member.name.toLowerCase());
+      }
+    }
+  }
+  if (options.includeParameters && exp.signatures) {
+    for (const sig of exp.signatures) {
+      for (const param of sig.parameters || []) {
+        keywords.add(param.name.toLowerCase());
+      }
+    }
+  }
+  return Array.from(keywords);
+}
+function buildContent(exp, options = {}) {
+  const parts = [];
+  parts.push(exp.name);
+  if (exp.description) {
+    parts.push(exp.description);
+  }
+  if (options.includeSignatures !== false) {
+    parts.push(buildSignatureString(exp));
+  }
+  if (exp.tags) {
+    parts.push(...exp.tags.map((t) => `${t.name} ${t.text}`));
+  }
+  if (options.includeMembers !== false && exp.members) {
+    const props = getProperties(exp.members);
+    const methods = getMethods(exp.members);
+    for (const prop of props) {
+      if (prop.name) {
+        parts.push(prop.name);
+        if (prop.description)
+          parts.push(prop.description);
+      }
+    }
+    for (const method of methods) {
+      if (method.name) {
+        parts.push(method.name);
+        if (method.description)
+          parts.push(method.description);
+      }
+    }
+  }
+  if (options.includeParameters !== false && exp.signatures) {
+    for (const sig of exp.signatures) {
+      for (const param of sig.parameters || []) {
+        parts.push(param.name);
+        if (param.description)
+          parts.push(param.description);
+      }
+    }
+  }
+  return parts.join(" ");
+}
+function createSearchRecord(exp, _packageName, options = {}) {
+  const { baseUrl = "/api", slugify = defaultSlugify } = options;
+  return {
+    id: exp.id,
+    name: exp.name,
+    kind: exp.kind,
+    signature: buildSignatureString(exp),
+    description: exp.description,
+    content: buildContent(exp, options),
+    keywords: extractKeywords(exp, options),
+    url: `${baseUrl}/${slugify(exp.name)}`,
+    deprecated: exp.deprecated === true
+  };
+}
+function toSearchIndex(spec, options = {}) {
+  const records = spec.exports.map((exp) => createSearchRecord(exp, spec.meta.name, options));
+  return {
+    records,
+    version: spec.meta.version || "0.0.0",
+    generatedAt: new Date().toISOString(),
+    packageName: spec.meta.name
+  };
+}
+function toPagefindRecords(spec, options = {}) {
+  const { baseUrl = "/api", slugify = defaultSlugify, weights = {} } = options;
+  const { name: nameWeight = 10, description: descWeight = 5, signature: sigWeight = 3 } = weights;
+  return spec.exports.map((exp) => {
+    const content = buildContent(exp, options);
+    const signature = buildSignatureString(exp);
+    const filters = {
+      kind: [exp.kind]
+    };
+    if (exp.deprecated) {
+      filters.deprecated = ["true"];
+    }
+    if (exp.tags?.length) {
+      filters.tags = exp.tags.map((t) => t.name.replace("@", ""));
+    }
+    return {
+      url: `${baseUrl}/${slugify(exp.name)}`,
+      content,
+      word_count: content.split(/\s+/).length,
+      filters,
+      meta: {
+        title: exp.name,
+        kind: exp.kind,
+        description: exp.description?.slice(0, 160),
+        signature
+      },
+      weighted_sections: [
+        { weight: nameWeight, text: exp.name },
+        ...exp.description ? [{ weight: descWeight, text: exp.description }] : [],
+        { weight: sigWeight, text: signature }
+      ]
+    };
+  });
+}
+function toAlgoliaRecords(spec, options = {}) {
+  const { baseUrl = "/api", slugify = defaultSlugify } = options;
+  return spec.exports.map((exp) => ({
+    objectID: exp.id,
+    name: exp.name,
+    kind: exp.kind,
+    description: exp.description,
+    signature: buildSignatureString(exp),
+    content: buildContent(exp, options),
+    tags: (exp.tags || []).map((t) => t.name.replace("@", "")),
+    deprecated: exp.deprecated === true,
+    url: `${baseUrl}/${slugify(exp.name)}`,
+    hierarchy: {
+      lvl0: spec.meta.name,
+      lvl1: `${exp.kind.charAt(0).toUpperCase() + exp.kind.slice(1)}s`,
+      lvl2: exp.name
+    }
+  }));
+}
+function toSearchIndexJSON(spec, options = {}) {
+  const index = toSearchIndex(spec, options);
+  return options.pretty ? JSON.stringify(index, null, 2) : JSON.stringify(index);
+}
+
+export { QueryBuilder, query, hasDeprecatedTag, getDeprecationMessage, findMissingParamDocs, analyzeSpec, getMemberBadges, formatBadges, formatSchema, formatTypeParameters, formatParameters, formatReturnType, buildSignatureString, resolveTypeRef, isMethod, isProperty, getMethods, getProperties, groupByVisibility, sortByName, formatConditionalType, formatMappedType, toSearchIndex, toPagefindRecords, toAlgoliaRecords, toSearchIndexJSON };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpkg-ts/sdk",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "TypeScript API extraction SDK - programmatic primitives for OpenPkg specs",
   "keywords": [
     "openpkg",
@@ -24,6 +24,10 @@
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
+    },
+    "./browser": {
+      "import": "./dist/browser.js",
+      "types": "./dist/browser.d.ts"
     }
   },
   "files": [