@openpkg-ts/spec 0.6.0 → 0.8.0

package/dist/index.d.ts

@@ -36,20 +36,121 @@ type SpecSource = {
 	line?: number;
 	url?: string;
 };
-type SpecSchema = unknown;
-type SpecExample = Record<string, unknown>;
+type SpecSchemaPrimitive = {
+	type: "string";
+	format?: string;
+	enum?: string[];
+} | {
+	type: "number";
+	enum?: number[];
+} | {
+	type: "boolean";
+	enum?: boolean[];
+} | {
+	type: "integer";
+	format?: string;
+} | {
+	type: "null";
+} | {
+	type: "undefined";
+} | {
+	type: "any";
+} | {
+	type: "unknown";
+} | {
+	type: "never";
+} | {
+	type: "void";
+};
+type SpecSchemaComposite = {
+	type: "array";
+	items?: SpecSchema;
+} | {
+	type: "tuple";
+	items: SpecSchema[];
+	minItems?: number;
+	maxItems?: number;
+} | {
+	type: "object";
+	properties?: Record<string, SpecSchema>;
+	required?: string[];
+	additionalProperties?: boolean | SpecSchema;
+	description?: string;
+} | {
+	type: "function";
+	signatures?: SpecSignature[];
+};
+type SpecSchemaCombinator = {
+	anyOf: SpecSchema[];
+	discriminator?: {
+		propertyName: string;
+	};
+} | {
+	allOf: SpecSchema[];
+} | {
+	oneOf: SpecSchema[];
+};
+type SpecSchemaRef = {
+	$ref: string;
+};
+type SpecSchemaFallback = {
+	type: string;
+	tsType?: string;
+};
+type SpecSchemaGeneric = Record<string, unknown>;
+type SpecSchema = string | SpecSchemaPrimitive | SpecSchemaComposite | SpecSchemaCombinator | SpecSchemaRef | SpecSchemaFallback | SpecSchemaGeneric;
+type SpecExampleLanguage = "ts" | "js" | "tsx" | "jsx" | "shell" | "json";
+type SpecExample = {
+	code: string;
+	title?: string;
+	description?: string;
+	language?: SpecExampleLanguage;
+	runnable?: boolean;
+	expectedOutput?: string;
+	tags?: string[];
+};
+type SpecRelationType = "uses" | "returns" | "implements" | "extends" | "see-also" | "companion";
+type SpecRelation = {
+	type: SpecRelationType;
+	target: string;
+	description?: string;
+};
 type SpecExtension = Record<string, unknown>;
-type SpecDocSignal = "description" | "params" | "returns" | "examples";
+/**
+* All possible drift type identifiers.
+*/
+type DriftType = "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";
 type SpecDocDrift = {
-	type: "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";
+	type: DriftType;
 	target?: string;
 	issue: string;
 	suggestion?: string;
 };
+/**
+* Drift categories group related drift types for progressive disclosure.
+*
+* - `structural`: Signature/type mismatches (mostly auto-fixable via JSDoc)
+* - `semantic`: Metadata/visibility/reference issues
+* - `example`: Code example problems
+*/
+type DriftCategory = "structural" | "semantic" | "example";
+/**
+* Maps each drift type to its category.
+*/
+declare const DRIFT_CATEGORIES: Record<DriftType, DriftCategory>;
+/**
+* Human-readable category labels.
+*/
+declare const DRIFT_CATEGORY_LABELS: Record<DriftCategory, string>;
+/**
+* Category descriptions for help text.
+*/
+declare const DRIFT_CATEGORY_DESCRIPTIONS: Record<DriftCategory, string>;
 type SpecVisibility = "public" | "protected" | "private";
 type SpecDocsMetadata = {
 	coverageScore?: number;
-	missing?: SpecDocSignal[];
+	/** Rule IDs that failed quality checks */
+	missing?: string[];
 	drift?: SpecDocDrift[];
 };
 type SpecTypeParameter = {
@@ -109,8 +210,7 @@ type SpecExport = {
 	type?: string | SpecSchema;
 	schema?: SpecSchema;
 	description?: string;
-	examples?: string[];
-	docs?: SpecDocsMetadata;
+	examples?: (string | SpecExample)[];
 	source?: SpecSource;
 	deprecated?: boolean;
 	flags?: Record<string, unknown>;
@@ -123,6 +223,7 @@ type SpecExport = {
 	decorators?: SpecDecorator[];
 	isAugmentation?: boolean;
 	augmentedModule?: string;
+	related?: SpecRelation[];
 };
 type SpecType = {
 	id: string;
@@ -145,6 +246,7 @@ type SpecType = {
 	typeAliasKind?: SpecTypeAliasKind;
 	conditionalType?: SpecConditionalType;
 	mappedType?: SpecMappedType;
+	related?: SpecRelation[];
 };
 type OpenPkgMeta = {
 	name: string;
@@ -163,13 +265,23 @@ type OpenPkg = {
 	exports: SpecExport[];
 	types?: SpecType[];
 	examples?: SpecExample[];
-	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;
+/**
+* Export with optional docs metadata for diff comparison.
+* Pure OpenPkg specs won't have docs; enriched specs will.
+*/
+type ExportWithDocs = SpecExport & {
+	docs?: SpecDocsMetadata;
+};
+type SpecWithDocs = OpenPkg & {
+	docs?: SpecDocsMetadata;
+	exports: ExportWithDocs[];
+};
 type BreakingSeverity = "high" | "medium" | "low";
 interface CategorizedBreaking {
 	id: string;
@@ -198,7 +310,12 @@ type SpecDiff = {
 	driftIntroduced: number;
 	driftResolved: number;
 };
-declare function diffSpec(oldSpec: OpenPkg, newSpec: OpenPkg): SpecDiff;
+/**
+* Compare two OpenPkg specs and compute differences.
+* If specs are enriched (have docs metadata), coverage changes are tracked.
+* For pure structural specs, coverage fields will be 0.
+*/
+declare function diffSpec(oldSpec: SpecWithDocs, newSpec: SpecWithDocs): SpecDiff;
 /**
 * Categorize breaking changes by severity
 *
@@ -208,7 +325,7 @@ declare function diffSpec(oldSpec: OpenPkg, newSpec: OpenPkg): SpecDiff;
 * @param memberChanges - Optional member-level changes for classes
 * @returns Categorized breaking changes sorted by severity (high first)
 */
-declare function categorizeBreakingChanges(breaking: string[], oldSpec: OpenPkg, newSpec: OpenPkg, memberChanges?: MemberChangeInfo[]): CategorizedBreaking[];
+declare function categorizeBreakingChanges(breaking: string[], oldSpec: SpecWithDocs, newSpec: SpecWithDocs, memberChanges?: MemberChangeInfo[]): CategorizedBreaking[];
 declare function normalize(spec: OpenPkg): OpenPkg;
 /** Supported schema versions */
 type SchemaVersion = "0.1.0" | "0.2.0" | "0.3.0" | "latest";
@@ -246,4 +363,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, SpecTypeAliasKind, SpecType, SpecThrows, SpecTag, SpecSource, SpecSignatureReturn, SpecSignatureParameter, SpecSignature, SpecSchema, SpecMember, SpecMappedType, SpecExtension, SpecExportKind, SpecExport, SpecExample, SpecDocsMetadata, SpecDocSignal, SpecDocDrift, SpecDiff, SpecDecorator, SpecConditionalType, SCHEMA_VERSION, SCHEMA_URL, OpenPkgVersion, OpenPkgMeta, OpenPkg, MemberChangeInfo, JSON_SCHEMA_DRAFT, CategorizedBreaking, BreakingSeverity };
+export { validateSpec, normalize, getValidationErrors, diffSpec, dereference, categorizeBreakingChanges, assertSpec, SpecVisibility, SpecTypeParameter, SpecTypeKind, SpecTypeAliasKind, SpecType, SpecThrows, SpecTag, SpecSource, SpecSignatureReturn, SpecSignatureParameter, SpecSignature, SpecSchemaRef, SpecSchemaPrimitive, SpecSchemaGeneric, SpecSchemaFallback, SpecSchemaComposite, SpecSchemaCombinator, SpecSchema, SpecRelationType, SpecRelation, SpecMember, SpecMappedType, SpecExtension, SpecExportKind, SpecExport, SpecExampleLanguage, SpecExample, SpecDocsMetadata, SpecDocDrift, SpecDiff, SpecDecorator, SpecConditionalType, SCHEMA_VERSION, SCHEMA_URL, OpenPkgVersion, OpenPkgMeta, OpenPkg, MemberChangeInfo, JSON_SCHEMA_DRAFT, DriftType, DriftCategory, DRIFT_CATEGORY_LABELS, DRIFT_CATEGORY_DESCRIPTIONS, DRIFT_CATEGORIES, CategorizedBreaking, BreakingSeverity };

package/dist/index.js

@@ -318,6 +318,33 @@ function normalizeType(item) {
   }
   return clone;
 }
+// src/types.ts
+var DRIFT_CATEGORIES = {
+  "param-mismatch": "structural",
+  "param-type-mismatch": "structural",
+  "return-type-mismatch": "structural",
+  "optionality-mismatch": "structural",
+  "generic-constraint-mismatch": "structural",
+  "property-type-drift": "structural",
+  "async-mismatch": "structural",
+  "deprecated-mismatch": "semantic",
+  "visibility-mismatch": "semantic",
+  "broken-link": "semantic",
+  "example-drift": "example",
+  "example-syntax-error": "example",
+  "example-runtime-error": "example",
+  "example-assertion-failed": "example"
+};
+var DRIFT_CATEGORY_LABELS = {
+  structural: "Signature mismatches",
+  semantic: "Metadata issues",
+  example: "Example problems"
+};
+var DRIFT_CATEGORY_DESCRIPTIONS = {
+  structural: "JSDoc types or parameters don't match the actual code signature",
+  semantic: "Deprecation, visibility, or reference issues",
+  example: "@example code has errors or doesn't work correctly"
+};
 // src/validate.ts
 import Ajv from "ajv/dist/2020.js";
 import addFormats from "ajv-formats";
@@ -1244,7 +1271,7 @@ var openpkg_schema_default3 = {
           type: "array",
           description: "Usage examples from documentation",
           items: {
-            type: "string"
+            $ref: "#/$defs/example"
           }
         },
         signatures: {
@@ -1310,6 +1337,13 @@ var openpkg_schema_default3 = {
         augmentedModule: {
           type: "string",
           description: "The module being augmented (e.g., 'express')"
+        },
+        related: {
+          type: "array",
+          description: "Related exports/types (auto-detected + @see tags)",
+          items: {
+            $ref: "#/$defs/relation"
+          }
         }
       }
     },
@@ -1396,6 +1430,13 @@ var openpkg_schema_default3 = {
         mappedType: {
           $ref: "#/$defs/mappedType",
           description: "Structural details for mapped types"
+        },
+        related: {
+          type: "array",
+          description: "Related exports/types (auto-detected + @see tags)",
+          items: {
+            $ref: "#/$defs/relation"
+          }
         }
       }
     },
@@ -1542,28 +1583,39 @@ var openpkg_schema_default3 = {
       }
     },
     schema: {
-      anyOf: [
-        {
-          type: "boolean"
-        },
+      description: "Flexible JSON Schema for type representation",
+      oneOf: [
+        { type: "string" },
+        { 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
+            type: { type: "string" },
+            format: { type: "string" },
+            enum: { type: "array" },
+            items: { $ref: "#/$defs/schema" },
+            properties: {
+              type: "object",
+              additionalProperties: { $ref: "#/$defs/schema" }
+            },
+            required: { type: "array", items: { type: "string" } },
+            additionalProperties: {
+              oneOf: [{ type: "boolean" }, { $ref: "#/$defs/schema" }]
+            },
+            anyOf: { type: "array", items: { $ref: "#/$defs/schema" } },
+            allOf: { type: "array", items: { $ref: "#/$defs/schema" } },
+            oneOf: { type: "array", items: { $ref: "#/$defs/schema" } },
+            $ref: { type: "string" },
+            discriminator: {
+              type: "object",
+              properties: { propertyName: { type: "string" } }
+            },
+            tsType: { type: "string" },
+            description: { type: "string" },
+            minItems: { type: "integer" },
+            maxItems: { type: "integer" },
+            signatures: { type: "array" }
+          }
         }
       ]
     },
@@ -1674,6 +1726,76 @@ var openpkg_schema_default3 = {
         }
       },
       additionalProperties: false
+    },
+    exampleLanguage: {
+      type: "string",
+      description: "Programming language for an example",
+      enum: ["ts", "js", "tsx", "jsx", "shell", "json"]
+    },
+    example: {
+      description: "Usage example - can be a simple string or structured object",
+      oneOf: [
+        { type: "string" },
+        {
+          type: "object",
+          required: ["code"],
+          properties: {
+            code: {
+              type: "string",
+              description: "The example code"
+            },
+            title: {
+              type: "string",
+              description: "Short title for the example"
+            },
+            description: {
+              type: "string",
+              description: "Longer description of what the example demonstrates"
+            },
+            language: {
+              $ref: "#/$defs/exampleLanguage"
+            },
+            runnable: {
+              type: "boolean",
+              description: "Whether this example can be run/tested automatically"
+            },
+            expectedOutput: {
+              type: "string",
+              description: "Expected output when the example is run"
+            },
+            tags: {
+              type: "array",
+              description: "Categorization tags (e.g., 'basic', 'advanced', 'error-handling')",
+              items: { type: "string" }
+            }
+          },
+          additionalProperties: false
+        }
+      ]
+    },
+    relationType: {
+      type: "string",
+      description: "Type of relationship between exports",
+      enum: ["uses", "returns", "implements", "extends", "see-also", "companion"]
+    },
+    relation: {
+      type: "object",
+      description: "Relationship to another export or type",
+      required: ["type", "target"],
+      properties: {
+        type: {
+          $ref: "#/$defs/relationType"
+        },
+        target: {
+          type: "string",
+          description: "Target export/type ID or reference"
+        },
+        description: {
+          type: "string",
+          description: "Optional description of the relationship"
+        }
+      },
+      additionalProperties: false
     }
   }
 };
@@ -1746,5 +1868,8 @@ export {
   assertSpec,
   SCHEMA_VERSION,
   SCHEMA_URL,
-  JSON_SCHEMA_DRAFT
+  JSON_SCHEMA_DRAFT,
+  DRIFT_CATEGORY_LABELS,
+  DRIFT_CATEGORY_DESCRIPTIONS,
+  DRIFT_CATEGORIES
 };

package/package.json

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

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

@@ -192,7 +192,7 @@
           "type": "array",
           "description": "Usage examples from documentation",
           "items": {
-            "type": "string"
+            "$ref": "#/$defs/example"
           }
         },
         "signatures": {
@@ -258,6 +258,13 @@
         "augmentedModule": {
           "type": "string",
           "description": "The module being augmented (e.g., 'express')"
+        },
+        "related": {
+          "type": "array",
+          "description": "Related exports/types (auto-detected + @see tags)",
+          "items": {
+            "$ref": "#/$defs/relation"
+          }
         }
       }
     },
@@ -344,6 +351,13 @@
         "mappedType": {
           "$ref": "#/$defs/mappedType",
           "description": "Structural details for mapped types"
+        },
+        "related": {
+          "type": "array",
+          "description": "Related exports/types (auto-detected + @see tags)",
+          "items": {
+            "$ref": "#/$defs/relation"
+          }
         }
       }
     },
@@ -490,28 +504,39 @@
       }
     },
     "schema": {
-      "anyOf": [
-        {
-          "type": "boolean"
-        },
+      "description": "Flexible JSON Schema for type representation",
+      "oneOf": [
+        { "type": "string" },
+        { "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
+            "type": { "type": "string" },
+            "format": { "type": "string" },
+            "enum": { "type": "array" },
+            "items": { "$ref": "#/$defs/schema" },
+            "properties": {
+              "type": "object",
+              "additionalProperties": { "$ref": "#/$defs/schema" }
+            },
+            "required": { "type": "array", "items": { "type": "string" } },
+            "additionalProperties": {
+              "oneOf": [{ "type": "boolean" }, { "$ref": "#/$defs/schema" }]
+            },
+            "anyOf": { "type": "array", "items": { "$ref": "#/$defs/schema" } },
+            "allOf": { "type": "array", "items": { "$ref": "#/$defs/schema" } },
+            "oneOf": { "type": "array", "items": { "$ref": "#/$defs/schema" } },
+            "$ref": { "type": "string" },
+            "discriminator": {
+              "type": "object",
+              "properties": { "propertyName": { "type": "string" } }
+            },
+            "tsType": { "type": "string" },
+            "description": { "type": "string" },
+            "minItems": { "type": "integer" },
+            "maxItems": { "type": "integer" },
+            "signatures": { "type": "array" }
+          }
         }
       ]
     },
@@ -622,6 +647,76 @@
         }
       },
       "additionalProperties": false
+    },
+    "exampleLanguage": {
+      "type": "string",
+      "description": "Programming language for an example",
+      "enum": ["ts", "js", "tsx", "jsx", "shell", "json"]
+    },
+    "example": {
+      "description": "Usage example - can be a simple string or structured object",
+      "oneOf": [
+        { "type": "string" },
+        {
+          "type": "object",
+          "required": ["code"],
+          "properties": {
+            "code": {
+              "type": "string",
+              "description": "The example code"
+            },
+            "title": {
+              "type": "string",
+              "description": "Short title for the example"
+            },
+            "description": {
+              "type": "string",
+              "description": "Longer description of what the example demonstrates"
+            },
+            "language": {
+              "$ref": "#/$defs/exampleLanguage"
+            },
+            "runnable": {
+              "type": "boolean",
+              "description": "Whether this example can be run/tested automatically"
+            },
+            "expectedOutput": {
+              "type": "string",
+              "description": "Expected output when the example is run"
+            },
+            "tags": {
+              "type": "array",
+              "description": "Categorization tags (e.g., 'basic', 'advanced', 'error-handling')",
+              "items": { "type": "string" }
+            }
+          },
+          "additionalProperties": false
+        }
+      ]
+    },
+    "relationType": {
+      "type": "string",
+      "description": "Type of relationship between exports",
+      "enum": ["uses", "returns", "implements", "extends", "see-also", "companion"]
+    },
+    "relation": {
+      "type": "object",
+      "description": "Relationship to another export or type",
+      "required": ["type", "target"],
+      "properties": {
+        "type": {
+          "$ref": "#/$defs/relationType"
+        },
+        "target": {
+          "type": "string",
+          "description": "Target export/type ID or reference"
+        },
+        "description": {
+          "type": "string",
+          "description": "Optional description of the relationship"
+        }
+      },
+      "additionalProperties": false
     }
   }
 }