@openpkg-ts/spec 0.37.0 → 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

@@ -414,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">;
@@ -425,66 +428,6 @@ 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;
@@ -579,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 */
@@ -622,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, 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 };
+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",
@@ -99,103 +100,6 @@ function resolveTypeRef(id, lookup, seen) {
   }
   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 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) {
   const { includeDocsOnly = true, kinds } = options ?? {};
@@ -430,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"];
@@ -503,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",
@@ -811,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",
@@ -1237,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",
@@ -2234,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",
@@ -2716,6 +2717,7 @@ export {
   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.37.0",
+  "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",