@openpkg-ts/spec 0.8.0 → 0.9.0

package/dist/index.d.ts

@@ -256,6 +256,70 @@ 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;
+	};
+	/** 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 +330,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";
@@ -363,4 +429,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, 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 };

package/dist/index.js

@@ -1083,7 +1083,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",
@@ -1144,9 +1144,137 @@ var openpkg_schema_default3 = {
     docs: {
       $ref: "#/$defs/docsMetadata",
       description: "Aggregate documentation coverage metadata"
+    },
+    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"
+            }
+          },
+          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"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpkg-ts/spec",
-  "version": "0.8.0",
+  "version": "0.9.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",
@@ -65,9 +65,137 @@
     "docs": {
       "$ref": "#/$defs/docsMetadata",
       "description": "Aggregate documentation coverage metadata"
+    },
+    "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"
+            }
+          },
+          "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"]