Files
reverse-engineering-anything/src/domain/analysisView/environmentStateWriteStamps.test.ts
T

610 lines
19 KiB
TypeScript

import { describe, expect, it } from "vitest";
import type { JsonObject } from "./environmentStateRules.js";
import {
explainCreate,
explainUpdate,
type CreateEvidence,
} from "./environmentStateWriteExplain.js";
import type { UpdateEvidence } from "./environmentStateWriteChanges.js";
import type { FieldRule } from "./environmentStateWriteRules.js";
import {
envelopeOf,
nestedClockValue,
pinnedQuery,
sameQuery,
stampProblem,
storedRestamp,
} from "./environmentStateWriteStamps.js";
const START = Date.UTC(2026, 2, 4, 5, 6, 0);
const at = (ms: number): string => new Date(ms).toISOString();
const EDITOR = { id: 1, email: "rea@example.test" };
const created = (
entity: JsonObject,
body: JsonObject,
type: readonly JsonObject[] = [],
): CreateEvidence => ({
entity,
call: { path: "/items", pathValues: new Map(), body },
idField: "id",
startMs: START,
collection: [],
type,
});
const updated = (
before: JsonObject,
after: JsonObject,
body: JsonObject,
others: readonly JsonObject[] = [],
): UpdateEvidence => ({
before,
after,
call: { path: "/items/42", pathValues: new Map([["item", "42"]]), body },
method: "PATCH",
idField: "id",
id: "42",
startMs: START,
others,
});
const ruleFor = (
rules: readonly FieldRule[],
field: string,
): FieldRule | undefined => rules.find((rule) => rule.field === field);
describe("values an update stamps without being sent them", () => {
it("stamps no field that only shares a name's ending with one holding the value, nor one naming what the call sent", () => {
const loose = explainUpdate(
updated(
{
id: "42",
createdByName: "Rea Admin",
assignedUserName: null,
locationName: "Pantry",
categoryName: "Dry",
},
{
id: "42",
createdByName: "Rea Admin",
assignedUserName: "Rea Admin",
locationName: "Pantry",
categoryName: "Pantry",
},
{ note: "x" },
),
);
expect(loose.unexplained).toEqual(["assignedUserName", "categoryName"]);
const referenced = explainUpdate(
updated(
{ id: "42", createdByName: "Rea Admin", modifiedByName: null },
{
id: "42",
createdByName: "Rea Admin",
modifiedByName: "Rea Admin",
modifiedById: "7",
},
{ modifiedById: "7" },
),
);
expect(referenced.unexplained).toContain("modifiedByName");
});
it("derives a value from the one member the call stores nowhere when the value shows that member's text", () => {
const result = explainUpdate(
updated(
{ id: "42", title: "Post", excerpt: "Old body." },
{ id: "42", title: "Post (edited)", excerpt: "Edited body text." },
{ title: "Post (edited)", html: "<p>Edited body text.</p>" },
),
);
expect(result.unexplained).toEqual([]);
expect(ruleFor(result.rules, "excerpt")).toEqual({
field: "excerpt",
rule: "derived",
value: "Edited body text.",
from: "Old body.",
member: "html",
});
});
it("derives nothing a member's text does not show, nor beside a second member stored nowhere", () => {
const unrelated = explainUpdate(
updated(
{ id: "42", title: "Post", excerpt: "Old body.", visibility: "public" },
{
id: "42",
title: "Post",
excerpt: "Edited body text.",
visibility: "members",
},
{ title: "Post", html: "<p>Edited body text.</p>" },
),
);
expect(unrelated.unexplained).toEqual(["visibility"]);
const twoMembers = explainUpdate(
updated(
{ id: "42", title: "Post", excerpt: "Old body." },
{ id: "42", title: "Post", excerpt: "Edited body text." },
{
title: "Post",
html: "<p>Edited body text.</p>",
note: "kept nowhere",
},
),
);
expect(twoMembers.unexplained).toEqual(["excerpt"]);
});
it("refuses a derived value for an entity holding another than the recorded one, and a held clock sent otherwise than held", () => {
const rules: FieldRule[] = [
{
field: "excerpt",
rule: "derived",
value: "New.",
from: "Old body.",
member: "html",
},
{
field: "updated_at",
rule: "held-clock",
format: { kind: "iso", separator: "T", fraction: 3, zone: "Z" },
},
];
const before = {
excerpt: "Old body.",
updated_at: "2026-03-04T05:06:00.000Z",
};
expect(
stampProblem(rules, before, {
html: "<p>New.</p>",
updated_at: before.updated_at,
}),
).toBeUndefined();
expect(
stampProblem(
rules,
{ ...before, excerpt: "Custom." },
{ html: "<p>New.</p>" },
),
).toContain("derives excerpt");
expect(
stampProblem(rules, before, { updated_at: "2026-01-01T00:00:00.000Z" }),
).toContain("must repeat the value");
expect(
stampProblem(
rules,
{ ...before, excerpt: "Custom." },
{ title: "No html", updated_at: before.updated_at },
),
).toBeUndefined();
});
});
describe("the acting user's paired fields and same-second clocks", () => {
it("stamps the acting name and a matching ID when the recording shows both", () => {
const actor = "Rea Admin";
const before = {
id: "42",
name: "Draft",
createdByName: actor,
modifiedByName: null,
};
const after = { ...before, name: "Final", modifiedByName: actor };
const body = { name: "Final" };
const nameStamp = { field: "modifiedByName", rule: "stamp", value: actor };
const nameOnly = explainUpdate(updated(before, after, body));
expect(nameOnly.unexplained).toEqual([]);
expect(nameOnly.rules).toContainEqual(nameStamp);
const paired = { ...before, createdById: "u1" };
const matching = explainUpdate(
updated(
paired,
{ ...after, createdById: "u1", modifiedById: "u1" },
body,
),
);
expect(matching.rules).toContainEqual(nameStamp);
expect(ruleFor(matching.rules, "modifiedById")).toEqual({
field: "modifiedById",
rule: "stamp",
value: "u1",
});
const other = explainUpdate(
updated(
paired,
{ ...after, createdById: "u1", modifiedById: "u2" },
body,
),
);
expect(ruleFor(other.rules, "modifiedById")).toBeUndefined();
});
it("names the unsent whole-second clocks an update left in its own second, and no finer or creation one", () => {
const second = "2026-03-04T05:06:00Z";
const result = explainUpdate(
updated(
{
id: "42",
name: "A",
modifiedAt: second,
seenAt: "2026-03-04T05:06:00.250Z",
createdAt: second,
},
{
id: "42",
name: "B",
modifiedAt: second,
seenAt: "2026-03-04T05:06:00.250Z",
createdAt: second,
},
{ name: "B" },
),
);
expect(result.unstamped).toEqual(["modifiedAt"]);
});
});
describe("clocks an update sends back unchanged", () => {
it("stamps anew the one clock a call sent back in whole seconds within the call's second", () => {
const second = "2026-03-04T05:06:00.000Z";
const held = explainUpdate(
updated(
{ id: "42", title: "Post", updated_at: second },
{ id: "42", title: "Post (edited)", updated_at: second },
{ title: "Post (edited)", updated_at: second },
),
);
expect(ruleFor(held.rules, "updated_at")).toEqual({
field: "updated_at",
rule: "held-clock",
format: { kind: "iso", separator: "T", fraction: 3, zone: "Z" },
});
expect(held.body.accepted).toContain("updated_at");
});
it("stores as sent a finer clock, and both of two clocks a whole object sent back", () => {
const finer = "2026-03-04T05:06:00.000000001Z";
const echoed = explainUpdate(
updated(
{ id: "42", title: "Item", updated_at: finer },
{ id: "42", title: "Item (edited)", updated_at: finer },
{ title: "Item (edited)", updated_at: finer },
),
);
expect(ruleFor(echoed.rules, "updated_at")).toEqual({
field: "updated_at",
rule: "echo",
});
const second = "2026-03-04T05:06:00.000Z";
const whole = explainUpdate(
updated(
{ id: "42", title: "Post", created_at: second, updated_at: second },
{
id: "42",
title: "Post (edited)",
created_at: second,
updated_at: second,
},
{ title: "Post (edited)", created_at: second, updated_at: second },
),
);
expect(ruleFor(whole.rules, "created_at")?.rule).toBe("echo");
expect(ruleFor(whole.rules, "updated_at")?.rule).toBe("echo");
});
it("echoes a creation clock a call sent back in the second the entity was made", () => {
const second = "2026-03-04T05:06:00.000Z";
const result = explainUpdate(
updated(
{ id: "42", title: "Post", created_at: second },
{ id: "42", title: "Post (edited)", created_at: second },
{ title: "Post (edited)", created_at: second },
),
);
expect(ruleFor(result.rules, "created_at")).toEqual({
field: "created_at",
rule: "echo",
});
});
});
describe("objects whose clocks a write stamps", () => {
const editInfo = (ms: number) => ({ timestamp: at(ms), ...EDITOR });
it("stamps the clocks of an object a create wrote, where the type shows the same object stamped otherwise", () => {
const result = explainCreate(
created(
{ id: 7, name: "Tally", editInfo: editInfo(START + 30) },
{ name: "Tally" },
[{ id: 2, name: "Old", editInfo: editInfo(START - 86_400_000) }],
),
);
expect(ruleFor(result.rules, "editInfo")).toEqual({
field: "editInfo",
rule: "nested-clock",
members: ["timestamp"],
format: { kind: "iso", separator: "T", fraction: 3, zone: "Z" },
});
});
it("stamps no object other entities hold otherwise, nor a parent made just before the request", () => {
const parent = (ms: number, id: number) => ({
id,
name: `Parent ${String(id)}`,
created_at: at(ms),
});
const references = explainCreate(
created({ id: 7, parent: parent(START + 30, 9) }, { name: "Child" }, [
{ id: 2, parent: parent(START - 86_400_000, 3) },
]),
);
expect(ruleFor(references.rules, "parent")).toBeUndefined();
const earlier = explainCreate(
created({ id: 7, editInfo: editInfo(START - 1_500) }, { name: "Tally" }, [
{ id: 2, editInfo: editInfo(START - 86_400_000) },
]),
);
expect(ruleFor(earlier.rules, "editInfo")).toBeUndefined();
});
it("restamps an object an update changed only in clocks, and not one it gave an object to", () => {
const others = [{ id: "43", editInfo: editInfo(START - 86_400_000) }];
const restamped = explainUpdate(
updated(
{ id: "42", name: "Tally", editInfo: editInfo(START - 60_000) },
{ id: "42", name: "Tally 2", editInfo: editInfo(START + 40) },
{ name: "Tally 2" },
others,
),
);
expect(ruleFor(restamped.rules, "editInfo")).toMatchObject({
rule: "nested-clock",
members: ["timestamp"],
});
const filled = explainUpdate(
updated(
{ id: "42", name: "Tally", editInfo: null },
{ id: "42", name: "Tally 2", editInfo: editInfo(START + 40) },
{ name: "Tally 2" },
others,
),
);
expect(filled.unexplained).toEqual(["editInfo"]);
});
it("serves a nested clock only on an entity holding the object, keeping its other members", () => {
const rule: Extract<FieldRule, { rule: "nested-clock" }> = {
field: "editInfo",
rule: "nested-clock",
members: ["timestamp"],
format: { kind: "iso", separator: "T", fraction: 3, zone: "Z" },
};
expect(nestedClockValue({ timestamp: "old", id: 3 }, rule, "now")).toEqual({
ok: true,
value: { timestamp: "now", id: 3 },
});
expect(nestedClockValue(null, rule, "now").ok).toBe(false);
});
it("stores a nested clock as a read restamped it, within seconds and in those members only", () => {
const own = { timestamp: "2026-10-18T20:39:29.464Z", id: 1 };
const read = { id: 1, timestamp: "2026-10-18T20:39:29.453678Z" };
expect(storedRestamp(own, read, ["timestamp"])).toEqual(read);
expect(
storedRestamp(own, { ...read, id: 2 }, ["timestamp"]),
).toBeUndefined();
expect(
storedRestamp(own, { ...read, timestamp: "2026-10-18T20:39:35.000Z" }, [
"timestamp",
]),
).toBeUndefined();
});
});
describe("generated tokens", () => {
it("generates opaque tokens like the ones the type holds, unless another field repeats the value", () => {
const nanoid = explainCreate(
created(
{ id: 7, name: "Tally", entity_id: "cdMLcknG-Lcu6oWL-3ZgA" },
{ name: "Tally" },
[{ id: 2, entity_id: "chYl65ZvCJ9U6yNk-YyqK" }],
),
);
expect(ruleFor(nanoid.rules, "entity_id")).toEqual({
field: "entity_id",
rule: "unique",
});
const repeated = explainCreate(
created(
{
id: "6ad47ba51023b5000108740b",
title: "Post",
comment_id: "6ad47ba51023b5000108740b",
},
{ title: "Post" },
[
{
id: "6ad47b5c1023b500010873e3",
comment_id: "6ad47b5c1023b500010873e3",
},
],
),
);
expect(ruleFor(repeated.rules, "comment_id")?.rule).not.toBe("unique");
const etag = explainUpdate(
updated(
{ id: "42", Name: "Item", Etag: "3f4bd8a5a1c74f2fbd4c1e2d9a6b7c80" },
{ id: "42", Name: "Item 2", Etag: "9e1c5b7a2d4f4a8e8c3b6d1f0a2e4c69" },
{ Name: "Item 2" },
[{ id: "43", Etag: "5a6b7c8d9e0f41a2b3c4d5e6f7a8b9c0" }],
),
);
expect(ruleFor(etag.rules, "Etag")).toEqual({
field: "Etag",
rule: "unique",
});
});
it("slugs a renamed title before reading the slug as a fresh token", () => {
const result = explainUpdate(
updated(
{
id: "42",
title: "Quarterly report 2025",
slug: "quarterly-report-2025",
},
{
id: "42",
title: "Quarterly report 2026",
slug: "quarterly-report-2026",
},
{ title: "Quarterly report 2026" },
),
);
expect(ruleFor(result.rules, "slug")).toEqual({
field: "slug",
rule: "slug",
from: "title",
});
});
});
describe("members accepted only as recorded", () => {
const card = {
id: 7,
name: "Tally",
collection_id: 8,
collection: { id: 8, name: "Ledger" },
};
it("takes only the recorded value of a member naming an object the entity nests", () => {
const result = explainCreate(
created(card, { name: "Tally", collection_id: 8 }),
);
expect(result.body.accepted).toEqual(["name"]);
expect(result.body.fixed).toEqual([{ member: "collection_id", sent: 8 }]);
const update = explainUpdate(
updated(
{ ...card, id: "42" },
{ ...card, id: "42", name: "Tally 2" },
{ name: "Tally 2", collection_id: 8 },
),
);
expect(update.body.fixed.map(({ member }) => member)).toEqual([
"collection_id",
]);
});
it("takes only the recorded state other fields go with", () => {
const post = { id: 9, title: "New", status: "draft", published_at: null };
const others = [
{
id: 1,
title: "A",
status: "published",
published_at: "2026-01-01T00:00:00Z",
},
{
id: 2,
title: "B",
status: "published",
published_at: "2026-01-02T00:00:00Z",
},
];
const pinned = explainCreate(
created(post, { title: "New", status: "draft" }, others),
);
expect(pinned.body.fixed).toEqual([{ member: "status", sent: "draft" }]);
// A value each entity holds its own of names it, not a state.
const slugged = explainCreate(
created(
{ id: 9, slug: "new-post", published_at: null },
{ slug: "new-post" },
[
{ id: 1, slug: "a-post", published_at: "2026-01-01T00:00:00Z" },
{ id: 2, slug: "b-post", published_at: "2026-01-02T00:00:00Z" },
],
),
);
expect(slugged.body.accepted).toEqual(["slug"]);
});
});
describe("call shapes", () => {
it("reads a body that wraps one object in a one-element array as that object, and spells one query one way", () => {
expect(envelopeOf({ posts: [{ title: "Post" }] })).toEqual({
member: "posts",
object: { title: "Post" },
});
expect(
envelopeOf({ posts: [{ title: "A" }, { title: "B" }] }),
).toBeUndefined();
expect(envelopeOf({ posts: [{ title: "A" }], meta: {} })).toBeUndefined();
expect(sameQuery("?source=html&b=2", "b=2&source=html")).toBe(true);
expect(sameQuery(null, "")).toBe(true);
expect(sameQuery("a=1&a=2", "a=1&a=2")).toBe(false);
// A call that leaves a pinned parameter out takes the recorded value; another value or parameter is refused.
const recorded = "?source=html";
expect(pinnedQuery(recorded, new Map())).toEqual({
ok: true,
value: new Map([["source", "html"]]),
});
expect(pinnedQuery(recorded, new Map([["source", "markdown"]]))).toEqual({
ok: false,
error: "takes only the query its recording sent (source=html).",
});
expect(pinnedQuery(null, new Map([["page", "2"]])).ok).toBe(false);
});
});
it("does not explain nested opaque-token references as independent generation", () => {
const before = "Abcdef0123456789A";
const after = "Abcdef0123456789B";
const other = "Abcdef0123456789C";
for (const metadata of [
{ version: after },
[after],
{ text: `token:${after}` },
]) {
const creation = explainCreate(
created(
{ id: "42", title: "New", version: after, metadata },
{ title: "New" },
[{ id: "41", version: before }],
),
);
expect(ruleFor(creation.rules, "version")?.rule).not.toBe("unique");
const update = explainUpdate(
updated(
{ id: "42", version: before, metadata },
{ id: "42", version: after, metadata },
{},
[{ id: "41", version: other }],
),
);
expect(update.unexplained).toContain("version");
}
});
it.each(["__proto__", "constructor", "toString"])(
"treats an absent %s stamp field as missing JSON data",
(field) => {
const rule: FieldRule = {
rule: "derived",
field,
member: "change",
from: null,
value: 1,
};
expect(stampProblem([rule], {}, { change: true })).toBeUndefined();
expect(
stampProblem([rule], Object.fromEntries([[field, 7]]), { change: true }),
).toContain("accepted only");
},
);