@openpkg-ts/spec 0.7.0 → 0.9.0

package/dist/index.d.ts

@@ -116,17 +116,41 @@ type SpecRelation = {
 	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 = {
@@ -187,7 +211,6 @@ type SpecExport = {
 	schema?: SpecSchema;
 	description?: string;
 	examples?: (string | SpecExample)[];
-	docs?: SpecDocsMetadata;
 	source?: SpecSource;
 	deprecated?: boolean;
 	flags?: Record<string, unknown>;
@@ -233,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 = {
@@ -242,13 +329,25 @@ type OpenPkg = {
 	exports: SpecExport[];
 	types?: SpecType[];
 	examples?: SpecExample[];
-	docs?: SpecDocsMetadata;
 	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";
 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;
@@ -277,7 +376,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
 *
@@ -287,7 +391,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";
@@ -325,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, 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, 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

@@ -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";
@@ -1056,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",
@@ -1117,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"]
@@ -1841,5 +1996,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.7.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"]