name: "Carrick - TypeScript Context Engine" description: "Maps your TypeScript codebase across services and repositories, giving AI agents existing types, routes and functions." branding: icon: "link" color: "purple" inputs: path: description: "Path to analyze" required: false default: "." install-dependencies: description: | Install the scanned repository's dependencies before the scan, so types that resolve through a package are real types instead of `any`. "auto" (the default) prepares every service this repo holds, with lifecycle scripts disabled, and skips a service that states no install. A service is prepared where its own nearest lockfile sits, so a monorepo whose packages carry lockfiles of their own is installed package by package, and a workspace that hoists to one lockfile is installed once. Set it to "false" to scan the checkout as-is, which also allows the bare scan that leaves. A failed or slow install does not fail this step, but it is not scanned past either: the scan that follows refuses a service whose dependencies are still missing and names the command that installs them. `allow-unprepared: true` scans it anyway, with the types that resolve through those packages indexed as `any`. Private registries use your own auth. Set NPM_TOKEN (or whatever your .npmrc references) in the job's `env:` and the install step inherits it. required: false default: "auto" allow-unprepared: description: | Scan a checkout that is not prepared instead of refusing it: a service whose dependencies are not installed, or whose TypeScript or Deno config maps a specifier to a directory that is not on the checkout (a generated client, say, whose generator has not run). Carrick refuses those by default, because every type that resolves through a package or a generated module is `any` and the scan costs the same either way. The refusal names the service and, where the lockfile says which package manager to use, the exact command. Setting `install-dependencies: false` implies this, because that input already says the checkout is meant to be scanned as it is. required: false default: "false" full-scan: description: | Re-analyze every file instead of reusing the cached answer for a file whose content has not changed. Leave this false. A scan reads the model once per changed file and reuses what it already has for the rest, which is what makes a routine scan cheap and fast. Set it to true for one run when the answers themselves need redoing rather than the files — after Carrick starts extracting something it did not extract before, where the cache holds answers from before it could. Wire it to a `workflow_dispatch` input so it is asked for deliberately, never a default a push carries. required: false default: "false" outputs: success: description: "Analysis completed successfully (also 'true' when the run was skipped on a fork PR, where GitHub withholds OIDC credentials)" value: ${{ steps.fork-check.outputs.skip == 'true' && 'true' || steps.analysis.outputs.success }} issues-found: description: "Number of API issues detected ('0' can also mean the run was skipped on a fork PR, where GitHub withholds OIDC credentials)" value: ${{ steps.fork-check.outputs.skip == 'true' && '0' || steps.analysis.outputs.issues-found }} runs: using: "composite" steps: - name: Check fork PR (OIDC unavailable) id: fork-check shell: bash env: EVENT_NAME: ${{ github.event_name }} HEAD_REPO: ${{ github.event.pull_request.head.repo.full_name }} BASE_REPO: ${{ github.repository }} run: | # GitHub withholds OIDC credentials (ACTIONS_ID_TOKEN_REQUEST_URL / # ACTIONS_ID_TOKEN_REQUEST_TOKEN) from pull_request runs that originate # from forks, so the scanner cannot authenticate to the Carrick cloud. # Skip successfully rather than fail the contributor's PR red — the # scan runs when a maintainer pushes the branch to this repository. # # Only genuine forks (head repo differs from base repo) get the green # skip. A same-repo run with the OIDC env vars absent means the # workflow forgot `permissions: id-token: write` — fail loudly with the # fix instead of silently never scanning. SKIP=false if [ "$EVENT_NAME" = "pull_request" ] && [ -n "$HEAD_REPO" ] && [ "$HEAD_REPO" != "$BASE_REPO" ]; then SKIP=true echo "::notice::Carrick skipped: fork PRs don't receive OIDC credentials, so this run can't authenticate to the Carrick cloud. The check will run when a maintainer pushes the branch to this repository." elif [ -z "${ACTIONS_ID_TOKEN_REQUEST_URL:-}" ] || [ -z "${ACTIONS_ID_TOKEN_REQUEST_TOKEN:-}" ]; then echo "::error::Carrick can't mint an OIDC token: this run has no ACTIONS_ID_TOKEN_REQUEST_URL / ACTIONS_ID_TOKEN_REQUEST_TOKEN. Add 'permissions: id-token: write' to the workflow (or job) so Carrick can authenticate to the cloud." echo "skip=$SKIP" >> "$GITHUB_OUTPUT" exit 1 fi echo "skip=$SKIP" >> "$GITHUB_OUTPUT" - name: Set up Node.js if: steps.fork-check.outputs.skip != 'true' uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 with: node-version: "24" # The scanner selects Deno per declared service, including nested services # and explicit configs. Supply the runtime even when installs are disabled. - name: Set up Deno for type resolution if: steps.fork-check.outputs.skip != 'true' uses: denoland/setup-deno@22d081ff2d3a40755e97629de92e3bcbfa7cf2ed # v2 with: deno-version: "2.9.4" - name: Resolve the Carrick version if: steps.fork-check.outputs.skip != 'true' id: version shell: bash run: | # Pin to the release matching this action checkout: release-please # bumps Cargo.toml and npm/carrick/package.json in the same commit it # tags, so the version here identifies what this ref shipped with. # Without the pin every run would float to the latest published # package regardless of which action ref the workflow pinned. VERSION=$(grep -m1 '^version' "$GITHUB_ACTION_PATH/Cargo.toml" | sed 's/.*"\(.*\)".*/\1/') echo "Using carrick@$VERSION" echo "version=$VERSION" >> "$GITHUB_OUTPUT" # Which copy of Carrick this run uses. The npm package is the one artefact # from carrick#710; the release asset is what every run used before it, and # it stays until the npm path has been proven on a real scan. A probe # rather than a fallback around the scan itself: a scan that runs and exits # non-zero has found issues, and must never be mistaken for a missing # package. - name: Resolve how to run Carrick if: steps.fork-check.outputs.skip != 'true' id: resolve shell: bash run: | VERSION="${{ steps.version.outputs.version }}" # Two halves to prove, and both fail quietly if only one is checked: # the package resolves at all (npx exits non-zero when it does not), # and the platform package for THIS runner came with it. `--help` # exits 0 either way and says so in its output, so a release that # published four platforms out of five falls back here rather than # failing the scan. The download this warms is the one the scan reuses # from npx's cache. if OUT=$(npx --yes "carrick@$VERSION" --help 2>&1) && ! grep -q "is not installed" <<<"$OUT"; then echo "carrick@$VERSION resolves on npm, with a binary for $(uname -s)/$(uname -m)" echo "mode=npx" >> "$GITHUB_OUTPUT" else echo "::notice::carrick@$VERSION is not installable from npm on this runner; running from the release asset instead." echo "mode=tarball" >> "$GITHUB_OUTPUT" fi - name: Download Carrick from the release asset if: steps.resolve.outputs.mode == 'tarball' id: download shell: bash env: GH_TOKEN: ${{ github.token }} run: | # The repo that hosts this action's releases. GITHUB_ACTION_REPOSITORY # is set by the runner for action steps, so release downloads follow # the action if the repo moves orgs; the literal is a fallback for # runners that don't set it. ACTION_REPO="${GITHUB_ACTION_REPOSITORY:-carrick-tools/carrick}" ASSET="carrick-action-linux.tar.gz" JQ_ASSET_URL=".assets[] | select(.name==\"$ASSET\") | .browser_download_url" # `gh api` prints the JSON error body to stdout on a 404 (e.g. a release # tag that doesn't exist). Captured into DOWNLOAD_URL that blob is # non-empty, so it slips past the `-z` fallback guards below and is # handed to curl as a "URL". Only accept a value that is actually one. valid_url() { case "$1" in https://*) return 0 ;; *) return 1 ;; esac; } # Pin the binary to the release matching this action checkout: # release-please bumps Cargo.toml in the same commit it tags, so the # version here identifies the release this ref shipped with. Without # this, every run floated to the latest release regardless of which # action ref the workflow pinned. VERSION=$(grep -m1 '^version' "$GITHUB_ACTION_PATH/Cargo.toml" | sed 's/.*"\(.*\)".*/\1/') echo "Resolving Carrick release for version $VERSION" # release-please tags releases as carrick-v. DOWNLOAD_URL=$(gh api "repos/$ACTION_REPO/releases/tags/carrick-v$VERSION" \ --jq "$JQ_ASSET_URL" 2>/dev/null || true) valid_url "$DOWNLOAD_URL" || DOWNLOAD_URL="" if [ -z "$DOWNLOAD_URL" ]; then # Fallback for any other tag scheme: match a release whose tag ends # with this version. DOWNLOAD_URL=$(gh api "repos/$ACTION_REPO/releases" --paginate \ --jq ".[] | select(.tag_name | endswith(\"$VERSION\")) | $JQ_ASSET_URL" \ 2>/dev/null | head -n 1 || true) valid_url "$DOWNLOAD_URL" || DOWNLOAD_URL="" fi if [ -z "$DOWNLOAD_URL" ]; then echo "::warning::No release found matching version $VERSION (expected when running from an untagged ref); falling back to the latest release" DOWNLOAD_URL=$(gh api "repos/$ACTION_REPO/releases/latest" --jq "$JQ_ASSET_URL" 2>/dev/null || true) valid_url "$DOWNLOAD_URL" || DOWNLOAD_URL="" fi if [ -z "$DOWNLOAD_URL" ]; then echo "::error::Could not resolve a download URL for $ASSET from any release of $ACTION_REPO" exit 1 fi # Extract into a scratch directory: extracting into the workspace # would clobber any carrick/sidecar paths in the user's repo # and pollute their scan root. DIST_DIR="$RUNNER_TEMP/carrick-dist" mkdir -p "$DIST_DIR" echo "Downloading $DOWNLOAD_URL" curl -fsSL --retry 3 --retry-delay 2 -o "$DIST_DIR/$ASSET" "$DOWNLOAD_URL" tar -xzf "$DIST_DIR/$ASSET" -C "$DIST_DIR" chmod +x "$DIST_DIR/carrick" echo "dist-dir=$DIST_DIR" >> "$GITHUB_OUTPUT" - name: Install sidecar dependencies if: steps.resolve.outputs.mode == 'tarball' shell: bash run: cd "${{ steps.download.outputs.dist-dir }}/sidecar" && npm ci # One name for whichever copy of Carrick this run resolved, so a step that # asks it a question does not branch on the mode again. The installer asks # it which services this repo has, and `npx` is a command rather than a # path, so the name has to be a file either way. # # Deliberately not exported as CARRICK_BIN: to the npm package that # variable names a scanner BINARY to run, so the wrapper would resolve # itself and re-enter forever. - name: Name the resolved Carrick if: steps.fork-check.outputs.skip != 'true' && inputs.install-dependencies != 'false' id: cli shell: bash env: MODE: ${{ steps.resolve.outputs.mode }} VERSION: ${{ steps.version.outputs.version }} DIST_DIR: ${{ steps.download.outputs.dist-dir }} run: | CLI="$RUNNER_TEMP/carrick-cli" if [ "$MODE" = "npx" ]; then printf '%s\n' '#!/usr/bin/env bash' "exec npx --yes \"carrick@$VERSION\" \"\$@\"" > "$CLI" else printf '%s\n' '#!/usr/bin/env bash' "exec \"$DIST_DIR/carrick\" \"\$@\"" > "$CLI" fi chmod +x "$CLI" echo "path=$CLI" >> "$GITHUB_OUTPUT" # The scanned repo's own dependencies, not Carrick's. Without them every # import from a package resolves to the compiler's `error` type and the # indexed request/response types degrade to `any`. Node installs are # lockfile-gated; Deno prepares its declared dependencies in frozen mode. # Scripts disabled and time-boxed: see scripts/install-scanned-deps.sh for # the posture, and for why the set prepared is every service the pre-flight # will check rather than the scan root alone (carrick#1312). - name: Detect what the scanned repo needs installed if: steps.fork-check.outputs.skip != 'true' && inputs.install-dependencies != 'false' id: deps shell: bash env: SCAN_PATH: ${{ inputs.path }} CARRICK_CLI: ${{ steps.cli.outputs.path }} run: | "$GITHUB_ACTION_PATH/scripts/install-scanned-deps.sh" detect "$SCAN_PATH" \ | tee -a "$GITHUB_OUTPUT" # Keyed on the hash of EVERY lockfile the run installs from, so a repo # whose nested service changed its dependencies does not restore a store # keyed on the root's unchanged lockfile. The store, not node_modules: # `npm ci` deletes node_modules before installing, and a cache written from # a half-finished install would poison the next run. - name: Restore the package managers' stores # `continue-on-error` is not supported on a composite action's steps, so # this leans on actions/cache's own behaviour: a restore that misses or # fails warns, it does not fail the step. if: steps.fork-check.outputs.skip != 'true' && steps.deps.outputs.should_install == 'true' && steps.deps.outputs.cache_dirs != '' uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4 with: path: ${{ steps.deps.outputs.cache_dirs }} key: carrick-deps-${{ runner.os }}-${{ steps.deps.outputs.managers }}-${{ steps.deps.outputs.lockfiles_sha256 }} restore-keys: | carrick-deps-${{ runner.os }}-${{ steps.deps.outputs.managers }}- - name: Install the scanned repo's dependencies if: steps.fork-check.outputs.skip != 'true' && steps.deps.outputs.should_install == 'true' shell: bash env: SCAN_PATH: ${{ inputs.path }} CARRICK_CLI: ${{ steps.cli.outputs.path }} run: | "$GITHUB_ACTION_PATH/scripts/install-scanned-deps.sh" install "$SCAN_PATH" - name: Run analysis if: steps.fork-check.outputs.skip != 'true' id: analysis shell: bash env: # Auth is keyless: the scanner mints a GitHub Actions OIDC token from # ACTIONS_ID_TOKEN_REQUEST_URL / ACTIONS_ID_TOKEN_REQUEST_TOKEN (present # automatically when the job grants `permissions: id-token: write`) and # sends it as X-Carrick-OIDC. No API key required. CI: "true" # A pipeline that deliberately scans a bare checkout says so here # rather than being refused (carrick#1254). `install-dependencies: # false` is already that statement, so it carries the same meaning. CARRICK_ALLOW_UNPREPARED: ${{ (inputs.allow-unprepared == 'true' || inputs.install-dependencies == 'false') && '1' || '' }} run: | # Stream output live (multi-minute scans shouldn't look hung) while # still capturing it for the issue-count grep below. The log lives in # RUNNER_TEMP so it never pollutes the user's workspace. LOG_FILE="$RUNNER_TEMP/carrick-analysis.log" # The npm package carries the binary for this runner (an optional # dependency npm resolves by os and cpu) and the type sidecar with its # dependencies, so that path downloads, untars and installs nothing. # A full scan is one argument, built here so both invocations below # take exactly the same flags. Anything other than a literal "true" # leaves the incremental path alone. SCAN_ARGS=() if [ "${{ inputs.full-scan }}" = "true" ]; then echo "::notice::full-scan requested: re-analyzing every file, ignoring the cached answers." SCAN_ARGS+=("--no-cache") fi set +e if [ "${{ steps.resolve.outputs.mode }}" = "npx" ]; then npx --yes "carrick@${{ steps.version.outputs.version }}" "${{ inputs.path }}" "${SCAN_ARGS[@]}" 2>&1 | tee "$LOG_FILE" else "${{ steps.download.outputs.dist-dir }}/carrick" "${{ inputs.path }}" "${SCAN_ARGS[@]}" 2>&1 | tee "$LOG_FILE" fi EXIT_CODE=${PIPESTATUS[0]} set -e ISSUES=0 if grep -q "CARRICK_ISSUE_COUNT:" "$LOG_FILE"; then # -m1: only the first marker counts — log echoes of the output (or a # rerun appending to the same log) must not yield a multi-line value. ISSUES=$(grep -m1 "CARRICK_ISSUE_COUNT:" "$LOG_FILE" | sed 's/.*CARRICK_ISSUE_COUNT:\([0-9]*\).*/\1/') fi if [ $EXIT_CODE -eq 0 ]; then echo "success=true" >> $GITHUB_OUTPUT else echo "success=false" >> $GITHUB_OUTPUT fi echo "issues-found=$ISSUES" >> $GITHUB_OUTPUT # PR comments are posted by the Carrick GitHub App from the cloud, not # by this workflow: on pull_request runs the scanner relays the # rendered findings to api.carrick.tools, which upserts one marked # comment (gated on the project's pr_comments_enabled toggle). No # github-script step or pull-requests:write permission is needed here. exit $EXIT_CODE