@openpkg-ts/spec 0.2.2 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +27 -17
  2. package/dist/index.d.ts +9 -3
  3. package/dist/index.js +40 -2
  4. package/package.json +1 -1
  5. package/schemas/v0.2.0/openpkg.schema.json +40 -2
package/README.md CHANGED
@@ -1,33 +1,43 @@
1
1
  # @openpkg-ts/spec
2
2
 
3
- Canonical schema, TypeScript types, validation, normalization, deref, diff, and migration helpers for OpenPkg specs.
3
+ OpenPkg schema, types, validation, and diffing utilities.
4
4
 
5
5
  ## Install
6
+
6
7
  ```bash
7
8
  npm install @openpkg-ts/spec
8
9
  ```
9
10
 
10
- ## Quick Helpers
11
- ```ts
12
- import { normalize, validateSpec } from '@openpkg-ts/spec';
11
+ ## Usage
12
+
13
+ ```typescript
14
+ import { validateSpec, normalize, diffSpec } from '@openpkg-ts/spec';
13
15
 
14
- const normalized = normalize(spec);
15
- const result = validateSpec(normalized);
16
+ // Validate
17
+ const result = validateSpec(normalize(spec));
16
18
  if (!result.ok) {
17
- throw new Error(result.errors.map((e) => `${e.instancePath || '/'} ${e.message}`).join('\n'));
19
+ console.error(result.errors);
18
20
  }
21
+
22
+ // Diff two specs
23
+ const diff = diffSpec(oldSpec, newSpec);
24
+ console.log(`Coverage delta: ${diff.coverageDelta}%`);
19
25
  ```
20
26
 
21
- ```ts
22
- import { dereference, diffSpec } from '@openpkg-ts/spec';
27
+ ## Exports
23
28
 
24
- const left = dereference(specA);
25
- const right = dereference(specB);
26
- const diff = diffSpec(left, right);
27
- ```
29
+ - `validateSpec` / `assertSpec` - Schema validation
30
+ - `normalize` - Ensure consistent structure
31
+ - `dereference` - Resolve `$ref` pointers
32
+ - `diffSpec` - Compare specs
33
+
34
+ ## Documentation
35
+
36
+ - [Spec Overview](../../docs/spec/overview.md)
37
+ - [Types Reference](../../docs/spec/types.md)
38
+ - [Drift Types](../../docs/spec/drift-types.md)
39
+ - [Diffing](../../docs/spec/diffing.md)
28
40
 
29
- ## See Also
30
- - [SDK generator](../sdk/README.md)
31
- - [CLI usage](../cli/README.md)
41
+ ## License
32
42
 
33
- MIT License
43
+ MIT
package/dist/index.d.ts CHANGED
@@ -15,7 +15,7 @@ type SpecExample = Record<string, unknown>;
15
15
  type SpecExtension = Record<string, unknown>;
16
16
  type SpecDocSignal = "description" | "params" | "returns" | "examples";
17
17
  type SpecDocDrift = {
18
- type: "param-mismatch" | "param-type-mismatch" | "return-type-mismatch" | "generic-constraint-mismatch" | "optionality-mismatch" | "deprecated-mismatch" | "visibility-mismatch" | "example-drift" | "broken-link";
18
+ 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";
19
19
  target?: string;
20
20
  issue: string;
21
21
  suggestion?: string;
@@ -59,13 +59,14 @@ type SpecMember = {
59
59
  schema?: SpecSchema;
60
60
  signatures?: SpecSignature[];
61
61
  };
62
- type SpecExportKind = "function" | "class" | "variable" | "interface" | "type" | "enum" | "module" | "namespace" | "reference";
63
- type SpecTypeKind = "class" | "interface" | "type" | "enum";
62
+ type SpecExportKind = "function" | "class" | "variable" | "interface" | "type" | "enum" | "module" | "namespace" | "reference" | "external";
63
+ type SpecTypeKind = "class" | "interface" | "type" | "enum" | "external";
64
64
  type SpecExport = {
65
65
  id: string;
66
66
  name: string;
67
67
  slug?: string;
68
68
  displayName?: string;
69
+ alias?: string;
69
70
  category?: string;
70
71
  importPath?: string;
71
72
  kind: SpecExportKind;
@@ -81,12 +82,15 @@ type SpecExport = {
81
82
  deprecated?: boolean;
82
83
  flags?: Record<string, unknown>;
83
84
  tags?: SpecTag[];
85
+ extends?: string;
86
+ implements?: string[];
84
87
  };
85
88
  type SpecType = {
86
89
  id: string;
87
90
  name: string;
88
91
  slug?: string;
89
92
  displayName?: string;
93
+ alias?: string;
90
94
  category?: string;
91
95
  importPath?: string;
92
96
  kind: SpecTypeKind;
@@ -97,6 +101,8 @@ type SpecType = {
97
101
  source?: SpecSource;
98
102
  tags?: SpecTag[];
99
103
  rawComments?: string;
104
+ extends?: string;
105
+ implements?: string[];
100
106
  };
101
107
  type OpenPkgMeta = {
102
108
  name: string;
package/dist/index.js CHANGED
@@ -332,7 +332,12 @@ var openpkg_schema_default = {
332
332
  "optionality-mismatch",
333
333
  "deprecated-mismatch",
334
334
  "visibility-mismatch",
335
+ "async-mismatch",
336
+ "property-type-drift",
335
337
  "example-drift",
338
+ "example-syntax-error",
339
+ "example-runtime-error",
340
+ "example-assertion-failed",
336
341
  "broken-link"
337
342
  ]
338
343
  },
@@ -399,6 +404,10 @@ var openpkg_schema_default = {
399
404
  type: "string",
400
405
  description: "UI-friendly label"
401
406
  },
407
+ alias: {
408
+ type: "string",
409
+ description: "Export alias if re-exported with a different name (id uses alias, name uses original)"
410
+ },
402
411
  category: {
403
412
  type: "string",
404
413
  description: "Grouping hint for navigation"
@@ -410,7 +419,7 @@ var openpkg_schema_default = {
410
419
  kind: {
411
420
  type: "string",
412
421
  description: "Kind of export",
413
- enum: ["function", "class", "variable", "interface", "type", "enum"]
422
+ enum: ["function", "class", "variable", "interface", "type", "enum", "namespace", "external"]
414
423
  },
415
424
  description: {
416
425
  type: "string",
@@ -439,6 +448,15 @@ var openpkg_schema_default = {
439
448
  description: "Class/interface/enum members",
440
449
  items: { type: "object" }
441
450
  },
451
+ extends: {
452
+ type: "string",
453
+ description: "Base class or interface that this class/interface extends"
454
+ },
455
+ implements: {
456
+ type: "array",
457
+ description: "Interfaces implemented by this class",
458
+ items: { type: "string" }
459
+ },
442
460
  tags: {
443
461
  type: "array",
444
462
  description: "JSDoc/TSDoc tags",
@@ -481,6 +499,10 @@ var openpkg_schema_default = {
481
499
  type: "string",
482
500
  description: "UI-friendly label"
483
501
  },
502
+ alias: {
503
+ type: "string",
504
+ description: "Export alias if re-exported with a different name (id uses alias, name uses original)"
505
+ },
484
506
  category: {
485
507
  type: "string",
486
508
  description: "Grouping hint for navigation"
@@ -492,7 +514,7 @@ var openpkg_schema_default = {
492
514
  kind: {
493
515
  type: "string",
494
516
  description: "Kind of type definition",
495
- enum: ["interface", "type", "enum", "class"]
517
+ enum: ["interface", "type", "enum", "class", "external"]
496
518
  },
497
519
  description: {
498
520
  type: "string",
@@ -510,6 +532,15 @@ var openpkg_schema_default = {
510
532
  description: "Members for classes/interfaces/enums",
511
533
  items: { type: "object" }
512
534
  },
535
+ extends: {
536
+ type: "string",
537
+ description: "Base class or interface that this class/interface extends"
538
+ },
539
+ implements: {
540
+ type: "array",
541
+ description: "Interfaces implemented by this class",
542
+ items: { type: "string" }
543
+ },
513
544
  tags: {
514
545
  type: "array",
515
546
  description: "JSDoc/TSDoc tags",
@@ -564,6 +595,13 @@ var openpkg_schema_default = {
564
595
  description: {
565
596
  type: "string",
566
597
  description: "Parameter description"
598
+ },
599
+ default: {
600
+ description: "Default value for the parameter"
601
+ },
602
+ rest: {
603
+ type: "boolean",
604
+ description: "Whether this is a rest parameter (...args)"
567
605
  }
568
606
  }
569
607
  },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@openpkg-ts/spec",
3
- "version": "0.2.2",
3
+ "version": "0.3.1",
4
4
  "description": "Shared schema, validation, and diff utilities for OpenPkg specs",
5
5
  "keywords": [
6
6
  "openpkg",
package/schemas/v0.2.0/openpkg.schema.json CHANGED
@@ -86,7 +86,12 @@
86
86
  "optionality-mismatch",
87
87
  "deprecated-mismatch",
88
88
  "visibility-mismatch",
89
+ "async-mismatch",
90
+ "property-type-drift",
89
91
  "example-drift",
92
+ "example-syntax-error",
93
+ "example-runtime-error",
94
+ "example-assertion-failed",
90
95
  "broken-link"
91
96
  ]
92
97
  },
@@ -153,6 +158,10 @@
153
158
  "type": "string",
154
159
  "description": "UI-friendly label"
155
160
  },
161
+ "alias": {
162
+ "type": "string",
163
+ "description": "Export alias if re-exported with a different name (id uses alias, name uses original)"
164
+ },
156
165
  "category": {
157
166
  "type": "string",
158
167
  "description": "Grouping hint for navigation"
@@ -164,7 +173,7 @@
164
173
  "kind": {
165
174
  "type": "string",
166
175
  "description": "Kind of export",
167
- "enum": ["function", "class", "variable", "interface", "type", "enum"]
176
+ "enum": ["function", "class", "variable", "interface", "type", "enum", "namespace", "external"]
168
177
  },
169
178
  "description": {
170
179
  "type": "string",
@@ -193,6 +202,15 @@
193
202
  "description": "Class/interface/enum members",
194
203
  "items": { "type": "object" }
195
204
  },
205
+ "extends": {
206
+ "type": "string",
207
+ "description": "Base class or interface that this class/interface extends"
208
+ },
209
+ "implements": {
210
+ "type": "array",
211
+ "description": "Interfaces implemented by this class",
212
+ "items": { "type": "string" }
213
+ },
196
214
  "tags": {
197
215
  "type": "array",
198
216
  "description": "JSDoc/TSDoc tags",
@@ -235,6 +253,10 @@
235
253
  "type": "string",
236
254
  "description": "UI-friendly label"
237
255
  },
256
+ "alias": {
257
+ "type": "string",
258
+ "description": "Export alias if re-exported with a different name (id uses alias, name uses original)"
259
+ },
238
260
  "category": {
239
261
  "type": "string",
240
262
  "description": "Grouping hint for navigation"
@@ -246,7 +268,7 @@
246
268
  "kind": {
247
269
  "type": "string",
248
270
  "description": "Kind of type definition",
249
- "enum": ["interface", "type", "enum", "class"]
271
+ "enum": ["interface", "type", "enum", "class", "external"]
250
272
  },
251
273
  "description": {
252
274
  "type": "string",
@@ -264,6 +286,15 @@
264
286
  "description": "Members for classes/interfaces/enums",
265
287
  "items": { "type": "object" }
266
288
  },
289
+ "extends": {
290
+ "type": "string",
291
+ "description": "Base class or interface that this class/interface extends"
292
+ },
293
+ "implements": {
294
+ "type": "array",
295
+ "description": "Interfaces implemented by this class",
296
+ "items": { "type": "string" }
297
+ },
267
298
  "tags": {
268
299
  "type": "array",
269
300
  "description": "JSDoc/TSDoc tags",
@@ -318,6 +349,13 @@
318
349
  "description": {
319
350
  "type": "string",
320
351
  "description": "Parameter description"
352
+ },
353
+ "default": {
354
+ "description": "Default value for the parameter"
355
+ },
356
+ "rest": {
357
+ "type": "boolean",
358
+ "description": "Whether this is a rest parameter (...args)"
321
359
  }
322
360
  }
323
361
  },