Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions REUSE.toml
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,8 @@ path = [
"openapi-full.json",
"openapi.json",
"package-lock.json",
"tests/sdk-generation/package.json",
"tests/sdk-generation/package-lock.json",
"package.json",
"patches.json",
"patches.lock.json",
Expand Down
82 changes: 82 additions & 0 deletions tests/sdk-generation/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
<!--
- SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
- SPDX-License-Identifier: AGPL-3.0-or-later
-->

# TypeScript Axios generation evaluation

This harness evaluates disposable generated code; it is not an SDK. Docker,
Node.js and npm are required. From the repository root:

```sh
tests/sdk-generation/setup.sh
tests/sdk-generation/generate.sh
tests/sdk-generation/generate.sh build/sdk-generation/repeat
diff -qr build/sdk-generation/typescript build/sdk-generation/repeat
npm run compile --prefix tests/sdk-generation
npm test --prefix tests/sdk-generation
npm run test:anyof --prefix tests/sdk-generation
```

The last command **passes while the known defect exists**: it assigns an invalid
array to the generated `EffectivePolicyValue` without suppressing diagnostics.
A missing client fails with TS2307; a corrected type that rejects arrays fails
with TS2322 and requires reevaluating the No-Go report. `npm test` checks
transport, generation cleanup and live-check error handling, and writes
the generated operation inventory to `build/sdk-generation/inventory.md`.
Compare that inventory with the checked-in evaluation snapshot when changing the
specification. This does not prove every operation's runtime serialization.

The generator validates the full specification first and never uses
`--skip-validate-spec`. Its Docker image digest pins OpenAPI Generator 7.27.0;
`useSingleRequestParameter=true` is enabled. npm dependencies are pinned by
`package-lock.json`. After validating the input, the script clears only the
selected output subdirectory before generation. It rejects the build root,
symlinked output paths and inputs inside the output directory. Generated code
stays under ignored `build/` and must not be edited.
See [REPORT.md](REPORT.md) and [inventory.md](inventory.md) for results.

## Normalized-input experiment

This separate experiment changes all 22 `anyOf` keywords to `oneOf` in a
**disposable generator input**, never in the committed specification:

```sh
node tests/sdk-generation/normalize-input.cjs
tests/sdk-generation/generate.sh build/sdk-generation/normalized/typescript build/sdk-generation/normalized/openapi-full.oneof.json
npm run test:normalized --prefix tests/sdk-generation
```

The positive/negative type checks pass, including rejection of the invalid
policy array and invalid scalar object unions. They also explicitly record that
schema-valid `null` is still rejected. This is partial mitigation, not a Go.
`oneOf` and `anyOf` are not equivalent validation contracts: `integer` and
`number` overlap. The transformed file must never replace the source contract.

## Real Nextcloud Axios import probe

```sh
npm run test:nextcloud --prefix tests/sdk-generation
```

With the locked `@nextcloud/axios` 2.6.0 on Node 24.22.2 this **fails** with
`ReferenceError: window is not defined` in `@nextcloud/browser-storage`, imported
by `@nextcloud/auth`. This invokes the real ESM package without browser shims.
Real Nextcloud instance injection therefore remains unverified; the deterministic
transport tests use ordinary Axios. Browser integration and CSRF retry behavior
need a separate browser environment.

## Optional live Nextcloud check

After generation and setup, set `SDK_TEST_URL` to the local HTTPS Nextcloud
base URL, and `SDK_TEST_USER` / `SDK_TEST_PASSWORD` to a local administrator's
credentials, then run `npm run test:live --prefix tests/sdk-generation`. Do not
store credentials in files or commit them. The live test performs read-only
requests plus one deliberately invalid authentication attempt. It requires a
local instance and is not part of the deterministic harness. It accepts only
localhost hostnames and disables TLS certificate verification for the local
development proxy; do not use it with remote systems. The PDF check reports a
404 as unverified when no certificate policy PDF is configured. Other PDF errors
mark the run as failed but still allow the invalid-credentials check to run.
That check requires HTTP 401; HTTP 403 and 429 do not count as authentication
success for this negative test.
138 changes: 138 additions & 0 deletions tests/sdk-generation/REPORT.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,138 @@
<!--
- SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
- SPDX-License-Identifier: AGPL-3.0-or-later
-->

# Compatibility evaluation

## Decision: No-Go for unmodified input

OpenAPI Generator 7.27.0's `typescript-axios` output is not a sufficiently
faithful SDK foundation: `EffectivePolicyValue` is an empty interface and
accepts invalid arrays. Version 7.15.0 has the same defect. The separate
normalized-input experiment partially improves unions; it does not change
this decision or approve any source contract change. Multipart is tracked
separately in #9435.

## Input and toolchain

- Application base: `9aebe13938369e70344a4fb1e16fc331387427ea` (upstream main).
- `openapi-full.json` SHA-256:
`2501bc11fcee0545dfb703a28d93018a80e62f6e14ba81bae549d1b130de9243`.
- Generator: `openapitools/openapi-generator-cli` 7.27.0 at
`sha256:949efd0d5cf3c093ef169887b2ebe0879ee2e8074b6476264232ce4fd8ef46d0`;
`typescript-axios`, `useSingleRequestParameter=true`.
- Previous comparison: 7.15.0 at
`sha256:509f01c3c7eee9d1ad286506a7b6aa4624a95b410be9a238a306d209e900621f`.
- TypeScript 5.8.3, Axios 1.20.0, `@nextcloud/axios` 2.6.0, tsx 4.19.4;
Node 24.22.2, npm 11.19.1. npm dependencies/transitives are locked.
Axios matches the application's locked version and satisfies Nextcloud Axios.
- All deterministic README commands ran with fresh generated directories.
Validation succeeded with unused `Capabilities` and `PublicCapabilities`
warnings. Two generations had an empty recursive diff including metadata.
No generated source was edited.
- Warm timings: setup 1.05 s; validation/generation 4.91 s (repeat 5.79 s);
strict compilation 2.09 s; transport/inventory 1.06 s; normalized
validation/generation 4.71 s and type checks 1.36 s. These are single-machine
observations with cached images, not cold CI benchmarks. No CI job is added.

## Unmodified input results

The [inventory](inventory.md) covers 90 operations (69 default, 21
administration), rather than the issue's original 88: 90 matched, zero inventory
errors, ten functional classes. The checked-in snapshot matches the new output.
The check matches method/path, generated documentation and public TypeScript
class methods; it does not exhaustively validate signatures or serialization.
Generated Markdown examples still use positional arguments despite the chosen
single-request-parameter configuration; use actual class signatures.

Strict compilation with `skipLibCheck` passes. `types.ts` tests number/string
`NewFile.nodeId` (rejecting boolean), inherited/local `SignerDetail` fields,
nullable/optional fields and enums. `test:anyof` exits 0 because the generated
empty interface accepts an invalid policy array. This is a passing reproduction
of a failed SDK acceptance criterion, so the decision remains No-Go. The fixture
has no error suppression: missing generated output fails with TS2307; a type
that rejects arrays fails with TS2322, requiring the report to be reevaluated.

The controlled Axios adapter tests generated calls for account GET and typed
OCS envelope, encoded policy path and simulated HTTP 403, signature-request
JSON POST, and non-OCS PDF with explicit `responseType: arraybuffer`. Basic-only
and bearer-only configurations are independent, with assertions that the other
credential mechanism is absent. Both root and subdirectory paths pass.
An instance at `https://instance.test/installed` overrides configuration
`https://example.test/nextcloud` for both OCS and PDF URLs, proving precedence
with different values.

The real locked `@nextcloud/axios` ESM import probe exits 1 in Node with
`ReferenceError: window is not defined`: `@nextcloud/auth` imports
`@nextcloud/browser-storage`, whose `StorageBuilder.build` accesses browser
storage during initialization. No browser globals are mocked. Real Nextcloud
Axios injection and its CSRF/session interceptors remain unverified; the
successful transport tests use ordinary Axios.

## Normalized-input experiment

`normalize-input.cjs` writes only
`build/sdk-generation/normalized/openapi-full.oneof.json`, renaming all 22
`anyOf` keywords to `oneOf`. Generation is separate from the main evaluation.
It produces:

- `EffectivePolicyValue = boolean | number | string | { [key: string]: object }`;
- `FileListResponseDataInner = DetailedFile | FileSummary`;
- `FileRuntimeMetadata = ValidateMetadata | { [key: string]: object }`.

`test:normalized` passes strict compilation and positive/negative checks:
policy primitives/object values and object union members compile; policy arrays,
undefined and scalar file/metadata values are rejected. It also records a
remaining defect: schema-valid `null` is rejected by `EffectivePolicyValue`.
Passing this diagnostic suite does not establish full contract fidelity.

This transformation is **generator-input normalization only**, not an equivalent
validation contract. In particular, integers match both `integer` and `number`
alternatives: `anyOf` allows that overlap, while `oneOf` requires exactly one
match. Never replace committed OpenAPI with this experiment's output.

## Remaining limits

OCS envelopes are not automatically unwrapped, and callers must pass the OCS
header argument. Adapter status settlement is simulated; server authorization
and OCS-level errors inside HTTP 200 are not tested. Basic auth is inspected as
Axios config, not a real on-wire Authorization header. PDF types are generated
as `File` although explicit arraybuffer transport returns bytes; callers must
reconcile those types. No live Nextcloud checks were rerun for this version;
real account success, binary download, subdirectory deployment and state-changing
signature requests remain unverified. Tests sample models, not runtime JSON
validation or numerical limits. No production SDK or frontend migration is
included.

## Multipart limitations

The harness checks the generated signatures and requests, and the controller
source supplies the expected upload names:

| operationId | Runtime upload | Generated behavior |
| --- | --- | --- |
| `account-upload-pfx` | `file` in `AccountController::uploadPfx` | No typed file parameter or request body; generated call sends no body. |
| `file-save` | `file` or `files` in `FileController::prepareFilesForSaving` | Typed JSON body supports `NewFile` representations, but exposes no typed multipart upload. |
| `admin-signature-background-save` | `image` in `AdminController::signatureBackgroundSave` | No typed image parameter or request body; generated call sends no body. |

Generic Axios options may allow a caller to handcraft a request, but that is not
verified typed multipart support. An official SDK or frontend migration would
need a reviewed contract/extractor correction and regenerated serialization, or
another explicitly designed solution. Changes to PHP or OpenAPI extraction are
outside this evaluation.

## Handoff

Maintainers must choose among these options; this evaluation selects none:

1. Conditional Go with reviewed generator-input normalization, addressing the
remaining nullable and transport limitations before SDK infrastructure.
2. Correct the source contract/extractor to emit `oneOf` where semantically
valid, explicitly resolving overlapping alternatives rather than blindly
renaming keywords.
3. Evaluate another generator against the same acceptance criteria.

Rerun the harness against the approved contract and toolchain. Multipart source
contract work belongs to #9435. No PHP controller, extractor, committed OpenAPI,
generated frontend type, CI job or permanent SDK is changed here.
9 changes: 9 additions & 0 deletions tests/sdk-generation/anyof-defect.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
/*
* SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
import type { EffectivePolicyValue } from '../../build/sdk-generation/typescript/api'
// This defect-reproduction check passes only while invalid arrays are accepted.
// Missing generated output or a corrected union must fail compilation.
const accepted: EffectivePolicyValue = ['not a policy value']
void accepted
34 changes: 34 additions & 0 deletions tests/sdk-generation/generate.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
#!/bin/sh
# SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
# SPDX-License-Identifier: AGPL-3.0-or-later
#
# Usage: generate.sh [output [input]]
# The input defaults to the repository's openapi-full.json. Any other input
# must be a disposable copy under build/sdk-generation/.
set -eu
root=$(CDPATH= cd -- "$(dirname -- "$0")/../.." && pwd)
# OpenAPI Generator 7.27.0
image='openapitools/openapi-generator-cli@sha256:949efd0d5cf3c093ef169887b2ebe0879ee2e8074b6476264232ce4fd8ef46d0'
output=${1:-build/sdk-generation/typescript}
input=${2:-openapi-full.json}
case "$output$input" in *..*) echo 'Paths must not contain ..' >&2; exit 1;; esac
case "$output" in build/sdk-generation/?*) ;; *) echo 'Output must be under build/sdk-generation/' >&2; exit 1;; esac
case "$input" in openapi-full.json|build/sdk-generation/*) ;; *) echo 'Input must be openapi-full.json or a copy under build/sdk-generation/' >&2; exit 1;; esac
cd "$root"
# Keep cleanup inside build/ and prevent aliases from hiding input/output overlap.
for candidate in "$output" "$input"; do
case "$candidate" in */.|*/./*|*//*|*/) echo 'Paths must not contain dot or empty components' >&2; exit 1;; esac
ancestor=$candidate
while [ "$ancestor" != . ]; do
if [ -L "$ancestor" ]; then
echo 'Input/output paths and their ancestors must not be symlinks' >&2
exit 1
fi
ancestor=$(dirname -- "$ancestor")
done
done
case "$input" in "$output"|"$output"/*) echo 'Input must be outside the output directory' >&2; exit 1;; esac
docker run --rm --user "$(id -u):$(id -g)" -v "$root:/local" "$image" validate -i "/local/$input"
rm -rf -- "$output"
mkdir -p "$output"
docker run --rm --user "$(id -u):$(id -g)" -v "$root:/local" "$image" generate -i "/local/$input" -g typescript-axios -o "/local/$output" --additional-properties=useSingleRequestParameter=true
45 changes: 45 additions & 0 deletions tests/sdk-generation/generate.test.cjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
/*
* SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
const assert = require('node:assert/strict')
const fs = require('node:fs')
const os = require('node:os')
const path = require('node:path')
const { spawnSync } = require('node:child_process')
const { test } = require('node:test')

test('generation clears only its output and protects inputs and build siblings', () => {
const root = fs.mkdtempSync(path.join(os.tmpdir(), 'sdk-generation-'))
try {
fs.mkdirSync(path.join(root, 'tests/sdk-generation'), { recursive: true })
fs.mkdirSync(path.join(root, 'build/sdk-generation/typescript'), { recursive: true })
fs.mkdirSync(path.join(root, 'bin'))
const script = path.join(root, 'tests/sdk-generation/generate.sh')
fs.copyFileSync(path.join(__dirname, 'generate.sh'), script)
// Stub Docker: test filesystem behavior without generating or editing a client.
fs.writeFileSync(path.join(root, 'bin/docker'), '#!/bin/sh\nexit 0\n', { mode: 0o755 })
fs.writeFileSync(path.join(root, 'build/sdk-generation/keep'), 'sibling')
const output = path.join(root, 'build/sdk-generation/typescript')
fs.writeFileSync(path.join(output, 'stale.ts'), 'stale')
const run = (...args) => spawnSync('sh', [script, ...args], {
encoding: 'utf8', env: { ...process.env, PATH: `${root}/bin:${process.env.PATH}` },
})
assert.equal(run().status, 0)
assert.equal(fs.existsSync(path.join(output, 'stale.ts')), false)
assert.equal(fs.readFileSync(path.join(root, 'build/sdk-generation/keep'), 'utf8'), 'sibling')
for (const invalid of ['build/sdk-generation/', 'build/sdk-generation/.', 'build/sdk-generation//', 'build/sdk-generation/./', 'build/sdk-generation/../', 'src']) {
assert.notEqual(run(invalid).status, 0, invalid)
}
fs.writeFileSync(path.join(output, 'input.json'), '{}')
assert.notEqual(run('build/sdk-generation/typescript', 'build/sdk-generation/typescript/input.json').status, 0)
assert.equal(fs.existsSync(path.join(output, 'input.json')), true)
assert.notEqual(run('build/sdk-generation/typescript', 'build/sdk-generation/./typescript/input.json').status, 0)
fs.symlinkSync(output, path.join(root, 'build/sdk-generation/link'))
assert.notEqual(run('build/sdk-generation/link/child').status, 0)
assert.notEqual(run('build/sdk-generation/typescript', 'build/sdk-generation/link/input.json').status, 0)
assert.equal(fs.existsSync(path.join(output, 'input.json')), true)
} finally {
fs.rmSync(root, { recursive: true, force: true })
}
})
58 changes: 58 additions & 0 deletions tests/sdk-generation/inventory.cjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
/*
* SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
const fs = require('node:fs')
const path = require('node:path')
const ts = require('typescript')
const root = path.resolve(__dirname, '../..')
const dir = path.join(root, 'build/sdk-generation/typescript')
const spec = JSON.parse(fs.readFileSync(path.join(root, 'openapi-full.json')))
const source = ts.createSourceFile('api.ts', fs.readFileSync(path.join(dir, 'api.ts'), 'utf8'), ts.ScriptTarget.Latest, true)
const classes = new Map()
for (const node of source.statements) {
if (!ts.isClassDeclaration(node) || !node.name) {
continue
}
classes.set(node.name.text, new Set(node.members.filter(ts.isMethodDeclaration).map(m => m.name.getText(source))))
}
const generated = new Map()
for (const tag of ['policies', 'identity', 'documents', 'requests', 'signing', 'appearance', 'verification', 'certificates', 'notifications', 'system']) {
const name = tag[0].toUpperCase() + tag.slice(1) + 'Api'
const doc = fs.readFileSync(path.join(dir, 'docs', name + '.md'), 'utf8')
const rows = [...doc.matchAll(/^\|\[\*\*(\w+)\*\*\]\([^\n]*?\| \*\*(GET|POST|PUT|DELETE|PATCH)\*\* ([^ |]+)/gm)]
for (const [, method, verb, url] of rows) {
const key = `${verb} ${url}`
if (!generated.has(key)) {
generated.set(key, [])
}
generated.get(key).push({ name, method, exists: classes.get(name)?.has(method) === true })
}
}
const rows = []
const ids = new Set()
let errors = 0
for (const [url, operations] of Object.entries(spec.paths)) {
for (const [verb, op] of Object.entries(operations)) {
if (!['get', 'post', 'put', 'delete', 'patch'].includes(verb)) {
continue
}
const key = `${verb.toUpperCase()} ${url}`
const found = generated.get(key) || []
const expected = op.tags[0][0].toUpperCase() + op.tags[0].slice(1) + 'Api'
const ok = !ids.has(op.operationId) && found.length === 1 && found[0].name === expected && found[0].exists
ids.add(op.operationId)
if (!ok) {
errors++
}
rows.push(`| ${op.operationId} | ${key} | ${found.map(x => `${x.name}.${x.method}${x.exists ? '' : ' (missing)'}`).join(', ') || 'MISSING'} | ${ok ? 'OK' : 'FAIL'} |`)
generated.delete(key)
}
}
errors += generated.size
const output = ['<!--', ' - SPDX-FileCopyrightText: 2026 LibreCode coop and contributors', ' - SPDX-License-Identifier: AGPL-3.0-or-later', '-->', '', '# Generated operation inventory', '', '| operationId | HTTP operation | Generated class.method | Result |', '| --- | --- | --- | --- |', ...rows, '', `${rows.length} input operations; ${errors} inventory errors. Presence does not establish serialization compatibility.`, ''].join('\n')
fs.writeFileSync(path.join(root, 'build/sdk-generation/inventory.md'), output)
console.log(`${rows.length} operations; ${errors} inventory errors; build/sdk-generation/inventory.md`)
if (errors) {
process.exitCode = 1
}
Loading
Loading