xdbc 1.0.217 → 1.0.219

package/.gitattributes

@@ -1,8 +1,16 @@
-# Exclude generated site output from GitHub language statistics.
-docs/** linguist-generated=true
-coverage/** linguist-generated=true
-dist/** linguist-generated=true
-
-# These HTML files are examples/assessment artifacts, not source code.
-Assessment.html linguist-generated=true
-Test.html linguist-generated=true
+# Enforce LF line endings for all text files
+* text=auto eol=lf
+
+# Explicitly binary files
+*.png binary
+*.jpg binary
+*.ico binary
+
+# Exclude generated site output from GitHub language statistics.
+docs/** linguist-generated=true
+coverage/** linguist-generated=true
+dist/** linguist-generated=true
+
+# These HTML files are examples/assessment artifacts, not source code.
+Assessment.html linguist-generated=true
+Test.html linguist-generated=true

package/.vscode/settings.json

@@ -1,3 +1,3 @@
-{
-	"cSpell.words": ["alia", "esign", "ontract", "Paramvalue", "Postconditions"]
-}
+{
+	"cSpell.words": ["alia", "esign", "ontract", "Paramvalue", "Postconditions"]
+}

package/.vscode/tasks.json

@@ -1,23 +1,23 @@
-{
-	"version": "2.0.0",
-	"tasks": [
-		{
-			"label": "Build and Publish to NPM",
-			"type": "shell",
-			"command": "npm version patch --no-git-tag-version; npm run build; npm publish",
-			"problemMatcher": [],
-			"group": "build"
-		},
-		{
-			"label": "Serve Test.html",
-			"type": "shell",
-			"command": "Copy-Item Test.html dist\\index.html; npm start",
-			"problemMatcher": [],
-			"isBackground": true,
-			"presentation": {
-				"reveal": "always",
-				"panel": "new"
-			}
-		}
-	]
-}
+{
+	"version": "2.0.0",
+	"tasks": [
+		{
+			"label": "Build and Publish to NPM",
+			"type": "shell",
+			"command": "npm version patch --no-git-tag-version; npm run build; npm publish",
+			"problemMatcher": [],
+			"group": "build"
+		},
+		{
+			"label": "Serve Test.html",
+			"type": "shell",
+			"command": "Copy-Item Test.html dist\\index.html; npm start",
+			"problemMatcher": [],
+			"isBackground": true,
+			"presentation": {
+				"reveal": "always",
+				"panel": "new"
+			}
+		}
+	]
+}

package/ASSESSMENT.md

@@ -0,0 +1,249 @@
+# XDBC — Code Quality Assessment
+
+**Date:** May 9, 2026
+**Version:** 1.0.217
+**Scope:** 24 TypeScript source files (4,425 LOC), 19 test suites (1,539 LOC, 218 tests), build configuration, and project structure.
+
+---
+
+## Executive Summary
+
+XDBC is a production-ready TypeScript Design by Contract framework built on the decorator pattern. It provides 17 contract types — from basic type and equality checks through Zod schema validation, conditional logic, and declarative HTML input binding — all surfaced as ergonomic `@PRE`, `@POST`, and `@INVARIANT` decorators. The codebase is clean, fully documented, zero-warning, and comprehensively tested. Architecture is mature: factory helpers centralize decorator wiring, caching is bounded, DBC instances are decoupled from global state, and the DOM binding layer extends the framework declaratively to HTML without any JavaScript wiring.
+
+| Dimension | Score | Notes |
+|---|---|---|
+| Architecture | 9 / 10 | Clean hierarchy, factory pattern, decoupled instances, composable contracts |
+| Code Quality | 9 / 10 | 0 TypeScript errors, JSDoc on all public APIs, justified `any` usage |
+| Test Coverage | 9 / 10 | 218 tests across 19 suites; all contracts, decorators, DOM binding, and callbacks covered |
+| Security | 9.5 / 10 | Prototype pollution blocked, ReDoS-safe, HTML-sanitized errors, 0 audit vulnerabilities |
+| Performance | 8 / 10 | Lazy regex compilation, bounded FIFO caches, zero-cost disabling |
+| Maintainability | 9 / 10 | Consistent patterns, factory helpers, extensible DOM registry, 0 TODO/FIXME debt |
+| **Overall** | **9 / 10** | Production-ready with excellent correctness, security, test coverage, and extensibility |
+
+---
+
+## 1. Architecture
+
+XDBC follows a single-inheritance hierarchy: `DBC` is the base class providing the entire decorator infrastructure, and 17 contract classes extend it. Each contract class exposes three static decorator factories (`PRE`, `POST`, `INVARIANT`), a static `checkAlgorithm()` for composable use, and an instance `check()` method for dynamic scenarios.
+
+**Strengths:**
+
+- **Factory helpers** (`createPRE`, `createPOST`, `createINVARIANT`) centralize decorator wiring in the base class, eliminating hundreds of lines of duplicated boilerplate across contracts
+- **Decoupled instances** — `DBC.register()` separates construction from global mounting; `DBC.isolated()` enables test isolation without global state pollution; `DBC.getRegistered()` provides a typed public accessor
+- **Composability** — `AE` (Array Element) accepts any `{ check(toCheck) }` object, enabling contract chaining (e.g., AE + REGEX to validate every element of an array matches a pattern)
+- **Path resolution** — Dot notation, array indices, method calls, and `::` multi-path syntax for deep property access in nested structures
+- **Lazy initialization** — `REGEX.stdExp` patterns compiled on first access, not at import time
+- **DOM binding layer** — `scanDOM()` + `registerDOMContract()` extend the framework to HTML inputs declaratively, with a full registry of all attribute-expressible contracts and an OR fragment combinator
+
+**Contract library:**
+
+| Category | Contracts |
+|---|---|
+| Equality | EQ, DIFFERENT |
+| Type | TYPE, INSTANCE, DEFINED, UNDEFINED |
+| Comparison | GREATER, LESS, GREATER_OR_EQUAL, LESS_OR_EQUAL |
+| Pattern | REGEX (+ 13 built-in standard patterns), ZOD |
+| Structure | JSON_OP, JSON_Parse, HasAttribute, ARRAY, PLAIN_OBJECT |
+| Logic | OR, AE (Array Element), IF (conditional) |
+
+---
+
+## 2. Code Quality
+
+### Compiler Status
+
+**0 TypeScript errors.** Strict mode enabled with `experimentalDecorators`, `emitDecoratorMetadata`, target ES6, `moduleResolution: "bundler"`, and explicit `rootDir: "./src"`.
+
+### Type Safety
+
+`any` annotations are confined to reflection and decorator boundaries where TypeScript cannot express the runtime types. Each is documented with a `biome-ignore lint/suspicious/noExplicitAny` comment explaining the necessity. No gratuitous `any` usage exists outside those boundaries.
+
+### Documentation
+
+100% JSDoc coverage on all public methods with `@param`, `@returns`, and `@throws` tags. Region markers (`#region`/`#endregion`) structure each file into logical sections. TypeDoc configuration generates browsable HTML documentation (`npm run docs`).
+
+### Code Organization
+
+| File | LOC | Responsibility |
+|---|---|---|
+| DBC.ts | ~800 | Core infrastructure: decorators, caching, path resolution, reporting, `onInfringement` callback |
+| Demo.ts | ~500 | Full-coverage usage examples — all 17 contracts demonstrated |
+| AE.ts | ~271 | Array element contract (most complex) |
+| REGEX.ts | ~179 | Pattern matching + 13 lazy standard expressions |
+| OR.ts | ~175 | Logical OR composition |
+| DOM.ts | ~120 | Declarative HTML input binding via `data-xdbc-*` attributes |
+| Remaining 17 | 30–150 each | Individual contracts, well-scoped |
+
+No dead code, no unused imports, no TODO/FIXME comments.
+
+---
+
+## 3. Test Coverage
+
+**218 tests across 19 suites — all passing.**
+
+| Test Suite | Tests | Focus |
+|---|---|---|
+| ARRAY | ~8 | Array type enforcement, null/undefined passthrough |
+| PLAIN_OBJECT | ~8 | Plain object enforcement, array/null rejection |
+| DEFINED | ~6 | Null and undefined rejection |
+| UNDEFINED | ~6 | Non-undefined rejection |
+| REGEX | ~15 | Pattern matching, standard expressions, invert mode |
+| TYPE | ~10 | Type checking, multi-type strings |
+| EQ | ~10 | Strict equality, path resolution, inversion |
+| GREATER / LESS / comparisons | ~16 | All four comparison directions, boundary values |
+| AE | ~14 | Array element checking, index and range modes |
+| INSTANCE | ~8 | Constructor instance checks |
+| OR | ~10 | Multi-condition OR logic |
+| IF | ~8 | Conditional contract (condition + inCase) |
+| HasAttribute | ~8 | HTMLElement attribute presence |
+| JSON_OP | ~8 | Object property + type checking |
+| JSON_Parse | ~6 | JSON string parseability |
+| ZOD | ~12 | Zod schema validation (string, number, object) |
+| Decorators | ~25 | PRE, POST, INVARIANT, ParamvalueProvider, static methods |
+| onInfringement | ~19 | Callback signature, type/value context, decorator integration |
+| DOM | ~38 | All 10 attribute contracts, OR fragments, IME, registerDOMContract, onInfringement integration |
+
+**Notable test characteristics:**
+
+- Happy path and negative cases for every contract
+- Edge cases: null, undefined, empty string, zero, false, boundary values
+- Invert mode tested where applicable (EQ→DIFFERENT, HasAttribute, IF)
+- HTMLElement contracts tested natively via jsdom environment
+- DOM tests verify input reversion, event cleanup, and IME composition handling
+- `onInfringement` tests verify all three context types (`precondition`, `postcondition`, `invariant`) and the `value` field
+
+---
+
+## 4. Security
+
+| Protection | Implementation | Status |
+|---|---|---|
+| Prototype pollution | `resolve()` blocks `__proto__`, `constructor`, `prototype` tokens | ✅ |
+| ReDoS | `REGEX.stdExp.url` uses non-backtracking pattern | ✅ |
+| Error message injection | `DBC.sanitize()` HTML-entity-encodes all interpolated values | ✅ |
+| No dangerous patterns | No `eval()`, `Function()`, or dynamic code execution | ✅ |
+| DOM input reversion | Invalid input reverted before the DOM sees it; throws swallowed inside event handler | ✅ |
+| Minimal dependencies | `reflect-metadata` + `zod` at runtime only | ✅ |
+| 0 npm audit vulnerabilities | Clean dependency tree (overrides applied for transitive vulnerabilities) | ✅ |
+
+---
+
+## 5. Performance
+
+| Optimization | Detail |
+|---|---|
+| **Lazy regex** | `REGEX.stdExp` compiles 13 patterns on first access, not at import |
+| **Cached DBC lookups** | Decorator factories resolve the DBC instance once and reuse on subsequent calls |
+| **Path token cache** | Parsed path tokens cached (FIFO, max 1000 entries) |
+| **DBC instance cache** | Resolved namespace paths cached (FIFO, max 1000 entries) |
+| **Zero-cost disable** | `executionSettings.check*` flags short-circuit before any validation logic |
+| **IME-aware DOM binding** | Validation suspended during composition; fired once on `compositionend` |
+
+**Inherent characteristics** (not defects):
+
+- Closures per decorated method — required by the decorator pattern
+- `paramValueRequests` nested Map — O(1) key lookup, iteration only over contracted parameters per method (typically 1–5)
+- `scanDOM()` queries the subtree once at call time; listeners are attached per element with a cleanup function returned
+
+---
+
+## 6. Notable Features
+
+### `onInfringement` Callback
+
+Infringement handling is configurable per DBC instance via `infringementSettings`:
+
+```ts
+dbc.infringementSettings.throwException = true;
+dbc.infringementSettings.logToConsole = false;
+dbc.infringementSettings.onInfringement = (infringement, context) => {
+    // infringement — DBC.Infringement (extends Error, has .message and .stack)
+    // context.type — "precondition" | "postcondition" | "invariant"
+    // context.value — the raw value that violated the contract
+    Sentry.captureException(infringement, { extra: context });
+};
+```
+
+The callback fires before `throwException`, so it always runs even when an exception is thrown. All three settings are independent and combinable.
+
+### DOM / HTML Input Binding
+
+```ts
+import { scanDOM } from "xdbc/DBC/DOM";
+const cleanup = scanDOM(); // returns a removeEventListeners function
+```
+
+```html
+<input data-xdbc data-xdbc-regex="^\d*$" />
+<input data-xdbc data-xdbc-or="regex:^\d+$;;eq:N/A" />
+```
+
+All 10 attribute-expressible contracts are registered out of the box. Custom contracts can be added via `registerDOMContract(key, checkFn)` before calling `scanDOM()`.
+
+### `DBC.getRegistered(path?)`
+
+Public static that returns a registered DBC instance by namespace path, enabling programmatic access to any registered instance without holding a direct reference.
+
+---
+
+## 7. Build & Tooling
+
+| Tool | Version | Configuration |
+|---|---|---|
+| TypeScript | 5.8 | Strict, decorators, ES6 target, `moduleResolution: "bundler"` |
+| Webpack | 5.99 | `ts-loader`, inline source maps, entry `./src/Demo.ts` |
+| Jest + ts-jest | 29.7 | jsdom environment, 19 test suites |
+| Biome | 1.9.4 | Tabs, recommended lint rules, import organization |
+| TypeDoc | configured | `npm run docs` generates full HTML API documentation |
+| GitHub Actions | CI workflow | Lint → Test (with coverage) → Build on every push |
+
+**Runtime dependencies:** `reflect-metadata`, `zod` — minimal and appropriate.
+
+---
+
+## 8. Strengths
+
+- **Comprehensive contract library** — 17 contracts covering types, equality, comparison, regex, JSON, arrays, instances, conditionals, and schema validation
+- **Ergonomic API** — Non-invasive decorators that preserve clean method signatures
+- **Rich error context** — Infringement messages include class name, method name, parameter index, path, and violation details; `onInfringement` callback provides the full `DBC.Infringement` instance and context type
+- **Flexible execution** — Enable/disable preconditions, postconditions, and invariants independently; log, callback, or throw on violations
+- **Deep property validation** — Dot notation paths, array indices, method calls, multi-path `::` syntax
+- **Type-safe imperative checks** — `tsCheck()` static methods on REGEX, TYPE, INSTANCE, OR, EQ, ZOD for use outside decorators
+- **Standard pattern library** — 13 ready-to-use RegExp patterns (email, URL, BCP47, date, CSS selectors, etc.) lazily compiled
+- **Declarative DOM binding** — `scanDOM()` + `data-xdbc-*` attributes enforce contracts on HTML inputs without per-element JavaScript
+- **Extensible** — `registerDOMContract()` lets consumers plug in custom contracts; `DBC.register()` decouples instance lifecycle
+- **Zero technical debt** — No TODO/FIXME, no dead code, no unused imports, 0 TS errors, 0 lint violations, 0 audit vulnerabilities
+
+---
+
+## 9. Recommendations
+
+| # | Recommendation | Priority | Effort |
+|---|---|---|---|
+| 1 | Add Jest coverage thresholds to `jest.config.js` to protect coverage over time | Low | 15m |
+| 2 | Add pre-commit hooks (husky + lint-staged) to enforce format/lint before commit | Low | 1h |
+| 3 | Publish `DOM.ts` as a separate npm entry point (`"exports"` field in `package.json`) for consumers who do not need DOM binding | Low | 30m |
+
+---
+
+## Appendix: Null/Undefined Behavior Matrix
+
+| Contract | `null` | `undefined` | Rationale |
+|---|---|---|---|
+| DEFINED | Error | Error | Exists to catch null/undefined |
+| UNDEFINED | Error | Pass | Exists to require undefined |
+| TYPE | Pass | Pass | Optional parameters — no value means no violation |
+| REGEX | Pass | Pass | Optional parameters — no value means no violation |
+| INSTANCE | Pass | Pass | Optional parameters — no value means no violation |
+| ARRAY | Pass | Pass | Optional parameters — no value means no violation |
+| PLAIN_OBJECT | Pass | Pass | Optional parameters — no value means no violation |
+| EQ | `=== null` | `=== undefined` | Strict equality — works correctly |
+| COMPARISON | Crashes | Crashes | Correct — comparing null numerically is a programming error |
+| AE | Delegates | Delegates | Passes through to sub-contract behavior |
+| OR | Delegates | Delegates | Passes through to sub-contract behavior |
+| IF | Delegates | Delegates | Depends on condition/inCase contracts |
+| JSON_OP | Error | Error | Invalid input |
+| JSON_Parse | Throws | Throws | Not a parseable string |
+| HasAttribute | Error | Error | Not an HTMLElement |
+| ZOD | Delegates | Delegates | Depends on Zod schema definition |