@openpkg-ts/spec 0.8.0 → 0.10.0

package/dist/index.d.ts

@@ -256,6 +256,79 @@ type OpenPkgMeta = {
 	repository?: string;
 	ecosystem?: string;
 };
+/**
+* Method used to detect the entry point for analysis.
+*/
+type EntryPointDetectionMethod = "types" | "exports" | "main" | "module" | "fallback" | "explicit" | "llm";
+/**
+* Severity level for issues encountered during spec generation.
+*/
+type GenerationIssueSeverity = "error" | "warning" | "info";
+/**
+* An issue encountered during spec generation.
+*/
+type GenerationIssue = {
+	/** Machine-readable issue code */
+	code: string;
+	/** Human-readable issue message */
+	message: string;
+	/** Severity level */
+	severity: GenerationIssueSeverity;
+	/** Suggested resolution */
+	suggestion?: string;
+};
+/**
+* Metadata about how a spec was generated.
+* Provides transparency about the analysis process and any limitations.
+*/
+type SpecGenerationInfo = {
+	/** ISO 8601 timestamp of when the spec was generated */
+	timestamp: string;
+	/** Information about the tool that generated the spec */
+	generator: {
+		/** Tool name (e.g., '@doccov/cli', '@doccov/api') */
+		name: string;
+		/** Tool version */
+		version: string;
+	};
+	/** Details about the analysis process */
+	analysis: {
+		/** Entry point file that was analyzed (relative path) */
+		entryPoint: string;
+		/** How the entry point was detected */
+		entryPointSource: EntryPointDetectionMethod;
+		/** Whether this was a declaration-only analysis (.d.ts file) */
+		isDeclarationOnly: boolean;
+		/** Whether external types from node_modules were resolved */
+		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: {
+		/** Detected package manager */
+		packageManager?: string;
+		/** Whether node_modules was available for type resolution */
+		hasNodeModules: boolean;
+		/** Whether this is a monorepo */
+		isMonorepo?: boolean;
+		/** Target package name (for monorepos) */
+		targetPackage?: string;
+	};
+	/** Issues encountered during generation */
+	issues: GenerationIssue[];
+	/** Whether the result came from cache */
+	fromCache?: boolean;
+};
 /** Supported OpenPkg spec versions */
 type OpenPkgVersion = "0.2.0" | "0.3.0";
 type OpenPkg = {
@@ -266,6 +339,8 @@ type OpenPkg = {
 	types?: SpecType[];
 	examples?: SpecExample[];
 	extensions?: SpecExtension;
+	/** Required metadata about how this spec was generated */
+	generation: SpecGenerationInfo;
 };
 declare const SCHEMA_VERSION: OpenPkgVersion;
 declare const SCHEMA_URL = "https://unpkg.com/@openpkg-ts/spec/schemas/v0.3.0/openpkg.schema.json";
@@ -326,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";
@@ -363,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, 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 };
+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"];
@@ -1083,7 +1149,7 @@ var openpkg_schema_default3 = {
   title: "OpenPkg Specification",
   description: "Schema for OpenPkg specification files",
   type: "object",
-  required: ["openpkg", "meta", "exports"],
+  required: ["openpkg", "meta", "exports", "generation"],
   properties: {
     $schema: {
       type: "string",
@@ -1141,12 +1207,174 @@ 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",
+      description: "Required metadata about how this spec was generated"
     }
   },
   $defs: {
+    entryPointDetectionMethod: {
+      type: "string",
+      description: "Method used to detect the entry point for analysis",
+      enum: ["types", "exports", "main", "module", "fallback", "explicit", "llm"]
+    },
+    generationIssueSeverity: {
+      type: "string",
+      description: "Severity level for issues encountered during spec generation",
+      enum: ["error", "warning", "info"]
+    },
+    generationIssue: {
+      type: "object",
+      description: "An issue encountered during spec generation",
+      required: ["code", "message", "severity"],
+      properties: {
+        code: {
+          type: "string",
+          description: "Machine-readable issue code"
+        },
+        message: {
+          type: "string",
+          description: "Human-readable issue message"
+        },
+        severity: {
+          $ref: "#/$defs/generationIssueSeverity"
+        },
+        suggestion: {
+          type: "string",
+          description: "Suggested resolution"
+        }
+      },
+      additionalProperties: false
+    },
+    generationInfo: {
+      type: "object",
+      description: "Metadata about how the spec was generated",
+      required: ["timestamp", "generator", "analysis", "environment", "issues"],
+      properties: {
+        timestamp: {
+          type: "string",
+          format: "date-time",
+          description: "ISO 8601 timestamp of when the spec was generated"
+        },
+        generator: {
+          type: "object",
+          description: "Information about the tool that generated the spec",
+          required: ["name", "version"],
+          properties: {
+            name: {
+              type: "string",
+              description: "Tool name (e.g., '@doccov/cli', '@doccov/api')"
+            },
+            version: {
+              type: "string",
+              description: "Tool version"
+            }
+          },
+          additionalProperties: false
+        },
+        analysis: {
+          type: "object",
+          description: "Details about the analysis process",
+          required: [
+            "entryPoint",
+            "entryPointSource",
+            "isDeclarationOnly",
+            "resolvedExternalTypes"
+          ],
+          properties: {
+            entryPoint: {
+              type: "string",
+              description: "Entry point file that was analyzed (relative path)"
+            },
+            entryPointSource: {
+              $ref: "#/$defs/entryPointDetectionMethod"
+            },
+            isDeclarationOnly: {
+              type: "boolean",
+              description: "Whether this was a declaration-only analysis (.d.ts file)"
+            },
+            resolvedExternalTypes: {
+              type: "boolean",
+              description: "Whether external types from node_modules were resolved"
+            },
+            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
+        },
+        environment: {
+          type: "object",
+          description: "Environment information during generation",
+          required: ["hasNodeModules"],
+          properties: {
+            packageManager: {
+              type: "string",
+              description: "Detected package manager"
+            },
+            hasNodeModules: {
+              type: "boolean",
+              description: "Whether node_modules was available for type resolution"
+            },
+            isMonorepo: {
+              type: "boolean",
+              description: "Whether this is a monorepo"
+            },
+            targetPackage: {
+              type: "string",
+              description: "Target package name (for monorepos)"
+            }
+          },
+          additionalProperties: false
+        },
+        issues: {
+          type: "array",
+          description: "Issues encountered during generation",
+          items: {
+            $ref: "#/$defs/generationIssue"
+          }
+        },
+        fromCache: {
+          type: "boolean",
+          description: "Whether the result came from cache"
+        }
+      },
+      additionalProperties: false
+    },
     docSignal: {
       type: "string",
       enum: ["description", "params", "returns", "examples"]
@@ -1259,7 +1487,9 @@ var openpkg_schema_default3 = {
             "interface",
             "type",
             "enum",
+            "module",
             "namespace",
+            "reference",
             "external"
           ]
         },
@@ -1288,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",
@@ -1309,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"
@@ -1398,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",
@@ -1419,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"
@@ -1539,7 +1791,7 @@ var openpkg_schema_default3 = {
     },
     parameter: {
       type: "object",
-      required: ["name", "required"],
+      required: ["name"],
       properties: {
         name: {
           type: "string",
@@ -1582,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: [
@@ -1594,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" }
@@ -1614,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",
@@ -1631,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)"
         }
       }
     },
@@ -1773,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",
@@ -1860,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.8.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

@@ -4,7 +4,7 @@
   "title": "OpenPkg Specification",
   "description": "Schema for OpenPkg specification files",
   "type": "object",
-  "required": ["openpkg", "meta", "exports"],
+  "required": ["openpkg", "meta", "exports", "generation"],
   "properties": {
     "$schema": {
       "type": "string",
@@ -62,12 +62,174 @@
         "$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",
+      "description": "Required metadata about how this spec was generated"
     }
   },
   "$defs": {
+    "entryPointDetectionMethod": {
+      "type": "string",
+      "description": "Method used to detect the entry point for analysis",
+      "enum": ["types", "exports", "main", "module", "fallback", "explicit", "llm"]
+    },
+    "generationIssueSeverity": {
+      "type": "string",
+      "description": "Severity level for issues encountered during spec generation",
+      "enum": ["error", "warning", "info"]
+    },
+    "generationIssue": {
+      "type": "object",
+      "description": "An issue encountered during spec generation",
+      "required": ["code", "message", "severity"],
+      "properties": {
+        "code": {
+          "type": "string",
+          "description": "Machine-readable issue code"
+        },
+        "message": {
+          "type": "string",
+          "description": "Human-readable issue message"
+        },
+        "severity": {
+          "$ref": "#/$defs/generationIssueSeverity"
+        },
+        "suggestion": {
+          "type": "string",
+          "description": "Suggested resolution"
+        }
+      },
+      "additionalProperties": false
+    },
+    "generationInfo": {
+      "type": "object",
+      "description": "Metadata about how the spec was generated",
+      "required": ["timestamp", "generator", "analysis", "environment", "issues"],
+      "properties": {
+        "timestamp": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 timestamp of when the spec was generated"
+        },
+        "generator": {
+          "type": "object",
+          "description": "Information about the tool that generated the spec",
+          "required": ["name", "version"],
+          "properties": {
+            "name": {
+              "type": "string",
+              "description": "Tool name (e.g., '@doccov/cli', '@doccov/api')"
+            },
+            "version": {
+              "type": "string",
+              "description": "Tool version"
+            }
+          },
+          "additionalProperties": false
+        },
+        "analysis": {
+          "type": "object",
+          "description": "Details about the analysis process",
+          "required": [
+            "entryPoint",
+            "entryPointSource",
+            "isDeclarationOnly",
+            "resolvedExternalTypes"
+          ],
+          "properties": {
+            "entryPoint": {
+              "type": "string",
+              "description": "Entry point file that was analyzed (relative path)"
+            },
+            "entryPointSource": {
+              "$ref": "#/$defs/entryPointDetectionMethod"
+            },
+            "isDeclarationOnly": {
+              "type": "boolean",
+              "description": "Whether this was a declaration-only analysis (.d.ts file)"
+            },
+            "resolvedExternalTypes": {
+              "type": "boolean",
+              "description": "Whether external types from node_modules were resolved"
+            },
+            "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
+        },
+        "environment": {
+          "type": "object",
+          "description": "Environment information during generation",
+          "required": ["hasNodeModules"],
+          "properties": {
+            "packageManager": {
+              "type": "string",
+              "description": "Detected package manager"
+            },
+            "hasNodeModules": {
+              "type": "boolean",
+              "description": "Whether node_modules was available for type resolution"
+            },
+            "isMonorepo": {
+              "type": "boolean",
+              "description": "Whether this is a monorepo"
+            },
+            "targetPackage": {
+              "type": "string",
+              "description": "Target package name (for monorepos)"
+            }
+          },
+          "additionalProperties": false
+        },
+        "issues": {
+          "type": "array",
+          "description": "Issues encountered during generation",
+          "items": {
+            "$ref": "#/$defs/generationIssue"
+          }
+        },
+        "fromCache": {
+          "type": "boolean",
+          "description": "Whether the result came from cache"
+        }
+      },
+      "additionalProperties": false
+    },
     "docSignal": {
       "type": "string",
       "enum": ["description", "params", "returns", "examples"]
@@ -180,7 +342,9 @@
             "interface",
             "type",
             "enum",
+            "module",
             "namespace",
+            "reference",
             "external"
           ]
         },
@@ -209,7 +373,7 @@
         "members": {
           "type": "array",
           "description": "Class/interface/enum members",
-          "items": { "type": "object" }
+          "items": { "$ref": "#/$defs/member" }
         },
         "extends": {
           "type": "string",
@@ -230,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"
@@ -319,7 +501,7 @@
         "members": {
           "type": "array",
           "description": "Members for classes/interfaces/enums",
-          "items": { "type": "object" }
+          "items": { "$ref": "#/$defs/member" }
         },
         "extends": {
           "type": "string",
@@ -340,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"
@@ -460,7 +646,7 @@
     },
     "parameter": {
       "type": "object",
-      "required": ["name", "required"],
+      "required": ["name"],
       "properties": {
         "name": {
           "type": "string",
@@ -503,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": [
@@ -515,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" }
@@ -535,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",
@@ -552,6 +762,10 @@
           "type": "integer",
           "description": "Line number in source file",
           "minimum": 1
+        },
+        "url": {
+          "type": "string",
+          "description": "URL to source (e.g., GitHub permalink)"
         }
       }
     },
@@ -694,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",