# Languages

Upseam supports JavaScript, TypeScript, Python and Go. SDK detection covers
their manifests and lockfiles only.

## SDK versions

The SDK version comes from the lockfile or the manifest, up to three
directories deep:

| Language               | Files read                                                                                          |
| ---------------------- | --------------------------------------------------------------------------------------------------- |
| JavaScript, TypeScript | `package.json`, then the npm, yarn or pnpm lockfile next to it                                      |
| Python                 | `requirements*.txt`, then `pyproject.toml`, `Pipfile`, `poetry.lock` and `uv.lock`, first match wins |
| Go                     | `go.mod`: `require` lines and blocks, `replace` directives                                          |

In JavaScript, the SDK must be listed in `dependencies` or `devDependencies`
of a `package.json`. Its version is read from `package-lock.json`, `yarn.lock`
or `pnpm-lock.yaml` in the same directory; without one, it is the first
version number in the `package.json` range (`^16.2.0` gives `16.2.0`). A
workspace lockfile in a parent directory is not used.

`Pipfile.lock` is not read. A Python requirement with an upper bound or an
exclusion only, such as `<3` or `!=2.0`, gives an unknown SDK version.

In Go, a module path with a major suffix (`github.com/stripe/stripe-go/v82`)
matches the SDK, and its tag (`v82.1.0`) is the SDK version; `+incompatible`
and pseudo-versions are read by their numeric part. A `replace` with a local
path or another module gives an unknown version; a `replace` with another
version of the same module gives that version. `go.sum` and `go.work` are not
read. Only official Go SDKs are recognised, see [Providers](providers.md#go).
In `.go` files a changed field also matches its Go names: `current_period_end`
matches `CurrentPeriodEnd`, `sink_sid` matches `SinkSid` and `SetSinkSid`.

## Rescans

A push to the default branch makes Upseam scan the repository again when it
changes a manifest or lockfile (`package.json`, `package-lock.json`,
`yarn.lock`, `pnpm-lock.yaml`, `pyproject.toml`, `Pipfile`, `poetry.lock`,
`uv.lock`, `requirements*.txt`, `go.mod`, `go.sum`), `.github/upseam.yml`, or
a source or spec file Upseam reads (for example `.js`, `.ts`, `.py`, `.go`,
`.graphql`, `.yaml`, `.json`).

## API version pins

The API version comes from the pin in code, for example `apiVersion` in
JavaScript or `stripe.api_version` in Python; each
[provider](providers.md) lists its pins. Without a pin, the version is
inferred from the SDK version and marked as inferred, but only for SDK
releases Upseam has a default version for; otherwise the version is unknown.

## Comments and imports

Comments are neither pins nor matches:

- comment lines starting with `//`, `#` or `*`, and `/* … */` blocks;
- Python docstrings: a `"""` or `'''` block at the start of a file or right
  after a `def` or `class` header.

Code after `*/` on the closing line is still code, and a block that never
closes is not a comment. A comment after code on the same line, attribute
docstrings and strings after imports are not recognised as comments. Lines
that start with `import` or `from`, and lines inside a Go `import (…)` block,
are not matches.

## MCP configs and agent files

For [MCP servers](mcp.md) Upseam also reads JSON and JSONC MCP configs
(comments and trailing commas allowed), Codex `config.toml`, Claude Code
settings and agent instruction files in Markdown. Only the known file paths
at the repository root are read.

## Patches

The patch gates cover every supported language. Every changed JavaScript or
TypeScript file must parse with the TypeScript compiler, every changed Python
file must pass the Python lexer, and every changed Go file must pass the Go
lexer. Go test files (`_test.go`) and `go.mod` are never patched, so a Go
import path or module major bump always goes to a person. The allowed conversions and forbidden names differ
per language; see [Patch gates](security.md#patch-gates). Patches to MCP
configs, settings and instructions may only switch a matched tool name; see
[MCP servers](mcp.md#how-a-patch-is-checked).