@openpkg-ts/spec 0.9.0 → 0.10.0

package/dist/index.d.ts

@@ -303,6 +303,15 @@ type SpecGenerationInfo = {
 		resolvedExternalTypes: boolean;
 		/** Maximum type depth used for nested type resolution */
 		maxTypeDepth?: number;
+		/** Schema extraction method and metadata */
+		schemaExtraction?: {
+			/** How schemas were extracted */
+			method: "standard-json-schema" | "static-ast" | "hybrid";
+			/** Number of schemas extracted via Standard Schema runtime */
+			runtimeCount?: number;
+			/** Vendors detected (e.g., ['zod', 'valibot']) */
+			vendors?: string[];
+		};
 	};
 	/** Environment information during generation */
 	environment: {
@@ -392,6 +401,63 @@ declare function diffSpec(oldSpec: SpecWithDocs, newSpec: SpecWithDocs): SpecDif
 * @returns Categorized breaking changes sorted by severity (high first)
 */
 declare function categorizeBreakingChanges(breaking: string[], oldSpec: SpecWithDocs, newSpec: SpecWithDocs, memberChanges?: MemberChangeInfo[]): CategorizedBreaking[];
+/**
+* Semver version bump type.
+*/
+type SemverBump = "major" | "minor" | "patch" | "none";
+/**
+* Semver recommendation result.
+*/
+interface SemverRecommendation {
+	/** Recommended version bump */
+	bump: SemverBump;
+	/** Reason for the recommendation */
+	reason: string;
+	/** Count of breaking changes */
+	breakingCount: number;
+	/** Count of non-breaking additions */
+	additionCount: number;
+	/** Whether only docs changed */
+	docsOnlyChanges: boolean;
+}
+/**
+* Recommend a semver version bump based on spec diff.
+*
+* - MAJOR: Any breaking changes (removals or signature changes)
+* - MINOR: New exports/types added (non-breaking)
+* - PATCH: Documentation-only changes
+* - NONE: No changes
+*
+* @param diff - The spec diff result
+* @returns Semver recommendation with reason
+*
+* @example
+* ```typescript
+* import { diffSpec, recommendSemverBump } from '@openpkg-ts/spec';
+*
+* const diff = diffSpec(oldSpec, newSpec);
+* const recommendation = recommendSemverBump(diff);
+*
+* console.log(`Recommended: ${recommendation.bump}`);
+* console.log(`Reason: ${recommendation.reason}`);
+* ```
+*/
+declare function recommendSemverBump(diff: SpecDiff): SemverRecommendation;
+/**
+* Calculate the next version number based on current version and recommended bump.
+*
+* @param currentVersion - Current version string (e.g., "1.2.3")
+* @param bump - Recommended bump type
+* @returns Next version string
+*
+* @example
+* ```typescript
+* calculateNextVersion('1.2.3', 'major'); // '2.0.0'
+* calculateNextVersion('1.2.3', 'minor'); // '1.3.0'
+* calculateNextVersion('1.2.3', 'patch'); // '1.2.4'
+* ```
+*/
+declare function calculateNextVersion(currentVersion: string, bump: SemverBump): string;
 declare function normalize(spec: OpenPkg): OpenPkg;
 /** Supported schema versions */
 type SchemaVersion = "0.1.0" | "0.2.0" | "0.3.0" | "latest";
@@ -429,4 +495,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, SpecSchemaRef, SpecSchemaPrimitive, SpecSchemaGeneric, SpecSchemaFallback, SpecSchemaComposite, SpecSchemaCombinator, SpecSchema, SpecRelationType, SpecRelation, SpecMember, SpecMappedType, SpecGenerationInfo, SpecExtension, SpecExportKind, SpecExport, SpecExampleLanguage, SpecExample, SpecDocsMetadata, SpecDocDrift, SpecDiff, SpecDecorator, SpecConditionalType, SCHEMA_VERSION, SCHEMA_URL, OpenPkgVersion, OpenPkgMeta, OpenPkg, MemberChangeInfo, JSON_SCHEMA_DRAFT, GenerationIssueSeverity, GenerationIssue, EntryPointDetectionMethod, DriftType, DriftCategory, DRIFT_CATEGORY_LABELS, DRIFT_CATEGORY_DESCRIPTIONS, DRIFT_CATEGORIES, CategorizedBreaking, BreakingSeverity };
+export { validateSpec, recommendSemverBump, normalize, getValidationErrors, diffSpec, dereference, categorizeBreakingChanges, calculateNextVersion, assertSpec, SpecVisibility, SpecTypeParameter, SpecTypeKind, SpecTypeAliasKind, SpecType, SpecThrows, SpecTag, SpecSource, SpecSignatureReturn, SpecSignatureParameter, SpecSignature, SpecSchemaRef, SpecSchemaPrimitive, SpecSchemaGeneric, SpecSchemaFallback, SpecSchemaComposite, SpecSchemaCombinator, SpecSchema, SpecRelationType, SpecRelation, SpecMember, SpecMappedType, SpecGenerationInfo, SpecExtension, SpecExportKind, SpecExport, SpecExampleLanguage, SpecExample, SpecDocsMetadata, SpecDocDrift, SpecDiff, SpecDecorator, SpecConditionalType, SemverRecommendation, SemverBump, SCHEMA_VERSION, SCHEMA_URL, OpenPkgVersion, OpenPkgMeta, OpenPkg, MemberChangeInfo, JSON_SCHEMA_DRAFT, GenerationIssueSeverity, GenerationIssue, EntryPointDetectionMethod, DriftType, DriftCategory, DRIFT_CATEGORY_LABELS, DRIFT_CATEGORY_DESCRIPTIONS, DRIFT_CATEGORIES, CategorizedBreaking, BreakingSeverity };

package/dist/index.js

@@ -282,6 +282,72 @@ function categorizeBreakingChanges(breaking, oldSpec, newSpec, memberChanges) {
   const severityOrder = { high: 0, medium: 1, low: 2 };
   return categorized.sort((a, b) => severityOrder[a.severity] - severityOrder[b.severity]);
 }
+function recommendSemverBump(diff) {
+  const breakingCount = diff.breaking.length;
+  const additionCount = diff.nonBreaking.length;
+  const docsOnlyCount = diff.docsOnly.length;
+  if (breakingCount > 0) {
+    return {
+      bump: "major",
+      reason: `${breakingCount} breaking change${breakingCount === 1 ? "" : "s"} detected`,
+      breakingCount,
+      additionCount,
+      docsOnlyChanges: false
+    };
+  }
+  if (additionCount > 0) {
+    return {
+      bump: "minor",
+      reason: `${additionCount} new export${additionCount === 1 ? "" : "s"} added`,
+      breakingCount: 0,
+      additionCount,
+      docsOnlyChanges: false
+    };
+  }
+  if (docsOnlyCount > 0) {
+    return {
+      bump: "patch",
+      reason: `${docsOnlyCount} documentation-only change${docsOnlyCount === 1 ? "" : "s"}`,
+      breakingCount: 0,
+      additionCount: 0,
+      docsOnlyChanges: true
+    };
+  }
+  return {
+    bump: "none",
+    reason: "No changes detected",
+    breakingCount: 0,
+    additionCount: 0,
+    docsOnlyChanges: false
+  };
+}
+function calculateNextVersion(currentVersion, bump) {
+  if (bump === "none") {
+    return currentVersion;
+  }
+  const normalized = currentVersion.replace(/^v/, "");
+  const match = normalized.match(/^(\d+)\.(\d+)\.(\d+)/);
+  if (!match) {
+    return currentVersion;
+  }
+  let [, major, minor, patch] = match.map(Number);
+  switch (bump) {
+    case "major":
+      major++;
+      minor = 0;
+      patch = 0;
+      break;
+    case "minor":
+      minor++;
+      patch = 0;
+      break;
+    case "patch":
+      patch++;
+      break;
+  }
+  const prefix = currentVersion.startsWith("v") ? "v" : "";
+  return `${prefix}${major}.${minor}.${patch}`;
+}
 // src/normalize.ts
 var DEFAULT_ECOSYSTEM = "js/ts";
 var arrayFieldsByExport = ["signatures", "members", "examples", "tags"];
@@ -1141,9 +1207,17 @@ var openpkg_schema_default3 = {
         $ref: "#/$defs/typeDef"
       }
     },
-    docs: {
-      $ref: "#/$defs/docsMetadata",
-      description: "Aggregate documentation coverage metadata"
+    examples: {
+      type: "array",
+      description: "Package-level usage examples",
+      items: {
+        $ref: "#/$defs/example"
+      }
+    },
+    extensions: {
+      type: "object",
+      description: "Custom extension data",
+      additionalProperties: true
     },
     generation: {
       $ref: "#/$defs/generationInfo",
@@ -1213,7 +1287,12 @@ var openpkg_schema_default3 = {
         analysis: {
           type: "object",
           description: "Details about the analysis process",
-          required: ["entryPoint", "entryPointSource", "isDeclarationOnly", "resolvedExternalTypes"],
+          required: [
+            "entryPoint",
+            "entryPointSource",
+            "isDeclarationOnly",
+            "resolvedExternalTypes"
+          ],
           properties: {
             entryPoint: {
               type: "string",
@@ -1233,6 +1312,27 @@ var openpkg_schema_default3 = {
             maxTypeDepth: {
               type: "integer",
               description: "Maximum type depth used for nested type resolution"
+            },
+            schemaExtraction: {
+              type: "object",
+              description: "Schema extraction method and metadata",
+              properties: {
+                method: {
+                  type: "string",
+                  description: "How schemas were extracted",
+                  enum: ["standard-json-schema", "static-ast", "hybrid"]
+                },
+                runtimeCount: {
+                  type: "integer",
+                  description: "Number of schemas extracted via Standard Schema runtime"
+                },
+                vendors: {
+                  type: "array",
+                  description: "Vendors detected (e.g., ['zod', 'valibot'])",
+                  items: { type: "string" }
+                }
+              },
+              additionalProperties: false
             }
           },
           additionalProperties: false
@@ -1387,7 +1487,9 @@ var openpkg_schema_default3 = {
             "interface",
             "type",
             "enum",
+            "module",
             "namespace",
+            "reference",
             "external"
           ]
         },
@@ -1416,7 +1518,7 @@ var openpkg_schema_default3 = {
         members: {
           type: "array",
           description: "Class/interface/enum members",
-          items: { type: "object" }
+          items: { $ref: "#/$defs/member" }
         },
         extends: {
           type: "string",
@@ -1437,6 +1539,24 @@ var openpkg_schema_default3 = {
         source: {
           $ref: "#/$defs/sourceLocation"
         },
+        deprecated: {
+          type: "boolean",
+          description: "Whether this export is deprecated"
+        },
+        flags: {
+          type: "object",
+          description: "Export flags (readonly, abstract, etc.)",
+          additionalProperties: true
+        },
+        schema: {
+          $ref: "#/$defs/schema",
+          description: "Inline schema for the export"
+        },
+        typeParameters: {
+          type: "array",
+          description: "Generic type parameters",
+          items: { $ref: "#/$defs/typeParameter" }
+        },
         docs: {
           $ref: "#/$defs/docsMetadata",
           description: "Documentation coverage metadata for this export"
@@ -1526,7 +1646,7 @@ var openpkg_schema_default3 = {
         members: {
           type: "array",
           description: "Members for classes/interfaces/enums",
-          items: { type: "object" }
+          items: { $ref: "#/$defs/member" }
         },
         extends: {
           type: "string",
@@ -1547,6 +1667,10 @@ var openpkg_schema_default3 = {
         source: {
           $ref: "#/$defs/sourceLocation"
         },
+        rawComments: {
+          type: "string",
+          description: "Raw JSDoc/TSDoc comment text"
+        },
         typeAliasKind: {
           $ref: "#/$defs/typeAliasKind",
           description: "Kind of type alias"
@@ -1667,7 +1791,7 @@ var openpkg_schema_default3 = {
     },
     parameter: {
       type: "object",
-      required: ["name", "required"],
+      required: ["name"],
       properties: {
         name: {
           type: "string",
@@ -1710,6 +1834,26 @@ var openpkg_schema_default3 = {
         }
       }
     },
+    schemaType: {
+      type: "string",
+      description: "Explicit type enum aligned with TypeScript type system",
+      enum: [
+        "string",
+        "number",
+        "boolean",
+        "integer",
+        "null",
+        "undefined",
+        "any",
+        "unknown",
+        "never",
+        "void",
+        "array",
+        "tuple",
+        "object",
+        "function"
+      ]
+    },
     schema: {
       description: "Flexible JSON Schema for type representation",
       oneOf: [
@@ -1722,6 +1866,11 @@ var openpkg_schema_default3 = {
             format: { type: "string" },
             enum: { type: "array" },
             items: { $ref: "#/$defs/schema" },
+            prefixedItems: {
+              type: "array",
+              items: { $ref: "#/$defs/schema" },
+              description: "Tuple element schemas (draft-2020-12)"
+            },
             properties: {
               type: "object",
               additionalProperties: { $ref: "#/$defs/schema" }
@@ -1742,14 +1891,13 @@ var openpkg_schema_default3 = {
             description: { type: "string" },
             minItems: { type: "integer" },
             maxItems: { type: "integer" },
-            signatures: { type: "array" }
+            signatures: { type: "array", items: { $ref: "#/$defs/signature" } }
           }
         }
       ]
     },
     sourceLocation: {
       type: "object",
-      required: ["file", "line"],
       properties: {
         file: {
           type: "string",
@@ -1759,6 +1907,10 @@ var openpkg_schema_default3 = {
           type: "integer",
           description: "Line number in source file",
           minimum: 1
+        },
+        url: {
+          type: "string",
+          description: "URL to source (e.g., GitHub permalink)"
         }
       }
     },
@@ -1901,6 +2053,56 @@ var openpkg_schema_default3 = {
         }
       ]
     },
+    visibility: {
+      type: "string",
+      description: "Visibility modifier for class members",
+      enum: ["public", "protected", "private"]
+    },
+    member: {
+      type: "object",
+      description: "Class/interface/enum member definition",
+      properties: {
+        id: {
+          type: "string",
+          description: "Unique identifier for the member"
+        },
+        name: {
+          type: "string",
+          description: "Member name"
+        },
+        kind: {
+          type: "string",
+          description: "Kind of member (e.g., 'property', 'method', 'constructor')"
+        },
+        description: {
+          type: "string",
+          description: "JSDoc/TSDoc description"
+        },
+        visibility: {
+          $ref: "#/$defs/visibility"
+        },
+        tags: {
+          type: "array",
+          items: { $ref: "#/$defs/tag" }
+        },
+        flags: {
+          type: "object",
+          description: "Member flags (static, readonly, abstract, etc.)",
+          additionalProperties: true
+        },
+        schema: {
+          $ref: "#/$defs/schema"
+        },
+        signatures: {
+          type: "array",
+          items: { $ref: "#/$defs/signature" }
+        },
+        decorators: {
+          type: "array",
+          items: { $ref: "#/$defs/decorator" }
+        }
+      }
+    },
     relationType: {
       type: "string",
       description: "Type of relationship between exports",
@@ -1988,11 +2190,13 @@ function getValidationErrors(spec, version = "latest") {
 }
 export {
   validateSpec,
+  recommendSemverBump,
   normalize,
   getValidationErrors,
   diffSpec,
   dereference,
   categorizeBreakingChanges,
+  calculateNextVersion,
   assertSpec,
   SCHEMA_VERSION,
   SCHEMA_URL,

package/package.json

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

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

@@ -62,9 +62,17 @@
         "$ref": "#/$defs/typeDef"
       }
     },
-    "docs": {
-      "$ref": "#/$defs/docsMetadata",
-      "description": "Aggregate documentation coverage metadata"
+    "examples": {
+      "type": "array",
+      "description": "Package-level usage examples",
+      "items": {
+        "$ref": "#/$defs/example"
+      }
+    },
+    "extensions": {
+      "type": "object",
+      "description": "Custom extension data",
+      "additionalProperties": true
     },
     "generation": {
       "$ref": "#/$defs/generationInfo",
@@ -134,7 +142,12 @@
         "analysis": {
           "type": "object",
           "description": "Details about the analysis process",
-          "required": ["entryPoint", "entryPointSource", "isDeclarationOnly", "resolvedExternalTypes"],
+          "required": [
+            "entryPoint",
+            "entryPointSource",
+            "isDeclarationOnly",
+            "resolvedExternalTypes"
+          ],
           "properties": {
             "entryPoint": {
               "type": "string",
@@ -154,6 +167,27 @@
             "maxTypeDepth": {
               "type": "integer",
               "description": "Maximum type depth used for nested type resolution"
+            },
+            "schemaExtraction": {
+              "type": "object",
+              "description": "Schema extraction method and metadata",
+              "properties": {
+                "method": {
+                  "type": "string",
+                  "description": "How schemas were extracted",
+                  "enum": ["standard-json-schema", "static-ast", "hybrid"]
+                },
+                "runtimeCount": {
+                  "type": "integer",
+                  "description": "Number of schemas extracted via Standard Schema runtime"
+                },
+                "vendors": {
+                  "type": "array",
+                  "description": "Vendors detected (e.g., ['zod', 'valibot'])",
+                  "items": { "type": "string" }
+                }
+              },
+              "additionalProperties": false
             }
           },
           "additionalProperties": false
@@ -308,7 +342,9 @@
             "interface",
             "type",
             "enum",
+            "module",
             "namespace",
+            "reference",
             "external"
           ]
         },
@@ -337,7 +373,7 @@
         "members": {
           "type": "array",
           "description": "Class/interface/enum members",
-          "items": { "type": "object" }
+          "items": { "$ref": "#/$defs/member" }
         },
         "extends": {
           "type": "string",
@@ -358,6 +394,24 @@
         "source": {
           "$ref": "#/$defs/sourceLocation"
         },
+        "deprecated": {
+          "type": "boolean",
+          "description": "Whether this export is deprecated"
+        },
+        "flags": {
+          "type": "object",
+          "description": "Export flags (readonly, abstract, etc.)",
+          "additionalProperties": true
+        },
+        "schema": {
+          "$ref": "#/$defs/schema",
+          "description": "Inline schema for the export"
+        },
+        "typeParameters": {
+          "type": "array",
+          "description": "Generic type parameters",
+          "items": { "$ref": "#/$defs/typeParameter" }
+        },
         "docs": {
           "$ref": "#/$defs/docsMetadata",
           "description": "Documentation coverage metadata for this export"
@@ -447,7 +501,7 @@
         "members": {
           "type": "array",
           "description": "Members for classes/interfaces/enums",
-          "items": { "type": "object" }
+          "items": { "$ref": "#/$defs/member" }
         },
         "extends": {
           "type": "string",
@@ -468,6 +522,10 @@
         "source": {
           "$ref": "#/$defs/sourceLocation"
         },
+        "rawComments": {
+          "type": "string",
+          "description": "Raw JSDoc/TSDoc comment text"
+        },
         "typeAliasKind": {
           "$ref": "#/$defs/typeAliasKind",
           "description": "Kind of type alias"
@@ -588,7 +646,7 @@
     },
     "parameter": {
       "type": "object",
-      "required": ["name", "required"],
+      "required": ["name"],
       "properties": {
         "name": {
           "type": "string",
@@ -631,6 +689,26 @@
         }
       }
     },
+    "schemaType": {
+      "type": "string",
+      "description": "Explicit type enum aligned with TypeScript type system",
+      "enum": [
+        "string",
+        "number",
+        "boolean",
+        "integer",
+        "null",
+        "undefined",
+        "any",
+        "unknown",
+        "never",
+        "void",
+        "array",
+        "tuple",
+        "object",
+        "function"
+      ]
+    },
     "schema": {
       "description": "Flexible JSON Schema for type representation",
       "oneOf": [
@@ -643,6 +721,11 @@
             "format": { "type": "string" },
             "enum": { "type": "array" },
             "items": { "$ref": "#/$defs/schema" },
+            "prefixedItems": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/schema" },
+              "description": "Tuple element schemas (draft-2020-12)"
+            },
             "properties": {
               "type": "object",
               "additionalProperties": { "$ref": "#/$defs/schema" }
@@ -663,14 +746,13 @@
             "description": { "type": "string" },
             "minItems": { "type": "integer" },
             "maxItems": { "type": "integer" },
-            "signatures": { "type": "array" }
+            "signatures": { "type": "array", "items": { "$ref": "#/$defs/signature" } }
           }
         }
       ]
     },
     "sourceLocation": {
       "type": "object",
-      "required": ["file", "line"],
       "properties": {
         "file": {
           "type": "string",
@@ -680,6 +762,10 @@
           "type": "integer",
           "description": "Line number in source file",
           "minimum": 1
+        },
+        "url": {
+          "type": "string",
+          "description": "URL to source (e.g., GitHub permalink)"
         }
       }
     },
@@ -822,6 +908,56 @@
         }
       ]
     },
+    "visibility": {
+      "type": "string",
+      "description": "Visibility modifier for class members",
+      "enum": ["public", "protected", "private"]
+    },
+    "member": {
+      "type": "object",
+      "description": "Class/interface/enum member definition",
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Unique identifier for the member"
+        },
+        "name": {
+          "type": "string",
+          "description": "Member name"
+        },
+        "kind": {
+          "type": "string",
+          "description": "Kind of member (e.g., 'property', 'method', 'constructor')"
+        },
+        "description": {
+          "type": "string",
+          "description": "JSDoc/TSDoc description"
+        },
+        "visibility": {
+          "$ref": "#/$defs/visibility"
+        },
+        "tags": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/tag" }
+        },
+        "flags": {
+          "type": "object",
+          "description": "Member flags (static, readonly, abstract, etc.)",
+          "additionalProperties": true
+        },
+        "schema": {
+          "$ref": "#/$defs/schema"
+        },
+        "signatures": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/signature" }
+        },
+        "decorators": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/decorator" }
+        }
+      }
+    },
     "relationType": {
       "type": "string",
       "description": "Type of relationship between exports",