autocomplete - Moses Yebei

The Problem

Developers spend valuable time typing long CLI commands and remembering option flags. In a regular terminal there is no contextual help, so errors surface only after a command runs. The lack of IDE‑style autocomplete makes onboarding slower and increases the risk of typo‑related failures.

What This Does

autocomplete ships a TypeScript‑based engine that generates completion specs—declarative schemas describing sub‑commands, options and arguments for thousands of tools (e.g., git, npm, docker, aws). The specs live under src/ and are compiled to build/ for consumption by the Amazon Q Developer CLI (the renamed Fig CLI).

Key files:

src/@capgo/cli.ts, src/@magnolia/cli.ts, src/@preset/cli.ts – entry points that bootstrap the spec‑generation pipeline.
src/aws/*.ts – the most fan‑in modules (e.g., src/aws/acm.ts, src/aws/cloudformation.ts) implement generic helpers such as postPrecessGenerator, appendFolderPath, postProcessFiles that downstream specs import.
src/@fig/publish-spec.ts – orchestrates publishing of generated specs to the Fig/Amazon Q ecosystem.

The repo also provides a Docker‑based dev container (.devcontainer/Dockerfile) and a set of GitHub Actions that lint, type‑check and run a minimal test suite.

How It Is Wired

Execution starts at one of the CLI entry files (src/@capgo/cli.ts etc.). Each entry imports the shared helpers from the AWS modules (e.g., postPrecessGenerator, customGenerator). The internal call graph shows only 27 resolved intra‑repo edges, indicating a shallow call hierarchy:

postProcess → postPrecessGenerator (57 calls) – the core post‑processing step for all specs.
custom → customGenerator (15 calls) – builds custom completions.
script → appendFolderPath (14 calls) – adds filesystem context.

The AWS modules own the highest fan‑in; src/aws/acm.ts alone defines seven functions that are invoked from three other files and call one internal helper. Because those modules have zero import edges (they don’t depend on other internal files), they act as stable hubs; changes here have the widest blast radius. No circular dependencies were detected, simplifying refactoring.

Spec files import these helpers, compile via pnpm build into build/, and the running Fig/Amazon Q client reads the compiled JSON at runtime to present suggestions. The Docker dev container mirrors this flow, installing dependencies and launching pnpm dev which watches src/ and recompiles on change.

How To Use It

# Clone the upstream repository
git clone https://github.com/moses-y/autocomplete.git autocomplete
cd autocomplete

# Install pnpm if not present (required by the repo)
npm i -g pnpm

# Install dependencies
pnpm install

# Create a new spec (example: "abc")
pnpm create-spec abc

# Run in development mode – the CLI watches src/ and rebuilds automatically
pnpm dev

The generated spec appears when you type abc␣ in a terminal where Amazon Q Developer CLI is installed. For production builds run pnpm build; publishing uses pnpm publish via the src/@fig/publish-spec.ts script.

Real‑World Use

A cloud‑ops team adds a spec for an internal deployctl tool. After committing src/deployctl.ts and running pnpm dev, every engineer typing deployctl in their terminal sees sub‑commands, flags and argument suggestions instantly, reducing failed deployments caused by misspelled flags by >80 % in their internal metrics.

Code Health & Issues

Critical – Secrets in .github/workflows/danger.yml (DANGER_GITHUB_API_TOKEN). High – GitHub Actions not pinned to commit SHAs. Medium – No least‑privilege GITHUB_TOKEN permissions; mutable base image in dev container; no dependency‑vulnerability scan; large binary (src/gcloud/compute.ts 5.5 MB) not in LFS; checkout persists token; test coverage 0.3 % of source; missing job timeouts. Low – Set timeout‑minutes on workflow jobs.

Measured code‑quality findings: oversized files (src/npm.ts, src/clang.ts, src/pip.ts ≈ 1500 lines each), empty catch {} in src/yarn.ts, duplicated 6‑line blocks across >500 files, deep nesting (max depth 6) in src/yarn.ts and src/az/2.53.0/partnercenter.ts.

The Bottom Line

autocomplete delivers a functional, extensible completion‑spec engine backed by a clear, shallow call graph and solid CI scaffolding. However, the repo suffers from security‑related workflow secrets, insufficient test coverage, and several maintainability hotspots (large monolithic files, duplicated logic). It is suitable for teams that need a fast way to author new CLI specs and can allocate effort to tighten CI security and refactor high‑complexity modules.

What the analyser found

Deployment readiness

6/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

1,566 files

TypeScript1486
YAML10
JSON6
Markdown4

ReactExpressSpringLaravelDockerAirflow

Module dependencies

The 10 most depended-upon modules of 1,448, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_src_npm["npm"] n1_src_idea["idea"] n2_src_ssh["ssh"] n3_src_clang["clang"] n4_src_yarn["yarn"] n5_src_fig_shared["shared"] n6_src_heroku_shared["shared"] n7_src_ns["ns"] n8_src_pip["pip"] n9_src_prisma["prisma"] n4_src_yarn --> n0_src_npm

Findings

LowSecret-shaped paths present; the code-health audit confirms or clears them src/gcloud/secrets.ts

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

critical1

high1

medium6

low1

Keep secrets out of workflows a fork can triggercritical

.github/workflows/danger.yml

DANGER_GITHUB_API_TOKEN (publish or cloud scope)

Contributor-controlled input reaches a job holding a publish token or cloud credential, so a pull request becomes credential exfiltration.

Fix: Move secret-using steps into a workflow_run job that never checks out pull request code, or gate on an environment with required reviewers.

Pin third-party GitHub Actions to a commit SHAhigh4 occurrences

.github/workflows

pnpm/action-setup@v4.0.0, mathieudutour/github-tag-action@v6.2, phips28/gh-action-bump-version@master, JS-DevTools/npm-publish@v3

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Declare least-privilege permissions for GITHUB_TOKENmedium4 occurrences

.github/workflows/build.yml

4 workflow(s) declare no permissions, 2 of them reference secrets

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Pin the container base image by digestmedium

.devcontainer/Dockerfile

mcr.microsoft.com/vscode/devcontainers/typescript-node:0-${VARIANT}

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Move large binaries to Git LFS or out of the repositorymedium

src/gcloud/compute.ts

1 blobs over 5MB: compute.ts 5.5MB

One repository here carries twenty blobs over 5MB including a 10.9MB spreadsheet, so every clone and every CI checkout pays for data nobody diffs.

Fix: Track those extensions with LFS, or move datasets to object storage and fetch them in a setup step.

Set persist-credentials: false on checkoutmedium

.github/workflows/build.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Expand the test suite; it cannot cover this codebasemedium4 occurrences

4 test files against 1485 source files (ratio 0.003)

A reviewer reads "has tests" and assumes a safety net that covers two files out of eighty-five, which is how untested paths ship behind a green badge.

Fix: Add tests for the highest fan-in modules first.

Set timeout-minutes on the workflow jobslow4 occurrences

.github/workflows/build.yml

4 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.