Skip to content

test(sdk): evaluate typescript axios client compatibility - #9437

Merged
YvesCesar merged 4 commits into
LibreSign:mainfrom
lfals:feat/sdk-9089-finalize
Nov 14, 2026
Merged

YvesCesar merged 4 commits into
LibreSign:mainfrom
lfals:feat/sdk-9089-finalize

Conversation

@lfals

@lfals lfals commented Nov 11, 2026 •

Copy link
Copy Markdown

Resolves: #9089

📝 Summary

Evaluates whether OpenAPI Generator's typescript-axios client is a suitable foundation for an official LibreSign SDK. The reproducible harness covers the current 90-operation contract and records a No-Go for unmodified input: EffectivePolicyValue becomes an empty interface that accepts invalid arrays in both 7.15.0 and 7.27.0.

Pins generator 7.27.0 by Docker digest and adds strict model checks, operation inventory, controlled Axios transport tests, independent basic/bearer configurations, and conflicting baseURL/basePath tests. A separate disposable anyOf → oneOf input experiment rejects invalid arrays but still loses nullable policy values. The transformation is not an equivalent validation contract because integer/number alternatives overlap.

Maintainers must choose between conditional Go with reviewed input normalization, a semantically correct source/extractor change, or another generator. Multipart remains in #9435. Results and limitations are documented in tests/sdk-generation/REPORT.md.

🧪 How to test

From the repository root, with Docker, Node.js and npm available:

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

All seven commands should pass. test:anyof passing reproduces the known defect: the generated type accepts an invalid array. A missing client fails with TS2307; a corrected type that rejects arrays fails with TS2322 and requires reevaluating the No-Go report. generate.sh validates its input before clearing the selected output subdirectory, so rerunning it removes stale generated files.

Run the separate normalized-input experiment:

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

These commands pass; the type checks also explicitly record that schema-valid null remains rejected.

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

The real @nextcloud/axios 2.6.0 import fails in plain Node with ReferenceError: window is not defined, from browser storage initialized by @nextcloud/auth. Real Nextcloud Axios injection remains unverified. See the README for the optional live test, which was not rerun for this evaluation.

Validation evidence

  • Focused regression/acceptance tests executed: transport passes; 90 operations, zero inventory errors; original-input failure reproduced; normalized type checks pass with documented limits.
  • Relevant type checks: strict generated-client compilation and git diff --check pass.
  • Broader suite required by the changed surface — no broad PHP/frontend suite run; changes are isolated to the evaluation harness.
  • CI reviewed.

Validated against application base 9aebe13938369e70344a4fb1e16fc331387427ea, with spec SHA-256 2501bc11fcee0545dfb703a28d93018a80e62f6e14ba81bae549d1b130de9243. Two generations were byte-identical. Node 24.22.2 / npm 11.19.1; local execution on 2026-11-11 with cached Docker images.

Executed commands, timings and remaining verification limits
Command Exit Seconds Result
tests/sdk-generation/setup.sh 0 1.05 added 46 packages in 717ms
tests/sdk-generation/generate.sh 0 4.91 validation/generation pass; unused Capabilities and PublicCapabilities warnings
tests/sdk-generation/generate.sh build/sdk-generation/repeat 0 5.79 validation/generation pass; same warnings
diff -qr build/sdk-generation/typescript build/sdk-generation/repeat 0 0.06 empty output; byte-identical generated trees
npm run compile --prefix tests/sdk-generation 0 2.09 strict compilation passes, no diagnostics
npm test --prefix tests/sdk-generation 0 1.06 PASS transport; 90 operations; 0 inventory errors
npm run test:anyof --prefix tests/sdk-generation 0 — Passing reproduction of invalid-array acceptance; rerun after review on 2026-11-12
node tests/sdk-generation/normalize-input.cjs 0 0.05 22 anyOf schemas rewritten to oneOf
tests/sdk-generation/generate.sh build/sdk-generation/normalized/typescript build/sdk-generation/normalized/openapi-full.oneof.json 0 4.71 validation/generation pass; same unused-model warnings
npm run test:normalized --prefix tests/sdk-generation 0 1.36 strict positive/negative type checks pass, no diagnostics
npm run test:nextcloud --prefix tests/sdk-generation 1 0.21 ReferenceError: window is not defined in StorageBuilder.build; real package cannot import in plain Node
diff -u tests/sdk-generation/inventory.md build/sdk-generation/inventory.md 0 0.01 empty output; checked-in inventory unchanged

Additional checks: generated a fresh comparison with Docker image 7.15.0
(sha256:509f01c3c7eee9d1ad286506a7b6aa4624a95b410be9a238a306d209e900621f)
using the same typescript-axios configuration, then compiled the original, pre-review negative
fixture against it: exit 2, TS2578. The current fixture instead passes while
the defect exists, without suppressing diagnostics. git diff --check passed. Upstream main
was fetched again and equals the rebased branch's parent. No matching PR was
returned by gh pr list --repo LibreSign/libresign --state all --search 9089.

Not verified: test:live was not rerun; no browser integration, real Nextcloud
Axios injection/CSRF retries, real binary download, live subdirectory deployment,
positive live account response or state-changing request. Controlled adapter
tests do not establish server authorization, on-wire basic-auth headers,
HTTP-200 OCS error handling, exhaustive signatures or runtime JSON validation.
No broad PHP/frontend test suite was run locally for this isolated harness change; the repository ESLint command was rerun after review.

Review corrections verified on 2026-11-12

  • npm run test:anyof --prefix tests/sdk-generation: exit 0 with the current defective client; exit 2 / TS2307 without generated output. The same fixture against the normalized generated client fails with TS2322. No generated source was patched.
  • generate.sh removes a deliberately stale output file; a repeated real generation produces an empty recursive diff. Cleanup regression tests reject the build root, path aliases, symlink paths and inputs inside the output directory while preserving sibling files.
  • npm test --prefix tests/sdk-generation: transport passes, 90 operations and zero inventory errors, 12 simulated live-check cases and the generation cleanup test pass. PDF HTTP 500 is recorded as a failure while invalid credentials are still tested; only HTTP 401 passes that check, not 200, 403 or 429.
  • npm run compile --prefix tests/sdk-generation, npm run test:normalized --prefix tests/sdk-generation, npm run lint, shell syntax and git diff --check: passed. Repository ESLint reports 0 errors and 23 warnings outside the changed harness.
  • Live Nextcloud was not exercised; the live error-path regression uses a synthetic Axios adapter.

⚙️ API / Back-end changes

  • Added a disposable generated-client evaluation harness with model, inventory and transport checks.
  • Added positive/negative type tests and documented unsupported contracts.
  • Updated reproduction instructions, compatibility report and operation inventory.

No production API, PHP controller, extractor, committed OpenAPI, generated frontend type or capability changes. API regeneration is not required. Authorization remains server-enforced; the harness does not validate live server permissions. No permanent SDK or CI job is introduced.

🚧 Tasks

  • Pin and evaluate OpenAPI Generator 7.27.0.
  • Reproduce the unmodified-input type defect and retain the No-Go decision.
  • Evaluate normalized input separately and document semantic and nullable limitations.
  • Test independent authentication and conflicting base URLs; record the real Nextcloud Axios import limitation.
  • Maintainer review of the generator/contract decision before SDK infrastructure.

✅ Checklist

  • I have read and followed the contribution guide.
  • The diff does not contain unrelated refactors or generated changes.
  • Commits follow Conventional Commits where applicable.
  • All commits include the required DCO sign-off.

🤖 AI (if applicable)

  • The content of this PR was partially or fully generated using AI.

Luis Amorim and others added 2 commits November 11, 2026 00:14
Signed-off-by: Luis Amorim <luisfelipeamorim@hotmail.com>
Pin generator 7.27.0 and evaluate normalized input separately. Cover independent authentication and base URL precedence, and document the real Nextcloud Axios Node import limitation.

Co-authored-by: Codex <noreply@openai.com>
Signed-off-by: Luis Amorim <luisfelipeamorim@hotmail.com>
@lfals
lfals requested a review from a team as a code owner November 11, 2026 03:43
@lfals
lfals marked this pull request as draft November 11, 2026 03:47
Signed-off-by: Luis Amorim <luisfelipeamorim@hotmail.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
@lfals
lfals marked this pull request as ready for review November 12, 2026 13:13
@YvesCesar
YvesCesar self-requested a review November 12, 2026 13:25

@YvesCesar YvesCesar left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @lfals !

I made a few revisions. Could you take a look?

Comment thread tests/sdk-generation/package.json Resolved
Comment thread tests/sdk-generation/generate.sh Resolved
Comment thread tests/sdk-generation/live.ts Resolved
Comment thread tests/sdk-generation/live.ts Resolved
Make anyOf defect reproduction fail for missing or corrected generated types. Clear validated generation output safely and cover stale files and path boundaries. Continue live checks after PDF failures and require HTTP 401 for invalid credentials.

Co-authored-by: Codex <noreply@openai.com>
Signed-off-by: Luis Amorim <luisfelipeamorim@hotmail.com>

Copy link
Copy Markdown
Member

@lfals, I was looking at PR #9437 and I have some questions about how we plan to organize SDK generation.

We already generate the OpenAPI files automatically from the PHP code. I think we could use these files to generate each SDK in its own repository, with tests to check that all endpoints are included, that the types are correct, and that API calls work.

This PR seems to add a separate setup inside the LibreSign repository, with a package.json, scripts, an operation list, tests, and reports. I am not sure why all of this needs to stay in the main repository.

REPORT.md also looks like a record of this investigation, rather than permanent project documentation.

It is important to check if the generator works correctly, and this work has found real problems. But would it make more sense to keep the regular SDK generation and tests in the TypeScript SDK repository?

What do you think about this approach?

@lfals

lfals commented Nov 12, 2026

Copy link
Copy Markdown
Author

@lfals, I was looking at PR #9437 and I have some questions about how we plan to organize SDK generation.

We already generate the OpenAPI files automatically from the PHP code. I think we could use these files to generate each SDK in its own repository, with tests to check that all endpoints are included, that the types are correct, and that API calls work.

This PR seems to add a separate setup inside the LibreSign repository, with a package.json, scripts, an operation list, tests, and reports. I am not sure why all of this needs to stay in the main repository.

REPORT.md also looks like a record of this investigation, rather than permanent project documentation.

It is important to check if the generator works correctly, and this work has found real problems. But would it make more sense to keep the regular SDK generation and tests in the TypeScript SDK repository?

What do you think about this approach?
@vitormattos

The long-term layout you describe is the one I would use for an official SDK: PHP remains the source of the OpenAPI files, and each published SDK lives in its own repository with its own generation, inventory and tests.

This PR is not that SDK. Issue #9089 asked for a disposable evaluation inside LibreSign (tests/sdk-generation/, output under build/) and a Go/No-Go on typescript-axios, without publishing a package or creating a permanent SDK repository. That matches epic #9087.

The files are here so the result is tied to the same revision as openapi-full.json. The current decision is No-Go: OpenAPI Generator 7.15.0 and 7.27.0 both emit EffectivePolicyValue as an empty interface, so an invalid array type-checks. Multipart is a separate contract gap (#9435 / nextcloud/openapi-extractor#401), not a reason this harness exists.

If we generated the client only in a TypeScript SDK repo today, we would ship that type defect as the foundation. I would keep a small reproducible harness in this repository until that decision is settled, then move regular generation and tests to the SDK repository in the next epic.

REPORT.md can move to the PR/issue if you prefer not to keep the write-up in tree. The scripts, pinned generator digest and failing anyOf check are the part that has to stay reproducible.

Happy to drop or slim the in-repo files once you confirm you want the evaluation evidence only on the PR, or once we start the SDK-repo epic.

@YvesCesar YvesCesar left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, @lfals !

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Generate and validate a TypeScript Axios client from LibreSign OpenAPI

3 participants