Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

ci: add dead-code detection (knip + vulture + orphaned-CI check) (#3787)

Alberto Schiabel15a03c10fb1d
diff --git a/.github/scripts/check-orphan-ci.sh b/.github/scripts/check-orphan-ci.sh
new file mode 100755
index 000000000..43876f06c
--- /dev/null
+++ b/.github/scripts/check-orphan-ci.sh
@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+#
+# Report orphaned CI plumbing — the GitHub Actions analogue of the "dead file"
+# problem knip/vulture catch for TS/Python:
+#
+# * composite actions under .github/actions/* that no workflow `uses:`
+# * reusable workflows (on: workflow_call) that nothing calls AND that have
+# no self-trigger (push/pull_request/schedule/...), i.e. truly unreachable
+#
+# Report-only: prints findings and always exits 0 so it never blocks CI on a
+# heuristic. Vet anything it prints by hand before deleting.
+
+set -uo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+workflows_dir="$repo_root/.github/workflows"
+actions_dir="$repo_root/.github/actions"
+
+findings=0
+
+note() {
+ findings=$((findings + 1))
+ echo " - $1"
+}
+
+echo "### Orphaned CI check"
+echo ""
+echo "Composite actions with no callers:"
+
+if [[ -d "$actions_dir" ]]; then
+ for action_yml in "$actions_dir"/*/action.yml "$actions_dir"/*/action.yaml; do
+ [[ -f "$action_yml" ]] || continue
+ name="$(basename "$(dirname "$action_yml")")"
+ # A caller references it as `uses: ./.github/actions/<name>`.
+ if ! grep -rqs "uses:.*\.github/actions/$name\b" "$workflows_dir" "$actions_dir"; then
+ note "action \`$name\` (.github/actions/$name) is referenced by no workflow"
+ fi
+ done
+fi
+[[ $findings -eq 0 ]] && echo " _(none)_"
+
+before_wf=$findings
+echo ""
+echo "Reusable workflows that are unreachable:"
+
+for wf in "$workflows_dir"/*.yml "$workflows_dir"/*.yaml; do
+ [[ -f "$wf" ]] || continue
+ # Only reusable workflows are candidates.
+ grep -qs "workflow_call:" "$wf" || continue
+ base="$(basename "$wf")"
+ # Called by another workflow?
+ if grep -rqs "uses:.*\.github/workflows/$base\b" "$workflows_dir"; then
+ continue
+ fi
+ # Self-triggering (has a real event trigger besides workflow_call)?
+ if grep -Eqs "^[[:space:]]+(push|pull_request|schedule|workflow_dispatch|release|issues|issue_comment|repository_dispatch|merge_group):" "$wf"; then
+ continue
+ fi
+ note "workflow \`$base\` exposes workflow_call but has no caller and no self-trigger"
+done
+[[ $findings -eq $before_wf ]] && echo " _(none)_"
+
+echo ""
+if [[ $findings -eq 0 ]]; then
+ echo "No orphaned CI plumbing found."
+else
+ echo "Found $findings orphaned CI item(s) above — review before removing."
+fi
+
+# Report-only.
+exit 0
diff --git a/.github/workflows/dead-code.yml b/.github/workflows/dead-code.yml
new file mode 100644
index 000000000..11b9f3d50
--- /dev/null
+++ b/.github/workflows/dead-code.yml
@@ -0,0 +1,107 @@
+name: Dead Code
+
+# Surfaces likely-dead code on every PR so orphaned files/exports/deps get
+# noticed instead of rotting (see the root Dockerfile cleanup, #3783).
+#
+# Report-only by design: every job writes findings to the run's Step Summary
+# and never fails the build. These tools carry false positives (public API
+# surface, dynamic imports, import-map targets), so a red X here would train
+# people to ignore it. Tighten a job to blocking only once its config is
+# refined enough that a clean run is the steady state.
+
+on:
+ push:
+ branches: [master, next]
+ paths:
+ - 'ts/**'
+ - 'python/**'
+ - '.github/actions/**'
+ - '.github/workflows/**'
+ - '.github/scripts/check-orphan-ci.sh'
+ - 'knip.json'
+ - 'package.json'
+ - 'pnpm-workspace.yaml'
+ - 'pnpm-lock.yaml'
+ - 'mise.toml'
+ - 'mise.lock'
+ pull_request:
+ branches: [master, next]
+ paths:
+ - 'ts/**'
+ - 'python/**'
+ - '.github/actions/**'
+ - '.github/workflows/**'
+ - '.github/scripts/check-orphan-ci.sh'
+ - 'knip.json'
+ - 'package.json'
+ - 'pnpm-workspace.yaml'
+ - 'pnpm-lock.yaml'
+ - 'mise.toml'
+ - 'mise.lock'
+
+concurrency:
+ group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.ref || github.run_id }}
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+ contents: read
+
+jobs:
+ knip:
+ name: TypeScript (knip)
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout Code
+ uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+ - name: Setup Node.js, pnpm, Bun
+ uses: ./.github/actions/setup-node-pnpm-bun
+
+ - name: Install dependencies
+ run: pnpm install --frozen-lockfile
+
+ - name: Run knip (report-only)
+ run: |
+ {
+ echo '## Knip — TypeScript dead code'
+ echo ''
+ echo 'Unused files, exports, types and dependencies. False positives'
+ echo 'usually mean a missing `entry` in `knip.json`; vet before deleting.'
+ echo ''
+ echo '```'
+ pnpm dlx knip@5 --no-exit-code --no-progress 2>&1 || true
+ echo '```'
+ } >> "$GITHUB_STEP_SUMMARY"
+
+ vulture:
+ name: Python (vulture)
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout Code
+ uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+ - name: Setup Python with UV
+ uses: ./.github/actions/setup-python-uv
+
+ - name: Run vulture (report-only)
+ run: |
+ {
+ echo '## Vulture — Python dead code'
+ echo ''
+ echo 'Likely-unused functions, classes and variables. Suppress'
+ echo 'confirmed false positives in `python/config/vulture_allowlist.py`.'
+ echo ''
+ echo '```'
+ (cd python && uv run nox -s dead_code) 2>&1 || true
+ echo '```'
+ } >> "$GITHUB_STEP_SUMMARY"
+
+ orphaned-ci:
+ name: GitHub Actions (orphan check)
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout Code
+ uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+ - name: Check for orphaned workflows and composite actions
+ run: bash .github/scripts/check-orphan-ci.sh >> "$GITHUB_STEP_SUMMARY"
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e1cf0717b..13b9b4a51 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -127,6 +127,28 @@ pnpm check:peer-deps
pnpm update:peer-deps
```
+### Dead code detection
+
+The `Dead Code` CI workflow reports likely-orphaned code on every PR (findings
+land in the run's Step Summary; it never fails the build). Run the same checks
+locally:
+
+```bash
+# TypeScript — unused files, exports, types and dependencies
+pnpm dlx knip@5 # config in knip.json
+
+# Python — unused functions, classes and variables
+cd python && make dead-code # vulture; allowlist in python/config/vulture_allowlist.py
+
+# GitHub Actions — orphaned reusable workflows and composite actions
+bash .github/scripts/check-orphan-ci.sh
+```
+
+These tools carry false positives (public API surface, dynamic imports,
+import-map targets), so treat their output as advisory: verify a finding is
+truly unreferenced before deleting, and suppress confirmed false positives via
+`knip.json` / `vulture_allowlist.py`.
+
## Coding Standards
### TypeScript
diff --git a/knip.json b/knip.json
new file mode 100644
index 000000000..f345b1439
--- /dev/null
+++ b/knip.json
@@ -0,0 +1,21 @@
+{
+ "$schema": "https://unpkg.com/knip@5/schema.json",
+ "ignoreWorkspaces": [
+ "ts/e2e-tests/**"
+ ],
+ "ignoreBinaries": [
+ "mise",
+ "swift",
+ "python",
+ "python3",
+ "vhs",
+ "ps",
+ "ruff"
+ ],
+ "ignore": [
+ "**/.next/**",
+ "**/build/**",
+ "docs/**",
+ "**/*.d.ts"
+ ]
+}
diff --git a/python/Makefile b/python/Makefile
index 5b7802a9b..91c4b12ab 100644
--- a/python/Makefile
+++ b/python/Makefile
@@ -1,4 +1,4 @@
-.PHONY: clean-build sync provider create-provider env fmt chk snt tst type_inference bump build format check sanity test
+.PHONY: clean-build sync provider create-provider env fmt chk snt tst type_inference dead-code bump build format check sanity test
clean-build:
@rm -rf dist/ build/
@@ -53,6 +53,9 @@ fmt:
chk:
@nox -s chk
+dead-code:
+ @nox -s dead_code
+
snt:
@nox -s snt
diff --git a/python/config/vulture_allowlist.py b/python/config/vulture_allowlist.py
new file mode 100644
index 000000000..9457bfebf
--- /dev/null
+++ b/python/config/vulture_allowlist.py
@@ -0,0 +1,17 @@
+# Vulture allowlist — confirmed false positives.
+#
+# Vulture (see the `dead_code` nox session) cannot see some usages: symbols
+# referenced only through `__all__`, dynamic attribute access, framework entry
+# points, or `TYPE_CHECKING`-only re-exports look "unused" to it. List such
+# confirmed-intentional names here so they stop showing up in the report.
+#
+# The idiom is a *bare reference* to the name (a load), one per line — that is
+# what marks it "used". Keep a comment explaining why each entry is a false
+# positive, and prune entries when the underlying symbol is deleted.
+
+# Re-exported for downstream typing via `__all__` in
+# composio/core/models/custom_tool.py (TYPE_CHECKING-only imports, so vulture
+# does not connect the __all__ string to the import binding).
+SessionAttachResponseExperimental # noqa: B018, F821
+SessionCreateResponseExperimental # noqa: B018, F821
+SessionRetrieveResponseExperimental # noqa: B018, F821
diff --git a/python/noxfile.py b/python/noxfile.py
index 6ec9970d4..7b8313de3 100644
--- a/python/noxfile.py
+++ b/python/noxfile.py
@@ -139,3 +139,36 @@ def type_inference(session: Session):
"tests/test_type_inference_llamaindex.py",
"tests/test_type_inference_openai_agents.py",
)
+
+
+# Modules scanned for dead code (source only, no tests/examples/scripts)
+modules_for_vulture = [
+ "composio/",
+ "providers/",
+]
+
+
[email protected](name="dead_code")
+def dead_code(session: Session):
+ """Report likely-dead code (unused functions, classes, variables).
+
+ Report-only: vulture exits 1 when it finds candidates, but we do not fail
+ the session on that so it never blocks CI on false positives. Vet the
+ output by hand; suppress confirmed false positives by adding the symbol to
+ ``config/vulture_allowlist.py``. Ruff already covers unused imports (F401)
+ and unused locals (F841) in the `chk` session; vulture adds cross-module
+ unused functions/classes that ruff cannot see.
+ """
+ session.install("vulture>=2.14")
+ session.run(
+ "vulture",
+ *modules_for_vulture,
+ "config/vulture_allowlist.py",
+ "--min-confidence",
+ "80",
+ "--exclude",
+ "*/build/*,*/dist/*,*/.venv/*,*/.nox/*,*/__pycache__/*",
+ # vulture exit codes: 0 = clean, 3 = candidates found. Report-only, so
+ # neither should fail the session. (1/2 are real usage/parse errors.)
+ success_codes=[0, 3],
+ )