@openpkg-ts/spec 0.34.1 → 0.37.0

package/dist/index.d.ts

@@ -244,6 +244,8 @@ type SpecMember = {
 	schema?: SpecSchema;
 	signatures?: SpecSignature[];
 	decorators?: SpecDecorator[];
+	deprecated?: boolean;
+	deprecationReason?: string;
 };
 type SpecInheritedMember = SpecMember & {
 	/** Name of the class this member was inherited from */
@@ -414,7 +416,75 @@ type OpenPkg = {
 declare const SCHEMA_VERSION: OpenPkgVersion;
 declare const SCHEMA_URL = "https://unpkg.com/@openpkg-ts/spec/schemas/v0.4.0/openpkg.schema.json";
 declare const JSON_SCHEMA_DRAFT = "https://json-schema.org/draft/2020-12/schema";
+/** The 6 kinds relevant for UI display (excludes namespace, module, reference, external). */
+type DisplayKind = Extract<SpecExportKind, "function" | "class" | "interface" | "type" | "enum" | "variable">;
+/** Canonical display order for UI-facing kind groups. */
+declare const DISPLAY_KIND_ORDER: DisplayKind[];
+/** Human-readable plural labels for every kind. */
+declare const KIND_LABELS: Record<SpecExportKind, string>;
+/** URL-safe slug for every kind. */
+declare const KIND_SLUGS: Record<SpecExportKind, string>;
 declare function dereference(spec: OpenPkg): OpenPkg;
+declare function isStringSchema(s: SpecSchema): s is Extract<SpecSchemaPrimitive, {
+	type: "string";
+}>;
+declare function isNumberSchema(s: SpecSchema): s is Extract<SpecSchemaPrimitive, {
+	type: "number";
+}>;
+declare function isBooleanSchema(s: SpecSchema): s is Extract<SpecSchemaPrimitive, {
+	type: "boolean";
+}>;
+declare function isIntegerSchema(s: SpecSchema): s is Extract<SpecSchemaPrimitive, {
+	type: "integer";
+}>;
+declare function isNullSchema(s: SpecSchema): s is Extract<SpecSchemaPrimitive, {
+	type: "null";
+}>;
+declare function isVoidSchema(s: SpecSchema): s is Extract<SpecSchemaPrimitive, {
+	type: "void";
+}>;
+declare function isNeverSchema(s: SpecSchema): s is Extract<SpecSchemaPrimitive, {
+	type: "never";
+}>;
+declare function isAnySchema(s: SpecSchema): s is Extract<SpecSchemaPrimitive, {
+	type: "any";
+}>;
+declare function isObjectSchema(s: SpecSchema): s is Extract<SpecSchemaComposite, {
+	type: "object";
+}>;
+declare function isArraySchema(s: SpecSchema): s is Extract<SpecSchemaComposite, {
+	type: "array";
+}>;
+declare function isTupleSchema(s: SpecSchema): s is Extract<SpecSchemaComposite, {
+	type: "tuple";
+}>;
+declare function isFunctionSchema(s: SpecSchema): s is Extract<SpecSchemaComposite, {
+	type: "function";
+}>;
+declare function isAnyOfSchema(s: SpecSchema): s is Extract<SpecSchemaCombinator, {
+	anyOf: SpecSchema[];
+}>;
+declare function isAllOfSchema(s: SpecSchema): s is Extract<SpecSchemaCombinator, {
+	allOf: SpecSchema[];
+}>;
+declare function isOneOfSchema(s: SpecSchema): s is Extract<SpecSchemaCombinator, {
+	oneOf: SpecSchema[];
+}>;
+declare function isRefSchema(s: SpecSchema): s is SpecSchemaRef;
+/**
+* Resolve a $ref schema to the referenced SpecType.
+* Returns null if the ref can't be resolved.
+*/
+declare function resolveRef(schema: SpecSchema, spec: OpenPkg): SpecType | null;
+/**
+* Flatten nested anyOf into a single array of schemas.
+* Non-anyOf schemas return as a single-element array.
+*/
+declare function flattenAnyOf(schema: SpecSchema): SpecSchema[];
+/**
+* Get a human-readable type string from a schema.
+*/
+declare function getSchemaType(schema: SpecSchema): string;
 type BreakingSeverity = "high" | "medium" | "low";
 interface CategorizedBreaking {
 	id: string;
@@ -510,8 +580,10 @@ declare function recommendSemverBump(diff: SpecDiff): SemverRecommendation;
 */
 declare function calculateNextVersion(currentVersion: string, bump: SemverBump): string;
 declare function normalize(spec: OpenPkg): OpenPkg;
+/** Concrete schema versions (excludes 'latest' alias) */
+type ConcreteSchemaVersion = "0.1.0" | "0.2.0" | "0.3.0" | "0.4.0";
 /** Supported schema versions */
-type SchemaVersion = "0.1.0" | "0.2.0" | "0.3.0" | "0.4.0" | "latest";
+type SchemaVersion = ConcreteSchemaVersion | "latest";
 type SpecError = {
 	instancePath: string;
 	message: string;
@@ -550,4 +622,4 @@ declare function assertSpec(spec: unknown, version?: SchemaVersion): asserts spe
 * @returns Array of validation errors (empty if valid)
 */
 declare function getValidationErrors(spec: unknown, version?: SchemaVersion): SpecError[];
-export { validateSpec, recommendSemverBump, normalize, getValidationErrors, getAvailableVersions, diffSpec, dereference, categorizeBreakingChanges, calculateNextVersion, assertSpec, SpecVisibility, SpecTypePredicate, SpecTypeParameter, SpecTypeKind, SpecTypeAliasKind, SpecType, SpecThrows, SpecTagParam, SpecTag, SpecSource, SpecSkippedExport, SpecSignatureReturn, SpecSignatureParameter, SpecSignature, SpecSchemaRef, SpecSchemaPrimitive, SpecSchemaGeneric, SpecSchemaFallback, SpecSchemaComposite, SpecSchemaCombinator, SpecSchema, SpecPresentationMeta, SpecMember, SpecMappedType, SpecInheritedMember, SpecGenerationMeta, SpecGenerationInfo, SpecExtractionMode, SpecExtractionLimitation, SpecExtensions, SpecExtension, SpecExportKind, SpecExport, SpecExampleLanguage, SpecExample, SpecDiff, SpecDecorator, SpecConditionalType, SemverRecommendation, SemverBump, SCHEMA_VERSION, SCHEMA_URL, OpenPkgVersion, OpenPkgMeta, OpenPkg, MemberChangeInfo, JSON_SCHEMA_DRAFT, JSONSchemaExtensions, GenerationIssueSeverity, GenerationIssue, EntryPointDetectionMethod, DiffOptions, CategorizedBreaking, BreakingSeverity };
+export { validateSpec, resolveRef, recommendSemverBump, normalize, isVoidSchema, isTupleSchema, isStringSchema, isRefSchema, isOneOfSchema, isObjectSchema, isNumberSchema, isNullSchema, isNeverSchema, isIntegerSchema, isFunctionSchema, isBooleanSchema, isArraySchema, isAnySchema, isAnyOfSchema, isAllOfSchema, getValidationErrors, getSchemaType, getAvailableVersions, flattenAnyOf, diffSpec, dereference, categorizeBreakingChanges, calculateNextVersion, assertSpec, SpecVisibility, SpecTypePredicate, SpecTypeParameter, SpecTypeKind, SpecTypeAliasKind, SpecType, SpecThrows, SpecTagParam, SpecTag, SpecSource, SpecSkippedExport, SpecSignatureReturn, SpecSignatureParameter, SpecSignature, SpecSchemaRef, SpecSchemaPrimitive, SpecSchemaGeneric, SpecSchemaFallback, SpecSchemaComposite, SpecSchemaCombinator, SpecSchema, SpecPresentationMeta, SpecMember, SpecMappedType, SpecInheritedMember, SpecGenerationMeta, SpecGenerationInfo, SpecExtractionMode, SpecExtractionLimitation, SpecExtensions, SpecExtension, SpecExportKind, SpecExport, SpecExampleLanguage, SpecExample, SpecDiff, SpecDecorator, SpecConditionalType, SemverRecommendation, SemverBump, SCHEMA_VERSION, SCHEMA_URL, OpenPkgVersion, OpenPkgMeta, OpenPkg, MemberChangeInfo, KIND_SLUGS, KIND_LABELS, JSON_SCHEMA_DRAFT, JSONSchemaExtensions, GenerationIssueSeverity, GenerationIssue, EntryPointDetectionMethod, DisplayKind, DiffOptions, DISPLAY_KIND_ORDER, CategorizedBreaking, BreakingSeverity };

package/dist/index.js

@@ -2,9 +2,41 @@
 var SCHEMA_VERSION = "0.4.0";
 var SCHEMA_URL = "https://unpkg.com/@openpkg-ts/spec/schemas/v0.4.0/openpkg.schema.json";
 var JSON_SCHEMA_DRAFT = "https://json-schema.org/draft/2020-12/schema";
+var DISPLAY_KIND_ORDER = [
+  "function",
+  "class",
+  "interface",
+  "type",
+  "enum",
+  "variable"
+];
+var KIND_LABELS = {
+  function: "Functions",
+  class: "Classes",
+  interface: "Interfaces",
+  type: "Types",
+  enum: "Enums",
+  variable: "Variables",
+  namespace: "Namespaces",
+  module: "Modules",
+  reference: "References",
+  external: "External"
+};
+var KIND_SLUGS = {
+  function: "functions",
+  class: "classes",
+  interface: "interfaces",
+  type: "types",
+  enum: "enums",
+  variable: "variables",
+  namespace: "namespaces",
+  module: "modules",
+  reference: "references",
+  external: "externals"
+};
 // src/deref.ts
 function dereference(spec) {
-  const clone = JSON.parse(JSON.stringify(spec));
+  const clone = structuredClone(spec);
   const typeLookup = buildTypeLookup(clone.types);
   const visit = (value, seen) => {
     if (Array.isArray(value)) {
@@ -63,9 +95,106 @@ function resolveTypeRef(id, lookup, seen) {
   }
   seen.add(id);
   if (target.schema) {
-    return JSON.parse(JSON.stringify(target.schema));
+    return structuredClone(target.schema);
+  }
+  return structuredClone(target);
+}
+// src/guards.ts
+function isObj(s) {
+  return typeof s === "object" && s !== null;
+}
+function hasType(s, t) {
+  return isObj(s) && "type" in s && s.type === t;
+}
+function isStringSchema(s) {
+  return hasType(s, "string");
+}
+function isNumberSchema(s) {
+  return hasType(s, "number");
+}
+function isBooleanSchema(s) {
+  return hasType(s, "boolean");
+}
+function isIntegerSchema(s) {
+  return hasType(s, "integer");
+}
+function isNullSchema(s) {
+  return hasType(s, "null");
+}
+function isVoidSchema(s) {
+  return hasType(s, "void");
+}
+function isNeverSchema(s) {
+  return hasType(s, "never");
+}
+function isAnySchema(s) {
+  return hasType(s, "any");
+}
+function isObjectSchema(s) {
+  return hasType(s, "object");
+}
+function isArraySchema(s) {
+  return hasType(s, "array");
+}
+function isTupleSchema(s) {
+  return hasType(s, "tuple");
+}
+function isFunctionSchema(s) {
+  return hasType(s, "function");
+}
+function isAnyOfSchema(s) {
+  return isObj(s) && "anyOf" in s && Array.isArray(s.anyOf);
+}
+function isAllOfSchema(s) {
+  return isObj(s) && "allOf" in s && Array.isArray(s.allOf);
+}
+function isOneOfSchema(s) {
+  return isObj(s) && "oneOf" in s && Array.isArray(s.oneOf);
+}
+function isRefSchema(s) {
+  return isObj(s) && "$ref" in s && typeof s.$ref === "string";
+}
+// src/schema-utils.ts
+function resolveRef(schema, spec) {
+  if (!isRefSchema(schema))
+    return null;
+  const prefix = "#/types/";
+  if (!schema.$ref.startsWith(prefix))
+    return null;
+  const name = schema.$ref.slice(prefix.length);
+  return spec.types?.find((t) => t.name === name) ?? null;
+}
+function flattenAnyOf(schema) {
+  if (!isAnyOfSchema(schema))
+    return [schema];
+  const result = [];
+  for (const s of schema.anyOf) {
+    if (isAnyOfSchema(s)) {
+      result.push(...flattenAnyOf(s));
+    } else {
+      result.push(s);
+    }
   }
-  return JSON.parse(JSON.stringify(target));
+  return result;
+}
+function getSchemaType(schema) {
+  if (typeof schema === "string")
+    return schema;
+  if ("$ref" in schema && typeof schema.$ref === "string") {
+    const ref = schema.$ref;
+    const prefix = "#/types/";
+    return ref.startsWith(prefix) ? ref.slice(prefix.length) : ref;
+  }
+  if ("anyOf" in schema)
+    return "union";
+  if ("allOf" in schema)
+    return "intersection";
+  if ("oneOf" in schema)
+    return "oneOf";
+  if ("type" in schema && typeof schema.type === "string") {
+    return schema.type;
+  }
+  return "unknown";
 }
 // src/diff.ts
 function diffSpec(oldSpec, newSpec, options) {
@@ -281,7 +410,9 @@ function calculateNextVersion(currentVersion, bump) {
   if (!match) {
     return currentVersion;
   }
-  let [, major, minor, patch] = match.map(Number);
+  let major = parseInt(match[1], 10);
+  let minor = parseInt(match[2], 10);
+  let patch = parseInt(match[3], 10);
   switch (bump) {
     case "major":
       major++;
@@ -332,30 +463,9 @@ function normalizeGeneration(gen) {
   }
   return gen;
 }
-function normalizeExport(item) {
-  const clone = structuredClone(item);
-  for (const field of arrayFieldsByExport) {
-    if (!Array.isArray(clone[field])) {
-      clone[field] = [];
-    }
-  }
-  if (clone.type !== undefined && typeof clone.type !== "string") {
-    if (!clone.schema) {
-      clone.schema = clone.type;
-    }
-    delete clone.type;
-  }
-  if (clone.tags && clone.tags.length > 0) {
-    clone.tags = clone.tags.map(normalizeTag);
-  }
-  if (clone.members && clone.members.length > 0) {
-    clone.members = clone.members.map(normalizeMember);
-  }
-  return clone;
-}
-function normalizeType(item) {
+function normalizeEntry(item, arrayFields) {
   const clone = structuredClone(item);
-  for (const field of arrayFieldsByType) {
+  for (const field of arrayFields) {
     if (!Array.isArray(clone[field])) {
       clone[field] = [];
     }
@@ -374,6 +484,8 @@ function normalizeType(item) {
   }
   return clone;
 }
+var normalizeExport = (item) => normalizeEntry(item, arrayFieldsByExport);
+var normalizeType = (item) => normalizeEntry(item, arrayFieldsByType);
 function normalizeTag(tag) {
   const result = {
     name: tag.name,
@@ -2575,10 +2687,29 @@ function getValidationErrors(spec, version = "latest") {
 }
 export {
   validateSpec,
+  resolveRef,
   recommendSemverBump,
   normalize,
+  isVoidSchema,
+  isTupleSchema,
+  isStringSchema,
+  isRefSchema,
+  isOneOfSchema,
+  isObjectSchema,
+  isNumberSchema,
+  isNullSchema,
+  isNeverSchema,
+  isIntegerSchema,
+  isFunctionSchema,
+  isBooleanSchema,
+  isArraySchema,
+  isAnySchema,
+  isAnyOfSchema,
+  isAllOfSchema,
   getValidationErrors,
+  getSchemaType,
   getAvailableVersions,
+  flattenAnyOf,
   diffSpec,
   dereference,
   categorizeBreakingChanges,
@@ -2586,5 +2717,8 @@ export {
   assertSpec,
   SCHEMA_VERSION,
   SCHEMA_URL,
-  JSON_SCHEMA_DRAFT
+  KIND_SLUGS,
+  KIND_LABELS,
+  JSON_SCHEMA_DRAFT,
+  DISPLAY_KIND_ORDER
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpkg-ts/spec",
-  "version": "0.34.1",
+  "version": "0.37.0",
   "description": "Shared schema, validation, and diff utilities for OpenPkg specs",
   "keywords": [
     "openpkg",