xdbc 1.0.207 → 1.0.209

package/SECURITY.md

@@ -1,36 +1,78 @@
 # Security Policy
 
-## Introduction
+## Supported Versions
 
-This security policy outlines our commitment to ensuring the security of XDBC and its users.
+| Version | Supported |
+|---|---|
+| 1.0.x (latest) | Yes |
+| < 1.0.0 | No |
 
-## Reporting Vulnerabilities
+Only the latest published version on npm receives security patches. Users are encouraged to stay up to date.
 
-To report a security vulnerability, please send an email to [Security@WaXCode.net](mailto:Security@WaXCode.net). Please include the following information:
+---
 
-* Description of the vulnerability
-* Steps to reproduce
-* Affected components/versions
-* Potential impact
+## Reporting a Vulnerability
 
-We will acknowledge your report within 24 - 48 hours and provide updates as we investigate.
+**Do not open a public GitHub issue for security vulnerabilities.**
 
-## Vulnerability Handling
+To report a security concern, please email **[Security@WaXCode.net](mailto:Security@WaXCode.net)** with the following details:
 
-We will triage and assess reported vulnerabilities, prioritizing them based on severity. We will develop and test patches, and communicate updates to users.
+- Description of the vulnerability
+- Steps to reproduce or a proof of concept
+- Affected component(s) and version(s)
+- Potential impact and severity assessment
+- Suggested fix, if any
 
-## Disclosure Policy
+### Response Timeline
 
-We will publicly disclose vulnerabilities after a fix is available. We may provide credit to reporters with their consent.
+| Stage | Timeframe |
+|---|---|
+| Acknowledgment of report | Within 48 hours |
+| Initial triage and severity assessment | Within 5 business days |
+| Patch development and internal testing | Dependent on severity |
+| Public disclosure (after fix is available) | Coordinated with reporter |
 
-## Security Best Practices
+---
 
-We follow secure coding standards and regularly update dependencies.
+## Vulnerability Handling Process
+
+1. **Triage** — The report is reviewed, reproduced, and assigned a severity level (Critical / High / Medium / Low).
+2. **Fix** — A patch is developed and tested against the current release.
+3. **Release** — A patched version is published to npm.
+4. **Disclosure** — A security advisory is published on GitHub after the fix is available. The reporter will be credited (with consent).
+
+---
+
+## Scope
+
+This policy covers the XDBC npm package (`xdbc`) and its source code. It does **not** cover:
+
+- Third-party dependencies (report those to the respective maintainers)
+- The generated documentation site
+- User applications that consume XDBC
+
+---
+
+## Security Best Practices for Users
+
+- Keep XDBC updated to the latest version
+- Run `npm audit` regularly to check for transitive dependency vulnerabilities
+- Do not disable contract checking in security-sensitive paths without understanding the implications
+- Avoid passing untrusted input directly to `path` resolution without validation
+
+---
 
 ## Responsible Disclosure
 
-We encourage responsible disclosure and will not take legal action against reporters.
+We are committed to responsible disclosure and will not pursue legal action against individuals who:
+
+- Report vulnerabilities in good faith
+- Allow reasonable time for a fix before public disclosure
+- Do not exploit the vulnerability beyond what is necessary to demonstrate it
+
+---
 
-## Policy Updates
+## Contact
 
-This policy will be reviewed and updated regularly.
+Security reports: **[Security@WaXCode.net](mailto:Security@WaXCode.net)**
+General inquiries: **[XDBC@WaXCode.net](mailto:XDBC@WaXCode.net)**

package/SUPPORT.md

@@ -0,0 +1,65 @@
+# Support
+
+## Getting Help
+
+If you need help using XDBC, there are several resources available:
+
+### Documentation
+
+- **[API Reference](https://callaris.github.io/XDBC/)** — Full generated API documentation
+- **[README](README.md)** — Quick start guide, contracts reference, and configuration
+- **[Demo.ts](src/Demo.ts)** — Annotated usage examples
+
+### Community
+
+- **[GitHub Discussions](https://github.com/CallariS/XDBC/discussions)** — Ask questions, share ideas, and connect with other users
+- **[GitHub Issues](https://github.com/CallariS/XDBC/issues)** — Report bugs or request features
+
+### Direct Contact
+
+- **Email**: [XDBC@WaXCode.net](mailto:XDBC@WaXCode.net)
+
+---
+
+## Frequently Asked Questions
+
+### How do I install XDBC?
+
+```sh
+npm install xdbc
+```
+
+Ensure your `tsconfig.json` has `experimentalDecorators` and `emitDecoratorMetadata` enabled.
+
+### Why do I need `@DBC.ParamvalueProvider`?
+
+TypeScript parameter decorators cannot access the actual parameter values at runtime. The `@DBC.ParamvalueProvider` method decorator intercepts the method call and captures parameter values so that `PRE` contracts can validate them.
+
+### Can I disable contract checking in production?
+
+Yes. Access the DBC instance and toggle execution settings:
+
+```typescript
+const dbc = (globalThis as any).WaXCode.DBC;
+dbc.executionSettings.checkPreconditions = false;
+dbc.executionSettings.checkPostconditions = false;
+dbc.executionSettings.checkInvariants = false;
+```
+
+### Does XDBC work in Node.js?
+
+Yes. XDBC uses `globalThis` for host resolution and works in both browser and Node.js environments.
+
+### How do I report a security vulnerability?
+
+Do not open a public issue. Email **[Security@WaXCode.net](mailto:Security@WaXCode.net)** directly. See [SECURITY.md](SECURITY.md) for the full policy.
+
+---
+
+## Sponsoring
+
+If XDBC is useful in your work, consider supporting its development:
+
+- **[GitHub Sponsors](https://github.com/sponsors/CallariS)**
+- **[Patreon](https://patreon.com/salvatorecallari)**
+- **[PayPal](https://paypal.me/CallariS)**

package/__tests__/DBC/DEFINED.test.ts

@@ -0,0 +1,53 @@
+import { DEFINED } from "../../src/DBC/DEFINED";
+
+describe("DEFINED", () => {
+    const defined = new DEFINED();
+
+    test("Should not report infringement with a string value", () => {
+        expect(defined.check("hello")).toBe(true);
+    });
+
+    test("Should not report infringement with a number value", () => {
+        expect(defined.check(42)).toBe(true);
+    });
+
+    test("Should not report infringement with an empty string", () => {
+        expect(defined.check("")).toBe(true);
+    });
+
+    test("Should not report infringement with zero", () => {
+        expect(defined.check(0)).toBe(true);
+    });
+
+    test("Should not report infringement with false", () => {
+        expect(defined.check(false)).toBe(true);
+    });
+
+    test("Should report infringement with null", () => {
+        expect(typeof defined.check(null)).toBe("string");
+    });
+
+    test("Should report infringement with undefined", () => {
+        expect(typeof defined.check(undefined)).toBe("string");
+    });
+
+    describe("checkAlgorithm", () => {
+        test("Should return true for defined values", () => {
+            expect(DEFINED.checkAlgorithm("test")).toBe(true);
+            expect(DEFINED.checkAlgorithm(0)).toBe(true);
+            expect(DEFINED.checkAlgorithm(false)).toBe(true);
+        });
+
+        test("Should return string for null", () => {
+            const result = DEFINED.checkAlgorithm(null);
+            expect(typeof result).toBe("string");
+            expect(result).toContain("NULL");
+        });
+
+        test("Should return string for undefined", () => {
+            const result = DEFINED.checkAlgorithm(undefined);
+            expect(typeof result).toBe("string");
+            expect(result).toContain("UNDEFINED");
+        });
+    });
+});

package/__tests__/DBC/Decorators.test.ts

@@ -0,0 +1,365 @@
+import "reflect-metadata";
+import { DBC } from "../../src/DBC";
+import { REGEX } from "../../src/DBC/REGEX";
+import { TYPE } from "../../src/DBC/TYPE";
+import { EQ } from "../../src/DBC/EQ";
+import { GREATER } from "../../src/DBC/COMPARISON/GREATER";
+import { GREATER_OR_EQUAL } from "../../src/DBC/COMPARISON/GREATER_OR_EQUAL";
+import { LESS } from "../../src/DBC/COMPARISON/LESS";
+import { LESS_OR_EQUAL } from "../../src/DBC/COMPARISON/LESS_OR_EQUAL";
+import { DIFFERENT } from "../../src/DBC/EQ/DIFFERENT";
+import { INSTANCE } from "../../src/DBC/INSTANCE";
+import { AE } from "../../src/DBC/AE";
+import { OR } from "../../src/DBC/OR";
+
+// Ensure a DBC instance is registered (DBC.ts module-level code does this via DBC.register)
+const dbc: DBC = (window as any).WaXCode?.DBC;
+
+describe("Decorator: @PRE (Preconditions)", () => {
+    class PreTestSubject {
+        @DBC.ParamvalueProvider
+        public regexPre(@REGEX.PRE(/^[A-Z]+$/) input: string): string {
+            return input;
+        }
+
+        @DBC.ParamvalueProvider
+        public typePre(@TYPE.PRE("string") input: unknown): unknown {
+            return input;
+        }
+
+        @DBC.ParamvalueProvider
+        public eqPre(@EQ.PRE("hello") input: string): string {
+            return input;
+        }
+
+        @DBC.ParamvalueProvider
+        public greaterPre(@GREATER.PRE(5) input: number): number {
+            return input;
+        }
+
+        @DBC.ParamvalueProvider
+        public greaterOrEqualPre(@GREATER_OR_EQUAL.PRE(5) input: number): number {
+            return input;
+        }
+
+        @DBC.ParamvalueProvider
+        public lessPre(@LESS.PRE(10) input: number): number {
+            return input;
+        }
+
+        @DBC.ParamvalueProvider
+        public lessOrEqualPre(@LESS_OR_EQUAL.PRE(10) input: number): number {
+            return input;
+        }
+
+        @DBC.ParamvalueProvider
+        public differentPre(@DIFFERENT.PRE("forbidden", undefined) input: string): string {
+            return input;
+        }
+
+        @DBC.ParamvalueProvider
+        public instancePre(@INSTANCE.PRE(Date) input: unknown): unknown {
+            return input;
+        }
+
+        @DBC.ParamvalueProvider
+        public aePre(@AE.PRE([new TYPE("string")]) input: unknown[]): unknown[] {
+            return input;
+        }
+
+        @DBC.ParamvalueProvider
+        public orPre(@OR.PRE([new EQ("a"), new EQ("b")]) input: string): string {
+            return input;
+        }
+    }
+
+    const subject = new PreTestSubject();
+
+    // REGEX.PRE
+    test("REGEX.PRE passes with matching value", () => {
+        expect(() => subject.regexPre("ABC")).not.toThrow();
+    });
+    test("REGEX.PRE throws on non-matching value", () => {
+        expect(() => subject.regexPre("abc123")).toThrow();
+    });
+
+    // TYPE.PRE
+    test("TYPE.PRE passes with correct type", () => {
+        expect(() => subject.typePre("hello")).not.toThrow();
+    });
+    test("TYPE.PRE throws with wrong type", () => {
+        expect(() => subject.typePre(42)).toThrow();
+    });
+
+    // EQ.PRE
+    test("EQ.PRE passes with equal value", () => {
+        expect(() => subject.eqPre("hello")).not.toThrow();
+    });
+    test("EQ.PRE throws with non-equal value", () => {
+        expect(() => subject.eqPre("world")).toThrow();
+    });
+
+    // GREATER.PRE
+    test("GREATER.PRE passes with value > reference", () => {
+        expect(() => subject.greaterPre(10)).not.toThrow();
+    });
+    test("GREATER.PRE throws with value <= reference", () => {
+        expect(() => subject.greaterPre(5)).toThrow();
+    });
+    test("GREATER.PRE throws with value < reference", () => {
+        expect(() => subject.greaterPre(3)).toThrow();
+    });
+
+    // GREATER_OR_EQUAL.PRE
+    test("GREATER_OR_EQUAL.PRE passes with value >= reference", () => {
+        expect(() => subject.greaterOrEqualPre(5)).not.toThrow();
+    });
+    test("GREATER_OR_EQUAL.PRE passes with value > reference", () => {
+        expect(() => subject.greaterOrEqualPre(10)).not.toThrow();
+    });
+    test("GREATER_OR_EQUAL.PRE throws with value < reference", () => {
+        expect(() => subject.greaterOrEqualPre(3)).toThrow();
+    });
+
+    // LESS.PRE
+    test("LESS.PRE passes with value < reference", () => {
+        expect(() => subject.lessPre(5)).not.toThrow();
+    });
+    test("LESS.PRE throws with value >= reference", () => {
+        expect(() => subject.lessPre(10)).toThrow();
+    });
+
+    // LESS_OR_EQUAL.PRE
+    test("LESS_OR_EQUAL.PRE passes with value <= reference", () => {
+        expect(() => subject.lessOrEqualPre(10)).not.toThrow();
+    });
+    test("LESS_OR_EQUAL.PRE throws with value > reference", () => {
+        expect(() => subject.lessOrEqualPre(15)).toThrow();
+    });
+
+    // DIFFERENT.PRE
+    test("DIFFERENT.PRE passes with different value", () => {
+        expect(() => subject.differentPre("allowed")).not.toThrow();
+    });
+    test("DIFFERENT.PRE throws with equal value", () => {
+        expect(() => subject.differentPre("forbidden")).toThrow();
+    });
+
+    // INSTANCE.PRE
+    test("INSTANCE.PRE passes with correct instance", () => {
+        expect(() => subject.instancePre(new Date())).not.toThrow();
+    });
+    test("INSTANCE.PRE throws with wrong instance", () => {
+        expect(() => subject.instancePre("not a date")).toThrow();
+    });
+
+    // AE.PRE
+    test("AE.PRE passes with all elements matching", () => {
+        expect(() => subject.aePre(["a", "b", "c"])).not.toThrow();
+    });
+    test("AE.PRE throws when an element does not match", () => {
+        expect(() => subject.aePre(["a", 42, "c"])).toThrow();
+    });
+
+    // OR.PRE
+    test("OR.PRE passes when one contract is satisfied", () => {
+        expect(() => subject.orPre("a")).not.toThrow();
+    });
+    test("OR.PRE throws when no contract is satisfied", () => {
+        expect(() => subject.orPre("c")).toThrow();
+    });
+});
+
+describe("Decorator: @POST (Postconditions)", () => {
+    class PostTestSubject {
+        @REGEX.POST(/^OK:.*$/)
+        @DBC.ParamvalueProvider
+        public formatResponse(@TYPE.PRE("string") input: string): string {
+            return `OK:${input}`;
+        }
+
+        @REGEX.POST(/^OK:.*$/)
+        public failingPost(): string {
+            return "FAIL";
+        }
+
+        @EQ.POST("hello")
+        public eqPost(returnThis: string): string {
+            return returnThis;
+        }
+    }
+
+    const subject = new PostTestSubject();
+
+    test("POST passes when return value matches", () => {
+        expect(() => subject.formatResponse("test")).not.toThrow();
+    });
+
+    test("POST throws when return value does not match", () => {
+        expect(() => subject.failingPost()).toThrow();
+    });
+
+    test("EQ.POST passes with matching return value", () => {
+        expect(() => subject.eqPost("hello")).not.toThrow();
+    });
+
+    test("EQ.POST throws with non-matching return value", () => {
+        expect(() => subject.eqPost("world")).toThrow();
+    });
+});
+
+describe("Decorator: @INVARIANT (Field contracts)", () => {
+    test("INVARIANT allows valid initial value", () => {
+        expect(() => {
+            class InvariantSubject {
+                @REGEX.INVARIANT(/^[A-Z]+$/)
+                public code = "ABC";
+            }
+            new InvariantSubject();
+        }).not.toThrow();
+    });
+
+    test("INVARIANT throws on invalid initial value", () => {
+        expect(() => {
+            class InvariantSubject {
+                @REGEX.INVARIANT(/^[A-Z]+$/)
+                public code = "abc123";
+            }
+            new InvariantSubject();
+        }).toThrow();
+    });
+
+    test("INVARIANT throws on invalid reassignment", () => {
+        class InvariantSubject {
+            @REGEX.INVARIANT(/^[A-Z]+$/)
+            public code = "ABC";
+        }
+        const obj = new InvariantSubject();
+        expect(() => {
+            obj.code = "invalid!";
+        }).toThrow();
+    });
+
+    test("INVARIANT allows valid reassignment", () => {
+        class InvariantSubject {
+            @REGEX.INVARIANT(/^[A-Z]+$/)
+            public code = "ABC";
+        }
+        const obj = new InvariantSubject();
+        expect(() => {
+            obj.code = "XYZ";
+        }).not.toThrow();
+    });
+});
+
+describe("Decorator: @ParamvalueProvider", () => {
+    test("ParamvalueProvider passes multiple parameter contracts", () => {
+        class MultiParam {
+            @DBC.ParamvalueProvider
+            public method(
+                @TYPE.PRE("string") a: string,
+                @TYPE.PRE("number") b: number,
+            ): string {
+                return `${a}:${b}`;
+            }
+        }
+        const obj = new MultiParam();
+        expect(() => obj.method("hello", 42)).not.toThrow();
+    });
+
+    test("ParamvalueProvider catches second parameter violation", () => {
+        class MultiParam {
+            @DBC.ParamvalueProvider
+            public method(
+                @TYPE.PRE("string") a: string,
+                @TYPE.PRE("number") b: number,
+            ): string {
+                return `${a}:${b}`;
+            }
+        }
+        const obj = new MultiParam();
+        expect(() => obj.method("hello", "not a number" as any)).toThrow();
+    });
+});
+
+describe("DBC infringement settings", () => {
+    class InfringementTest {
+        @DBC.ParamvalueProvider
+        public method(@TYPE.PRE("string") input: unknown): unknown {
+            return input;
+        }
+    }
+
+    test("Violations throw DBC.Infringement by default", () => {
+        const obj = new InfringementTest();
+        expect(() => obj.method(42)).toThrow(/XDBC Infringement/);
+    });
+
+    test("Error message includes class name, method name, and parameter info", () => {
+        const obj = new InfringementTest();
+        try {
+            obj.method(42);
+            fail("Should have thrown");
+        } catch (e: any) {
+            expect(e.message).toContain("InfringementTest");
+            expect(e.message).toContain("method");
+            expect(e.message).toContain("1st parameter");
+        }
+    });
+});
+
+describe("DBC.register()", () => {
+    test("registers an instance at the default path", () => {
+        const custom = new DBC();
+        DBC.register(custom);
+        expect((window as any).WaXCode.DBC).toBe(custom);
+        // Restore original
+        DBC.register(dbc);
+    });
+
+    test("registers an instance at a custom path", () => {
+        const custom = new DBC();
+        DBC.register(custom, "TestVendor.DBC");
+        expect((window as any).TestVendor.DBC).toBe(custom);
+    });
+
+    test("constructor does not auto-mount to globalThis", () => {
+        const original = (window as any).WaXCode.DBC;
+        const orphan = new DBC();
+        // Constructor should NOT have replaced the registered instance
+        expect((window as any).WaXCode.DBC).toBe(original);
+        expect(orphan).not.toBe(original);
+    });
+});
+
+describe("DBC.isolated()", () => {
+    test("provides a temporary DBC instance and restores the original", () => {
+        const original = (window as any).WaXCode.DBC;
+        let isolatedInstance: DBC | undefined;
+        DBC.isolated((tempDbc) => {
+            isolatedInstance = tempDbc;
+            expect(tempDbc).not.toBe(original);
+            expect((window as any).WaXCode.DBC).toBe(tempDbc);
+        });
+        // After isolated() returns, the original is restored
+        expect((window as any).WaXCode.DBC).toBe(original);
+        expect(isolatedInstance).toBeDefined();
+    });
+
+    test("restores original even if callback throws", () => {
+        const original = (window as any).WaXCode.DBC;
+        expect(() => {
+            DBC.isolated(() => {
+                throw new Error("test error");
+            });
+        }).toThrow("test error");
+        expect((window as any).WaXCode.DBC).toBe(original);
+    });
+
+    test("isolated instance has independent settings", () => {
+        DBC.isolated((tempDbc) => {
+            tempDbc.executionSettings.checkPreconditions = false;
+            expect(dbc.executionSettings.checkPreconditions).toBe(true);
+        });
+    });
+});

package/__tests__/DBC/GREATER.test.ts

@@ -1,4 +1,6 @@
-import { GREATER } from "../../src/DBC/GREATER";
+import { GREATER } from "../../src/DBC/COMPARISON/GREATER";
+import { GREATER_OR_EQUAL } from "../../src/DBC/COMPARISON/GREATER_OR_EQUAL";
+import { LESS_OR_EQUAL } from "../../src/DBC/COMPARISON/LESS_OR_EQUAL";
 
 describe("GREATER", () => {
 	const greater = new GREATER(1);
@@ -11,16 +13,16 @@ describe("GREATER", () => {
 		expect(typeof greater.check(0)).toBe("string");
 	});
 
-	test("Should report infringement with '0' to check", () => {
-		expect(typeof greater.check(0)).toBe("string");
+	test("Should report infringement with '1' to check (equality not permitted)", () => {
+		expect(typeof greater.check(1)).toBe("string");
 	});
 
 	test("Should not report infringement with '1' and '1' to check since equality is now permitted", () => {
-		expect(new GREATER(1, true).check(1)).toBe(true);
+		expect(new GREATER_OR_EQUAL(1).check(1)).toBe(true);
 	});
 
-	test("Should not report infringement with '2' and '1' to check since inverting the result is now on", () => {
-		expect(new GREATER(1, true, true).check(1)).toBe(true);
+	test("Should not report infringement with '1' and '1' to check since inverting the result is now on", () => {
+		expect(new LESS_OR_EQUAL(1).check(1)).toBe(true);
 	});
 
 	test("Should not report infringement with 'undefined' and 'undefined' to check", () => {

package/__tests__/DBC/HasAttribute.test.ts

@@ -0,0 +1,56 @@
+import { HasAttribute } from "../../src/DBC/HasAttribute";
+
+describe("HasAttribute", () => {
+    const hasId = new HasAttribute("id");
+
+    test("Should not report infringement when attribute exists", () => {
+        const el = document.createElement("div");
+        el.setAttribute("id", "test");
+        expect(hasId.check(el)).toBe(true);
+    });
+
+    test("Should report infringement when attribute is missing", () => {
+        const el = document.createElement("div");
+        expect(typeof hasId.check(el)).toBe("string");
+    });
+
+    test("Should report infringement when value is not an HTMLElement", () => {
+        expect(typeof hasId.check("not an element")).toBe("string");
+    });
+
+    test("Should report infringement when value is a plain object", () => {
+        expect(typeof hasId.check({ id: "test" })).toBe("string");
+    });
+
+    describe("invert", () => {
+        const noId = new HasAttribute("id", true);
+
+        test("Should not report infringement when attribute is absent", () => {
+            const el = document.createElement("div");
+            expect(noId.check(el)).toBe(true);
+        });
+
+        test("Should report infringement when forbidden attribute exists", () => {
+            const el = document.createElement("div");
+            el.setAttribute("id", "test");
+            expect(typeof noId.check(el)).toBe("string");
+        });
+    });
+
+    describe("checkAlgorithm", () => {
+        test("Should return true when element has the attribute", () => {
+            const el = document.createElement("span");
+            el.setAttribute("class", "active");
+            expect(HasAttribute.checkAlgorithm(el, "class", false)).toBe(true);
+        });
+
+        test("Should return string when element lacks the attribute", () => {
+            const el = document.createElement("span");
+            expect(typeof HasAttribute.checkAlgorithm(el, "class", false)).toBe("string");
+        });
+
+        test("Should return string for non-HTMLElement", () => {
+            expect(typeof HasAttribute.checkAlgorithm(42, "id", false)).toBe("string");
+        });
+    });
+});