@openpkg-ts/spec 0.35.1 → 0.41.0

package/README.md

@@ -1,6 +1,6 @@
 # @openpkg-ts/spec
 
-OpenPkg specification types, validation, normalization, and diffing utilities.
+Types, validation, normalization, and diffing for [OpenPkg](https://openpkg.dev) documents. Part of [openpkg-ts](https://github.com/ryanwaits/openpkg-ts), the TypeScript reference implementation of the OpenPkg standard.
 
 ## Install
 

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 */
@@ -412,7 +414,10 @@ type OpenPkg = {
 	generation?: SpecGenerationMeta | SpecGenerationInfo;
 };
 declare const SCHEMA_VERSION: OpenPkgVersion;
-declare const SCHEMA_URL = "https://unpkg.com/@openpkg-ts/spec/schemas/v0.4.0/openpkg.schema.json";
+/** Canonical schema URL — hosted by the OpenPkg standard, independent of any implementation's packaging. */
+declare const SCHEMA_URL = "https://openpkg.dev/schemas/v0.4.0/openpkg.schema.json";
+/** Mirror of the canonical schema, served from the published @openpkg-ts/spec npm package. */
+declare const SCHEMA_URL_MIRROR = "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">;
@@ -517,7 +522,67 @@ declare function recommendSemverBump(diff: SpecDiff): SemverRecommendation;
 * ```
 */
 declare function calculateNextVersion(currentVersion: string, bump: SemverBump): string;
+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;
 declare function normalize(spec: OpenPkg): OpenPkg;
+/**
+* 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;
 /** Concrete schema versions (excludes 'latest' alias) */
 type ConcreteSchemaVersion = "0.1.0" | "0.2.0" | "0.3.0" | "0.4.0";
 /** Supported schema versions */
@@ -560,4 +625,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, KIND_SLUGS, KIND_LABELS, JSON_SCHEMA_DRAFT, JSONSchemaExtensions, GenerationIssueSeverity, GenerationIssue, EntryPointDetectionMethod, DisplayKind, DiffOptions, DISPLAY_KIND_ORDER, 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_MIRROR, 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

@@ -1,6 +1,7 @@
 // src/constants.ts
 var SCHEMA_VERSION = "0.4.0";
-var SCHEMA_URL = "https://unpkg.com/@openpkg-ts/spec/schemas/v0.4.0/openpkg.schema.json";
+var SCHEMA_URL = "https://openpkg.dev/schemas/v0.4.0/openpkg.schema.json";
+var SCHEMA_URL_MIRROR = "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",
@@ -333,6 +334,61 @@ function calculateNextVersion(currentVersion, bump) {
   const prefix = currentVersion.startsWith("v") ? "v" : "";
   return `${prefix}${major}.${minor}.${patch}`;
 }
+// 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/normalize.ts
 var DEFAULT_ECOSYSTEM = "js/ts";
 var arrayFieldsByExport = ["signatures", "members", "examples", "tags"];
@@ -406,13 +462,55 @@ function normalizeMember(member) {
   }
   return clone;
 }
+// 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 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/validate.ts
 import Ajv from "ajv/dist/2020.js";
 import addFormats from "ajv-formats";
 // schemas/v0.1.0/openpkg.schema.json
 var openpkg_schema_default = {
   $schema: "https://json-schema.org/draft/2020-12/schema",
-  $id: "https://unpkg.com/@openpkg-ts/spec/schemas/v0.1.0/openpkg.schema.json",
+  $id: "https://openpkg.dev/schemas/v0.1.0/openpkg.schema.json",
   title: "OpenPkg Specification",
   description: "Schema for OpenPkg specification files",
   type: "object",
@@ -714,7 +812,7 @@ var openpkg_schema_default = {
 // schemas/v0.2.0/openpkg.schema.json
 var openpkg_schema_default2 = {
   $schema: "https://json-schema.org/draft/2020-12/schema",
-  $id: "https://unpkg.com/@openpkg-ts/spec/schemas/v0.2.0/openpkg.schema.json",
+  $id: "https://openpkg.dev/schemas/v0.2.0/openpkg.schema.json",
   title: "OpenPkg Specification",
   description: "Schema for OpenPkg specification files",
   type: "object",
@@ -1140,7 +1238,7 @@ var openpkg_schema_default2 = {
 // schemas/v0.3.0/openpkg.schema.json
 var openpkg_schema_default3 = {
   $schema: "https://json-schema.org/draft/2020-12/schema",
-  $id: "https://unpkg.com/@openpkg-ts/spec/schemas/v0.3.0/openpkg.schema.json",
+  $id: "https://openpkg.dev/schemas/v0.3.0/openpkg.schema.json",
   title: "OpenPkg Specification",
   description: "Schema for OpenPkg specification files",
   type: "object",
@@ -2137,7 +2235,7 @@ var openpkg_schema_default3 = {
 // schemas/v0.4.0/openpkg.schema.json
 var openpkg_schema_default4 = {
   $schema: "https://json-schema.org/draft/2020-12/schema",
-  $id: "https://unpkg.com/@openpkg-ts/spec/schemas/v0.4.0/openpkg.schema.json",
+  $id: "https://openpkg.dev/schemas/v0.4.0/openpkg.schema.json",
   title: "OpenPkg Specification v0.4.0",
   description: "Minimal tool-agnostic TypeScript export representation",
   type: "object",
@@ -2590,16 +2688,36 @@ 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,
   calculateNextVersion,
   assertSpec,
   SCHEMA_VERSION,
+  SCHEMA_URL_MIRROR,
   SCHEMA_URL,
   KIND_SLUGS,
   KIND_LABELS,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpkg-ts/spec",
-  "version": "0.35.1",
+  "version": "0.41.0",
   "description": "Shared schema, validation, and diff utilities for OpenPkg specs",
   "keywords": [
     "openpkg",
@@ -36,7 +36,8 @@
     "test": "bun test",
     "lint": "biome check src/",
     "lint:fix": "biome check --write src/",
-    "format": "biome format --write src/"
+    "format": "biome format --write src/",
+    "typecheck": "tsc --noEmit -p ."
   },
   "dependencies": {
     "ajv": "^8.17.1",

package/schemas/v0.1.0/openpkg.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://unpkg.com/@openpkg-ts/spec/schemas/v0.1.0/openpkg.schema.json",
+  "$id": "https://openpkg.dev/schemas/v0.1.0/openpkg.schema.json",
   "title": "OpenPkg Specification",
   "description": "Schema for OpenPkg specification files",
   "type": "object",

package/schemas/v0.2.0/openpkg.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://unpkg.com/@openpkg-ts/spec/schemas/v0.2.0/openpkg.schema.json",
+  "$id": "https://openpkg.dev/schemas/v0.2.0/openpkg.schema.json",
   "title": "OpenPkg Specification",
   "description": "Schema for OpenPkg specification files",
   "type": "object",

package/schemas/v0.3.0/openpkg.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://unpkg.com/@openpkg-ts/spec/schemas/v0.3.0/openpkg.schema.json",
+  "$id": "https://openpkg.dev/schemas/v0.3.0/openpkg.schema.json",
   "title": "OpenPkg Specification",
   "description": "Schema for OpenPkg specification files",
   "type": "object",

package/schemas/v0.4.0/openpkg.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://unpkg.com/@openpkg-ts/spec/schemas/v0.4.0/openpkg.schema.json",
+  "$id": "https://openpkg.dev/schemas/v0.4.0/openpkg.schema.json",
   "title": "OpenPkg Specification v0.4.0",
   "description": "Minimal tool-agnostic TypeScript export representation",
   "type": "object",