@openpkg-ts/spec 0.7.0 → 0.8.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>;
@@ -242,13 +265,23 @@ type OpenPkg = {
 	exports: SpecExport[];
 	types?: SpecType[];
 	examples?: SpecExample[];
-	docs?: SpecDocsMetadata;
 	extensions?: SpecExtension;
 };
 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 +310,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 +325,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 +363,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, 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 };

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";
@@ -1841,5 +1868,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.8.0",
   "description": "Shared schema, validation, and diff utilities for OpenPkg specs",
   "keywords": [
     "openpkg",