# Contributing

Thanks for helping Active become a sharper framework. This repo is still before `0.1.0`, so the highest-value contributions are fixes that improve correctness, security, documentation and consistency.

## Setup

```sh
npm install
npm run dev
```

Use Node `>=22`. The pinned local version is in `.nvmrc`.

## Verification

Run the focused tests for your area first, then the full gate:

```sh
npm run check
npm test
npm run build
npm run test:static
npm run test:bundle
npm run test:all
```

`npm run lint` currently exposes repository-wide cleanup debt and is not part of CI yet. Do
not add new lint violations in files you touch.

## Repository Layout

- `src/libs/*`: pure contracts, constants, helpers and shared types. No Svelte runes. No browser-only APIs.
- `src/svrs/*`: server-authoritative engines, handlers and adapters.
- `src/arts/*`: Svelte-facing active engines and client/runtime integrations.
- `src/web/routes/active`: documentation site.
- `src/web/routes/test`: integration and module test pages.

## Naming And Contracts

- Directories use the short artifact aliases: `aapp`, `logr`, `fmts`, `stor`, `cach`, etc.
- Public types use descriptive names: `EngineLogger`, `ActiveStorage`, `EngineAuth`.
- Root factories use `createEngineX(...)` and `createActiveX(...)`.
- Active engines should follow the shared active-engine contract where applicable.

## Constants First

Do not add magic strings to implementation files for:

- logger categories or messages;
- event names;
- route names;
- cookie names;
- header names;
- error names and codes;
- public method names used in errors;
- storage keys and cache tags.

Add constants in the owning module first, then import them.

## Logging And Diagnostics

Modules should accept the shared `Logger` interface from `src/libs/logr` when they need direct logging. Diagnostics may wrap that logger, but diagnostics must not create a hard dependency from pure libs to an art module.

## Documentation

Documentation and code comments are written in English.

When changing public API, update:

- the module README;
- `/active/docs/<module>`;
- examples if behavior changes;
- tests that snapshot or verify the public surface.

## Deprecation Policy For 0.1.x

Stable public APIs in the `0.1.x` line should not break silently.

Use this process:

- add `@deprecated` JSDoc;
- keep runtime compatibility for at least one minor release;
- emit a runtime warning only when the deprecated path is used;
- introduce experimental replacements under an explicit `__EXPERIMENTAL_*` name if the shape is not final;
- remove only after the documented deprecation window.

## Security Changes

Security-sensitive changes must include regression tests. Read `SECURITY.md` before touching `auth`, `sess`, `perm`, `cach`, `stor`, `http` or cookie/CSRF/OAuth code.