The Problem

Developers frequently hit the "works on my machine" problem: identical code runs on one machine but fails on another because of missing or mismatched CLI tools, environment variables, files, or directories. Manually auditing each machine's setup is slow and error-prone, especially across a team or CI environment.

What This Does

Solidarity is an environment checker that codifies a project's dependency requirements into a .solidarity file, then verifies those requirements against any machine. It checks for CLI binaries, environment variables, files, and directories, and reports mismatches with actionable output.

The repo is a TypeScript CLI with commands under src/commands/ (solidarity.ts, snapshot.ts, onboard.ts, report.ts, fix.ts, create.ts, help.ts) and a rule-checking engine under src/extensions/functions/. It supports plugins (e.g., solidarity-react-native) that provide pre-built rule sets for specific technologies.

How It Is Wired

Execution starts at run in src/commands/solidarity.ts, which calls checkForEscapeHatchFlags and then delegates to the rule-checking pipeline. The core routing happens through src/extensions/functions/checkRequirement.ts, which defines taskWithFix and configureSubtask — the functions every rule check flows through.

The rule checks themselves are spread across checkCLI.ts, checkENV.ts, checkFile.ts, checkDir.ts, and checkShell.ts. These are the leaf functions that actually touch the filesystem and the network — getSolidarityHelpers.ts owns the outbound network call (loadWebCheck) and file I/O (loadFile).

The module graph shows src/types.ts as a hub: 49 modules import it, making it the highest-blast-radius file in the repo. It also participates in a 23-module circular dependency chain alongside checkDir.ts and checkFile.ts. Changing types there ripples across nearly the entire codebase, and the cycle means any edit to those files risks subtle initialization-order bugs.

The snapshot command (src/commands/snapshot.ts) drives runPluginSnapshot and createSolidarityFile, which write the .solidarity file. The onboard command (src/commands/onboard.ts) walks users through creating a .solidarity file interactively via buildSpecificRequirement.ts's requiredInputQuestion.

How To Use It

# Install globally
npm i -g solidarity solidarity-react-native

# Check current project environment
solidarity

# Create/update a snapshot of current machine specs
solidarity snapshot

# Snapshot a specific rule
solidarity snapshot cli node

Configuration lives in .solidarity (or .solidarity.json) in the project root. The schema is defined in solidaritySchema.json. Node.js >= 7.6.0 is required.

Real-World Use

A team maintains a React Native app. They commit a .solidarity file specifying Node version, Yarn, Watchman, and the Android SDK path. Each new developer runs solidarity after cloning; the tool immediately flags missing tools and offers to run fixes. CI runs solidarity as a pre-build gate, catching environment drift before it wastes build time.

Code Health & Issues

Static analysis found 26 findings (25 high, 1 medium) across 4 kinds:

  • High – Import cycle member (x23): src/types.ts, src/extensions/functions/checkDir.ts, src/extensions/functions/checkFile.ts participate in circular imports. Fix: extract shared types or invert dependencies.
  • High – Hub module: src/types.ts has 49 dependents. Fix: keep it stable and small; move volatile logic out.
  • High – Duplicated code blocks: 56 repeated 6-line blocks across 8 test files including __tests__/command_helpers/getSolidarityHelpers.ts. Fix: extract shared test helpers.
  • Medium – High branching density: src/extensions/functions/getSolidarityHelpers.ts has 19 branch points over 58 lines. Fix: decompose into strategy dispatch.

Medium – No dependency update bot: package.json exists but no Dependabot/Renovate config. Fix: commit .github/dependabot.yml.

Tests (64 files) and CI (Travis) are present. No secrets committed.

The Bottom Line

Solidarity is a well-structured, tested CLI that solves a real pain point. The main technical debt is the types.ts hub and circular dependencies — manageable for a project this size but worth addressing before significant feature work. Teams with polyglot projects or onboarding friction will get the most value.