@openpkg-ts/sdk 0.1.0

package/README.md

@@ -0,0 +1,127 @@
+# OpenPkg SDK
+
+[![npm version](https://img.shields.io/npm/v/@openpkg-ts%2Fsdk.svg)](https://www.npmjs.com/package/@openpkg-ts/sdk)
+
+TypeScript SDK for generating and post-processing OpenPkg specs directly from your tooling.
+
+## Installation
+
+```bash
+# npm
+npm install @openpkg-ts/sdk
+
+# bun
+bun add @openpkg-ts/sdk
+
+# yarn
+yarn add @openpkg-ts/sdk
+
+# pnpm
+pnpm add @openpkg-ts/sdk
+```
+
+## Quick Start
+
+```ts
+import { OpenPkg } from '@openpkg-ts/sdk';
+
+const openpkg = new OpenPkg({
+  resolveExternalTypes: true,
+});
+
+const spec = await openpkg.analyzeFile('./src/index.ts', {
+  filters: {
+    include: ['createUser', 'deleteUser'],
+  },
+});
+
+console.log(`exports: ${spec.exports.length}`);
+console.log(`types: ${spec.types?.length ?? 0}`);
+```
+
+`OpenPkg` automatically resolves local sources, merges in declaration files, and keeps type references intact. Use `filters.include` / `filters.exclude` to narrow the surface area that lands in the final spec.
+
+## Filtering Exports
+
+```ts
+import { analyzeFile } from '@openpkg-ts/sdk';
+
+const spec = await analyzeFile('./src/index.ts', {
+  filters: {
+    include: ['publicFunction'],
+    exclude: ['internalHelper'],
+  },
+});
+```
+
+Filtering trims both the `exports` array and orphaned items under `types`. The SDK will surface informational diagnostics whenever an identifier cannot be located or when filtering drops transitive types you may still need.
+
+## Diagnostics
+
+Use the `analyzeFileWithDiagnostics` or `analyzeWithDiagnostics` helpers when you need visibility into parsing or filtering issues.
+
+```ts
+import { OpenPkg } from '@openpkg-ts/sdk';
+
+const openpkg = new OpenPkg();
+const { spec, diagnostics } = await openpkg.analyzeFileWithDiagnostics('./src/index.ts');
+
+diagnostics.forEach((diagnostic) => {
+  const location = diagnostic.location?.file
+    ? `${diagnostic.location.file}:${diagnostic.location.line ?? '?'}:${diagnostic.location.column ?? '?'}`
+    : '(unknown)';
+  console.log(`[${diagnostic.severity}] ${location} ${diagnostic.message}`);
+});
+```
+
+Diagnostics normalize TypeScript compiler messages into `error`, `warning`, and `info` severity levels so you can decide how to surface them in your own tools.
+
+## Programmatic Workflows
+
+### Analyze in-memory code
+
+```ts
+import { analyze } from '@openpkg-ts/sdk';
+
+const spec = await analyze(
+  `export const sum = (a: number, b: number) => a + b;`,
+  { filters: { include: ['sum'] } },
+);
+```
+
+### Batch project analysis
+
+```ts
+import { OpenPkg } from '@openpkg-ts/sdk';
+import { glob } from 'glob';
+
+const openpkg = new OpenPkg();
+const files = await glob('packages/**/src/index.ts');
+const specs = await Promise.all(files.map((file) => openpkg.analyzeFile(file)));
+```
+
+## API Surface
+
+- `new OpenPkg(options?)`
+  - `analyze(code, fileName?, options?)`
+  - `analyzeFile(filePath, options?)`
+  - `analyzeWithDiagnostics(code, fileName?, options?)`
+  - `analyzeFileWithDiagnostics(filePath, options?)`
+- `analyze(code, options?)` – convenience wrapper
+- `analyzeFile(filePath, options?)` – convenience wrapper
+- `extractPackageSpec(entry, packageDir, source, options)` – lower-level extractor
+- Types: `OpenPkgSpec`, `FilterOptions`, `AnalyzeOptions`, `AnalysisResult`, `Diagnostic`
+
+## Development
+
+```bash
+git clone https://github.com/ryanwaits/openpkg.git
+cd openpkg
+bun install
+bun run build:sdk
+bun test
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+interface OpenPkgOptions {
+	includePrivate?: boolean;
+	followImports?: boolean;
+	maxDepth?: number;
+	resolveExternalTypes?: boolean;
+}
+import { z } from "zod";
+import { OpenPkg } from "@openpkg-ts/spec";
+declare const openPkgSchema: z.ZodTypeAny;
+type OpenPkgSpec = OpenPkg;
+declare function extractPackageSpec(entryFile: string, packageDir?: string, content?: string, options?: OpenPkgOptions): Promise<OpenPkgSpec>;
+interface FilterOptions {
+	include?: string[];
+	exclude?: string[];
+}
+interface Diagnostic {
+	message: string;
+	severity: "error" | "warning" | "info";
+	location?: {
+		file: string
+		line?: number
+		column?: number
+	};
+}
+interface AnalysisResult {
+	spec: OpenPkgSpec;
+	diagnostics: Diagnostic[];
+	metadata: AnalysisMetadata;
+}
+interface AnalysisMetadata {
+	baseDir: string;
+	configPath?: string;
+	packageJsonPath?: string;
+	hasNodeModules: boolean;
+	resolveExternalTypes: boolean;
+}
+interface AnalyzeOptions {
+	filters?: FilterOptions;
+}
+declare class OpenPkg2 {
+	private readonly options;
+	constructor(options?: OpenPkgOptions);
+	analyze(code: string, fileName?: string, analyzeOptions?: AnalyzeOptions): Promise<OpenPkgSpec>;
+	analyzeFile(filePath: string, analyzeOptions?: AnalyzeOptions): Promise<OpenPkgSpec>;
+	analyzeProject(entryPath: string, analyzeOptions?: AnalyzeOptions): Promise<OpenPkgSpec>;
+	analyzeWithDiagnostics(code: string, fileName?: string, analyzeOptions?: AnalyzeOptions): Promise<AnalysisResult>;
+	analyzeFileWithDiagnostics(filePath: string, analyzeOptions?: AnalyzeOptions): Promise<AnalysisResult>;
+	private normalizeDiagnostic;
+	private mapSeverity;
+	private normalizeMetadata;
+	private applySpecFilters;
+}
+declare function analyze(code: string, options?: AnalyzeOptions): Promise<OpenPkgSpec>;
+declare function analyzeFile(filePath: string, options?: AnalyzeOptions): Promise<OpenPkgSpec>;
+export { openPkgSchema, extractPackageSpec, analyzeFile, analyze, OpenPkgSpec, OpenPkgOptions, OpenPkg2 as OpenPkg, FilterOptions, Diagnostic, AnalyzeOptions, AnalysisResult };