Contributing

Guidelines for setting up locally, running tests, and submitting contributions.

Setting Up Locally

Clone the repository and install dependencies:

git clone https://github.com/mihailShumilov/sysmara.git
cd sysmara
npm install

SysMARA is a TypeScript project using ES modules. Make sure you have Node.js 18 or later installed.

Project Structure

The source code is organized under src/:

src/
  cli/              # CLI command implementations
  compiler/         # Capability compiler
  config/           # Configuration loading and validation
  diagnostics/      # Diagnostic rules and code definitions
  graph/            # System graph construction
  impact/           # Impact analysis (BFS traversal)
  parser/           # YAML parsing and Zod validation
  planner/          # Change plan generation
  server/           # SysmaraServer and route handling
  types/            # Shared TypeScript types
  validator/        # Cross-validation logic

Each directory is self-contained with its own exports. The CLI commands in src/cli/ orchestrate the other modules.

Running Tests

SysMARA uses Vitest for testing. Run the full test suite with:

npm test

Run tests in watch mode during development:

npx vitest --watch

Run a specific test file:

npx vitest src/diagnostics/diagnostics.test.ts

Tests are colocated with their source files. A module at src/graph/builder.ts has its tests at src/graph/builder.test.ts.

Coding Standards

Follow these conventions when contributing:

• TypeScript strict mode. The project uses "strict": true in tsconfig.json. All code must pass strict type checking.
• ES modules only. Use import/export syntax. No CommonJS require() calls.
• No external HTTP frameworks. SysMARA's server is intentionally minimal. Do not add Express, Fastify, Koa, or similar dependencies.
• Pure functions preferred. Where possible, write pure functions that take inputs and return outputs without side effects. This makes testing straightforward.
• Zod for validation. All spec schemas are defined using Zod. When adding new spec types or fields, define the Zod schema first.
• Meaningful error messages. Diagnostic messages should tell the user what is wrong and how to fix it. Include the spec name and file path when available.

Adding New Diagnostic Checks

The diagnostic system is one of the most common areas for contributions. To add a new diagnostic rule:

1. Define the code. Add a new diagnostic code constant in src/diagnostics/. Follow the existing numbering scheme: AX1xx for duplicates, AX2xx for reference resolution, AX3xx for boundary violations, AX4xx for orphans, AX5xx for safety, AX6xx for consistency.
2. Implement the rule. Write a function that takes SystemSpecs (and optionally the system graph) and returns an array of diagnostic results. Each result includes the code, severity, message, and the spec that triggered it.
3. Register the rule. Add your rule to the diagnostic runner so it is executed during sysmara build and sysmara doctor.
4. Write tests. Create test cases for both the passing and failing scenarios. Test the message content, not just the presence of a diagnostic.
5. Document the code. Add the new code to the diagnostics reference page.

Extending the Compiler

The capability compiler transforms spec definitions into structured output. To extend it:

1. Understand the current compiler pipeline in src/compiler/.
2. Add your transformation as a new compiler pass or extend an existing one.
3. Ensure your changes are backward-compatible — existing specs should compile identically.
4. Add tests with sample specs that exercise the new behavior.

Adding New CLI Commands

CLI commands are defined in src/cli/. Each command is a self-contained module that:

1. Parses its arguments.
2. Loads configuration from sysmara.config.yaml.
3. Calls into the appropriate core modules (parser, validator, graph builder, etc.).
4. Formats output for the terminal (or as JSON when --json is passed).

When adding a new command, follow the pattern established by existing commands. All commands must support the --json flag.

Pull Request Process

1. Fork and branch. Create a feature branch from main.
2. Make your changes. Keep commits focused and well-described.
3. Run tests. Ensure npm test passes with no failures.
4. Run type checking. Ensure npx tsc --noEmit passes with no errors.
5. Submit a PR. Describe what your change does, why it is needed, and how to test it.
6. Respond to review. Address any feedback from maintainers.

Reporting Issues

If you find a bug or have a feature request, open an issue on GitHub. Include:

• What you expected to happen.
• What actually happened.
• Steps to reproduce (ideally with a minimal spec file).
• Your SysMARA version (sysmara --version).
• Your Node.js version.