active-svelte/CONTRIBUTING.md

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

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:

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.