stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
6e00a48e00da3b2cfbd976a53254275fa63583a6
git.stella-ops.org/docs/features/checked/sdk/sdk-generator-toolchain.md
master 5bca406787 save checkpoint: save features
2026-02-12 10:27:23 +02:00

5.0 KiB
Raw Blame History

SDK Generator Toolchain (Multi-Language)

Module

Sdk

Status

VERIFIED

Description

Multi-language SDK generator toolchain producing typed API clients in TypeScript, Python, Go, and Java from OpenAPI specifications, with postprocessing, release pipelines, and offline bundle support.

Implementation Details

  • Go Generator: src/Sdk/StellaOps.Sdk.Generator/go/ -- Go SDK generation configuration and scripts. Key files: config.yaml (OpenAPI Generator config for Go), generate-go.sh (generation script), test_generate_go.sh (test script).
  • Java Generator: src/Sdk/StellaOps.Sdk.Generator/java/ -- Java SDK generation. Key files: config.yaml, generate-java.sh, test_generate_java.sh.
  • Python Generator: src/Sdk/StellaOps.Sdk.Generator/python/ -- Python SDK generation. Key files: config.yaml, generate-python.sh, test_generate_python.sh.
  • Postprocessing Pipeline: src/Sdk/StellaOps.Sdk.Generator/postprocess/ -- post-generation processing adding hooks, error handling, and SDK-specific customizations. Key files: postprocess.sh (orchestrator), README.md (documentation).
  • Postprocessing Templates: src/Sdk/StellaOps.Sdk.Generator/postprocess/templates/ -- language-specific hook templates: go/hooks.go, java/src/main/java/org/stellaops/sdk/Hooks.java, python/sdk_hooks.py, typescript/sdk-hooks.ts, typescript/sdk-error.ts, typescript/package.json, typescript/tsconfig.*.json.
  • Toolchain Lock: src/Sdk/StellaOps.Sdk.Generator/toolchain.lock.yaml -- pinned versions of generator tools for reproducible builds.
  • Toolchain Documentation: src/Sdk/StellaOps.Sdk.Generator/TOOLCHAIN.md -- documentation of the toolchain, versions, and upgrade process.
  • Vendored Tools: src/Sdk/StellaOps.Sdk.Generator/tools/openapi-generator-cli-7.4.0.jar (OpenAPI Generator), tools/jdk-21.0.1.tar.gz (JDK for Java generation).
  • Postprocessing Tests: src/Sdk/StellaOps.Sdk.Generator/postprocess/tests/test_postprocess.sh -- tests for postprocessing pipeline.

E2E Test Plan

  • Run the Go SDK generation script (generate-go.sh) against the OpenAPI spec and verify it produces a compilable Go client package
  • Run the Java SDK generation script and verify the output compiles with the vendored JDK
  • Run the Python SDK generation script and verify the output is a valid Python package with correct module structure
  • Run the postprocessing pipeline on a generated TypeScript SDK and verify hooks, error handling, and package.json are correctly injected
  • Verify toolchain pinning inputs are present (toolchain.lock.yaml, vendored generator jar, vendored JDK tarball) and consumed by generator smoke workflows
  • Run all test scripts (test_generate_ts.sh, test_generate_go.sh, test_generate_java.sh, test_generate_python.sh, test_postprocess.sh) and verify they pass
  • Verify offline-capable generation path uses local fixture spec and vendored generator artifacts

Verification

  • Run ID: run-002
  • Date: 2026-02-11
  • Method: Tier 0 source verification + Tier 1/Tier 2 shell-based generator smoke replay
  • Build/Test: PASS (5/5 script-based generator/postprocess smoke checks)
  • Tier 0 Evidence: docs/qa/feature-checks/runs/sdk/sdk-generator-toolchain/run-002/tier0-source-check.json
  • Tier 1 Evidence: docs/qa/feature-checks/runs/sdk/sdk-generator-toolchain/run-002/tier1-build-check.json
  • Tier 2 Evidence: docs/qa/feature-checks/runs/sdk/sdk-generator-toolchain/run-002/tier2-integration-check.json
  • Command Output Evidence: docs/qa/feature-checks/runs/sdk/sdk-generator-toolchain/run-002/evidence/

Recheck Notes

  • Initial replay attempt (_run-001_capture) exposed a host-shell interoperability bug: Go/Java scripts were CRLF, causing set -euo pipefail parsing failures in Bash.
  • Fix applied: normalized LF endings for:
    • src/Sdk/StellaOps.Sdk.Generator/go/test_generate_go.sh
    • src/Sdk/StellaOps.Sdk.Generator/java/test_generate_java.sh
    • src/Sdk/StellaOps.Sdk.Generator/go/generate-go.sh
    • src/Sdk/StellaOps.Sdk.Generator/java/generate-java.sh
  • Retest (run-002) passed all generator/postprocess smoke checks with fresh evidence.

Recheck (Run-003)

  • Verified: 2026-02-11
  • Method: Strict Tier 2 shell-based behavioral replay with vendored JDK setup and explicit negative-path coverage.
  • Build/Test: PASS (7/7 script smokes): test_line_endings.sh, test_generate_ts.sh, test_generate_go.sh, test_generate_java.sh, test_generate_python.sh, test_postprocess.sh, test_generate_ts_hash_mismatch.sh.
  • Tier 0 Evidence: docs/qa/feature-checks/runs/sdk/sdk-generator-toolchain/run-003/tier0-source-check.json
  • Tier 1 Evidence: docs/qa/feature-checks/runs/sdk/sdk-generator-toolchain/run-003/tier1-build-check.json
  • Tier 2 Evidence: docs/qa/feature-checks/runs/sdk/sdk-generator-toolchain/run-003/tier2-integration-check.json
  • Outcome: Recheck remained green with new regression guards for LF line endings and TS spec-hash mismatch handling.