@openpkg-ts/spec 0.1.0 → 0.2.1

package/README.md

@@ -1,66 +1,33 @@
 # @openpkg-ts/spec
 
-Shared contract for the OpenPkg specification, including versioned JSON Schema files, TypeScript types, validation helpers, and diff utilities. The package is still under construction; functionality will be filled in as the spec is extracted from the CLI and SDK.
-
-## Development
+Canonical schema, TypeScript types, validation, normalization, deref, diff, and migration helpers for OpenPkg specs.
 
+## Install
 ```bash
-bun install
-bun run build
+npm install @openpkg-ts/spec
 ```
 
-The build compiles ESM output and type declarations under `dist/`. Schemas are published verbatim from the `schemas/` directory.
-
-
-## Usage Examples
-
-### Validate & Normalize a Generated Spec
+## Quick Helpers
 ```ts
-import { readFile } from 'node:fs/promises';
 import { normalize, validateSpec } from '@openpkg-ts/spec';
 
-const raw = await readFile('openpkg.json', 'utf8');
-const spec = JSON.parse(raw);
 const normalized = normalize(spec);
-
 const result = validateSpec(normalized);
 if (!result.ok) {
-  for (const err of result.errors) {
-    console.error(`schema: ${err.instancePath || '/'} ${err.message}`);
-  }
-  process.exit(1);
+  throw new Error(result.errors.map((e) => `${e.instancePath || '/'} ${e.message}`).join('\n'));
 }
-
-console.log('✅ spec is valid and normalized');
 ```
 
-### Diff Two Spec Snapshots
 ```ts
-import { readFile } from 'node:fs/promises';
-import { dereference, diffSpec, normalize } from '@openpkg-ts/spec';
+import { dereference, diffSpec } from '@openpkg-ts/spec';
 
-const [currentPath, nextPath] = process.argv.slice(2);
-const load = async (file: string) =>
-  dereference(normalize(JSON.parse(await readFile(file, 'utf8'))));
-
-const current = await load(currentPath);
-const next = await load(nextPath);
-const diff = diffSpec(current, next);
-
-console.log('Breaking changes:', diff.breaking);
-console.log('Non-breaking changes:', diff.nonBreaking);
-console.log('Docs-only changes:', diff.docsOnly);
+const left = dereference(specA);
+const right = dereference(specB);
+const diff = diffSpec(left, right);
 ```
 
-### Assert Valid Specs in Tests
-```ts
-import { expect, test } from 'bun:test';
-import { normalize, validateSpec } from '@openpkg-ts/spec';
-import spec from '../openpkg.json' assert { type: 'json' };
+## See Also
+- [SDK generator](../sdk/README.md)
+- [CLI usage](../cli/README.md)
 
-test('generated spec stays schema-valid', () => {
-  const normalized = normalize(spec);
-  const result = validateSpec(normalized);
-  expect(result.ok).toBe(true);
-});
-```
+MIT License

package/dist/index.d.ts

@@ -1,99 +1,148 @@
-declare const SCHEMA_VERSION = "0.1.0";
-declare const SCHEMA_URL = "https://unpkg.com/@openpkg-ts/spec/schemas/v0.1.0/openpkg.schema.json";
+declare const SCHEMA_VERSION = "0.2.0";
+declare const SCHEMA_URL = "https://unpkg.com/@openpkg-ts/spec/schemas/v0.2.0/openpkg.schema.json";
 declare const JSON_SCHEMA_DRAFT = "https://json-schema.org/draft/2020-12/schema";
 type SpecTag = {
-	name: string
-	text: string
+	name: string;
+	text: string;
 };
 type SpecSource = {
-	file?: string
-	line?: number
-	url?: string
+	file?: string;
+	line?: number;
+	url?: string;
 };
 type SpecSchema = unknown;
 type SpecExample = Record<string, unknown>;
 type SpecExtension = Record<string, unknown>;
+type SpecDocSignal = "description" | "params" | "returns" | "examples";
+type SpecDocDrift = {
+	type: "param-mismatch" | "param-type-mismatch" | "return-type-mismatch" | "generic-constraint-mismatch" | "optionality-mismatch" | "deprecated-mismatch" | "visibility-mismatch" | "example-drift" | "broken-link";
+	target?: string;
+	issue: string;
+	suggestion?: string;
+};
+type SpecVisibility = "public" | "protected" | "private";
+type SpecDocsMetadata = {
+	coverageScore?: number;
+	missing?: SpecDocSignal[];
+	drift?: SpecDocDrift[];
+};
+type SpecTypeParameter = {
+	name: string;
+	constraint?: string;
+	default?: string;
+};
 type SpecSignatureParameter = {
-	name: string
-	required?: boolean
-	description?: string
-	schema: SpecSchema
+	name: string;
+	required?: boolean;
+	description?: string;
+	schema: SpecSchema;
 };
 type SpecSignatureReturn = {
-	schema: SpecSchema
-	description?: string
+	schema: SpecSchema;
+	description?: string;
+	tsType?: string;
 };
 type SpecSignature = {
-	parameters?: SpecSignatureParameter[]
-	returns?: SpecSignatureReturn
-	description?: string
+	parameters?: SpecSignatureParameter[];
+	returns?: SpecSignatureReturn;
+	description?: string;
+	typeParameters?: SpecTypeParameter[];
+};
+type SpecMember = {
+	id?: string;
+	name?: string;
+	kind?: string;
+	description?: string;
+	tags?: SpecTag[];
+	visibility?: SpecVisibility;
+	flags?: Record<string, unknown>;
+	schema?: SpecSchema;
+	signatures?: SpecSignature[];
 };
-type SpecMember = unknown;
 type SpecExportKind = "function" | "class" | "variable" | "interface" | "type" | "enum" | "module" | "namespace" | "reference";
 type SpecTypeKind = "class" | "interface" | "type" | "enum";
 type SpecExport = {
-	id: string
-	name: string
-	kind: SpecExportKind
-	signatures?: SpecSignature[]
-	members?: SpecMember[]
-	type?: string | SpecSchema
-	schema?: SpecSchema
-	description?: string
-	examples?: string[]
-	source?: SpecSource
-	flags?: Record<string, unknown>
-	tags?: SpecTag[]
+	id: string;
+	name: string;
+	slug?: string;
+	displayName?: string;
+	category?: string;
+	importPath?: string;
+	kind: SpecExportKind;
+	signatures?: SpecSignature[];
+	typeParameters?: SpecTypeParameter[];
+	members?: SpecMember[];
+	type?: string | SpecSchema;
+	schema?: SpecSchema;
+	description?: string;
+	examples?: string[];
+	docs?: SpecDocsMetadata;
+	source?: SpecSource;
+	deprecated?: boolean;
+	flags?: Record<string, unknown>;
+	tags?: SpecTag[];
 };
 type SpecType = {
-	id: string
-	name: string
-	kind: SpecTypeKind
-	description?: string
-	schema?: SpecSchema
-	type?: string | SpecSchema
-	members?: SpecMember[]
-	source?: SpecSource
-	tags?: SpecTag[]
-	rawComments?: string
+	id: string;
+	name: string;
+	slug?: string;
+	displayName?: string;
+	category?: string;
+	importPath?: string;
+	kind: SpecTypeKind;
+	description?: string;
+	schema?: SpecSchema;
+	type?: string | SpecSchema;
+	members?: SpecMember[];
+	source?: SpecSource;
+	tags?: SpecTag[];
+	rawComments?: string;
 };
 type OpenPkgMeta = {
-	name: string
-	version?: string
-	description?: string
-	license?: string
-	repository?: string
-	ecosystem?: string
+	name: string;
+	version?: string;
+	description?: string;
+	license?: string;
+	repository?: string;
+	ecosystem?: string;
 };
 type OpenPkg = {
-	$schema?: string
-	openpkg: "0.1.0"
-	meta: OpenPkgMeta
-	exports: SpecExport[]
-	types?: SpecType[]
-	examples?: SpecExample[]
-	extensions?: SpecExtension
+	$schema?: string;
+	openpkg: "0.2.0";
+	meta: OpenPkgMeta;
+	exports: SpecExport[];
+	types?: SpecType[];
+	examples?: SpecExample[];
+	docs?: SpecDocsMetadata;
+	extensions?: SpecExtension;
+};
+declare function dereference(spec: OpenPkg): OpenPkg;
+type SpecDiff = {
+	breaking: string[];
+	nonBreaking: string[];
+	docsOnly: string[];
+	coverageDelta: number;
+	oldCoverage: number;
+	newCoverage: number;
+	newUndocumented: string[];
+	improvedExports: string[];
+	regressedExports: string[];
+	driftIntroduced: number;
+	driftResolved: number;
 };
+declare function diffSpec(oldSpec: OpenPkg, newSpec: OpenPkg): SpecDiff;
+declare function normalize(spec: OpenPkg): OpenPkg;
 type SpecError = {
-	instancePath: string
-	message: string
-	keyword: string
+	instancePath: string;
+	message: string;
+	keyword: string;
 };
 declare function validateSpec(spec: unknown): {
-	ok: true
+	ok: true;
 } | {
-	ok: false
-	errors: SpecError[]
+	ok: false;
+	errors: SpecError[];
 };
 declare function assertSpec(spec: unknown): asserts spec is OpenPkg;
 declare function getValidationErrors(spec: unknown): SpecError[];
-declare function normalize(spec: OpenPkg): OpenPkg;
-declare function dereference(spec: OpenPkg): OpenPkg;
-declare function migrate_0_1_0__to__0_2_0(spec: OpenPkg): OpenPkg;
-type SpecDiff = {
-	breaking: string[]
-	nonBreaking: string[]
-	docsOnly: string[]
-};
-declare function diffSpec(a: OpenPkg, b: OpenPkg): SpecDiff;
-export { validateSpec, normalize, migrate_0_1_0__to__0_2_0 as migrate, getValidationErrors, diffSpec, dereference, assertSpec, SpecTypeKind, SpecType, SpecTag, SpecSource, SpecSignatureReturn, SpecSignatureParameter, SpecSignature, SpecSchema, SpecMember, SpecExtension, SpecExportKind, SpecExport, SpecExample, SCHEMA_VERSION, SCHEMA_URL, OpenPkgMeta, OpenPkg, JSON_SCHEMA_DRAFT };
+export { validateSpec, normalize, getValidationErrors, diffSpec, dereference, assertSpec, SpecVisibility, SpecTypeParameter, SpecTypeKind, SpecType, SpecTag, SpecSource, SpecSignatureReturn, SpecSignatureParameter, SpecSignature, SpecSchema, SpecMember, SpecExtension, SpecExportKind, SpecExport, SpecExample, SpecDocsMetadata, SpecDocSignal, SpecDocDrift, SCHEMA_VERSION, SCHEMA_URL, OpenPkgMeta, OpenPkg, JSON_SCHEMA_DRAFT };