@crewhaus/tool-schema 0.7.0

package/README.md

@@ -0,0 +1,127 @@
+# @crewhaus/tool-schema
+
+Deterministic validation tools. Every one is pure: no filesystem, no network,
+no clock, no randomness. The same input always produces the same bytes.
+
+These are the tools for the moments a harness needs a *verdict* rather than an
+opinion. Does this payload match the contract; did this batch arrive clean; is
+this response still what it was last week; is the new schema safe to ship. A
+model asked those questions gives a plausible answer. These give the same
+answer twice — and say exactly which field, at which path, was wrong.
+
+```yaml
+tools:
+  - all-schema        # every tool below
+  - -JsonSchemaInfer  # ...except this one
+```
+
+| Tool | What it does |
+|---|---|
+| `Assert` | Evaluate declarative checks against a value and report which failed, with actual vs expected |
+| `CheckRequiredFields` | Verify dotted paths are present and non-empty, in one value or every row |
+| `CompareGolden` | Snapshot comparison with ignored paths, ignored array order and a numeric epsilon |
+| `DeepEqual` | Strict structural equality, with the first difference as a JSON Pointer |
+| `JsonSchemaInfer` | Infer a schema from example values |
+| `JsonSchemaValidate` | Validate a value against a JSON Schema, every error with a pointer path |
+| `MatchSubset` | Assert the parts of a value you care about, allowing extra properties |
+| `SchemaDiff` | What changed between two schemas, and whether a reader survives it |
+| `SchemaSummarize` | Flatten a schema into a field table — path, type, required, constraints |
+| `ValidateEnum` | Check values against an allowed set, with a "did you mean" for near misses |
+| `ValidateFormat` | Check strings against email, uri, ipv4, ipv6, uuid, date, date-time, hostname and more |
+| `ValidateRecords` | Validate a batch against one schema: per-row errors plus a pass/fail summary |
+| `ValidateReferences` | Check every reference points at something that exists |
+| `ValidateUniqueKeys` | Find rows sharing a key, including a composite key |
+
+## The JSON Schema subset
+
+`JsonSchemaValidate` and `ValidateRecords` share one Draft-07 validator,
+written out in `src/lib/jsonschema.ts` so its behaviour is auditable in a
+single file. (`JsonSchemaInfer` writes schemas rather than checking against
+them, and does not go through it.) The validator enforces:
+
+| Group | Keywords |
+|---|---|
+| any | `type`, `enum`, `const` |
+| number | `minimum`, `maximum`, `exclusiveMinimum`, `exclusiveMaximum`, `multipleOf` |
+| string | `minLength`, `maxLength`, `pattern`, `format` (opt-in) |
+| array | `items` (schema or tuple), `additionalItems`, `contains`, `minItems`, `maxItems`, `uniqueItems` |
+| object | `properties`, `patternProperties`, `additionalProperties`, `propertyNames`, `required`, `minProperties`, `maxProperties` |
+| logic | `allOf`, `anyOf`, `oneOf`, `not`, `if`/`then`/`else` |
+| reference | `$ref` to a local JSON Pointer, including `#/$defs/…` and `#/definitions/…` |
+
+Boolean schemas work wherever a schema is expected. `pattern` is an unanchored
+ECMA-262 match, and string lengths are counted in code points, both per spec.
+
+**What it does not enforce**, and says so: `dependencies`,
+`dependentRequired`, `dependentSchemas`, `unevaluatedProperties`,
+`unevaluatedItems`, the draft-04 boolean form of the exclusive bounds, and
+anything else outside the table. Every unenforced constraint keyword
+*encountered while validating* comes back in `unsupportedKeywords` — so a
+pass can be read honestly rather than mistaken for coverage it does not have.
+The list is built while walking, not by scanning the document, so a keyword
+sitting in a branch this particular value never reached is not in it. A
+`$ref` that points outside the document is an error, never a silent `true`.
+
+`format` follows Draft-07 and is an annotation until you pass `assertFormat`.
+
+## The formats
+
+Each format is a stated subset, not a full grammar, and each rejects the grey
+areas deliberately:
+
+- **email** — unquoted ASCII local part, hostname domain, at least one dot.
+  Quoted local parts, comments, IP-literal domains and non-ASCII are rejected.
+- **uri** — scheme, colon, non-empty remainder, no whitespace or control
+  characters. Use **uri-reference** for relative references.
+- **hostname** — labels of 1–63 alphanumerics and hyphens, 253 total. A
+  trailing dot and underscores are rejected; Unicode must arrive punycoded.
+- **ipv4** — four octets 0–255, **no leading zeros** (the ambiguity behind a
+  long line of SSRF bugs).
+- **ipv6** — full form, `::` compression, and an IPv4 tail. Zone identifiers
+  are rejected.
+- **uuid** — 8-4-4-4-12 hex, any version or variant, braces rejected.
+- **date** / **time** / **date-time** — RFC 3339, calendar-checked, so
+  `2023-02-30` fails and `2024-02-29` passes. A time needs an offset; a
+  date-time needs the `T`. A leap second (`:60`) is allowed.
+- **json-pointer**, **regex** — RFC 6901, and "does it compile".
+
+These grammars overlap, and not symmetrically: a hostname label is letters,
+digits and hyphens, so every dotted quad, every UUID and every `YYYY-MM-DD`
+date is also a valid hostname. `suggestFormats` therefore lists what a value
+matches narrowest first — `uuid` before `hostname` — rather than in the order
+the formats are declared.
+
+## What is deliberately not here
+
+`SchemaDiff` classifies a change as `compatible`, `breaking`, or `unknown` —
+and never rounds `unknown` to safe. Whether one regex accepts everything
+another does, and how two `anyOf` unions relate, are questions this package
+does not answer; it says so instead of guessing. A change to a keyword it does
+not model at all — `patternProperties`, `contains`, `propertyNames`,
+`dependencies` — is `unknown` too, rather than absent from the report. "Backward compatible" here
+means every value valid under the old schema is still valid under the new one,
+which is compatibility for a *reader* of the data.
+
+`JsonSchemaInfer` describes the samples it was given. It infers no numeric
+ranges, no string lengths and no patterns, because three samples never justify
+a range, and enum detection is opt-in for the same reason. Format detection is
+narrower than `ValidateFormat`: `json-pointer` is never inferred and
+`hostname` needs a dot in every sample, because both accept so much that
+`"active"` and `/tmp/x` would otherwise be labelled. A field whose distinct
+values overflow the tracking limit gets no format at all, since a format
+agreed on by the values it kept says nothing about the ones it dropped.
+
+JSON and YAML *parsing* and linting belong to `@crewhaus/tool-data`, not here.
+
+## Layout
+
+`src/lib/` holds the pure functions and is where the behaviour is tested;
+`src/index.ts` wraps them as tools. A bug in `isIpv6` reads better as a failing
+unit than as a failing tool call.
+
+## Safety flags
+
+All fourteen are `readOnly`, non-destructive, `scope: "internal"`, and declare
+no io capability, because none of them crosses a process or network boundary.
+`packages/tool-schema/src/index.test.ts` asserts that for every tool, so a
+future addition that reaches outside has to change the assertion deliberately.

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+import type { RegisteredTool } from "@crewhaus/tool-catalog";
+export declare const jsonSchemaValidate: RegisteredTool;
+export declare const jsonSchemaInfer: RegisteredTool;
+export declare const validateRecords: RegisteredTool;
+export declare const assert: RegisteredTool;
+export declare const compareGolden: RegisteredTool;
+export declare const deepEqual: RegisteredTool;
+export declare const matchSubset: RegisteredTool;
+export declare const checkRequiredFields: RegisteredTool;
+export declare const validateEnum: RegisteredTool;
+export declare const validateFormat: RegisteredTool;
+export declare const validateUniqueKeys: RegisteredTool;
+export declare const validateReferences: RegisteredTool;
+export declare const schemaDiff: RegisteredTool;
+export declare const schemaSummarize: RegisteredTool;
+/** Every tool this package registers, in the order a catalog should list them. */
+export declare const SCHEMA_TOOLS: ReadonlyArray<RegisteredTool>;
+/**
+ * The declarative check grammar, re-exported for other tool packages.
+ *
+ * `Assert` here and `Branch` in `@crewhaus/tool-flow` both have to answer
+ * "does this value satisfy this condition?", and two implementations of that
+ * question would drift: an operator who learned `startsWith` from one would
+ * find it missing, or subtly different, in the other. There is one
+ * vocabulary and one evaluator, and this is where it lives.
+ */
+export { ASSERT_OPS, type AssertOp, type AssertReport, type Check, type CheckResult, checkRequired, runChecks, } from "./lib/assert";