feat: add extract-code-examples composite action

[gavinsharp]

Summary

Adds a composite GitHub Action at extract-code-examples/ that any Phenoml SDK repo (TS, Python, Java) can call to extract Fern-generated code examples into a code-examples.json manifest for the docs generator. The extraction script auto-detects the SDK language from .fern/metadata.json and dispatches to a TypeScript, Python, or Java parser.

Layout

extract-code-examples/        # one composite action per top-level dir
  action.yml
  index.ts                    # CLI + parsers
  package.json + bun.lock
  tests/
    extract-code-examples.test.ts
    fixtures/{typescript,python,java}/...
.github/workflows/
  test.yml                    # matrix-runs each action's test suite
README.md                     # usage docs

Each future action gets its own top-level directory. The test workflow uses a single-entry matrix so adding another is a one-line entry.

Design notes

• Composite action rather than reusable workflow (workflow_call). The action runs inside the caller's existing job after their own actions/checkout, so no workflow_ref parsing, no double-checkout, and no implicit auto-commit. Callers decide whether/how to commit the manifest.
• Self-locating: the action uses github.action_path to find its bundled script and package.json, so it works at any pinned ref.
• Caller usage (from README.md):

  - uses: actions/checkout@v6
    with:
      ref: ${{ github.head_ref }}
  
  - uses: PhenoML/sdk-shared-actions/extract-code-examples@v1
  
  - name: Commit code-examples.json if changed
    run: |
      git add code-examples.json
      if ! git diff --cached --quiet -- code-examples.json; then
        git config user.name "github-actions[bot]"
        git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
        git commit -m "chore: update code-examples.json"
        git push
      fi

The TS SDK currently has an inlined copy of this script (in PhenoML/phenoml-ts-sdk#139); once this lands and gets tagged, that PR can be reduced to the caller stub above.

Tests

38-test bun:test suite covering both unit-level helpers and end-to-end parsing of real SDK files (Summary client + wire tests for TS, authtoken auth raw_client + wire tests for Python, RawAuthClient + AuthtokenAuthWireTest for Java).

Several parser bugs caught and fixed during review now have regression coverage:

• Python: def test_* boundary was matched on a trimmed line, so indented nested defs prematurely terminated body scanning.
• Python: 60-line scan cap silently dropped long generated wire tests.
• Java: brace-depth counting included braces inside string/char/comment/text-block literals — JSON fragments could corrupt method boundary detection.
• Java: method-detection regex [^>]+ couldn't match nested generics like PhenomlClientHttpResponse<Optional<Foo>>.
• Manifest builder: lowercased-concat chain-index keys could silently collapse different chains onto the same entry; collisions now warn + drop the ambiguous index entry rather than guess.

Test plan

• bun run test passes locally (38 tests)
• End-to-end CLI run against fixtures for all three languages
• Tag a release (e.g. v1) once merged
• Wire up the TS SDK's caller workflow against the tag and confirm code-examples.json is generated and committed
• Repeat for Python and Java SDKs (once their wire-test infra lands)

🤖 Generated with Claude Code

---

Note

Medium Risk
Medium risk because this introduces a large new composite action and parsing logic that will run in SDK CI and write code-examples.json, so failures or mis-parsing could affect downstream docs/automation.

Overview
Adds new composite action extract-code-examples that runs a Bun/TypeScript CLI to parse Fern-generated TypeScript, Python, and Java SDKs and emit a code-examples.json manifest keyed by HTTP_METHOD path (including normalized path params), combining endpoint mappings from generated clients with request/response/example call data from wire tests.

Adds a Bun test suite with fixtures to validate the extractors across all three languages (plus edge cases like long Python tests, Java multi-line signatures, and brace/comment handling) and wires up a GitHub workflow (test-js-actions.yml) to run bun install + bun test for JS-based actions via a matrix. Documentation and repo hygiene are updated via README entries and a root .gitignore for node_modules/.

^{Reviewed by Cursor Bugbot for commit b21c6d9. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 86e2eaa. Configure here.}