@openpkg-ts/sdk 0.1.0 → 0.30.0

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 (4) hide show
  1. package/README.md +106 -81
  2. package/dist/index.d.ts +1378 -43
  3. package/dist/index.js +5686 -1793
  4. package/package.json +22 -22
package/README.md CHANGED
@@ -1,125 +1,150 @@
1
- # OpenPkg SDK
1
+ # @openpkg-ts/sdk
2
2
 
3
- [![npm version](https://img.shields.io/npm/v/@openpkg-ts%2Fsdk.svg)](https://www.npmjs.com/package/@openpkg-ts/sdk)
3
+ Programmatic SDK for TypeScript API extraction and documentation generation.
4
4
 
5
- TypeScript SDK for generating and post-processing OpenPkg specs directly from your tooling.
6
-
7
- ## Installation
5
+ ## Install
8
6
 
9
7
  ```bash
10
- # npm
11
8
  npm install @openpkg-ts/sdk
9
+ ```
10
+
11
+ ## Quick Start
12
12
 
13
- # bun
14
- bun add @openpkg-ts/sdk
13
+ ```typescript
14
+ import { listExports, getExport, extractSpec, createDocs, toMarkdown } from '@openpkg-ts/sdk';
15
15
 
16
- # yarn
17
- yarn add @openpkg-ts/sdk
16
+ // List all exports
17
+ const { exports } = await listExports({ entryFile: './src/index.ts' });
18
18
 
19
- # pnpm
20
- pnpm add @openpkg-ts/sdk
19
+ // Get single export details
20
+ const { export: spec } = await getExport({ entryFile: './src/index.ts', exportName: 'myFunc' });
21
+
22
+ // Extract full spec
23
+ const { spec } = await extractSpec({ entryFile: './src/index.ts' });
24
+
25
+ // Generate docs
26
+ const docs = createDocs(spec);
27
+ const markdown = docs.toMarkdown();
21
28
  ```
22
29
 
23
- ## Quick Start
30
+ ## Primitives
24
31
 
25
- ```ts
26
- import { OpenPkg } from '@openpkg-ts/sdk';
32
+ Agent-native primitives for composable workflows:
27
33
 
28
- const openpkg = new OpenPkg({
29
- resolveExternalTypes: true,
30
- });
34
+ ### listExports
31
35
 
32
- const spec = await openpkg.analyzeFile('./src/index.ts', {
33
- filters: {
34
- include: ['createUser', 'deleteUser'],
35
- },
36
- });
36
+ List exports from entry point with metadata.
37
37
 
38
- console.log(`exports: ${spec.exports.length}`);
39
- console.log(`types: ${spec.types?.length ?? 0}`);
40
- ```
38
+ ```typescript
39
+ const { exports, errors } = await listExports({ entryFile: './src/index.ts' });
41
40
 
42
- `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.
41
+ // Returns: { name, kind, file, line, description }[]
42
+ ```
43
43
 
44
- ## Filtering Exports
44
+ ### getExport
45
45
 
46
- ```ts
47
- import { analyzeFile } from '@openpkg-ts/sdk';
46
+ Get detailed spec for a single export.
48
47
 
49
- const spec = await analyzeFile('./src/index.ts', {
50
- filters: {
51
- include: ['publicFunction'],
52
- exclude: ['internalHelper'],
53
- },
48
+ ```typescript
49
+ const { export: spec, types, errors } = await getExport({
50
+ entryFile: './src/index.ts',
51
+ exportName: 'createClient'
54
52
  });
55
53
  ```
56
54
 
57
- 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.
55
+ ### extractSpec
58
56
 
59
- ## Diagnostics
57
+ Generate full OpenPkg spec (all exports + types).
60
58
 
61
- Use the `analyzeFileWithDiagnostics` or `analyzeWithDiagnostics` helpers when you need visibility into parsing or filtering issues.
59
+ ```typescript
60
+ const { spec, diagnostics, verification } = await extractSpec({
61
+ entryFile: './src/index.ts',
62
+ maxTypeDepth: 4,
63
+ resolveExternalTypes: true,
64
+ only: ['use*'], // filter by pattern
65
+ ignore: ['*Internal'], // exclude by pattern
66
+ });
67
+ ```
62
68
 
63
- ```ts
64
- import { OpenPkg } from '@openpkg-ts/sdk';
69
+ ### diffSpecs
65
70
 
66
- const openpkg = new OpenPkg();
67
- const { spec, diagnostics } = await openpkg.analyzeFileWithDiagnostics('./src/index.ts');
71
+ Compare two specs for breaking changes.
68
72
 
69
- diagnostics.forEach((diagnostic) => {
70
- const location = diagnostic.location?.file
71
- ? `${diagnostic.location.file}:${diagnostic.location.line ?? '?'}:${diagnostic.location.column ?? '?'}`
72
- : '(unknown)';
73
- console.log(`[${diagnostic.severity}] ${location} ${diagnostic.message}`);
74
- });
73
+ ```typescript
74
+ import { diffSpecs } from '@openpkg-ts/sdk';
75
+
76
+ const diff = diffSpecs(oldSpec, newSpec);
77
+ console.log(`Breaking: ${diff.breaking.length}`);
75
78
  ```
76
79
 
77
- Diagnostics normalize TypeScript compiler messages into `error`, `warning`, and `info` severity levels so you can decide how to surface them in your own tools.
80
+ ## Documentation Generation
78
81
 
79
- ## Programmatic Workflows
82
+ ### createDocs / loadSpec
80
83
 
81
- ### Analyze in-memory code
84
+ ```typescript
85
+ import { createDocs, loadSpec } from '@openpkg-ts/sdk';
82
86
 
83
- ```ts
84
- import { analyze } from '@openpkg-ts/sdk';
87
+ // From file path
88
+ const docs = createDocs('./openpkg.json');
85
89
 
86
- const spec = await analyze(
87
- `export const sum = (a: number, b: number) => a + b;`,
88
- { filters: { include: ['sum'] } },
89
- );
90
+ // From spec object
91
+ const docs = loadSpec(spec);
90
92
  ```
91
93
 
92
- ### Batch project analysis
94
+ ### Render Functions
93
95
 
94
- ```ts
95
- import { OpenPkg } from '@openpkg-ts/sdk';
96
- import { glob } from 'glob';
96
+ ```typescript
97
+ // Full API reference
98
+ const markdown = docs.toMarkdown({ frontmatter: true, codeSignatures: true });
99
+ const html = docs.toHTML({ fullDocument: true, includeStyles: true });
100
+ const json = docs.toJSON();
97
101
 
98
- const openpkg = new OpenPkg();
99
- const files = await glob('packages/**/src/index.ts');
100
- const specs = await Promise.all(files.map((file) => openpkg.analyzeFile(file)));
102
+ // Single export
103
+ const markdown = docs.toMarkdown({ exportId: 'createClient' });
101
104
  ```
102
105
 
103
- ## API Surface
106
+ ### Navigation
104
107
 
105
- - `new OpenPkg(options?)`
106
- - `analyze(code, fileName?, options?)`
107
- - `analyzeFile(filePath, options?)`
108
- - `analyzeWithDiagnostics(code, fileName?, options?)`
109
- - `analyzeFileWithDiagnostics(filePath, options?)`
110
- - `analyze(code, options?)` – convenience wrapper
111
- - `analyzeFile(filePath, options?)` – convenience wrapper
112
- - `extractPackageSpec(entry, packageDir, source, options)` – lower-level extractor
113
- - Types: `OpenPkgSpec`, `FilterOptions`, `AnalyzeOptions`, `AnalysisResult`, `Diagnostic`
108
+ ```typescript
109
+ import { toFumadocsMetaJSON, toDocusaurusSidebarJS } from '@openpkg-ts/sdk';
114
110
 
115
- ## Development
111
+ const fumadocsMeta = toFumadocsMetaJSON(spec, { basePath: '/api' });
112
+ const docusaurusSidebar = toDocusaurusSidebarJS(spec);
113
+ ```
116
114
 
117
- ```bash
118
- git clone https://github.com/ryanwaits/openpkg.git
119
- cd openpkg
120
- bun install
121
- bun run build:sdk
122
- bun test
115
+ ### Search Index
116
+
117
+ ```typescript
118
+ import { toSearchIndex, toAlgoliaRecords } from '@openpkg-ts/sdk';
119
+
120
+ const searchIndex = toSearchIndex(spec);
121
+ const algoliaRecords = toAlgoliaRecords(spec, { indexName: 'api_docs' });
122
+ ```
123
+
124
+ ## Query Utilities
125
+
126
+ ```typescript
127
+ import {
128
+ buildSignatureString,
129
+ formatParameters,
130
+ formatReturnType,
131
+ getProperties,
132
+ getMethods,
133
+ resolveTypeRef,
134
+ } from '@openpkg-ts/sdk';
135
+ ```
136
+
137
+ ## Types
138
+
139
+ ```typescript
140
+ import type {
141
+ OpenPkg,
142
+ SpecExport,
143
+ ExtractOptions,
144
+ ExtractResult,
145
+ DocsInstance,
146
+ SimplifiedSpec,
147
+ } from '@openpkg-ts/sdk';
123
148
  ```
124
149
 
125
150
  ## License