@openpkg-ts/spec 0.6.0 → 0.7.0

package/dist/index.d.ts

@@ -36,8 +36,85 @@ 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";
 type SpecDocDrift = {
@@ -109,7 +186,7 @@ type SpecExport = {
 	type?: string | SpecSchema;
 	schema?: SpecSchema;
 	description?: string;
-	examples?: string[];
+	examples?: (string | SpecExample)[];
 	docs?: SpecDocsMetadata;
 	source?: SpecSource;
 	deprecated?: boolean;
@@ -123,6 +200,7 @@ type SpecExport = {
 	decorators?: SpecDecorator[];
 	isAugmentation?: boolean;
 	augmentedModule?: string;
+	related?: SpecRelation[];
 };
 type SpecType = {
 	id: string;
@@ -145,6 +223,7 @@ type SpecType = {
 	typeAliasKind?: SpecTypeAliasKind;
 	conditionalType?: SpecConditionalType;
 	mappedType?: SpecMappedType;
+	related?: SpecRelation[];
 };
 type OpenPkgMeta = {
 	name: string;
@@ -246,4 +325,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, SpecDocSignal, SpecDocDrift, SpecDiff, SpecDecorator, SpecConditionalType, SCHEMA_VERSION, SCHEMA_URL, OpenPkgVersion, OpenPkgMeta, OpenPkg, MemberChangeInfo, JSON_SCHEMA_DRAFT, CategorizedBreaking, BreakingSeverity };

package/dist/index.js

@@ -1244,7 +1244,7 @@ var openpkg_schema_default3 = {
           type: "array",
           description: "Usage examples from documentation",
           items: {
-            type: "string"
+            $ref: "#/$defs/example"
           }
         },
         signatures: {
@@ -1310,6 +1310,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 +1403,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 +1556,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 +1699,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
     }
   }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpkg-ts/spec",
-  "version": "0.6.0",
+  "version": "0.7.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
     }
   }
 }