@openpkg-ts/spec 0.23.0 → 0.26.0

package/dist/index.d.ts

@@ -140,6 +140,8 @@ type SpecTypeParameter = {
 	name: string;
 	constraint?: string;
 	default?: string;
+	variance?: "in" | "out" | "inout";
+	const?: boolean;
 };
 type SpecSignatureParameter = {
 	name: string;
@@ -158,12 +160,24 @@ type SpecSignature = {
 	parameters?: SpecSignatureParameter[];
 	returns?: SpecSignatureReturn;
 	description?: string;
+	tags?: SpecTag[];
+	examples?: SpecExample[];
 	typeParameters?: SpecTypeParameter[];
 	overloadIndex?: number;
 	isImplementation?: boolean;
 	throws?: SpecThrows[];
 };
 /**
+* Type predicate information for type guard functions.
+* Preserved in x-ts-type-predicate extension.
+*/
+type SpecTypePredicate = {
+	/** The parameter name that the type guard narrows */
+	parameterName: string;
+	/** The type that the parameter is narrowed to */
+	type: SpecSchema;
+};
+/**
 * JSON Schema extension fields for TypeScript-specific type information.
 *
 * These extensions use the `x-` prefix which is valid JSON Schema for vendor extensions.
@@ -179,6 +193,8 @@ type SpecSignature = {
 * | `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            |
+* | `x-ts-type-predicate`| Preserves type guard narrowing information                          |
+* | `x-ts-package`       | Package name for external type references                           |
 */
 type JSONSchemaExtensions = {
 	/**
@@ -206,6 +222,16 @@ type JSONSchemaExtensions = {
 	* Example: Map<string, number> → { "$ref": "#/$defs/Map", "x-ts-type-arguments": [...] }
 	*/
 	"x-ts-type-arguments"?: SpecSchema[];
+	/**
+	* Preserves type guard narrowing information for type predicate functions.
+	* Example: (value: unknown) => value is string → { "x-ts-type-predicate": { parameterName: "value", type: { type: "string" } } }
+	*/
+	"x-ts-type-predicate"?: SpecTypePredicate;
+	/**
+	* Package name for external type references from node_modules.
+	* Example: AnyRouter from @trpc/server → { "$ref": "#/types/AnyRouter", "x-ts-package": "@trpc/server" }
+	*/
+	"x-ts-package"?: string;
 };
 type SpecMember = {
 	id?: string;
@@ -219,6 +245,10 @@ type SpecMember = {
 	signatures?: SpecSignature[];
 	decorators?: SpecDecorator[];
 };
+type SpecInheritedMember = SpecMember & {
+	/** Name of the class this member was inherited from */
+	inheritedFrom: string;
+};
 type SpecExportKind = "function" | "class" | "variable" | "interface" | "type" | "enum" | "module" | "namespace" | "reference" | "external";
 type SpecTypeKind = "class" | "interface" | "type" | "enum" | "external";
 type SpecExport = {
@@ -345,10 +375,18 @@ type SpecGenerationInfo = {
 };
 /** Supported OpenPkg spec versions */
 type OpenPkgVersion = "0.2.0" | "0.3.0" | "0.4.0";
+/** Extraction mode indicating source type */
+type SpecExtractionMode = "source" | "declaration-only";
+/** Known limitations when extracting from declaration-only sources */
+type SpecExtractionLimitation = "No JSDoc descriptions" | "No @example tags" | "No @param descriptions";
 /** Minimal generation metadata for v0.4.0 */
 type SpecGenerationMeta = {
 	generator?: string;
 	timestamp?: string;
+	/** Extraction mode: 'source' (full .ts) or 'declaration-only' (.d.ts) */
+	mode?: SpecExtractionMode;
+	/** Known limitations when in declaration-only mode */
+	limitations?: SpecExtractionLimitation[];
 };
 type OpenPkg = {
 	$schema?: string;
@@ -491,4 +529,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, 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 };
+export { validateSpec, recommendSemverBump, normalize, getValidationErrors, getAvailableVersions, diffSpec, dereference, categorizeBreakingChanges, calculateNextVersion, assertSpec, SpecVisibility, SpecTypePredicate, SpecTypeParameter, SpecTypeKind, SpecTypeAliasKind, SpecType, SpecThrows, SpecTagParam, SpecTag, SpecSource, SpecSignatureReturn, SpecSignatureParameter, SpecSignature, SpecSchemaRef, SpecSchemaPrimitive, SpecSchemaGeneric, SpecSchemaFallback, SpecSchemaComposite, SpecSchemaCombinator, SpecSchema, SpecPresentationMeta, SpecMember, SpecMappedType, SpecInheritedMember, SpecGenerationMeta, SpecGenerationInfo, SpecExtractionMode, SpecExtractionLimitation, 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/package.json

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