@venn-lang/assert 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vinicius Borges
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,116 @@
+# @venn-lang/assert
+
+> The words that follow `expect`: `equals`, `contains`, `oneOf` and `closeTo`.
+
+`expect` belongs to the kernel; the vocabulary does not. This plugin registers four matchers, each
+carrying its own one-line failure message and the two values it compared. A red assertion therefore
+prints a sentence a person can read plus a structured diff, never `[object Object]`. The plugin
+contributes no verbs, declares no types and needs no host capability.
+
+## Install
+
+`@venn-lang/assert` is part of the stdlib the `venn` CLI and the language server load, so there is
+nothing to install. A file that asserts brings the namespace in:
+
+```ruby
+use "venn/assert"
+```
+
+A matcher used without that line is `VN2007`; a word no plugin registered is `VN2004`. Both are
+reported by `venn check`, before anything runs.
+
+## Usage
+
+```ruby
+module demo.matchers
+
+use "venn/assert"
+
+flow "Bareword matchers" {
+  step "checks" {
+    let plan = "pro"
+    let total = 99.005
+    expect plan oneOf ["free", "pro"]
+    expect "Total: $99.00" contains "$99.00"
+    expect total closeTo 99.0 { within: 0.01 }
+    expect plan equals "pro"
+    expect not plan oneOf ["a", "b"]
+  }
+}
+```
+
+Matchers are barewords: they resolve by name alone, not through the `assert.` prefix. The namespace
+is what `use` brings into the file.
+
+## Matchers
+
+| Matcher | Written as | Passes when |
+| --- | --- | --- |
+| `equals` | `expect res.status equals 200` | The two values are structurally the same. No coercion: `"200"` never equals `200`. |
+| `contains` | `expect body contains "$99.00"` | The subject is a string holding that substring, or a list holding that item. Anything else fails. |
+| `oneOf` | `expect plan oneOf ["free", "pro"]` | The subject is one of the listed values. |
+| `closeTo` | `expect total closeTo 99.0 { within: 0.01 }` | The two numbers differ by no more than the tolerance. `within` defaults to `0.01`. |
+
+`not` negates any of them: `expect not plan oneOf ["a", "b"]`.
+
+### How `equals` compares
+
+Maps and lists compare by value, not by reference: a body built twice the same way is the same
+thing, and comparing it by identity would fail an assertion that reads as true on the page.
+
+- A field set to nothing is not a field. `{ id: 1, ref: absent }` equals `{ id: 1 }`, because both
+  print and travel over the wire identically. A field holding `null` is still a field, so
+  `{ id: 1, ref: null }` does not.
+- A value that contains itself is handled rather than overflowing the stack: two containers already
+  open on the way down are taken as equal, the way one cycle matches another.
+- Anything that is neither a map nor a list (dates, plugin objects, closures) compares by identity.
+
+`contains` compares list items the same way, so `expect rows contains { id: 1 }` works.
+
+## What a failure looks like
+
+The title is one line, in the values' own terms:
+
+```
+expected {"status":"pending"} to equal {"status":"paid"}
+expected 500 to be one of [200,204]
+expected 99.5 to be within 0.01 of 99
+```
+
+Both sides are rendered to the same level of detail. Past a line's worth, both are summarised by
+shape (`expected a map with 3 fields to equal a map with 2 fields`) rather than one being spelled
+out beside one that is not. Strings are quoted, so `"200"` never reads as `200`.
+
+The full values are not lost: each matcher hands back the two sides, and the kernel turns them into
+the diff carried by the `VN6001` problem. Membership matchers (`contains`, `oneOf`) mark their sides
+unaligned, because the needle was held against every item and never stood opposite item 0. A
+negated `expect` gets no diff on purpose: under `not` the two sides matched, and "expected 200,
+actual 200" explains nothing.
+
+## API
+
+| Export | What it is |
+| --- | --- |
+| `assertPlugin` (also the default export) | The `PluginDefinition`: namespace `assert`, matchers only, no actions, no `typeDefs`, no required capability. |
+| `assertMatchers` | The four `MatcherDefinition`s, in order: `equals`, `contains`, `oneOf`, `closeTo`. |
+
+A matcher is a plain object, so it can be exercised directly:
+
+```ts
+import { assertMatchers } from "@venn-lang/assert";
+
+const equals = assertMatchers.find((matcher) => matcher.name === "equals");
+
+equals?.test({ subject: { id: 1 }, args: [{ id: 1 }], params: {} });
+// true
+equals?.message({ subject: "200", args: [200], params: {} });
+// 'expected "200" to equal 200'
+equals?.detail?.({ subject: { status: "pending" }, args: [{ status: "paid" }], params: {} });
+// { expected: { status: "paid" }, actual: { status: "pending" } }
+```
+
+## See also
+
+- [`@venn-lang/sdk`](../sdk) for `defineMatcher` and the definition types used here.
+- [`@venn-lang/runtime`](../runtime) for the registry that resolves a bareword and emits `VN6001`.
+- [`@venn-lang/fmt`](../std-fmt) for turning a value into text you can assert against.

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+import { MatcherDefinition, PluginDefinition } from "@venn-lang/sdk";
+//#region src/matchers/index.d.ts
+/** The words `expect` gains from this plugin: `equals`, `contains`, `oneOf`, `closeTo`. */
+declare const assertMatchers: MatcherDefinition[];
+//#endregion
+//#region src/plugin.d.ts
+/**
+ * The `assert` plugin: the vocabulary behind `expect`.
+ *
+ * `expect` is kernel syntax; the words that follow it are not. This plugin
+ * contributes those words and nothing else, so it declares no verbs, no
+ * resources, no types and no host capabilities.
+ */
+declare const assertPlugin: PluginDefinition;
+//#endregion
+export { assertMatchers, assertPlugin, assertPlugin as default };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/matchers/index.ts","../src/plugin.ts"],"mappings":";;;cAOa,gBAAgB;;;;;;;;;;cCGhB,cAAc"}

package/dist/index.js

@@ -0,0 +1,220 @@
+import { arg, defineMatcher, definePlugin, z } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+//#region src/matchers/failure-line.ts
+/** A failure title is one line. Past this, a value is summarised instead. */
+const LIMIT = 44;
+/**
+* Builds the line a failure leads with: `expected <subject> <relation> <other>`.
+*
+* Both sides render to the same level of detail: one spelled out next to one
+* summarised reads as a reporter glitch rather than a comparison. Nothing is
+* lost, the full values travel in the problem's diff.
+*/
+function failureLine(args) {
+	const [left, right] = pair(args.subject, args.other);
+	return `expected ${left} ${args.relation} ${right}`;
+}
+function pair(subject, other) {
+	const left = render(subject);
+	const right = render(other);
+	if (left.length <= LIMIT && right.length <= LIMIT) return [left, right];
+	return [summarize(subject), summarize(other)];
+}
+/** Strings quoted, maps and lists as compact JSON. Never `[object Object]`. */
+function render(value) {
+	if (value === void 0) return "absent";
+	if (value === null) return "null";
+	if (typeof value === "function") return "fn";
+	if (typeof value === "string") return JSON.stringify(value);
+	if (typeof value !== "object") return String(value);
+	return json(value);
+}
+function summarize(value) {
+	if (typeof value === "string") return `${JSON.stringify(value.slice(0, LIMIT))}…`;
+	if (typeof value === "object" && value !== null) return shapeOf(value);
+	return render(value);
+}
+function shapeOf(value) {
+	if (Array.isArray(value)) return `a list of ${value.length} ${plural("item", value.length)}`;
+	const count = Object.keys(value).length;
+	return `a map with ${count} ${plural("field", count)}`;
+}
+function json(value) {
+	try {
+		return JSON.stringify(value) ?? shapeOf(value);
+	} catch {
+		return shapeOf(value);
+	}
+}
+function plural(noun, count) {
+	return count === 1 ? noun : `${noun}s`;
+}
+//#endregion
+//#region src/matchers/close-to.ts
+const DEFAULT_WITHIN = .01;
+/** `expect x closeTo 99.0 { within: 0.01 }`: numeric equality within a tolerance. */
+const closeTo = defineMatcher({
+	name: "closeTo",
+	args: [arg("value", t.number, "The number to come near. `within` in the options sets how near.")],
+	params: z.object({ within: z.number().default(DEFAULT_WITHIN) }),
+	test: ({ subject, args, params }) => Math.abs(Number(subject) - Number(args[0])) <= tolerance(params),
+	message: ({ subject, args, params }) => failureLine({
+		subject,
+		relation: `to be within ${tolerance(params)} of`,
+		other: args[0]
+	}),
+	detail: ({ subject, args }) => ({
+		expected: args[0],
+		actual: subject
+	})
+});
+function tolerance(params) {
+	return params.within ?? DEFAULT_WITHIN;
+}
+//#endregion
+//#region src/matchers/deep-equals.ts
+/**
+* Structural equality over the language's values.
+*
+* A body, a row or a list of ids is a value, not a handle, so two built the
+* same way are equal. Anything that is not a plain map or a list (dates, plugin
+* objects, closures) still compares by identity: guessing at their innards
+* would be worse than being strict.
+*/
+function deepEquals(a, b) {
+	return equal(a, b, []);
+}
+/**
+* `open` holds the containers already entered on the way down, so a value that
+* contains itself cannot recurse until the stack gives out. Two containers
+* already open count as equal, the way one cycle matches another.
+*/
+function equal(a, b, open) {
+	if (a === b) return true;
+	const openA = open.includes(a);
+	const openB = open.includes(b);
+	if (openA || openB) return openA && openB;
+	if (Array.isArray(a) || Array.isArray(b)) return sameList(a, b, open);
+	if (!isMap(a) || !isMap(b)) return false;
+	return sameMap(a, b, open);
+}
+function sameList(a, b, open) {
+	if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+	const next = [
+		...open,
+		a,
+		b
+	];
+	return a.every((item, index) => equal(item, b[index], next));
+}
+/**
+* A field set to nothing is not a field. `{ id: 1, ref: absent }` prints, and
+* travels over the wire, exactly like `{ id: 1 }`, so the two compare equal.
+*/
+function sameMap(a, b, open) {
+	const keys = presentKeys(a);
+	if (keys.length !== presentKeys(b).length) return false;
+	const next = [
+		...open,
+		a,
+		b
+	];
+	return keys.every((key) => equal(a[key], b[key], next));
+}
+function presentKeys(value) {
+	return Object.keys(value).filter((key) => value[key] !== void 0);
+}
+function isMap(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+}
+//#endregion
+//#region src/matchers/contains.ts
+/** `expect x contains y`: substring for strings, membership for lists. */
+const contains = defineMatcher({
+	name: "contains",
+	args: [arg("value", t.dynamic, "What to look for: a substring, or an item of the list.")],
+	test: ({ subject, args }) => includes(subject, args[0]),
+	message: ({ subject, args }) => failureLine({
+		subject,
+		relation: "to contain",
+		other: args[0]
+	}),
+	detail: ({ subject, args }) => ({
+		expected: args[0],
+		actual: subject,
+		aligned: false
+	})
+});
+function includes(subject, value) {
+	if (typeof subject === "string") return subject.includes(String(value));
+	if (Array.isArray(subject)) return subject.some((item) => deepEquals(item, value));
+	return false;
+}
+//#endregion
+//#region src/matchers/equals.ts
+/** `expect x equals y`: the same value, no coercion, maps and lists included. */
+const equals = defineMatcher({
+	name: "equals",
+	args: [arg("value", t.dynamic, "What the subject should be, compared field by field.")],
+	test: ({ subject, args }) => deepEquals(subject, args[0]),
+	message: ({ subject, args }) => failureLine({
+		subject,
+		relation: "to equal",
+		other: args[0]
+	}),
+	detail: ({ subject, args }) => ({
+		expected: args[0],
+		actual: subject
+	})
+});
+//#endregion
+//#region src/matchers/one-of.ts
+/** `expect x oneOf [a, b]`: passes if the subject is one of the options. */
+const oneOf = defineMatcher({
+	name: "oneOf",
+	args: [arg("values", t.list(t.dynamic), "The accepted values. The subject must be one of them.")],
+	test: ({ subject, args }) => options(args[0]).some((option) => deepEquals(option, subject)),
+	message: ({ subject, args }) => failureLine({
+		subject,
+		relation: "to be one of",
+		other: args[0]
+	}),
+	detail: ({ subject, args }) => ({
+		expected: args[0],
+		actual: subject,
+		aligned: false
+	})
+});
+function options(value) {
+	return Array.isArray(value) ? value : [];
+}
+//#endregion
+//#region src/matchers/index.ts
+/** The words `expect` gains from this plugin: `equals`, `contains`, `oneOf`, `closeTo`. */
+const assertMatchers = [
+	equals,
+	contains,
+	oneOf,
+	closeTo
+];
+//#endregion
+//#region src/plugin.ts
+/**
+* The `assert` plugin: the vocabulary behind `expect`.
+*
+* `expect` is kernel syntax; the words that follow it are not. This plugin
+* contributes those words and nothing else, so it declares no verbs, no
+* resources, no types and no host capabilities.
+*/
+const assertPlugin = definePlugin({
+	name: "venn/assert",
+	version: "0.0.0",
+	namespace: "assert",
+	matchers: assertMatchers
+});
+//#endregion
+export { assertMatchers, assertPlugin, assertPlugin as default };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/matchers/failure-line.ts","../src/matchers/close-to.ts","../src/matchers/deep-equals.ts","../src/matchers/contains.ts","../src/matchers/equals.ts","../src/matchers/one-of.ts","../src/matchers/index.ts","../src/plugin.ts"],"sourcesContent":["/** A failure title is one line. Past this, a value is summarised instead. */\nconst LIMIT = 44;\n\n/**\n * Builds the line a failure leads with: `expected <subject> <relation> <other>`.\n *\n * Both sides render to the same level of detail: one spelled out next to one\n * summarised reads as a reporter glitch rather than a comparison. Nothing is\n * lost, the full values travel in the problem's diff.\n */\nexport function failureLine(args: { subject: unknown; relation: string; other: unknown }): string {\n  const [left, right] = pair(args.subject, args.other);\n  return `expected ${left} ${args.relation} ${right}`;\n}\n\nfunction pair(subject: unknown, other: unknown): [string, string] {\n  const left = render(subject);\n  const right = render(other);\n  if (left.length <= LIMIT && right.length <= LIMIT) return [left, right];\n  return [summarize(subject), summarize(other)];\n}\n\n/** Strings quoted, maps and lists as compact JSON. Never `[object Object]`. */\nfunction render(value: unknown): string {\n  if (value === undefined) return \"absent\";\n  if (value === null) return \"null\";\n  if (typeof value === \"function\") return \"fn\";\n  if (typeof value === \"string\") return JSON.stringify(value);\n  if (typeof value !== \"object\") return String(value);\n  return json(value);\n}\n\nfunction summarize(value: unknown): string {\n  if (typeof value === \"string\") return `${JSON.stringify(value.slice(0, LIMIT))}…`;\n  if (typeof value === \"object\" && value !== null) return shapeOf(value);\n  return render(value);\n}\n\nfunction shapeOf(value: object): string {\n  if (Array.isArray(value)) return `a list of ${value.length} ${plural(\"item\", value.length)}`;\n  const count = Object.keys(value).length;\n  return `a map with ${count} ${plural(\"field\", count)}`;\n}\n\nfunction json(value: object): string {\n  try {\n    return JSON.stringify(value) ?? shapeOf(value);\n  } catch {\n    return shapeOf(value);\n  }\n}\n\nfunction plural(noun: string, count: number): string {\n  return count === 1 ? noun : `${noun}s`;\n}\n","import { arg, defineMatcher, type MatcherDefinition, z } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\nimport { failureLine } from \"./failure-line.js\";\n\nconst DEFAULT_WITHIN = 0.01;\n\n/** `expect x closeTo 99.0 { within: 0.01 }`: numeric equality within a tolerance. */\nexport const closeTo: MatcherDefinition = defineMatcher({\n  name: \"closeTo\",\n  args: [arg(\"value\", t.number, \"The number to come near. `within` in the options sets how near.\")],\n  params: z.object({ within: z.number().default(DEFAULT_WITHIN) }),\n  test: ({ subject, args, params }) =>\n    Math.abs(Number(subject) - Number(args[0])) <= tolerance(params),\n  // The tolerance belongs in the title: without it a failure cannot be judged.\n  message: ({ subject, args, params }) =>\n    failureLine({ subject, relation: `to be within ${tolerance(params)} of`, other: args[0] }),\n  detail: ({ subject, args }) => ({ expected: args[0], actual: subject }),\n});\n\nfunction tolerance(params: unknown): number {\n  return (params as { within?: number }).within ?? DEFAULT_WITHIN;\n}\n","/**\n * Structural equality over the language's values.\n *\n * A body, a row or a list of ids is a value, not a handle, so two built the\n * same way are equal. Anything that is not a plain map or a list (dates, plugin\n * objects, closures) still compares by identity: guessing at their innards\n * would be worse than being strict.\n */\nexport function deepEquals(a: unknown, b: unknown): boolean {\n  return equal(a, b, []);\n}\n\n/**\n * `open` holds the containers already entered on the way down, so a value that\n * contains itself cannot recurse until the stack gives out. Two containers\n * already open count as equal, the way one cycle matches another.\n */\nfunction equal(a: unknown, b: unknown, open: readonly unknown[]): boolean {\n  if (a === b) return true;\n  const openA = open.includes(a);\n  const openB = open.includes(b);\n  if (openA || openB) return openA && openB;\n  if (Array.isArray(a) || Array.isArray(b)) return sameList(a, b, open);\n  if (!isMap(a) || !isMap(b)) return false;\n  return sameMap(a, b, open);\n}\n\nfunction sameList(a: unknown, b: unknown, open: readonly unknown[]): boolean {\n  if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;\n  const next = [...open, a, b];\n  return a.every((item, index) => equal(item, b[index], next));\n}\n\n/**\n * A field set to nothing is not a field. `{ id: 1, ref: absent }` prints, and\n * travels over the wire, exactly like `{ id: 1 }`, so the two compare equal.\n */\nfunction sameMap(\n  a: Record<string, unknown>,\n  b: Record<string, unknown>,\n  open: readonly unknown[],\n): boolean {\n  const keys = presentKeys(a);\n  if (keys.length !== presentKeys(b).length) return false;\n  const next = [...open, a, b];\n  return keys.every((key) => equal(a[key], b[key], next));\n}\n\nfunction presentKeys(value: Record<string, unknown>): string[] {\n  return Object.keys(value).filter((key) => value[key] !== undefined);\n}\n\nfunction isMap(value: unknown): value is Record<string, unknown> {\n  if (typeof value !== \"object\" || value === null) return false;\n  const proto = Object.getPrototypeOf(value);\n  return proto === Object.prototype || proto === null;\n}\n","import { arg, defineMatcher, type MatcherDefinition } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\nimport { deepEquals } from \"./deep-equals.js\";\nimport { failureLine } from \"./failure-line.js\";\n\n/** `expect x contains y`: substring for strings, membership for lists. */\nexport const contains: MatcherDefinition = defineMatcher({\n  name: \"contains\",\n  args: [arg(\"value\", t.dynamic, \"What to look for: a substring, or an item of the list.\")],\n  test: ({ subject, args }) => includes(subject, args[0]),\n  message: ({ subject, args }) => failureLine({ subject, relation: \"to contain\", other: args[0] }),\n  // `aligned: false`: the needle is held against every item, never against item\n  // 0, so the two sides do not correspond by position.\n  detail: ({ subject, args }) => ({ expected: args[0], actual: subject, aligned: false }),\n});\n\nfunction includes(subject: unknown, value: unknown): boolean {\n  if (typeof subject === \"string\") return subject.includes(String(value));\n  if (Array.isArray(subject)) return subject.some((item) => deepEquals(item, value));\n  return false;\n}\n","import { arg, defineMatcher, type MatcherDefinition } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\nimport { deepEquals } from \"./deep-equals.js\";\nimport { failureLine } from \"./failure-line.js\";\n\n/** `expect x equals y`: the same value, no coercion, maps and lists included. */\nexport const equals: MatcherDefinition = defineMatcher({\n  name: \"equals\",\n  args: [arg(\"value\", t.dynamic, \"What the subject should be, compared field by field.\")],\n  test: ({ subject, args }) => deepEquals(subject, args[0]),\n  message: ({ subject, args }) => failureLine({ subject, relation: \"to equal\", other: args[0] }),\n  detail: ({ subject, args }) => ({ expected: args[0], actual: subject }),\n});\n","import { arg, defineMatcher, type MatcherDefinition } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\nimport { deepEquals } from \"./deep-equals.js\";\nimport { failureLine } from \"./failure-line.js\";\n\n/** `expect x oneOf [a, b]`: passes if the subject is one of the options. */\nexport const oneOf: MatcherDefinition = defineMatcher({\n  name: \"oneOf\",\n  args: [arg(\"values\", t.list(t.dynamic), \"The accepted values. The subject must be one of them.\")],\n  test: ({ subject, args }) => options(args[0]).some((option) => deepEquals(option, subject)),\n  message: ({ subject, args }) =>\n    failureLine({ subject, relation: \"to be one of\", other: args[0] }),\n  // The subject is held against every option, never against one by position.\n  detail: ({ subject, args }) => ({ expected: args[0], actual: subject, aligned: false }),\n});\n\nfunction options(value: unknown): readonly unknown[] {\n  return Array.isArray(value) ? value : [];\n}\n","import type { MatcherDefinition } from \"@venn-lang/sdk\";\nimport { closeTo } from \"./close-to.js\";\nimport { contains } from \"./contains.js\";\nimport { equals } from \"./equals.js\";\nimport { oneOf } from \"./one-of.js\";\n\n/** The words `expect` gains from this plugin: `equals`, `contains`, `oneOf`, `closeTo`. */\nexport const assertMatchers: MatcherDefinition[] = [equals, contains, oneOf, closeTo];\n","import { definePlugin, type PluginDefinition } from \"@venn-lang/sdk\";\nimport { assertMatchers } from \"./matchers/index.js\";\n\n/**\n * The `assert` plugin: the vocabulary behind `expect`.\n *\n * `expect` is kernel syntax; the words that follow it are not. This plugin\n * contributes those words and nothing else, so it declares no verbs, no\n * resources, no types and no host capabilities.\n */\nexport const assertPlugin: PluginDefinition = definePlugin({\n  name: \"venn/assert\",\n  version: \"0.0.0\",\n  namespace: \"assert\",\n  matchers: assertMatchers,\n});\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@venn-lang/assert",
+  "version": "0.1.0",
+  "description": "The words that follow expect: equals, contains, oneOf and closeTo.",
+  "keywords": [
+    "venn",
+    "testing",
+    "e2e",
+    "assert"
+  ],
+  "homepage": "https://github.com/venn-lang/venn/tree/main/packages/std-assert#readme",
+  "bugs": "https://github.com/venn-lang/venn/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/venn-lang/venn.git",
+    "directory": "packages/std-assert"
+  },
+  "license": "MIT",
+  "author": "Vinicius Borges",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.suite.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@venn-lang/sdk": "0.1.0",
+    "@venn-lang/types": "0.1.0"
+  },
+  "devDependencies": {
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { assertMatchers } from "./matchers/index.js";
+export { assertPlugin, assertPlugin as default } from "./plugin.js";

package/src/matchers/close-to.ts

@@ -0,0 +1,22 @@
+import { arg, defineMatcher, type MatcherDefinition, z } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { failureLine } from "./failure-line.js";
+
+const DEFAULT_WITHIN = 0.01;
+
+/** `expect x closeTo 99.0 { within: 0.01 }`: numeric equality within a tolerance. */
+export const closeTo: MatcherDefinition = defineMatcher({
+  name: "closeTo",
+  args: [arg("value", t.number, "The number to come near. `within` in the options sets how near.")],
+  params: z.object({ within: z.number().default(DEFAULT_WITHIN) }),
+  test: ({ subject, args, params }) =>
+    Math.abs(Number(subject) - Number(args[0])) <= tolerance(params),
+  // The tolerance belongs in the title: without it a failure cannot be judged.
+  message: ({ subject, args, params }) =>
+    failureLine({ subject, relation: `to be within ${tolerance(params)} of`, other: args[0] }),
+  detail: ({ subject, args }) => ({ expected: args[0], actual: subject }),
+});
+
+function tolerance(params: unknown): number {
+  return (params as { within?: number }).within ?? DEFAULT_WITHIN;
+}

package/src/matchers/contains.ts

@@ -0,0 +1,21 @@
+import { arg, defineMatcher, type MatcherDefinition } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { deepEquals } from "./deep-equals.js";
+import { failureLine } from "./failure-line.js";
+
+/** `expect x contains y`: substring for strings, membership for lists. */
+export const contains: MatcherDefinition = defineMatcher({
+  name: "contains",
+  args: [arg("value", t.dynamic, "What to look for: a substring, or an item of the list.")],
+  test: ({ subject, args }) => includes(subject, args[0]),
+  message: ({ subject, args }) => failureLine({ subject, relation: "to contain", other: args[0] }),
+  // `aligned: false`: the needle is held against every item, never against item
+  // 0, so the two sides do not correspond by position.
+  detail: ({ subject, args }) => ({ expected: args[0], actual: subject, aligned: false }),
+});
+
+function includes(subject: unknown, value: unknown): boolean {
+  if (typeof subject === "string") return subject.includes(String(value));
+  if (Array.isArray(subject)) return subject.some((item) => deepEquals(item, value));
+  return false;
+}

package/src/matchers/deep-equals.ts

@@ -0,0 +1,57 @@
+/**
+ * Structural equality over the language's values.
+ *
+ * A body, a row or a list of ids is a value, not a handle, so two built the
+ * same way are equal. Anything that is not a plain map or a list (dates, plugin
+ * objects, closures) still compares by identity: guessing at their innards
+ * would be worse than being strict.
+ */
+export function deepEquals(a: unknown, b: unknown): boolean {
+  return equal(a, b, []);
+}
+
+/**
+ * `open` holds the containers already entered on the way down, so a value that
+ * contains itself cannot recurse until the stack gives out. Two containers
+ * already open count as equal, the way one cycle matches another.
+ */
+function equal(a: unknown, b: unknown, open: readonly unknown[]): boolean {
+  if (a === b) return true;
+  const openA = open.includes(a);
+  const openB = open.includes(b);
+  if (openA || openB) return openA && openB;
+  if (Array.isArray(a) || Array.isArray(b)) return sameList(a, b, open);
+  if (!isMap(a) || !isMap(b)) return false;
+  return sameMap(a, b, open);
+}
+
+function sameList(a: unknown, b: unknown, open: readonly unknown[]): boolean {
+  if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+  const next = [...open, a, b];
+  return a.every((item, index) => equal(item, b[index], next));
+}
+
+/**
+ * A field set to nothing is not a field. `{ id: 1, ref: absent }` prints, and
+ * travels over the wire, exactly like `{ id: 1 }`, so the two compare equal.
+ */
+function sameMap(
+  a: Record<string, unknown>,
+  b: Record<string, unknown>,
+  open: readonly unknown[],
+): boolean {
+  const keys = presentKeys(a);
+  if (keys.length !== presentKeys(b).length) return false;
+  const next = [...open, a, b];
+  return keys.every((key) => equal(a[key], b[key], next));
+}
+
+function presentKeys(value: Record<string, unknown>): string[] {
+  return Object.keys(value).filter((key) => value[key] !== undefined);
+}
+
+function isMap(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}

package/src/matchers/equals.ts

@@ -0,0 +1,13 @@
+import { arg, defineMatcher, type MatcherDefinition } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { deepEquals } from "./deep-equals.js";
+import { failureLine } from "./failure-line.js";
+
+/** `expect x equals y`: the same value, no coercion, maps and lists included. */
+export const equals: MatcherDefinition = defineMatcher({
+  name: "equals",
+  args: [arg("value", t.dynamic, "What the subject should be, compared field by field.")],
+  test: ({ subject, args }) => deepEquals(subject, args[0]),
+  message: ({ subject, args }) => failureLine({ subject, relation: "to equal", other: args[0] }),
+  detail: ({ subject, args }) => ({ expected: args[0], actual: subject }),
+});

package/src/matchers/failure-line.ts

@@ -0,0 +1,55 @@
+/** A failure title is one line. Past this, a value is summarised instead. */
+const LIMIT = 44;
+
+/**
+ * Builds the line a failure leads with: `expected <subject> <relation> <other>`.
+ *
+ * Both sides render to the same level of detail: one spelled out next to one
+ * summarised reads as a reporter glitch rather than a comparison. Nothing is
+ * lost, the full values travel in the problem's diff.
+ */
+export function failureLine(args: { subject: unknown; relation: string; other: unknown }): string {
+  const [left, right] = pair(args.subject, args.other);
+  return `expected ${left} ${args.relation} ${right}`;
+}
+
+function pair(subject: unknown, other: unknown): [string, string] {
+  const left = render(subject);
+  const right = render(other);
+  if (left.length <= LIMIT && right.length <= LIMIT) return [left, right];
+  return [summarize(subject), summarize(other)];
+}
+
+/** Strings quoted, maps and lists as compact JSON. Never `[object Object]`. */
+function render(value: unknown): string {
+  if (value === undefined) return "absent";
+  if (value === null) return "null";
+  if (typeof value === "function") return "fn";
+  if (typeof value === "string") return JSON.stringify(value);
+  if (typeof value !== "object") return String(value);
+  return json(value);
+}
+
+function summarize(value: unknown): string {
+  if (typeof value === "string") return `${JSON.stringify(value.slice(0, LIMIT))}…`;
+  if (typeof value === "object" && value !== null) return shapeOf(value);
+  return render(value);
+}
+
+function shapeOf(value: object): string {
+  if (Array.isArray(value)) return `a list of ${value.length} ${plural("item", value.length)}`;
+  const count = Object.keys(value).length;
+  return `a map with ${count} ${plural("field", count)}`;
+}
+
+function json(value: object): string {
+  try {
+    return JSON.stringify(value) ?? shapeOf(value);
+  } catch {
+    return shapeOf(value);
+  }
+}
+
+function plural(noun: string, count: number): string {
+  return count === 1 ? noun : `${noun}s`;
+}

package/src/matchers/index.ts

@@ -0,0 +1,8 @@
+import type { MatcherDefinition } from "@venn-lang/sdk";
+import { closeTo } from "./close-to.js";
+import { contains } from "./contains.js";
+import { equals } from "./equals.js";
+import { oneOf } from "./one-of.js";
+
+/** The words `expect` gains from this plugin: `equals`, `contains`, `oneOf`, `closeTo`. */
+export const assertMatchers: MatcherDefinition[] = [equals, contains, oneOf, closeTo];

package/src/matchers/one-of.ts

@@ -0,0 +1,19 @@
+import { arg, defineMatcher, type MatcherDefinition } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { deepEquals } from "./deep-equals.js";
+import { failureLine } from "./failure-line.js";
+
+/** `expect x oneOf [a, b]`: passes if the subject is one of the options. */
+export const oneOf: MatcherDefinition = defineMatcher({
+  name: "oneOf",
+  args: [arg("values", t.list(t.dynamic), "The accepted values. The subject must be one of them.")],
+  test: ({ subject, args }) => options(args[0]).some((option) => deepEquals(option, subject)),
+  message: ({ subject, args }) =>
+    failureLine({ subject, relation: "to be one of", other: args[0] }),
+  // The subject is held against every option, never against one by position.
+  detail: ({ subject, args }) => ({ expected: args[0], actual: subject, aligned: false }),
+});
+
+function options(value: unknown): readonly unknown[] {
+  return Array.isArray(value) ? value : [];
+}

package/src/plugin.ts

@@ -0,0 +1,16 @@
+import { definePlugin, type PluginDefinition } from "@venn-lang/sdk";
+import { assertMatchers } from "./matchers/index.js";
+
+/**
+ * The `assert` plugin: the vocabulary behind `expect`.
+ *
+ * `expect` is kernel syntax; the words that follow it are not. This plugin
+ * contributes those words and nothing else, so it declares no verbs, no
+ * resources, no types and no host capabilities.
+ */
+export const assertPlugin: PluginDefinition = definePlugin({
+  name: "venn/assert",
+  version: "0.0.0",
+  namespace: "assert",
+  matchers: assertMatchers,
+});