camunda-schema-bundler 1.3.1 → 1.3.2
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.
- package/README.md +102 -18
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -53,32 +53,68 @@ Available binaries:
|
|
|
53
53
|
## CLI Usage
|
|
54
54
|
|
|
55
55
|
```bash
|
|
56
|
-
#
|
|
56
|
+
# Fetch from upstream and bundle (simplest usage — fetches from main)
|
|
57
57
|
camunda-schema-bundler \
|
|
58
|
-
--spec-dir external-spec/upstream/zeebe/gateway-protocol/src/main/proto/v2 \
|
|
59
58
|
--output-spec external-spec/bundled/rest-api.bundle.json \
|
|
60
59
|
--output-metadata external-spec/bundled/spec-metadata.json
|
|
61
60
|
|
|
62
|
-
#
|
|
61
|
+
# Fetch a specific branch/tag/SHA
|
|
62
|
+
camunda-schema-bundler --ref stable/8.8 \
|
|
63
|
+
--output-spec rest-api.bundle.json
|
|
64
|
+
|
|
65
|
+
# Auto-detect upstream ref from current git branch
|
|
66
|
+
# (main → main, stable/* → stable/*, other → main)
|
|
67
|
+
camunda-schema-bundler --auto-ref \
|
|
68
|
+
--output-spec external-spec/bundled/rest-api.bundle.json
|
|
69
|
+
|
|
70
|
+
# Use already-fetched spec (no network)
|
|
63
71
|
camunda-schema-bundler \
|
|
64
72
|
--spec-dir external-spec/upstream/zeebe/gateway-protocol/src/main/proto/v2 \
|
|
65
|
-
--output-spec external-spec/bundled/rest-api.bundle.json
|
|
66
|
-
|
|
73
|
+
--output-spec external-spec/bundled/rest-api.bundle.json
|
|
74
|
+
|
|
75
|
+
# Bundle with path-local deref (for C# / Microsoft.OpenApi)
|
|
76
|
+
camunda-schema-bundler --deref-path-local \
|
|
77
|
+
--output-spec external-spec/bundled/rest-api.bundle.json
|
|
78
|
+
|
|
79
|
+
# Check version
|
|
80
|
+
camunda-schema-bundler --version
|
|
67
81
|
```
|
|
68
82
|
|
|
69
83
|
### CLI Options
|
|
70
84
|
|
|
71
85
|
| Option | Description |
|
|
72
86
|
|---|---|
|
|
73
|
-
|
|
|
87
|
+
| **Modes** | |
|
|
88
|
+
| `--fetch` | Fetch upstream spec before bundling (default when no `--spec-dir`) |
|
|
89
|
+
| `--spec-dir <path>` | Use an existing local spec directory (skip fetch) |
|
|
90
|
+
| **Fetch options** | |
|
|
91
|
+
| `--ref <ref>` | Git ref to fetch: branch, tag, or SHA (default: `main`) |
|
|
92
|
+
| `--auto-ref` | Auto-detect ref from current git branch or `SPEC_REF` env var |
|
|
93
|
+
| `--repo-url <url>` | Git repo URL (default: `https://github.com/camunda/camunda.git`) |
|
|
94
|
+
| `--output-dir <path>` | Local directory for fetched spec files |
|
|
95
|
+
| `--skip-fetch-if-exists` | Skip fetch if the entry file already exists locally |
|
|
96
|
+
| **Bundle options** | |
|
|
74
97
|
| `--entry-file <name>` | Entry YAML file name (default: `rest-api.yaml`) |
|
|
75
98
|
| `--output-spec <path>` | Output path for the bundled JSON spec |
|
|
76
99
|
| `--output-metadata <path>` | Output path for the metadata IR JSON |
|
|
77
100
|
| `--deref-path-local` | Inline remaining path-local `$ref`s (needed for Microsoft.OpenApi) |
|
|
78
101
|
| `--allow-like-refs` | Don't fail on surviving path-local `$like` refs |
|
|
102
|
+
| **General** | |
|
|
103
|
+
| `--help`, `-h` | Show help |
|
|
104
|
+
| `--version`, `-v` | Show version |
|
|
105
|
+
|
|
106
|
+
### Auto-ref detection
|
|
107
|
+
|
|
108
|
+
The `--auto-ref` flag (and `detectUpstreamRef()` in the library API) resolves the upstream spec ref using this priority:
|
|
109
|
+
|
|
110
|
+
1. `SPEC_REF` environment variable (always wins)
|
|
111
|
+
2. Current git branch: `main` → `main`, `stable/X.Y` → `stable/X.Y`
|
|
112
|
+
3. Falls back to `main` for other branches or if git is unavailable
|
|
79
113
|
|
|
80
114
|
## Library API
|
|
81
115
|
|
|
116
|
+
### `bundle()` — Bundle from a local spec directory
|
|
117
|
+
|
|
82
118
|
```typescript
|
|
83
119
|
import { bundle } from 'camunda-schema-bundler';
|
|
84
120
|
|
|
@@ -86,30 +122,78 @@ const result = await bundle({
|
|
|
86
122
|
specDir: 'external-spec/upstream/zeebe/gateway-protocol/src/main/proto/v2',
|
|
87
123
|
outputSpec: 'external-spec/bundled/rest-api.bundle.json',
|
|
88
124
|
outputMetadata: 'external-spec/bundled/spec-metadata.json',
|
|
89
|
-
dereferencePathLocalRefs: false, // set true for C#
|
|
125
|
+
dereferencePathLocalRefs: false, // set true for C# / Python
|
|
90
126
|
});
|
|
91
127
|
|
|
92
128
|
console.log(result.stats);
|
|
93
|
-
// {
|
|
129
|
+
// {
|
|
130
|
+
// pathCount: 140, schemaCount: 511, augmentedSchemaCount: 511,
|
|
131
|
+
// promotedInlineSchemaCount: 46, freshDedupCount: 298,
|
|
132
|
+
// dereferencedPathLocalRefCount: 0, pathLocalLikeRefCount: 0
|
|
133
|
+
// }
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
### `fetchAndBundle()` — Fetch + bundle in one call
|
|
137
|
+
|
|
138
|
+
```typescript
|
|
139
|
+
import { fetchAndBundle } from 'camunda-schema-bundler';
|
|
140
|
+
|
|
141
|
+
const result = await fetchAndBundle({
|
|
142
|
+
ref: 'stable/8.8', // optional, default: "main"
|
|
143
|
+
outputDir: 'external-spec/upstream/zeebe/gateway-protocol/src/main/proto/v2',
|
|
144
|
+
outputSpec: 'external-spec/bundled/rest-api.bundle.json',
|
|
145
|
+
outputMetadata: 'external-spec/bundled/spec-metadata.json',
|
|
146
|
+
});
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
### `fetchSpec()` — Fetch only
|
|
150
|
+
|
|
151
|
+
```typescript
|
|
152
|
+
import { fetchSpec } from 'camunda-schema-bundler';
|
|
153
|
+
|
|
154
|
+
const { specDir, entryPath, fetched } = await fetchSpec({
|
|
155
|
+
ref: 'main',
|
|
156
|
+
outputDir: 'external-spec/upstream/zeebe/gateway-protocol/src/main/proto/v2',
|
|
157
|
+
skipIfExists: true, // skip if already fetched
|
|
158
|
+
});
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
### `detectUpstreamRef()` — Auto-detect git ref
|
|
162
|
+
|
|
163
|
+
```typescript
|
|
164
|
+
import { detectUpstreamRef } from 'camunda-schema-bundler';
|
|
94
165
|
|
|
95
|
-
|
|
96
|
-
// {
|
|
166
|
+
const { ref, source, branch } = detectUpstreamRef();
|
|
167
|
+
// { ref: "stable/8.8", source: "branch-match", branch: "stable/8.8" }
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
### Utility exports
|
|
171
|
+
|
|
172
|
+
```typescript
|
|
173
|
+
import {
|
|
174
|
+
hashDirectoryTree, // SHA-256 hash of a directory for drift detection
|
|
175
|
+
listFilesRecursive, // List all files in a directory recursively
|
|
176
|
+
findPathLocalLikeRefs, // Find surviving path-local $like refs in a spec
|
|
177
|
+
} from 'camunda-schema-bundler';
|
|
97
178
|
```
|
|
98
179
|
|
|
99
180
|
## Bundling Pipeline
|
|
100
181
|
|
|
101
|
-
1. **
|
|
102
|
-
2. **
|
|
103
|
-
3. **
|
|
182
|
+
1. **Fetch** (optional) — Sparse git clone of [camunda/camunda](https://github.com/camunda/camunda) to extract only the OpenAPI spec directory
|
|
183
|
+
2. **Bundle** — `SwaggerParser.bundle()` merges multi-file YAML into a single document
|
|
184
|
+
3. **Augment** — Scan all upstream YAML files and add any schemas missing from the bundle
|
|
185
|
+
4. **Normalize** — Rewrite path-local `$ref`s back to `#/components/schemas/...` using:
|
|
104
186
|
- Signature matching (canonical JSON comparison against known component schemas)
|
|
105
|
-
- `$like` → `LikeFilter` rewrite
|
|
187
|
+
- `$like` → `LikeFilter` rewrite (handles both `$like` and `%24like` encoded forms)
|
|
106
188
|
- Manual overrides for known tricky paths
|
|
107
189
|
- Inline deduplication
|
|
108
190
|
- `x-semantic-type` extension rewriting
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
191
|
+
5. **Promote** — Inline schemas that couldn't be matched to existing components are promoted to new named component schemas
|
|
192
|
+
6. **Fresh dedup** — Iterative pass (up to 10 rounds until convergence) that deduplicates newly-promoted schemas against each other and existing components using signature matching, including resolution through intermediate `$ref` chains
|
|
193
|
+
7. **Rewrite** — Decode URI-encoded internal refs (`%24like` → `$like`)
|
|
194
|
+
8. **Validate** — Fail-fast if any path-local `$like` refs survive (configurable with `--allow-like-refs`)
|
|
195
|
+
9. **Dereference** (optional, `--deref-path-local`) — Inline remaining path-local `$ref`s for strict generators
|
|
196
|
+
10. **Extract metadata** — Build the intermediate representation (semantic keys, unions, operations, etc.)
|
|
113
197
|
|
|
114
198
|
## Metadata IR
|
|
115
199
|
|
package/package.json
CHANGED