bettera11y 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/CHANGELOG.md +43 -0
  2. package/README.md +89 -0
  3. package/dist/index.cjs +853 -0
  4. package/dist/index.cjs.map +1 -0
  5. package/dist/index.d.cts +195 -0
  6. package/dist/index.d.ts +195 -0
  7. package/dist/index.js +810 -0
  8. package/dist/index.js.map +1 -0
  9. package/package.json +48 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,43 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
+ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
+
8
+ ## [0.2.1](https://github.com/bettera11y/bettera11y/compare/v0.2.0...v0.2.1) (2026-04-14)
9
+
10
+
11
+ ### Bug Fixes
12
+
13
+ * **ci:** stabilize release validation and npm publish automation ([57f7712](https://github.com/bettera11y/bettera11y/commit/57f771292479ea4b8bcb3abd45c68c431a32ec45))
14
+ * **ci:** switch release workflow to release-please CLI ([a07abfb](https://github.com/bettera11y/bettera11y/commit/a07abfbbe8aa4d7e3a81e4216c0735c08e2e4277))
15
+
16
+ ## [0.2.0](https://github.com/bettera11y/bettera11y/compare/v0.1.0...v0.2.0) (2026-04-14)
17
+
18
+
19
+ ### Features
20
+
21
+ * **ci:** add automated release PR and publish pipelines ([5018410](https://github.com/bettera11y/bettera11y/commit/50184109fd5ceddaf668e53728914e76fc10a07c))
22
+
23
+
24
+ ### Bug Fixes
25
+
26
+ * **ci:** allow release-please PR creation and node24 runtime ([1f56fa6](https://github.com/bettera11y/bettera11y/commit/1f56fa66e9b0e844360f333250c9b78adec4ab05))
27
+
28
+
29
+ ### Miscellaneous
30
+
31
+ * initialize repository ([eeb2bc5](https://github.com/bettera11y/bettera11y/commit/eeb2bc57da437305693811f1c7d28b34c74ea74d))
32
+ * **tests:** add missing test snapshots ([2d11c73](https://github.com/bettera11y/bettera11y/commit/2d11c733af81b31e5bdbf9759c3f37d477f4c46e))
33
+
34
+ ## [Unreleased]
35
+
36
+ ### Added
37
+
38
+ - Versioned standalone contracts (`input`, `diagnostics`, `rules`, `session`).
39
+ - Async audit engine session API with cancellation and incremental caching.
40
+ - Expanded rule coverage with recommended/strict/WCAG-AA baseline presets.
41
+ - Integration mapping utilities for source locations, severity translation, and deterministic fingerprints.
42
+ - Contract, performance, and deterministic incremental test coverage.
43
+ - Integration and rule authoring documentation for downstream packages.
package/README.md ADDED
@@ -0,0 +1,89 @@
1
+ # BetterA11y Core API
2
+
3
+ `bettera11y` is the standalone, integration-agnostic API layer for BetterA11y.
4
+ It is designed to be imported by separate integration packages (ESLint, Vite,
5
+ Next.js, browser extension) without embedding any of those runtimes here.
6
+
7
+ ## Install
8
+
9
+ ```bash
10
+ npm install bettera11y
11
+ ```
12
+
13
+ ## Quick Start
14
+
15
+ ```ts
16
+ import { createEngine, recommendedPreset } from "bettera11y";
17
+
18
+ const engine = createEngine(recommendedPreset);
19
+ const result = await engine.run({
20
+ kind: "html",
21
+ source: { path: "pages/index.html", language: "html" },
22
+ html: `<html><main><h1>Welcome</h1><img src="/hero.png" /></main></html>`,
23
+ });
24
+
25
+ console.log(result.diagnostics);
26
+ ```
27
+
28
+ ## Integration SDK Surface
29
+
30
+ - `createEngine(initialRules?)`: creates an audit engine instance.
31
+ - `createAuditSession()` on engine: long-lived dev server/watch session API.
32
+ - `recommendedPreset`, `strictPreset`, `wcagAaBaselinePreset`: production rule presets.
33
+ - `MockAdapter`: reference adapter for integration contract testing.
34
+ - `createPrettyReporter()`, `createJsonReporter()`, `createMachineReporter()`: output formatting helpers.
35
+ - `selectorToSourceLocation()`, `translateSeverity()`, `createDiagnosticFingerprint()`: mapping/translation utilities for external integrations.
36
+
37
+ ### Engine Operations
38
+
39
+ - `registerRule(rule)` / `unregisterRule(ruleId)`: mutate runtime rule registry.
40
+ - `listRules()`: deterministic rule list sorted by rule id.
41
+ - `run(input, signal?)`: one-shot async audit with cancellation support.
42
+ - `runIncremental({ changes })`: batch-style incremental audit API for local-dev workflows.
43
+ - `createAuditSession()`: explicit session lifecycle for file-watcher/dev-server usage.
44
+
45
+ ## Session Data Flow
46
+
47
+ ```mermaid
48
+ flowchart LR
49
+ host[ExternalIntegrationHost] --> inputProvider[InputProviderContract]
50
+ inputProvider --> normalizer[InputNormalizer]
51
+ normalizer --> session[AuditSession]
52
+ session --> rules[RuleRuntime]
53
+ rules --> cache[IncrementalCache]
54
+ rules --> diagnostics[DiagnosticEmitter]
55
+ diagnostics --> mapping[MappingUtilities]
56
+ mapping --> host
57
+ ```
58
+
59
+ ## Rule Presets
60
+
61
+ - `recommendedPreset`: low-noise default for most integrations.
62
+ - `strictPreset`: full core ruleset for strict CI/dev policies.
63
+ - `wcagAaBaselinePreset`: WCAG AA oriented baseline.
64
+
65
+ ## Semver and Stability
66
+
67
+ - `BETTERA11Y_API_VERSION` provides protocol-level compatibility signaling.
68
+ - Top-level exports are semver-governed and contract-tested.
69
+ - Existing rule ids and diagnostic shape are compatibility-sensitive.
70
+ - Breaking changes to public contracts require a major version bump.
71
+
72
+ ## Changelog Policy
73
+
74
+ This project follows Keep a Changelog style entries and semantic versioning.
75
+ See `CHANGELOG.md` for release notes.
76
+
77
+ ## Release Process
78
+
79
+ - Commits must follow the Conventional Commits format (`feat:`, `fix:`, optional scope, and `BREAKING CHANGE` footer when needed).
80
+ - GitHub Actions enforces commit formatting on pull requests via commitlint.
81
+ - On merges to `main`, Release Please opens or updates a Release PR that:
82
+ - updates `CHANGELOG.md`
83
+ - bumps `package.json` version according to SemVer rules inferred from commits
84
+ - When the Release PR is merged, GitHub creates a release and a publish workflow releases the package to npm.
85
+
86
+ Required repository secret:
87
+
88
+ - `NPM_TOKEN` with publish access for the npm package.
89
+ - `RELEASE_PLEASE_TOKEN` (PAT or fine-grained token) with repo write permissions so release creation can trigger downstream workflows.