@openpkg-ts/spec 0.4.0 → 0.4.1

package/dist/index.d.ts

@@ -163,17 +163,40 @@ declare function diffSpec(oldSpec: OpenPkg, newSpec: OpenPkg): SpecDiff;
 */
 declare function categorizeBreakingChanges(breaking: string[], oldSpec: OpenPkg, newSpec: OpenPkg, memberChanges?: MemberChangeInfo[]): CategorizedBreaking[];
 declare function normalize(spec: OpenPkg): OpenPkg;
+/** Supported schema versions */
+type SchemaVersion = "0.1.0" | "0.2.0" | "latest";
 type SpecError = {
 	instancePath: string;
 	message: string;
 	keyword: string;
 };
-declare function validateSpec(spec: unknown): {
+/**
+* Validate a spec against a specific schema version.
+*
+* @param spec - The spec object to validate
+* @param version - Schema version to validate against (default: 'latest')
+* @returns Validation result
+*/
+declare function validateSpec(spec: unknown, version?: SchemaVersion): {
 	ok: true;
 } | {
 	ok: false;
 	errors: SpecError[];
 };
-declare function assertSpec(spec: unknown): asserts spec is OpenPkg;
-declare function getValidationErrors(spec: unknown): SpecError[];
+/**
+* Assert that a value is a valid OpenPkg spec.
+* Throws an error with details if validation fails.
+*
+* @param spec - The value to validate
+* @param version - Schema version to validate against (default: 'latest')
+*/
+declare function assertSpec(spec: unknown, version?: SchemaVersion): asserts spec is OpenPkg;
+/**
+* Get validation errors for a spec.
+*
+* @param spec - The spec to validate
+* @param version - Schema version to validate against (default: 'latest')
+* @returns Array of validation errors (empty if valid)
+*/
+declare function getValidationErrors(spec: unknown, version?: SchemaVersion): SpecError[];
 export { validateSpec, normalize, getValidationErrors, diffSpec, dereference, categorizeBreakingChanges, assertSpec, SpecVisibility, SpecTypeParameter, SpecTypeKind, SpecType, SpecTag, SpecSource, SpecSignatureReturn, SpecSignatureParameter, SpecSignature, SpecSchema, SpecMember, SpecExtension, SpecExportKind, SpecExport, SpecExample, SpecDocsMetadata, SpecDocSignal, SpecDocDrift, SpecDiff, SCHEMA_VERSION, SCHEMA_URL, OpenPkgMeta, OpenPkg, MemberChangeInfo, JSON_SCHEMA_DRAFT, CategorizedBreaking, BreakingSeverity };

package/dist/index.js

@@ -159,7 +159,21 @@ function toMap(items) {
   }
   return map;
 }
-var DOC_KEYS = new Set(["description", "examples", "tags", "source", "rawComments"]);
+var DOC_KEYS = new Set([
+  "description",
+  "examples",
+  "tags",
+  "rawComments",
+  "source",
+  "docs",
+  "displayName",
+  "slug",
+  "importPath",
+  "category",
+  "coverageScore",
+  "missing",
+  "drift"
+]);
 function isDocOnlyChange(a, b) {
   const structuralA = normalizeForComparison(removeDocFields(a));
   const structuralB = normalizeForComparison(removeDocFields(b));
@@ -483,7 +497,16 @@ var openpkg_schema_default = {
         kind: {
           type: "string",
           description: "Kind of export",
-          enum: ["function", "class", "variable", "interface", "type", "enum", "namespace", "external"]
+          enum: [
+            "function",
+            "class",
+            "variable",
+            "interface",
+            "type",
+            "enum",
+            "namespace",
+            "external"
+          ]
         },
         description: {
           type: "string",
@@ -724,8 +747,315 @@ var openpkg_schema_default = {
     }
   }
 };
+// schemas/v0.1.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.1.0/openpkg.schema.json",
+  title: "OpenPkg Specification",
+  description: "Schema for OpenPkg specification files",
+  type: "object",
+  required: ["openpkg", "meta", "exports"],
+  properties: {
+    $schema: {
+      type: "string",
+      description: "Reference to the OpenPkg schema version",
+      pattern: "^(https://raw\\.githubusercontent\\.com/ryanwaits/openpkg/main/schemas/v[0-9]+\\.[0-9]+\\.[0-9]+/openpkg\\.schema\\.json|https://unpkg\\.com/@openpkg-ts/spec/schemas/v[0-9]+\\.[0-9]+\\.[0-9]+/openpkg\\.schema\\.json)$"
+    },
+    openpkg: {
+      type: "string",
+      description: "OpenPkg specification version",
+      pattern: "^[0-9]+\\.[0-9]+\\.[0-9]+$",
+      const: "0.1.0"
+    },
+    meta: {
+      type: "object",
+      description: "Package metadata",
+      required: ["name"],
+      properties: {
+        name: {
+          type: "string",
+          description: "Package name"
+        },
+        version: {
+          type: "string",
+          description: "Package version"
+        },
+        description: {
+          type: "string",
+          description: "Package description"
+        },
+        license: {
+          type: "string",
+          description: "Package license"
+        },
+        repository: {
+          type: "string",
+          description: "Repository URL"
+        },
+        ecosystem: {
+          type: "string",
+          description: "Package ecosystem"
+        }
+      }
+    },
+    exports: {
+      type: "array",
+      description: "List of exported items",
+      items: {
+        $ref: "#/$defs/export"
+      }
+    },
+    types: {
+      type: "array",
+      description: "List of type definitions",
+      items: {
+        $ref: "#/$defs/typeDef"
+      }
+    }
+  },
+  $defs: {
+    export: {
+      type: "object",
+      required: ["id", "name", "kind"],
+      properties: {
+        id: {
+          type: "string",
+          description: "Unique identifier for the export"
+        },
+        name: {
+          type: "string",
+          description: "Export name"
+        },
+        slug: {
+          type: "string",
+          description: "Stable slug for linking"
+        },
+        displayName: {
+          type: "string",
+          description: "UI-friendly label"
+        },
+        category: {
+          type: "string",
+          description: "Grouping hint for navigation"
+        },
+        importPath: {
+          type: "string",
+          description: "Recommended import path"
+        },
+        kind: {
+          type: "string",
+          description: "Kind of export",
+          enum: ["function", "class", "variable", "interface", "type", "enum"]
+        },
+        description: {
+          type: "string",
+          description: "JSDoc/TSDoc description"
+        },
+        examples: {
+          type: "array",
+          description: "Usage examples from documentation",
+          items: {
+            type: "string"
+          }
+        },
+        signatures: {
+          type: "array",
+          description: "Function/method signatures",
+          items: {
+            $ref: "#/$defs/signature"
+          }
+        },
+        type: {
+          description: "Type reference or inline schema for variables",
+          oneOf: [{ type: "string" }, { $ref: "#/$defs/schema" }]
+        },
+        members: {
+          type: "array",
+          description: "Class/interface/enum members",
+          items: { type: "object" }
+        },
+        tags: {
+          type: "array",
+          description: "JSDoc/TSDoc tags",
+          items: {
+            type: "object",
+            required: ["name", "text"],
+            properties: {
+              name: { type: "string" },
+              text: { type: "string" }
+            },
+            additionalProperties: false
+          }
+        },
+        source: {
+          $ref: "#/$defs/sourceLocation"
+        }
+      }
+    },
+    typeDef: {
+      type: "object",
+      required: ["id", "name", "kind"],
+      properties: {
+        id: {
+          type: "string",
+          description: "Unique identifier for the type"
+        },
+        name: {
+          type: "string",
+          description: "Type name"
+        },
+        slug: {
+          type: "string",
+          description: "Stable slug for linking"
+        },
+        displayName: {
+          type: "string",
+          description: "UI-friendly label"
+        },
+        category: {
+          type: "string",
+          description: "Grouping hint for navigation"
+        },
+        importPath: {
+          type: "string",
+          description: "Recommended import path"
+        },
+        kind: {
+          type: "string",
+          description: "Kind of type definition",
+          enum: ["interface", "type", "enum", "class"]
+        },
+        description: {
+          type: "string",
+          description: "JSDoc/TSDoc description"
+        },
+        schema: {
+          $ref: "#/$defs/schema"
+        },
+        type: {
+          type: "string",
+          description: "Type expression for type aliases"
+        },
+        members: {
+          type: "array",
+          description: "Members for classes/interfaces/enums",
+          items: { type: "object" }
+        },
+        tags: {
+          type: "array",
+          description: "JSDoc/TSDoc tags",
+          items: {
+            type: "object",
+            required: ["name", "text"],
+            properties: {
+              name: { type: "string" },
+              text: { type: "string" }
+            },
+            additionalProperties: false
+          }
+        },
+        source: {
+          $ref: "#/$defs/sourceLocation"
+        }
+      }
+    },
+    signature: {
+      type: "object",
+      properties: {
+        parameters: {
+          type: "array",
+          items: {
+            $ref: "#/$defs/parameter"
+          }
+        },
+        returns: {
+          $ref: "#/$defs/returns"
+        },
+        description: {
+          type: "string",
+          description: "Signature-level description"
+        }
+      }
+    },
+    parameter: {
+      type: "object",
+      required: ["name", "required"],
+      properties: {
+        name: {
+          type: "string",
+          description: "Parameter name"
+        },
+        required: {
+          type: "boolean",
+          description: "Whether the parameter is required"
+        },
+        schema: {
+          $ref: "#/$defs/schema"
+        }
+      }
+    },
+    returns: {
+      type: "object",
+      properties: {
+        schema: {
+          $ref: "#/$defs/schema"
+        },
+        description: {
+          type: "string",
+          description: "Return value description"
+        }
+      }
+    },
+    schema: {
+      anyOf: [
+        {
+          type: "boolean"
+        },
+        {
+          type: "object",
+          properties: {
+            $ref: {
+              type: "string",
+              description: "Reference to another type",
+              pattern: "^#/types/[A-Za-z0-9_.-]+$"
+            }
+          },
+          required: ["$ref"],
+          additionalProperties: false
+        },
+        {
+          type: "object",
+          not: {
+            required: ["$ref"]
+          },
+          additionalProperties: true
+        }
+      ]
+    },
+    sourceLocation: {
+      type: "object",
+      required: ["file", "line"],
+      properties: {
+        file: {
+          type: "string",
+          description: "Source file path"
+        },
+        line: {
+          type: "integer",
+          description: "Line number in source file",
+          minimum: 1
+        }
+      }
+    }
+  }
+};
 
 // src/validate.ts
+var LATEST_VERSION = "0.2.0";
+var schemas = {
+  "0.1.0": openpkg_schema_default2,
+  "0.2.0": openpkg_schema_default
+};
 var ajv = new Ajv({
   strict: false,
   allErrors: true,
@@ -733,8 +1063,23 @@ var ajv = new Ajv({
   $data: true
 });
 addFormats(ajv);
-var validate = ajv.compile(openpkg_schema_default);
-function validateSpec(spec) {
+var validatorCache = new Map;
+function getValidator(version = "latest") {
+  const resolvedVersion = version === "latest" ? LATEST_VERSION : version;
+  let validator = validatorCache.get(resolvedVersion);
+  if (validator) {
+    return validator;
+  }
+  const schema = schemas[resolvedVersion];
+  if (!schema) {
+    throw new Error(`Unknown schema version: ${resolvedVersion}. Available: ${Object.keys(schemas).join(", ")}`);
+  }
+  validator = ajv.compile(schema);
+  validatorCache.set(resolvedVersion, validator);
+  return validator;
+}
+function validateSpec(spec, version = "latest") {
+  const validate = getValidator(version);
   const ok = validate(spec);
   if (ok) {
     return { ok: true };
@@ -749,8 +1094,8 @@ function validateSpec(spec) {
     errors
   };
 }
-function assertSpec(spec) {
-  const result = validateSpec(spec);
+function assertSpec(spec, version = "latest") {
+  const result = validateSpec(spec, version);
   if (!result.ok) {
     const details = result.errors.map((error) => `- ${error.instancePath || "/"} ${error.message}`).join(`
 `);
@@ -758,8 +1103,8 @@ function assertSpec(spec) {
 ${details}`);
   }
 }
-function getValidationErrors(spec) {
-  const result = validateSpec(spec);
+function getValidationErrors(spec, version = "latest") {
+  const result = validateSpec(spec, version);
   return result.ok ? [] : result.errors;
 }
 export {

package/package.json

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

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

@@ -173,7 +173,16 @@
         "kind": {
           "type": "string",
           "description": "Kind of export",
-          "enum": ["function", "class", "variable", "interface", "type", "enum", "namespace", "external"]
+          "enum": [
+            "function",
+            "class",
+            "variable",
+            "interface",
+            "type",
+            "enum",
+            "namespace",
+            "external"
+          ]
         },
         "description": {
           "type": "string",