@openpkg-ts/spec 0.4.1 → 0.5.0

package/dist/index.d.ts

@@ -1,9 +1,12 @@
-declare const SCHEMA_VERSION = "0.2.0";
-declare const SCHEMA_URL = "https://unpkg.com/@openpkg-ts/spec/schemas/v0.2.0/openpkg.schema.json";
-declare const JSON_SCHEMA_DRAFT = "https://json-schema.org/draft/2020-12/schema";
 type SpecTag = {
 	name: string;
 	text: string;
+	paramName?: string;
+	typeAnnotation?: string;
+	reference?: string;
+	language?: string;
+	version?: string;
+	reason?: string;
 };
 type SpecSource = {
 	file?: string;
@@ -36,6 +39,8 @@ type SpecSignatureParameter = {
 	required?: boolean;
 	description?: string;
 	schema: SpecSchema;
+	default?: unknown;
+	rest?: boolean;
 };
 type SpecSignatureReturn = {
 	schema: SpecSchema;
@@ -47,6 +52,8 @@ type SpecSignature = {
 	returns?: SpecSignatureReturn;
 	description?: string;
 	typeParameters?: SpecTypeParameter[];
+	overloadIndex?: number;
+	isImplementation?: boolean;
 };
 type SpecMember = {
 	id?: string;
@@ -112,9 +119,11 @@ type OpenPkgMeta = {
 	repository?: string;
 	ecosystem?: string;
 };
+/** Supported OpenPkg spec versions */
+type OpenPkgVersion = "0.2.0" | "0.3.0";
 type OpenPkg = {
 	$schema?: string;
-	openpkg: "0.2.0";
+	openpkg: OpenPkgVersion;
 	meta: OpenPkgMeta;
 	exports: SpecExport[];
 	types?: SpecType[];
@@ -122,6 +131,9 @@ type OpenPkg = {
 	docs?: SpecDocsMetadata;
 	extensions?: SpecExtension;
 };
+declare const SCHEMA_VERSION: OpenPkgVersion;
+declare const SCHEMA_URL = "https://unpkg.com/@openpkg-ts/spec/schemas/v0.3.0/openpkg.schema.json";
+declare const JSON_SCHEMA_DRAFT = "https://json-schema.org/draft/2020-12/schema";
 declare function dereference(spec: OpenPkg): OpenPkg;
 type BreakingSeverity = "high" | "medium" | "low";
 interface CategorizedBreaking {
@@ -164,7 +176,7 @@ 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 SchemaVersion = "0.1.0" | "0.2.0" | "0.3.0" | "latest";
 type SpecError = {
 	instancePath: string;
 	message: string;
@@ -199,4 +211,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, 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 };
+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, OpenPkgVersion, OpenPkgMeta, OpenPkg, MemberChangeInfo, JSON_SCHEMA_DRAFT, CategorizedBreaking, BreakingSeverity };

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) {
@@ -321,8 +321,310 @@ function normalizeType(item) {
 // src/validate.ts
 import Ajv from "ajv/dist/2020.js";
 import addFormats from "ajv-formats";
-// schemas/v0.2.0/openpkg.schema.json
+// 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_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",
@@ -747,10 +1049,10 @@ var openpkg_schema_default = {
     }
   }
 };
-// schemas/v0.1.0/openpkg.schema.json
-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.1.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",
@@ -765,7 +1067,7 @@ var openpkg_schema_default2 = {
       type: "string",
       description: "OpenPkg specification version",
       pattern: "^[0-9]+\\.[0-9]+\\.[0-9]+$",
-      const: "0.1.0"
+      const: "0.3.0"
     },
     meta: {
       type: "object",
@@ -811,9 +1113,83 @@ var openpkg_schema_default2 = {
       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"],
@@ -834,6 +1210,10 @@ var openpkg_schema_default2 = {
           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"
@@ -845,7 +1225,16 @@ var openpkg_schema_default2 = {
         kind: {
           type: "string",
           description: "Kind of export",
-          enum: ["function", "class", "variable", "interface", "type", "enum"]
+          enum: [
+            "function",
+            "class",
+            "variable",
+            "interface",
+            "type",
+            "enum",
+            "namespace",
+            "external"
+          ]
         },
         description: {
           type: "string",
@@ -874,21 +1263,28 @@ var openpkg_schema_default2 = {
           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
+            $ref: "#/$defs/tag"
           }
         },
         source: {
           $ref: "#/$defs/sourceLocation"
+        },
+        docs: {
+          $ref: "#/$defs/docsMetadata",
+          description: "Documentation coverage metadata for this export"
         }
       }
     },
@@ -912,6 +1308,10 @@ var openpkg_schema_default2 = {
           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"
@@ -923,7 +1323,7 @@ var openpkg_schema_default2 = {
         kind: {
           type: "string",
           description: "Kind of type definition",
-          enum: ["interface", "type", "enum", "class"]
+          enum: ["interface", "type", "enum", "class", "external"]
         },
         description: {
           type: "string",
@@ -941,17 +1341,20 @@ var openpkg_schema_default2 = {
           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
+            $ref: "#/$defs/tag"
           }
         },
         source: {
@@ -959,6 +1362,46 @@ var openpkg_schema_default2 = {
         }
       }
     },
+    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: {
@@ -974,6 +1417,40 @@ var openpkg_schema_default2 = {
         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"
         }
       }
     },
@@ -991,6 +1468,17 @@ var openpkg_schema_default2 = {
         },
         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)"
         }
       }
     },
@@ -1051,10 +1539,11 @@ var openpkg_schema_default2 = {
 };
 
 // src/validate.ts
-var LATEST_VERSION = "0.2.0";
+var LATEST_VERSION = "0.3.0";
 var schemas = {
-  "0.1.0": openpkg_schema_default2,
-  "0.2.0": openpkg_schema_default
+  "0.1.0": openpkg_schema_default,
+  "0.2.0": openpkg_schema_default2,
+  "0.3.0": openpkg_schema_default3
 };
 var ajv = new Ajv({
   strict: false,

package/package.json

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

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

@@ -0,0 +1,487 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$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",
+  "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.3.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": {
+            "$ref": "#/$defs/tag"
+          }
+        },
+        "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": {
+            "$ref": "#/$defs/tag"
+          }
+        },
+        "source": {
+          "$ref": "#/$defs/sourceLocation"
+        }
+      }
+    },
+    "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": {
+        "parameters": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/parameter"
+          }
+        },
+        "returns": {
+          "$ref": "#/$defs/returns"
+        },
+        "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"
+        }
+      }
+    },
+    "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
+        }
+      }
+    }
+  }
+}