@openpkg-ts/spec 0.11.1 → 0.19.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 = {
@@ -29,6 +46,10 @@ type SpecSource = {
 	file?: string;
 	line?: number;
 	url?: string;
+	/** Package name for external types (e.g., "@stacks/common") */
+	package?: string;
+	/** Package version for external types (e.g., "7.0.0") */
+	version?: string;
 };
 type SpecSchemaPrimitive = {
 	type: "string";
@@ -86,6 +107,7 @@ type SpecSchemaCombinator = {
 };
 type SpecSchemaRef = {
 	$ref: string;
+	typeArguments?: SpecSchema[];
 };
 type SpecSchemaFallback = {
 	type: string;
@@ -193,6 +215,8 @@ type SpecType = {
 	typeAliasKind?: SpecTypeAliasKind;
 	conditionalType?: SpecConditionalType;
 	mappedType?: SpecMappedType;
+	/** Whether this type is from an external package (node_modules) */
+	external?: boolean;
 };
 type OpenPkgMeta = {
 	name: string;
@@ -404,6 +428,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.
 *
@@ -419,4 +447,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, 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.11.1",
+  "version": "0.19.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
     },