@openpkg-ts/spec 0.12.0 → 0.23.0

package/README.md

@@ -1,6 +1,6 @@
 # @openpkg-ts/spec
 
-OpenPkg schema, types, validation, and diffing utilities.
+OpenPkg specification types, validation, normalization, and diffing utilities.
 
 ## Install
 
@@ -8,35 +8,126 @@ OpenPkg schema, types, validation, and diffing utilities.
 npm install @openpkg-ts/spec
 ```
 
-## Usage
+## Quick Start
 
 ```typescript
 import { validateSpec, normalize, diffSpec } from '@openpkg-ts/spec';
 
-// Validate
-const result = validateSpec(normalize(spec));
+// Validate a spec
+const result = validateSpec(spec);
 if (!result.ok) {
   console.error(result.errors);
 }
 
+// Normalize for consistent structure
+const normalized = normalize(spec);
+
 // Diff two specs
 const diff = diffSpec(oldSpec, newSpec);
-console.log(`Coverage delta: ${diff.coverageDelta}%`);
+console.log(`Breaking changes: ${diff.breaking.length}`);
+```
+
+## Validation
+
+```typescript
+import { validateSpec, assertSpec, getValidationErrors } from '@openpkg-ts/spec';
+
+// Returns { ok: boolean, errors?: ValidationError[] }
+const result = validateSpec(spec);
+
+// Throws on invalid
+assertSpec(spec);
+
+// Get errors only
+const errors = getValidationErrors(spec);
+```
+
+## Normalization
+
+Ensures consistent structure and defaults.
+
+```typescript
+import { normalize } from '@openpkg-ts/spec';
+
+const normalized = normalize(spec);
+// - Sorts exports alphabetically
+// - Ensures meta fields exist
+// - Normalizes type references
+```
+
+## Diffing
+
+Compare specs and detect breaking changes.
+
+```typescript
+import { diffSpec, recommendSemverBump, calculateNextVersion } from '@openpkg-ts/spec';
+
+const diff = diffSpec(baseSpec, headSpec);
+
+console.log(`Added: ${diff.added.length}`);
+console.log(`Removed: ${diff.removed.length}`);
+console.log(`Modified: ${diff.modified.length}`);
+console.log(`Breaking: ${diff.breaking.length}`);
+
+// Get semver recommendation
+const recommendation = recommendSemverBump(diff);
+console.log(`Suggested bump: ${recommendation.bump}`); // 'major' | 'minor' | 'patch'
+console.log(`Reason: ${recommendation.reason}`);
+
+// Calculate next version
+const next = calculateNextVersion('1.2.3', recommendation.bump);
+console.log(`Next version: ${next}`); // '2.0.0'
+```
+
+## Dereferencing
+
+Resolve `$ref` pointers in the spec.
+
+```typescript
+import { dereference } from '@openpkg-ts/spec';
+
+const dereferenced = dereference(spec);
+// All $ref pointers are resolved inline
+```
+
+## Types
+
+```typescript
+import type {
+  OpenPkg,
+  SpecExport,
+  SpecType,
+  SpecFunction,
+  SpecClass,
+  SpecInterface,
+  SpecMeta,
+} from '@openpkg-ts/spec';
 ```
 
 ## Exports
 
-- `validateSpec` / `assertSpec` - Schema validation
-- `normalize` - Ensure consistent structure
-- `dereference` - Resolve `$ref` pointers
-- `diffSpec` - Compare specs
+### Validation
+- `validateSpec(spec)` - Validate against schema
+- `assertSpec(spec)` - Throw on invalid
+- `getValidationErrors(spec)` - Get errors array
+- `getAvailableVersions()` - List schema versions
+
+### Transformation
+- `normalize(spec)` - Normalize structure
+- `dereference(spec)` - Resolve $ref pointers
 
-## Documentation
+### Diffing
+- `diffSpec(base, head)` - Compare specs
+- `recommendSemverBump(diff)` - Suggest version bump
+- `calculateNextVersion(version, bump)` - Calculate next version
+- `categorizeBreakingChanges(diff)` - Group by severity
 
-- [Spec Overview](../../docs/spec/overview.md)
-- [Types Reference](../../docs/spec/types.md)
-- [Drift Types](../../docs/spec/drift-types.md)
-- [Diffing](../../docs/spec/diffing.md)
+### Types
+- `OpenPkg` - Root spec type
+- `SpecExport` - Export definition
+- `SpecType` - Type definition
+- `SpecFunction`, `SpecClass`, `SpecInterface` - Export kinds
+- `SpecDiff` - Diff result type
 
 ## License
 

package/dist/index.d.ts

@@ -1,6 +1,23 @@
+/**
+* Structured data for @param tags.
+*/
+type SpecTagParam = {
+	/** Parameter name (e.g., "options", "opts.nested") */
+	name: string;
+	/** Type annotation from JSDoc {type} syntax */
+	type?: string;
+	/** Parameter description */
+	description?: string;
+	/** Whether param is marked optional with [brackets] */
+	optional?: boolean;
+};
 type SpecTag = {
+	/** Tag name (e.g., "param", "returns", "example") */
 	name: string;
+	/** Raw tag text (for backwards compatibility) */
 	text: string;
+	/** Structured data for @param tags */
+	param?: SpecTagParam;
 };
 type SpecTypeAliasKind = "alias" | "conditional" | "mapped" | "template-literal" | "infer";
 type SpecConditionalType = {
@@ -95,7 +112,7 @@ type SpecSchemaRef = {
 type SpecSchemaFallback = {
 	type: string;
 };
-type SpecSchemaGeneric = Record<string, unknown>;
+type SpecSchemaGeneric = Record<string, unknown> & Partial<JSONSchemaExtensions>;
 type SpecSchema = string | SpecSchemaPrimitive | SpecSchemaComposite | SpecSchemaCombinator | SpecSchemaRef | SpecSchemaFallback | SpecSchemaGeneric;
 type SpecExampleLanguage = "ts" | "js" | "tsx" | "jsx" | "shell" | "json";
 type SpecExample = {
@@ -146,6 +163,50 @@ type SpecSignature = {
 	isImplementation?: boolean;
 	throws?: SpecThrows[];
 };
+/**
+* JSON Schema extension fields for TypeScript-specific type information.
+*
+* These extensions use the `x-` prefix which is valid JSON Schema for vendor extensions.
+* They allow consumers to preserve TypeScript-specific information while still having
+* valid JSON Schema. The extensions are optional - a consumer can ignore them for pure
+* JSON Schema usage.
+*
+* Extension semantics:
+* | Extension            | Purpose                                                              |
+* |----------------------|----------------------------------------------------------------------|
+* | `x-ts-type`          | Preserves original TS type for types that map to JSON Schema but    |
+* |                      | lose fidelity (bigint → integer, symbol → string)                   |
+* | `x-ts-function`      | Marks a schema as representing a function type                      |
+* | `x-ts-signatures`    | Contains function/method signatures for callable types              |
+* | `x-ts-type-arguments`| Preserves generic type arguments for parameterized types            |
+*/
+type JSONSchemaExtensions = {
+	/**
+	* Preserves the original TypeScript type when mapping to JSON Schema loses fidelity.
+	* Examples:
+	* - bigint → { type: "integer", "x-ts-type": "bigint" }
+	* - symbol → { type: "string", "x-ts-type": "symbol" }
+	* - void → { type: "null", "x-ts-type": "void" } (optionally)
+	* - never, any, unknown, undefined also supported
+	*/
+	"x-ts-type"?: "bigint" | "symbol" | "void" | "never" | "any" | "unknown" | "undefined" | string;
+	/**
+	* Marks a schema as representing a function type.
+	* When true, the schema represents a callable TypeScript function.
+	*/
+	"x-ts-function"?: boolean;
+	/**
+	* Contains function/method signatures for callable types.
+	* Used in conjunction with `x-ts-function` to preserve full signature information.
+	*/
+	"x-ts-signatures"?: SpecSignature[];
+	/**
+	* Preserves generic type arguments for parameterized types.
+	* Used with $ref to maintain generic instantiation information.
+	* Example: Map<string, number> → { "$ref": "#/$defs/Map", "x-ts-type-arguments": [...] }
+	*/
+	"x-ts-type-arguments"?: SpecSchema[];
+};
 type SpecMember = {
 	id?: string;
 	name?: string;
@@ -411,6 +472,10 @@ declare function validateSpec(spec: unknown, version?: SchemaVersion): {
 	errors: SpecError[];
 };
 /**
+* Get available schema versions.
+*/
+declare function getAvailableVersions(): string[];
+/**
 * Assert that a value is a valid OpenPkg spec.
 * Throws an error with details if validation fails.
 *
@@ -426,4 +491,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, 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, SpecPresentationMeta, SpecMember, SpecMappedType, SpecGenerationMeta, SpecGenerationInfo, SpecExtensions, SpecExtension, SpecExportKind, SpecExport, SpecExampleLanguage, SpecExample, SpecDiff, SpecDecorator, SpecConditionalType, SemverRecommendation, SemverBump, SCHEMA_VERSION, SCHEMA_URL, OpenPkgVersion, OpenPkgMeta, OpenPkg, MemberChangeInfo, JSON_SCHEMA_DRAFT, GenerationIssueSeverity, GenerationIssue, EntryPointDetectionMethod, CategorizedBreaking, BreakingSeverity };
+export { validateSpec, recommendSemverBump, normalize, getValidationErrors, getAvailableVersions, diffSpec, dereference, categorizeBreakingChanges, calculateNextVersion, assertSpec, SpecVisibility, SpecTypeParameter, SpecTypeKind, SpecTypeAliasKind, SpecType, SpecThrows, SpecTagParam, SpecTag, SpecSource, SpecSignatureReturn, SpecSignatureParameter, SpecSignature, SpecSchemaRef, SpecSchemaPrimitive, SpecSchemaGeneric, SpecSchemaFallback, SpecSchemaComposite, SpecSchemaCombinator, SpecSchema, SpecPresentationMeta, SpecMember, SpecMappedType, SpecGenerationMeta, SpecGenerationInfo, SpecExtensions, SpecExtension, SpecExportKind, SpecExport, SpecExampleLanguage, SpecExample, SpecDiff, SpecDecorator, SpecConditionalType, SemverRecommendation, SemverBump, SCHEMA_VERSION, SCHEMA_URL, OpenPkgVersion, OpenPkgMeta, OpenPkg, MemberChangeInfo, JSON_SCHEMA_DRAFT, JSONSchemaExtensions, GenerationIssueSeverity, GenerationIssue, EntryPointDetectionMethod, CategorizedBreaking, BreakingSeverity };

package/dist/index.js

@@ -373,10 +373,14 @@ function normalizeType(item) {
   return clone;
 }
 function normalizeTag(tag) {
-  return {
+  const result = {
     name: tag.name,
     text: tag.text
   };
+  if (tag.param) {
+    result.param = tag.param;
+  }
+  return result;
 }
 function normalizeMember(member) {
   const clone = structuredClone(member);
@@ -2287,7 +2291,19 @@ var openpkg_schema_default4 = {
       required: ["name", "text"],
       properties: {
         name: { type: "string" },
-        text: { type: "string" }
+        text: { type: "string" },
+        param: { $ref: "#/$defs/tagParam" }
+      },
+      additionalProperties: false
+    },
+    tagParam: {
+      type: "object",
+      required: ["name"],
+      properties: {
+        name: { type: "string" },
+        type: { type: "string" },
+        description: { type: "string" },
+        optional: { type: "boolean" }
       },
       additionalProperties: false
     },
@@ -2539,6 +2555,9 @@ function validateSpec(spec, version = "latest") {
     errors
   };
 }
+function getAvailableVersions() {
+  return Object.keys(schemas);
+}
 function assertSpec(spec, version = "latest") {
   const result = validateSpec(spec, version);
   if (!result.ok) {
@@ -2557,6 +2576,7 @@ export {
   recommendSemverBump,
   normalize,
   getValidationErrors,
+  getAvailableVersions,
   diffSpec,
   dereference,
   categorizeBreakingChanges,

package/package.json

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

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

@@ -171,7 +171,19 @@
       "required": ["name", "text"],
       "properties": {
         "name": { "type": "string" },
-        "text": { "type": "string" }
+        "text": { "type": "string" },
+        "param": { "$ref": "#/$defs/tagParam" }
+      },
+      "additionalProperties": false
+    },
+    "tagParam": {
+      "type": "object",
+      "required": ["name"],
+      "properties": {
+        "name": { "type": "string" },
+        "type": { "type": "string" },
+        "description": { "type": "string" },
+        "optional": { "type": "boolean" }
       },
       "additionalProperties": false
     },