@openpkg-ts/spec 0.4.0 → 0.5.0

package/dist/index.js

@@ -1,6 +1,6 @@
 // src/constants.ts
-var SCHEMA_VERSION = "0.2.0";
-var SCHEMA_URL = "https://unpkg.com/@openpkg-ts/spec/schemas/v0.2.0/openpkg.schema.json";
+var SCHEMA_VERSION = "0.3.0";
+var SCHEMA_URL = "https://unpkg.com/@openpkg-ts/spec/schemas/v0.3.0/openpkg.schema.json";
 var JSON_SCHEMA_DRAFT = "https://json-schema.org/draft/2020-12/schema";
 // src/deref.ts
 function dereference(spec) {
@@ -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));
@@ -307,10 +321,738 @@ function normalizeType(item) {
 // 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",
+  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
+        }
+      }
+    }
+  }
+};
 // schemas/v0.2.0/openpkg.schema.json
-var openpkg_schema_default = {
+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",
+  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.2.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"
+      }
+    },
+    docs: {
+      $ref: "#/$defs/docsMetadata",
+      description: "Aggregate documentation coverage metadata"
+    }
+  },
+  $defs: {
+    docSignal: {
+      type: "string",
+      enum: ["description", "params", "returns", "examples"]
+    },
+    docDrift: {
+      type: "object",
+      required: ["type", "issue"],
+      properties: {
+        type: {
+          type: "string",
+          enum: [
+            "param-mismatch",
+            "param-type-mismatch",
+            "return-type-mismatch",
+            "generic-constraint-mismatch",
+            "optionality-mismatch",
+            "deprecated-mismatch",
+            "visibility-mismatch",
+            "async-mismatch",
+            "property-type-drift",
+            "example-drift",
+            "example-syntax-error",
+            "example-runtime-error",
+            "example-assertion-failed",
+            "broken-link"
+          ]
+        },
+        target: {
+          type: "string",
+          description: "Relevant identifier (e.g., parameter name)"
+        },
+        issue: {
+          type: "string",
+          description: "Human-friendly drift explanation"
+        },
+        suggestion: {
+          type: "string",
+          description: "Optional remediation hint"
+        }
+      },
+      additionalProperties: false
+    },
+    docsMetadata: {
+      type: "object",
+      description: "Documentation coverage metadata",
+      additionalProperties: false,
+      properties: {
+        coverageScore: {
+          type: "number",
+          minimum: 0,
+          maximum: 100,
+          description: "Documentation coverage value from 0-100."
+        },
+        missing: {
+          type: "array",
+          description: "Doc components missing for this entity",
+          items: {
+            $ref: "#/$defs/docSignal"
+          },
+          uniqueItems: true
+        },
+        drift: {
+          type: "array",
+          description: "Detected documentation drift signals",
+          items: {
+            $ref: "#/$defs/docDrift"
+          }
+        }
+      }
+    },
+    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"
+        },
+        alias: {
+          type: "string",
+          description: "Export alias if re-exported with a different name (id uses alias, name uses original)"
+        },
+        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",
+            "namespace",
+            "external"
+          ]
+        },
+        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" }
+        },
+        extends: {
+          type: "string",
+          description: "Base class or interface that this class/interface extends"
+        },
+        implements: {
+          type: "array",
+          description: "Interfaces implemented by this class",
+          items: { type: "string" }
+        },
+        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"
+        },
+        docs: {
+          $ref: "#/$defs/docsMetadata",
+          description: "Documentation coverage metadata for this export"
+        }
+      }
+    },
+    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"
+        },
+        alias: {
+          type: "string",
+          description: "Export alias if re-exported with a different name (id uses alias, name uses original)"
+        },
+        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", "external"]
+        },
+        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" }
+        },
+        extends: {
+          type: "string",
+          description: "Base class or interface that this class/interface extends"
+        },
+        implements: {
+          type: "array",
+          description: "Interfaces implemented by this class",
+          items: { type: "string" }
+        },
+        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"
+        },
+        description: {
+          type: "string",
+          description: "Parameter description"
+        },
+        default: {
+          description: "Default value for the parameter"
+        },
+        rest: {
+          type: "boolean",
+          description: "Whether this is a rest parameter (...args)"
+        }
+      }
+    },
+    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
+        }
+      }
+    }
+  }
+};
+// 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.2.0/openpkg.schema.json",
+  $id: "https://unpkg.com/@openpkg-ts/spec/schemas/v0.3.0/openpkg.schema.json",
   title: "OpenPkg Specification",
   description: "Schema for OpenPkg specification files",
   type: "object",
@@ -325,7 +1067,7 @@ var openpkg_schema_default = {
       type: "string",
       description: "OpenPkg specification version",
       pattern: "^[0-9]+\\.[0-9]+\\.[0-9]+$",
-      const: "0.2.0"
+      const: "0.3.0"
     },
     meta: {
       type: "object",
@@ -483,7 +1225,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",
@@ -525,13 +1276,7 @@ var openpkg_schema_default = {
           type: "array",
           description: "JSDoc/TSDoc tags",
           items: {
-            type: "object",
-            required: ["name", "text"],
-            properties: {
-              name: { type: "string" },
-              text: { type: "string" }
-            },
-            additionalProperties: false
+            $ref: "#/$defs/tag"
           }
         },
         source: {
@@ -609,13 +1354,7 @@ var openpkg_schema_default = {
           type: "array",
           description: "JSDoc/TSDoc tags",
           items: {
-            type: "object",
-            required: ["name", "text"],
-            properties: {
-              name: { type: "string" },
-              text: { type: "string" }
-            },
-            additionalProperties: false
+            $ref: "#/$defs/tag"
           }
         },
         source: {
@@ -623,6 +1362,46 @@ var openpkg_schema_default = {
         }
       }
     },
+    tag: {
+      type: "object",
+      description: "JSDoc/TSDoc tag with optional structured fields",
+      required: ["name", "text"],
+      properties: {
+        name: {
+          type: "string",
+          description: "Tag name (e.g., 'param', 'returns', 'deprecated')"
+        },
+        text: {
+          type: "string",
+          description: "Full tag text content"
+        },
+        paramName: {
+          type: "string",
+          description: "For @param tags: the parameter name"
+        },
+        typeAnnotation: {
+          type: "string",
+          description: "For @param/@returns: type annotation if present"
+        },
+        reference: {
+          type: "string",
+          description: "For @see/@link: resolved URL or symbol reference"
+        },
+        language: {
+          type: "string",
+          description: "For @example: code language hint (e.g., 'typescript', 'json')"
+        },
+        version: {
+          type: "string",
+          description: "For @since/@version: semver value"
+        },
+        reason: {
+          type: "string",
+          description: "For @deprecated: migration path or deprecation reason"
+        }
+      },
+      additionalProperties: true
+    },
     signature: {
       type: "object",
       properties: {
@@ -638,6 +1417,40 @@ var openpkg_schema_default = {
         description: {
           type: "string",
           description: "Signature-level description"
+        },
+        typeParameters: {
+          type: "array",
+          description: "Generic type parameters for this signature",
+          items: {
+            $ref: "#/$defs/typeParameter"
+          }
+        },
+        overloadIndex: {
+          type: "integer",
+          minimum: 0,
+          description: "Index of this overload (0-based), undefined for single signatures"
+        },
+        isImplementation: {
+          type: "boolean",
+          description: "True if this is the implementation signature (not user-callable)"
+        }
+      }
+    },
+    typeParameter: {
+      type: "object",
+      required: ["name"],
+      properties: {
+        name: {
+          type: "string",
+          description: "Type parameter name (e.g., 'T', 'K')"
+        },
+        constraint: {
+          type: "string",
+          description: "Type constraint (e.g., 'extends string')"
+        },
+        default: {
+          type: "string",
+          description: "Default type value"
         }
       }
     },
@@ -726,6 +1539,12 @@ var openpkg_schema_default = {
 };
 
 // src/validate.ts
+var LATEST_VERSION = "0.3.0";
+var schemas = {
+  "0.1.0": openpkg_schema_default,
+  "0.2.0": openpkg_schema_default2,
+  "0.3.0": openpkg_schema_default3
+};
 var ajv = new Ajv({
   strict: false,
   allErrors: true,
@@ -733,8 +1552,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 +1583,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 +1592,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 {