Contributing to BC Atlas

Thanks for helping make AL architecture easier to understand. Bug reports, documentation fixes, examples, and focused code changes are all welcome.

Before you start

• Search the existing issues before opening a new one.
• Use GitHub Discussions or the support guidance in SUPPORT.md for usage questions.
• Report vulnerabilities privately as described in SECURITY.md.
• Follow the Code of Conduct.

Development setup

BC Atlas requires Node.js 22 or newer.

git clone https://github.com/SchulzOli/BC-Atlas.git
cd BC-Atlas
npm ci
npm test
npm run check

Try the CLI against the included sample project:

node src/cli.js graph examples/warehouse-app --view project -o dist/example.d2
npm run examples

Making a change

1. Create a branch from the default branch.
2. Keep the change focused and add or update tests for observable behavior.
3. Update the README or CLI reference when commands, options, or output change.
4. Run npm run check, npm test, and npm pack --dry-run.
5. Open a pull request and explain the problem, solution, and verification.

The architecture pipeline deliberately keeps parsing, resolution, views, and rendering separate. Prefer extending the relevant stage instead of coupling presentation logic to the parser.

Project layout

src/
  cli.js               entry point: resolves the command and dispatches it
  capabilities.js      command catalog: feature areas, options, examples
  cli/                 argument parsing, help rendering, error types
  commands/            init, report, graph/inspect/watch, check
  docs/                AL UI-test documentation pipeline
  analyzer.js ...      parse -> resolve -> view -> render pipeline
  health.js            architecture health rules used by check and report
  output.js            shared D2/JSON/SVG/PNG/PDF writer
  mcp.js               MCP stdio server

To add or change a command, edit src/capabilities.js first. Help text, argument parsing, enum validation, the bca help --format json contract, and the generated reference in docs/reference/ all derive from it. Then add the handler in src/commands/, register it in src/cli.js, document every option in docs/cli-reference.md (a test enforces this), and run npm run docs.

Documentation website

The website at https://schulzoli.github.io/BC-Atlas/ is built with VitePress from the Markdown in this repository: README.md is the home page, docs/ the guides, and examples/ the generated samples. Edit those files, not the site.

npm run site:dev      # live preview
npm run site:build    # what CI runs; fails on dead links

The sidebar comes from scripts/docs-structure.js, which also generates docs/_TOC_.md (npm run docs). Add a new page there. Relative links to files that are not pages, such as .bca.example.json, point to GitHub automatically.

Tests and fixtures

Tests use Node's built-in test runner. Small, self-contained AL fixtures are preferred. A regression fixture should demonstrate only the syntax required to reproduce the issue and must not contain proprietary customer code.

Generated examples are deterministic. If a view changes intentionally, run npm run examples, inspect the changed .d2 and .svg files, and refresh the corresponding screenshots described in examples/README.md.

Commit and pull-request guidance

Use clear, imperative commit subjects. Pull requests should remain reviewable; large changes are easier to merge when split into independently useful steps. By contributing, you agree that your contributions are licensed under the project's MIT License.