Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

7.7 KB
Raw Blame

Contributing to Ix

Getting Started

Prerequisites

  • Node.js 22+ (22.22 or newer to build the docs site, which Astro requires)
  • Docker and Docker Compose

Local Setup

git clone https://github.com/ix-infrastructure/Ix.git
cd Ix
./scripts/backend.sh up    # Start ArangoDB + Memory Layer (Docker)
cd ix-cli && npm ci && npm run build

Building from Source

# core-ingestion (parser library, built automatically by ix-cli)
cd core-ingestion
npm ci
npm run build

# ix-cli
cd ../ix-cli
npm ci
npm run build

Verify Your Setup

# CLI tests
cd ix-cli && npm test

Development Workflow

  1. Create a branch from main
  2. Make your changes
  3. Run tests locally
  4. Open a PR using the pull request template
  5. Ensure CI passes before merge

Branch Naming

feat/<name>
fix/<name>
docs/<name>
refactor/<name>
test/<name>
ci/<name>
chore/<name>

Commit Format

Use conventional commit prefixes:

feat:      New feature
fix:       Bug fix
docs:      Documentation only
refactor:  Code change that neither fixes a bug nor adds a feature
test:      Adding or updating tests
ci:        CI/CD changes
chore:     Maintenance, dependencies, tooling

Breaking changes: use feat!: or fix!: prefix.

Testing

What changed Run
CLI code cd ix-cli && npm test
Any change Full test suite before opening PR

CLI Standards

Output quality

  • Clean, minimal output — no unnecessary verbosity
  • Consistent formatting across all commands

Error handling

  • No raw stack traces in normal mode
  • Use the structured error system (ix-cli/src/cli/errors.ts)
  • --debug may show detailed output

Language consistency

  • Follow existing Ix command voice and terminology
  • Match output patterns of existing commands

Exit codes

The graph commands share one set of codes, defined in ix-cli/src/cli/outcome.ts: 0 results, 1 error, 2 ambiguous target, 3 target not found, 4 workspace not mapped (IX_LEGACY_EXIT_CODES=1 collapses 2-4 to 1). A hook that runs ix exits with its own status, never ix's: Claude Code treats a hook's exit 2 as a block. Report a resolution failure through resolveFileOrReport or reportResolutionFailure rather than setting process.exitCode yourself, and the right code follows. ix read's ambiguity is the one exception: it exits 0 with its own ambiguous record, as it always has (see below for why adding a non-zero exit is not free).

Making a command exit non-zero is a breaking change to every plugin and MCP client, even when the payload it prints is an improvement. Both consumers throw stdout away on a failed run:

  • Plugins run ix through wrappers that treat a non-zero exit as an error and discard the output — bun's $`…` throws, and the shell hooks branch on || under set -euo pipefail.
  • ix mcp prefers stderr over stdout when the exit is non-zero (runCommand in ix-cli/src/mcp/server.ts), so a structured record written to stdout is replaced by whatever prose happened to reach stderr — usually the resolver's human guidance.

The failure mode is counter-intuitive: you add {"error": "...", "message": "..."} so machine callers can tell a refusal from an empty result, set the exit code to match, and the exit code is what stops anyone from ever seeing the payload.

Before adding a non-zero exit to an existing command, check whether anything calls it programmatically:

# from a directory holding checkouts of the plugin repos
grep -rnE '\$`ix <command>|runIx\(\["<command>"|\$\(ix <command>' . | grep -v '\.md:'

Those three forms cover every call site today — bun shell, the TypeScript runIx helper, and shell command substitution. They are literal on purpose: no plugin builds the command name from a variable, so a literal search is exhaustive. Re-check that assumption if the grep comes back empty for a command you expected to find.

Matches in .md files or agent prompt strings are prose telling a model to run the command — those are fine, the model sees stdout either way. Matches in .ts, .sh or .py are runners, and those break.

If a runner consumes it, the plugin change has to land first, in its own repo, and the Ix change follows. Say so in the PR body and open it as a draft until the dependency is merged.

Applies to: ix-claude-plugin, ix-codex-plugin, ix-cursor-plugin, ix-gemini-plugin, ix-openclaw-plugin, ix-opencode-plugin. Five of the six carry runners today, so "no plugin calls this" is a claim to verify, not assume.

Copyright Headers

Every source file starts with the copyright line, in that language's comment syntax:

// Copyright 2026 Ix Infrastructure Inc.

A shebang stays on line 1 — the header goes directly beneath it. This is enforced by the Lint & Typecheck job, so it gates merges through the required CI Passed check. If you add a file and it goes red, fix every offender at once:

python3 .github/scripts/copyright-headers.py --fix

Test fixtures, vendored code, and anything marked linguist-generated in .gitattributes are deliberately exempt — the parser tests snapshot fixture line numbers, and generated files lose the header on their next regeneration.

Security Checks

PRs and pushes to main run automated security checks:

  • Dependency review — flags new dependencies with known vulnerabilities (PRs only)
  • Trivy scanning — scans the repo filesystem and Docker image for vulnerabilities and misconfigurations
  • Config security — scans Docker Compose and deployment configs for unsafe exposure (e.g., auth disabled with public port bindings, 0.0.0.0 bindings). Local-only configs that bind to 127.0.0.1 are allowed.

All checks fail on CRITICAL or HIGH severity findings. If a check fails on your PR, inspect the output and either fix the vulnerability or document why it's a false positive.

Backend Development

The Scala memory-layer backend is developed in a separate, private repository (ix-infrastructure/Ix-memory). Its source is not publicly accessible, so cloning it is a maintainer-only step. Note that ix-memory-layer — the name used in the release notes, docker-compose.standalone.yml and the image path in .github/workflows/ — is the published artifact, not a repository you can clone.

You do not need the backend source to work on this repository. Everything in the ix CLI is developed against the published backend image, which is public and pullable anonymously. ./scripts/backend.sh up in Local Setup starts it (ghcr.io/ix-infrastructure/ix-memory-layer:latest on 127.0.0.1:8090, plus ArangoDB with no host port). It installs nothing itself — it runs docker compose -f docker-compose.standalone.yml against an already-installed Docker. What the curl | sh installer puts on the machine is a separate list: docs/prerequisites.md.

If a change you want needs the backend itself — a new endpoint, a different response shape, a query that is too slow — open an issue here describing the CLI behaviour you need and what the backend would have to do. A maintainer will carry it across. Please do not open a PR against this repository that assumes an endpoint the released backend does not serve. ix doctor reports the running graph schema version, and curl -s localhost:8090/v1/health returns both that and the backend's release version — that release is what to write against.

OSS vs Pro Boundary

This repository contains open-source Ix functionality. Some features are available only in Ix Pro.

Contributors must:

  • Not reintroduce Pro-only features into this repository
  • Not bypass licensing boundaries
  • Respect the separation between OSS and Pro functionality

If you're unsure whether a feature belongs in OSS or Pro, ask in your PR.