apcore-toolkit 0.10.2 → 0.11.1

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.11.1] - 2026-09-06
+
+Patch release. Bumps the required `apcore-js` floor to `0.30.0`. apcore-js 0.30.0 adds `Config.projectRoot` / `userLevelConfigPaths()`, a new `Config.load` deprecation notice for out-of-tree relative path-typed values, discards a set-but-empty path-typed `APCORE_*` override, and fixes `loadBindingDir` to read `bindings.dir` from the passed `Config` instead of re-reading `APCORE_BINDINGS_DIR` directly — all `Config`/binding-loader internals this toolkit never touches. The complete apcore-js surface this toolkit imports is `ModuleAnnotations`, `ModuleExample`, `DEFAULT_ANNOTATIONS`, `annotationsFromJSON`, `annotationsToJSON`, `Context`, `FunctionModule`, `jsonSchemaToTypeBox`, `ErrorCodes` and `ModuleError` (confirmed via grep: no `Config`, `loadBindingDir`, `ACL`, `ApprovalRequest`, `CancelToken` or `Executor` reference exists in `src/`). No code or API changes; all 680 tests pass unmodified against apcore-js 0.30.0. `pre-commit run --all-files` (`apdev-js check-chars`, `apdev-js check-imports`, `tsc --noEmit`) and `pnpm build` clean.
+
+## [0.11.0] - 2026-09-05
+
+Feature release: ships `OpenAPIScanner` and `TuiViewModel`, version-aligned with the Python and Rust SDKs.
+
+### Added
+
+- **`OpenAPIScanner`, `deriveModuleId`** (`src/openapi-scanner.ts`) and **`loadSpec`** (`src/openapi-loader.ts`, Node-only — kept in a separate file so `OpenAPIScanner` stays importable from `apcore-toolkit/browser`) — turn an OpenAPI 3.0/3.1 document into a `ScannedModule[]`, one module per operation. Re-exported from the package root and (excluding `loadSpec`) from `apcore-toolkit/browser`.
+- **`TuiViewModel`, `Column`, `Row`, `Cell`, `Sort`, `Filter`, `TonePalette`, `ToneRule`, `Group`, `modulesToViewModel`, `formatViewModel`** (`src/tui-view-model.ts`) — byte-equivalent module-list view-model builder and canonical JSON encoder. Re-exported from the package root and `apcore-toolkit/browser` (pure, no Node dependency).
+- 40 new tests: 35 conformance cases against the shared corpus in `apcore-toolkit/conformance/fixtures/` (`tests/openapi-scan-conformance.test.ts`, `tests/view-model-conformance.test.ts`), plus hand-written regression tests (`tests/openapi-scanner.test.ts`, `tests/tui-view-model.test.ts`).
+
+### Changed
+
+- **Required `apcore-js` floor raised to `0.29.0`.** apcore-js 0.29.0 adds `ApprovalRequest.callerId` / `.action` and `CancelToken.raiseIfCancelled()` (both additive), changes `AsyncTaskManager.startReaper()` to return `Promise<ReaperHandle>` (breaking only for a caller that does not `await` it), and closes the ACL pattern-array shape at every entry point — `callers` / `targets` of `[]`, `['$or']`, `['$not']` or the multi-operand `['$not', p1, p2]` are now refused with `ACLRuleError` instead of silently matching nothing ([apcore#112](https://github.com/aiperceivable/apcore/issues/112)). None of it touches the surface this toolkit imports: `FunctionModule`, `Registry`, `jsonSchemaToTypeBox`, `ModuleAnnotations`, `ModuleExample`, `Context`, `DEFAULT_ANNOTATIONS`, `annotationsToJSON` and `annotationsFromJSON` are the complete set (confirmed by grepping every `from 'apcore-js'` in `src/`; no `ACL`, `ApprovalRequest`, `CancelToken` or `AsyncTaskManager` reference exists). No code or API changes; all 657 tests pass unmodified against apcore-js 0.29.0, and `apdev-js check-imports --package apcore-js` is clean.
+
+### Fixed
+
+- **`TuiViewModel`'s `Filter.annotations` silently excluded every module when filtering by `requires_approval` or `open_world`.** The filter's flag names are the spec's snake_case (matching Python/Rust), but the installed `apcore-js` `ModuleAnnotations` type uses camelCase fields, so the raw property lookup always returned `undefined`. Fixed with an explicit snake_case → camelCase name mapping; regression tests added. Single-word flags (`readonly`, `destructive`, `idempotent`, `streaming`, `cacheable`, `paginated`, `discoverable`) were unaffected.
+- **`OpenAPIScanner`'s `deprecated` field used truthy coercion instead of a strict boolean check.** A malformed non-boolean value (e.g. the string `"false"`) was treated as deprecated; now requires the literal `true`, matching Rust.
+- Non-string `operationId` no longer leaks into `metadata.openapi.operation_id`.
+
+All 657 tests pass (was 652 at 0.10.2). `tsc --noEmit` and `npm run build` clean.
+
 ## [0.10.2] - 2026-09-01
 
 Patch release. Bumps the required `apcore-js` floor to `0.28.0`. The 0.28.0 release is scoped entirely to the ACL/Executor governance layer (argument-scoped approval, `ACL.defaultEffect`/`rules` accessors, `ACL.validateRules()`, `ExecutionPolicy.resolve()` call-site parameters, `Executor.governanceState()`) — none of it touches `Registry`, `FunctionModule`, `jsonSchemaToTypeBox`, or module annotations, which is all this toolkit uses (confirmed via grep). No code or API changes; all 617 tests pass unmodified against apcore-js 0.28.0.

package/README.md

@@ -80,7 +80,7 @@ const regWriter = new RegistryWriter();
 await regWriter.write(modules, registry);
 
 // Or use the factory
-const writer = getWriter('yaml'); // 'yaml' | 'typescript' | 'registry'
+const writer = getWriter('yaml'); // 'yaml' | 'typescript' | 'registry' | 'http-proxy'
 ```
 
 ### Conformance Verification
@@ -225,16 +225,33 @@ The **Browser** column marks whether a symbol is also re-exported from
 | `HTTPProxyRegistryWriter` | ✓ | Registers modules as HTTP-proxied entries in an in-memory registry. Each module's `execute()` forwards inputs to a backend URL via global `fetch`. Works in any runtime with `fetch` (Node 20+, browsers, edge, workers). |
 | `HTTPProxyRegistryWriterError` | ✓ | Error class thrown when HTTP fields cannot be extracted from a `ScannedModule` |
 | `getWriter()` | | Factory for writer instances |
-| `assertAnnotationsPreserved()` | ✓ | Conformance check for adapter test suites: registers a module and asserts its behavioral annotations (`requiresApproval` / `destructive`) survive `getDefinition`; throws otherwise. Guards against a writer silently disabling approval/ACL gating |
+| `assertAnnotationsPreserved()` | | Conformance check for adapter test suites: registers a module and asserts its behavioral annotations (`requiresApproval` / `destructive`) survive `getDefinition`; throws otherwise. Guards against a writer silently disabling approval/ACL gating |
 | `extractInputSchema()` | ✓ | Extract input schema from OpenAPI operation |
 | `extractOutputSchema()` | ✓ | Extract output schema from OpenAPI operation |
 | `resolveRef()` | ✓ | Resolve `$ref` in OpenAPI documents |
 | `resolveSchema()` | ✓ | Resolve schema with single-level `$ref` support |
 | `deepResolveRefs()` | ✓ | Recursively resolve all nested `$ref` pointers in a schema |
 | `enrichSchemaDescriptions()` | ✓ | Merge parameter descriptions into schema |
+| `OpenAPIScanner` _(v0.11.0)_ | ✓ | Turn an OpenAPI 3.x document into `ScannedModule[]`. Pure and synchronous — no I/O |
+| `OpenAPIScanOptions` _(v0.11.0)_ | ✓ | Options for `OpenAPIScanner.scan()` |
+| `deriveModuleId()` _(v0.11.0)_ | ✓ | Derive a stable, byte-identical `moduleId` for an OpenAPI operation; primary subject of the cross-SDK conformance corpus |
+| `InvalidSpecError` _(v0.11.0)_ | ✓ | Thrown by `OpenAPIScanner.scan()` when the input isn't a recognisable OpenAPI 3.0.x/3.1.x document |
+| `loadSpec()` _(v0.11.0)_ | | Fetch/parse an OpenAPI document from a local filesystem path or an `http(s)://` URL |
+| `LoadSpecOptions` _(v0.11.0)_ | | Options for `loadSpec()` |
 | `toMarkdown()` | ✓ | Convert dict to formatted Markdown |
-| `formatCsv()` _(v0.7.0)_ | ✓ | Byte-equivalent RFC 4180 CSV. Header = union of keys; canonical JSON for nested cells; CRLF terminator |
-| `formatJsonl()` _(v0.7.0)_ | ✓ | Byte-equivalent JSON Lines. Compact JSON per row, LF terminator |
+| `formatCsv()` _(v0.7.0)_ | | Byte-equivalent RFC 4180 CSV. Header = union of keys; canonical JSON for nested cells; CRLF terminator |
+| `formatJsonl()` _(v0.7.0)_ | | Byte-equivalent JSON Lines. Compact JSON per row, LF terminator |
+| `TuiViewModel` _(v0.11.0)_ | ✓ | The V1 `TuiViewModel` wire-format envelope: columns, rows, sort/filter intent, tone palette |
+| `modulesToViewModel()` _(v0.11.0)_ | ✓ | Build a byte-equivalent `TuiViewModel` from scanned modules |
+| `formatViewModel()` _(v0.11.0)_ | ✓ | Canonical, byte-identical compact JSON encoding of a `TuiViewModel` |
+| `Column` _(v0.11.0)_ | ✓ | A view-model column: render order and `Row.cells` index lookup |
+| `Row` _(v0.11.0)_ | ✓ | A view-model row; `cells[i]` corresponds to `columns[i]` |
+| `Cell` _(v0.11.0)_ | ✓ | A single table cell (discriminated union by `kind`) |
+| `Sort` _(v0.11.0)_ | ✓ | Annotates which sort the toolkit (or the caller) applied |
+| `Filter` _(v0.11.0)_ | ✓ | Annotates which filter the toolkit applied |
+| `TonePalette` _(v0.11.0)_ | ✓ | A named, ordered set of `ToneRule` |
+| `ToneRule` _(v0.11.0)_ | ✓ | First-match-wins rule mapping a tag to a semantic tone |
+| `Group` _(v0.11.0)_ | ✓ | A named group of row indices, present only when `kind === "grouped"` |
 | `moduleToDict()` | ✓ | Serialize module to snake_case dict |
 | `modulesToDicts()` | ✓ | Batch serialize modules |
 | `annotationsToDict()` | ✓ | Convert annotations to plain dict |

package/dist/browser/index.d.ts

@@ -14,4 +14,8 @@ export { WriteError, InvalidFormatError } from '../output/errors.js';
 export { RegistryVerifier, runVerifierChain } from '../output/verify-core.js';
 export { HTTPProxyRegistryWriter, HTTPProxyRegistryWriterError, } from '../output/http-proxy-writer.js';
 export type { HTTPProxyRegistryWriterOptions, ProxyRegistry, } from '../output/http-proxy-writer.js';
+export { OpenAPIScanner, deriveModuleId, InvalidSpecError } from '../openapi-scanner.js';
+export type { OpenAPIScanOptions } from '../openapi-scanner.js';
+export { modulesToViewModel, formatViewModel } from '../tui-view-model.js';
+export type { TuiViewModel, Column, Row, Cell, Sort, Filter, TonePalette, ToneRule, Group, View, Justify, Exposure, Direction, Tone, CellKind, ModulesToViewModelOptions, } from '../tui-view-model.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/browser/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":"AAkBA,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/D,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG5C,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EACL,UAAU,EACV,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,cAAc,GACf,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAOpD,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAK/D,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAMrE,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAO9E,OAAO,EACL,uBAAuB,EACvB,4BAA4B,GAC7B,MAAM,gCAAgC,CAAC;AACxC,YAAY,EACV,8BAA8B,EAC9B,aAAa,GACd,MAAM,gCAAgC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":"AAkBA,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/D,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG5C,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EACL,UAAU,EACV,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,cAAc,GACf,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAOpD,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAK/D,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAMrE,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAO9E,OAAO,EACL,uBAAuB,EACvB,4BAA4B,GAC7B,MAAM,gCAAgC,CAAC;AACxC,YAAY,EACV,8BAA8B,EAC9B,aAAa,GACd,MAAM,gCAAgC,CAAC;AAOxC,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzF,YAAY,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAGhE,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC3E,YAAY,EACV,YAAY,EACZ,MAAM,EACN,GAAG,EACH,IAAI,EACJ,IAAI,EACJ,MAAM,EACN,WAAW,EACX,QAAQ,EACR,KAAK,EACL,IAAI,EACJ,OAAO,EACP,QAAQ,EACR,SAAS,EACT,IAAI,EACJ,QAAQ,EACR,yBAAyB,GAC1B,MAAM,sBAAsB,CAAC"}

package/dist/browser/index.js

@@ -43,4 +43,12 @@ export { RegistryVerifier, runVerifierChain } from '../output/verify-core.js';
 // Works in any environment where `fetch` is available (Node 20+, browsers,
 // Deno, workers).
 export { HTTPProxyRegistryWriter, HTTPProxyRegistryWriterError, } from '../output/http-proxy-writer.js';
+// ---- OpenAPI scanner (pure — no I/O) --------------------------------------
+// `OpenAPIScanner.scan()` and `deriveModuleId` are pure document traversal
+// with no Node.js dependency. `loadSpec` (in `../openapi-loader.js`) is
+// intentionally NOT re-exported here — its local-file-path branch needs
+// Node's `fs`, matching how `BindingLoader` stays Node-only above.
+export { OpenAPIScanner, deriveModuleId, InvalidSpecError } from '../openapi-scanner.js';
+// ---- TUI view model (pure data, no Node.js dependency) --------------------
+export { modulesToViewModel, formatViewModel } from '../tui-view-model.js';
 //# sourceMappingURL=index.js.map

package/dist/browser/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,0EAA0E;AAC1E,0EAA0E;AAC1E,wEAAwE;AACxE,uEAAuE;AACvE,sBAAsB;AACtB,EAAE;AACF,6EAA6E;AAC7E,wEAAwE;AACxE,0EAA0E;AAC1E,0EAA0E;AAC1E,wEAAwE;AACxE,qEAAqE;AACrE,yEAAyE;AACzE,MAAM;AAIN,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/D,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,6EAA6E;AAC7E,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAE7B,6EAA6E;AAC7E,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EACL,UAAU,EACV,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,eAAe,CAAC;AAEvB,6EAA6E;AAC7E,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,cAAc,GACf,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEpD,6EAA6E;AAC7E,4EAA4E;AAC5E,6EAA6E;AAC7E,2EAA2E;AAC3E,qDAAqD;AACrD,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAO9B,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAErE,6EAA6E;AAC7E,gFAAgF;AAChF,2EAA2E;AAC3E,4BAA4B;AAC5B,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAE9E,6EAA6E;AAC7E,sEAAsE;AACtE,yEAAyE;AACzE,2EAA2E;AAC3E,kBAAkB;AAClB,OAAO,EACL,uBAAuB,EACvB,4BAA4B,GAC7B,MAAM,gCAAgC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,0EAA0E;AAC1E,0EAA0E;AAC1E,wEAAwE;AACxE,uEAAuE;AACvE,sBAAsB;AACtB,EAAE;AACF,6EAA6E;AAC7E,wEAAwE;AACxE,0EAA0E;AAC1E,0EAA0E;AAC1E,wEAAwE;AACxE,qEAAqE;AACrE,yEAAyE;AACzE,MAAM;AAIN,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/D,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,6EAA6E;AAC7E,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAE7B,6EAA6E;AAC7E,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EACL,UAAU,EACV,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,eAAe,CAAC;AAEvB,6EAA6E;AAC7E,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,cAAc,GACf,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEpD,6EAA6E;AAC7E,4EAA4E;AAC5E,6EAA6E;AAC7E,2EAA2E;AAC3E,qDAAqD;AACrD,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAO9B,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAErE,6EAA6E;AAC7E,gFAAgF;AAChF,2EAA2E;AAC3E,4BAA4B;AAC5B,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAE9E,6EAA6E;AAC7E,sEAAsE;AACtE,yEAAyE;AACzE,2EAA2E;AAC3E,kBAAkB;AAClB,OAAO,EACL,uBAAuB,EACvB,4BAA4B,GAC7B,MAAM,gCAAgC,CAAC;AAMxC,8EAA8E;AAC9E,2EAA2E;AAC3E,wEAAwE;AACxE,wEAAwE;AACxE,mEAAmE;AACnE,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAGzF,8EAA8E;AAC9E,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/index.d.ts

@@ -12,7 +12,7 @@ export { AIEnhancer } from './ai-enhancer.js';
 export type { AIEnhancerOptions, Enhancer } from './ai-enhancer.js';
 export { DisplayResolver } from './display/resolver.js';
 export type { DisplayResolveOptions, DisplayMetadata, SurfaceDisplay, } from './display/resolver.js';
-export { BindingLoader, BindingLoadError } from './binding-loader.js';
+export { BindingLoader, BindingLoadError, BindingParser, parseBindingDocument, } from './binding-loader.js';
 export type { BindingLoadOptions } from './binding-loader.js';
 export { YAMLWriter } from './output/yaml-writer.js';
 export { TypeScriptWriter } from './output/typescript-writer.js';
@@ -20,6 +20,12 @@ export { RegistryWriter } from './output/registry-writer.js';
 export { HTTPProxyRegistryWriter, HTTPProxyRegistryWriterError, } from './output/http-proxy-writer.js';
 export type { HTTPProxyRegistryWriterOptions, ProxyRegistry, } from './output/http-proxy-writer.js';
 export { getWriter } from './output/factory.js';
+export { OpenAPIScanner, deriveModuleId, InvalidSpecError } from './openapi-scanner.js';
+export type { OpenAPIScanOptions } from './openapi-scanner.js';
+export { loadSpec } from './openapi-loader.js';
+export type { LoadSpecOptions } from './openapi-loader.js';
+export { modulesToViewModel, formatViewModel } from './tui-view-model.js';
+export type { TuiViewModel, Column, Row, Cell, Sort, Filter, TonePalette, ToneRule, Group, View, Justify, Exposure, Direction, Tone, CellKind, ModulesToViewModelOptions, } from './tui-view-model.js';
 export { assertAnnotationsPreserved, DEFAULT_CONFORMANCE_FIELDS } from './conformance.js';
 export type { AnnotationCarryingRegistry, AnnotationWriter } from './conformance.js';
 export type { WriteResult, VerifyResult, Verifier } from './output/types.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAU9D,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EACL,UAAU,EACV,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EACL,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,SAAS,EACT,WAAW,GACZ,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EACV,WAAW,EACX,WAAW,EACX,OAAO,EACP,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,YAAY,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACpE,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,YAAY,EACV,qBAAqB,EACrB,eAAe,EACf,cAAc,GACf,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACtE,YAAY,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EACL,uBAAuB,EACvB,4BAA4B,GAC7B,MAAM,+BAA+B,CAAC;AACvC,YAAY,EACV,8BAA8B,EAC9B,aAAa,GACd,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,0BAA0B,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AAC1F,YAAY,EAAE,0BAA0B,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACrF,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAG7E,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,EACL,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAK/B,eAAO,MAAM,OAAO,EAAE,MAAqB,CAAC;AAQ5C,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAG7D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAEnD;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,CAE5E"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -15,12 +15,15 @@ export { resolveTarget } from './resolve-target.js';
 export { toMarkdown, formatSchema, formatModule, formatModules, formatCsv, formatJsonl, } from './formatting/index.js';
 export { AIEnhancer } from './ai-enhancer.js';
 export { DisplayResolver } from './display/resolver.js';
-export { BindingLoader, BindingLoadError } from './binding-loader.js';
+export { BindingLoader, BindingLoadError, BindingParser, parseBindingDocument, } from './binding-loader.js';
 export { YAMLWriter } from './output/yaml-writer.js';
 export { TypeScriptWriter } from './output/typescript-writer.js';
 export { RegistryWriter } from './output/registry-writer.js';
 export { HTTPProxyRegistryWriter, HTTPProxyRegistryWriterError, } from './output/http-proxy-writer.js';
 export { getWriter } from './output/factory.js';
+export { OpenAPIScanner, deriveModuleId, InvalidSpecError } from './openapi-scanner.js';
+export { loadSpec } from './openapi-loader.js';
+export { modulesToViewModel, formatViewModel } from './tui-view-model.js';
 export { assertAnnotationsPreserved, DEFAULT_CONFORMANCE_FIELDS } from './conformance.js';
 // TS-only ergonomic factory: Python/Rust callers construct WriteResult directly
 // via dataclass/struct literals. No counterpart in apcore-toolkit-python/-rust.

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9D,2BAA2B;AAC3B,2BAA2B;AAC3B,+EAA+E;AAC/E,0EAA0E;AAC1E,4EAA4E;AAC5E,+CAA+C;AAC/C,yDAAyD;AAEzD,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EACL,UAAU,EACV,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EACL,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,SAAS,EACT,WAAW,GACZ,MAAM,uBAAuB,CAAC;AAU/B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAMxD,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAEtE,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EACL,uBAAuB,EACvB,4BAA4B,GAC7B,MAAM,+BAA+B,CAAC;AAKvC,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,0BAA0B,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AAG1F,gFAAgF;AAChF,gFAAgF;AAChF,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,EACL,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAChD,MAAM,IAAI,GAAG,QAAQ,CAAC,iBAAiB,CAAwB,CAAC;AAChE,MAAM,CAAC,MAAM,OAAO,GAAW,IAAI,CAAC,OAAO,CAAC;AAE5C,iEAAiE;AACjE,2EAA2E;AAC3E,oEAAoE;AACpE,mEAAmE;AACnE,sEAAsE;AACtE,8BAA8B;AAC9B,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE7D,OAAO,EAAE,WAAW,IAAI,YAAY,EAAE,MAAM,cAAc,CAAC;AAG3D;;;;;;GAMG;AACH,MAAM,UAAU,0BAA0B,CAAC,MAAc;IACvD,OAAO,YAAY,CAAC,0BAA0B,CAAC,MAAM,CAAC,CAAC;AACzD,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9D,2BAA2B;AAC3B,2BAA2B;AAC3B,+EAA+E;AAC/E,0EAA0E;AAC1E,4EAA4E;AAC5E,+CAA+C;AAC/C,yDAAyD;AAEzD,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EACL,UAAU,EACV,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EACL,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,SAAS,EACT,WAAW,GACZ,MAAM,uBAAuB,CAAC;AAU/B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAMxD,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EACL,uBAAuB,EACvB,4BAA4B,GAC7B,MAAM,+BAA+B,CAAC;AAKvC,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExF,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAE/C,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAmB1E,OAAO,EAAE,0BAA0B,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AAG1F,gFAAgF;AAChF,gFAAgF;AAChF,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,EACL,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAChD,MAAM,IAAI,GAAG,QAAQ,CAAC,iBAAiB,CAAwB,CAAC;AAChE,MAAM,CAAC,MAAM,OAAO,GAAW,IAAI,CAAC,OAAO,CAAC;AAE5C,iEAAiE;AACjE,2EAA2E;AAC3E,oEAAoE;AACpE,mEAAmE;AACnE,sEAAsE;AACtE,8BAA8B;AAC9B,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE7D,OAAO,EAAE,WAAW,IAAI,YAAY,EAAE,MAAM,cAAc,CAAC;AAG3D;;;;;;GAMG;AACH,MAAM,UAAU,0BAA0B,CAAC,MAAc;IACvD,OAAO,YAAY,CAAC,0BAA0B,CAAC,MAAM,CAAC,CAAC;AACzD,CAAC"}

package/dist/openapi-loader.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `loadSpec` — fetch/parse an OpenAPI document from a local path or
+ * `http(s)://` URL.
+ *
+ * Convenience helper, explicitly outside the conformance corpus (I/O
+ * behaviour is deliberately not byte-specified). The URL/path is taken
+ * verbatim — no candidate paths are probed. See `Contract: load_spec` in
+ * `apcore-toolkit/docs/features/openapi-scanner.md`.
+ *
+ * Kept in its own file (not `openapi-scanner.ts`) because it needs Node's
+ * `fs` for the local-file-path branch, and `OpenAPIScanner` /
+ * `deriveModuleId` are pure and re-exported from `apcore-toolkit/browser`.
+ * Mirrors the existing `binding-parser.ts` (pure) / `binding-loader.ts`
+ * (Node-only) split in this package.
+ *
+ * Security: `source` is trusted input. Callers taking a URL from an
+ * untrusted source are responsible for their own allowlisting (SSRF) — see
+ * the spec doc's Security Considerations.
+ */
+/** Options for {@link loadSpec}. */
+export interface LoadSpecOptions {
+    /** Extra request headers (API-version headers, tenant selectors, ...). Ignored for local files. */
+    headers?: Record<string, string>;
+    /** Callable returning auth headers, invoked once per fetch. Ignored for local files. */
+    authHeaderFactory?: () => Record<string, string>;
+    /** Request timeout in milliseconds. Defaults to 30_000 (30s). Ignored for local files. */
+    timeout?: number;
+    /** Optional fetch implementation (primarily for tests). Defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Load and parse an OpenAPI document from a local filesystem path or an
+ * `http(s)://` URL, taken verbatim (no candidate paths are probed).
+ *
+ * JSON-or-YAML is sniffed from the trimmed text: `{`/`[` parses as JSON
+ * (via `JSON.parse`, whose `SyntaxError` propagates on malformed input);
+ * anything else parses as YAML via `js-yaml` (already a dependency of this
+ * package), with parse errors normalised to `SyntaxError` for the same
+ * cross-SDK error contract.
+ *
+ * @throws {Error} File not found/unreadable, or HTTP non-2xx / network failure.
+ * @throws {SyntaxError} Malformed JSON or YAML.
+ */
+export declare function loadSpec(source: string, options?: LoadSpecOptions): Promise<Record<string, unknown>>;
+//# sourceMappingURL=openapi-loader.d.ts.map

package/dist/openapi-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-loader.d.ts","sourceRoot":"","sources":["../src/openapi-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAKH,oCAAoC;AACpC,MAAM,WAAW,eAAe;IAC9B,mGAAmG;IACnG,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,wFAAwF;IACxF,iBAAiB,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjD,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2FAA2F;IAC3F,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAsBD;;;;;;;;;;;;GAYG;AACH,wBAAsB,QAAQ,CAC5B,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CA4ClC"}

package/dist/openapi-loader.js

@@ -0,0 +1,95 @@
+/**
+ * `loadSpec` — fetch/parse an OpenAPI document from a local path or
+ * `http(s)://` URL.
+ *
+ * Convenience helper, explicitly outside the conformance corpus (I/O
+ * behaviour is deliberately not byte-specified). The URL/path is taken
+ * verbatim — no candidate paths are probed. See `Contract: load_spec` in
+ * `apcore-toolkit/docs/features/openapi-scanner.md`.
+ *
+ * Kept in its own file (not `openapi-scanner.ts`) because it needs Node's
+ * `fs` for the local-file-path branch, and `OpenAPIScanner` /
+ * `deriveModuleId` are pure and re-exported from `apcore-toolkit/browser`.
+ * Mirrors the existing `binding-parser.ts` (pure) / `binding-loader.ts`
+ * (Node-only) split in this package.
+ *
+ * Security: `source` is trusted input. Callers taking a URL from an
+ * untrusted source are responsible for their own allowlisting (SSRF) — see
+ * the spec doc's Security Considerations.
+ */
+import * as fs from 'node:fs';
+import * as yaml from 'js-yaml';
+function parseDocument(text, source) {
+    const stripped = text.trimStart();
+    if (stripped.startsWith('{') || stripped.startsWith('[')) {
+        // JSON.parse throws SyntaxError natively on malformed input, matching
+        // the doc's Contract ("Malformed JSON/YAML: ... TypeScript SyntaxError").
+        return JSON.parse(text);
+    }
+    let loaded;
+    try {
+        loaded = yaml.load(text);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new SyntaxError(`loadSpec: malformed YAML spec at ${source}: ${msg}`);
+    }
+    if (typeof loaded !== 'object' || loaded === null || Array.isArray(loaded)) {
+        throw new SyntaxError(`loadSpec: malformed spec at ${source}: expected an object, got ${typeof loaded}`);
+    }
+    return loaded;
+}
+/**
+ * Load and parse an OpenAPI document from a local filesystem path or an
+ * `http(s)://` URL, taken verbatim (no candidate paths are probed).
+ *
+ * JSON-or-YAML is sniffed from the trimmed text: `{`/`[` parses as JSON
+ * (via `JSON.parse`, whose `SyntaxError` propagates on malformed input);
+ * anything else parses as YAML via `js-yaml` (already a dependency of this
+ * package), with parse errors normalised to `SyntaxError` for the same
+ * cross-SDK error contract.
+ *
+ * @throws {Error} File not found/unreadable, or HTTP non-2xx / network failure.
+ * @throws {SyntaxError} Malformed JSON or YAML.
+ */
+export async function loadSpec(source, options = {}) {
+    const { headers, authHeaderFactory, timeout = 30_000, fetchImpl } = options;
+    if (source.startsWith('http://') || source.startsWith('https://')) {
+        const f = fetchImpl ?? globalThis.fetch;
+        if (!f) {
+            throw new Error('loadSpec: global fetch is unavailable — pass `fetchImpl` explicitly or run on Node 20+.');
+        }
+        const requestHeaders = { ...(headers ?? {}) };
+        if (authHeaderFactory) {
+            Object.assign(requestHeaders, authHeaderFactory());
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeout);
+        let response;
+        try {
+            response = await f(source, { headers: requestHeaders, signal: controller.signal });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new Error(`loadSpec: request to ${source} failed: ${msg}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!response.ok) {
+            throw new Error(`loadSpec: request to ${source} failed with status ${response.status} ${response.statusText}`);
+        }
+        const text = await response.text();
+        return parseDocument(text, source);
+    }
+    let text;
+    try {
+        text = fs.readFileSync(source, 'utf-8');
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`loadSpec: failed to read ${source}: ${msg}`);
+    }
+    return parseDocument(text, source);
+}
+//# sourceMappingURL=openapi-loader.js.map

package/dist/openapi-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-loader.js","sourceRoot":"","sources":["../src/openapi-loader.ts"],"names":[],"mappings":"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"}

package/dist/openapi-scanner.d.ts

@@ -0,0 +1,73 @@
+/**
+ * OpenAPIScanner — turn an OpenAPI 3.x document into a `ScannedModule[]`.
+ *
+ * Document-level traversal layered on top of the shipped operation-level
+ * primitives in `./openapi.js` (`extractInputSchema`, `extractOutputSchema`,
+ * `resolveRef`) and `BaseScanner.inferAnnotationsFromMethod`.
+ *
+ * Pure and synchronous — no I/O. See `./openapi-loader.js` for the
+ * (Node-only) `loadSpec` convenience helper, which is intentionally kept in
+ * a separate file so this module stays importable from
+ * `apcore-toolkit/browser` (see `src/browser/index.ts`).
+ *
+ * See `apcore-toolkit/docs/features/openapi-scanner.md` for the full V1
+ * specification, worked examples, and conformance corpus.
+ */
+import { BaseScanner } from './scanner.js';
+import type { ScannedModule } from './types.js';
+/**
+ * Thrown by {@link OpenAPIScanner.scan} when the input document is not a
+ * recognisable OpenAPI 3.0.x/3.1.x document (missing `openapi` key, or an
+ * OpenAPI 2.0 / Swagger document). Matches the doc's Contract: "TypeScript
+ * throws `InvalidSpecError`".
+ */
+export declare class InvalidSpecError extends Error {
+    constructor(message: string);
+}
+/**
+ * Derive a stable, byte-identical `moduleId` for an OpenAPI operation.
+ *
+ * See `apcore-toolkit/docs/features/openapi-scanner.md` § `module_id`
+ * Derivation for the algorithm and worked examples. This function is the
+ * primary subject of the cross-SDK conformance corpus — implementations
+ * MUST match it byte-for-byte.
+ *
+ * @param path - The OpenAPI path template (e.g. `"/users/{user_id}"`).
+ * @param method - The HTTP method key as written in the document (e.g. `"get"`).
+ * @param operation - The operation object, consulted only for `operationId`.
+ * @returns The derived module ID. Never empty — falls back to `"root.<method>"`.
+ */
+export declare function deriveModuleId(path: string, method: string, operation: Record<string, unknown>): string;
+/**
+ * Options for {@link OpenAPIScanner.scan}. See
+ * `apcore-toolkit/docs/features/openapi-scanner.md` § Contract:
+ * OpenAPIScanner.scan and § Extension Hooks.
+ */
+export interface OpenAPIScanOptions {
+    /** Regex forwarded to `filterModules`; only matching module IDs are kept. */
+    include?: string;
+    /** Regex forwarded to `filterModules`; matching module IDs are removed. */
+    exclude?: string;
+    /** Prepended to every derived `moduleId` as `"<prefix>.<id>"`, before filtering/dedup. */
+    basePathPrefix?: string;
+    /** When `false`, operations with `deprecated: true` are omitted entirely. Default `true`. */
+    includeDeprecated?: boolean;
+    /** Patch or normalise an operation before extraction. Returning `null` skips it entirely. */
+    transformOperation?: (path: string, method: string, operation: Record<string, unknown>) => Record<string, unknown> | null;
+    /** Override the naming algorithm. Returning `null` falls back to {@link deriveModuleId}. */
+    deriveModuleId?: (path: string, method: string, operation: Record<string, unknown>) => string | null;
+    /** Adjust the finished module. Returning `null` drops it from the result. */
+    transformModule?: (module: ScannedModule) => ScannedModule | null;
+}
+/**
+ * Turn an OpenAPI 3.0/3.1 document into a list of `ScannedModule`.
+ *
+ * Pure and synchronous: `scan()` accepts an already-parsed document and
+ * performs no I/O. Use `loadSpec` (from `./openapi-loader.js`) to
+ * fetch/parse a document first.
+ */
+export declare class OpenAPIScanner extends BaseScanner {
+    scan(spec: Record<string, unknown>, options?: OpenAPIScanOptions): ScannedModule[];
+    getSourceName(): string;
+}
+//# sourceMappingURL=openapi-scanner.d.ts.map

package/dist/openapi-scanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-scanner.d.ts","sourceRoot":"","sources":["../src/openapi-scanner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAIhD;;;;;GAKG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,EAAE,MAAM;CAI5B;AAyCD;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,MAAM,CAsBR;AAiHD;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0FAA0F;IAC1F,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,6FAA6F;IAC7F,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,6FAA6F;IAC7F,kBAAkB,CAAC,EAAE,CACnB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC/B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACpC,4FAA4F;IAC5F,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,GAAG,IAAI,CAAC;IACrG,6EAA6E;IAC7E,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,aAAa,GAAG,IAAI,CAAC;CACnE;AAED;;;;;;GAMG;AACH,qBAAa,cAAe,SAAQ,WAAW;IAC7C,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAE,kBAAuB,GAAG,aAAa,EAAE;IAiJtF,aAAa,IAAI,MAAM;CAGxB"}