Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.
TypeScript ai-agentsbill-of-materialserpinventory-managementleanmanufacturingmanufacturing-execution-systemmcp-servermesmrpopen-source-erppostgresqlproduction-planningqmsquality-management-systemreact-routerself-hostedsupabasetraceabilitytypescript
// SPDX-License-Identifier: AGPL-3.0-only
// Carbon (github.com/crbnos/carbon). Modified or adapted versions of this file,
// including ports, remain AGPLv3; serving them over a network requires releasing their source.
import { beforeEach, describe, expect, it } from "vitest";
import {
FIELD_REGISTRY,
getFieldDef,
getFieldsForTargetType
} from "./field-registry";
import { ruleAppliesToItem } from "./rule-filters";
import {
__resetStorageRulesCache,
__storageRulesCacheSize,
breakQuantities,
compileRule,
compileWithCache,
evaluateRules,
getFieldsForTargetTypeAndSurfaces,
interpolateMessage,
isFieldAvailableOnSurfaces,
type RuleContext,
type StorageRuleRow,
SURFACE_CONTEXT_AVAILABILITY,
TRANSACTION_SURFACES
} from "./rules";
const ruleOf = (
conditions: Array<{ field: string; op: string; value?: unknown }>,
overrides: Partial<StorageRuleRow> = {}
): StorageRuleRow => ({
id: overrides.id ?? "rule_1",
targetType: overrides.targetType ?? "item",
severity: overrides.severity ?? "error",
message: overrides.message ?? "violated",
conditionAst: { kind: "all", conditions: conditions as never },
surfaces: overrides.surfaces,
updatedAt: overrides.updatedAt ?? "2026-05-04T00:00:00Z",
active: true
});
describe("operators", () => {
it.each([
["eq", "Part", true],
["eq", "Material", false],
["neq", "Part", false],
["neq", "Material", true]
])("%s comparing 'Part' vs %s", (op, value, expectedSatisfied) => {
const compiled = compileRule(ruleOf([{ field: "item.type", op, value }]));
expect(compiled.predicate({ item: { type: "Part" } })).toBe(
expectedSatisfied
);
});
it("in/notIn match arrays", () => {
const inRule = compileRule(
ruleOf([
{ field: "transaction.locationId", op: "in", value: ["loc_a", "loc_b"] }
])
);
expect(inRule.predicate({ transaction: { locationId: "loc_a" } })).toBe(
true
);
expect(inRule.predicate({ transaction: { locationId: "loc_x" } })).toBe(
false
);
const notIn = compileRule(
ruleOf([
{
field: "transaction.locationId",
op: "notIn",
value: ["loc_a", "loc_b"]
}
])
);
expect(notIn.predicate({ transaction: { locationId: "loc_x" } })).toBe(
true
);
expect(notIn.predicate({ transaction: { locationId: "loc_a" } })).toBe(
false
);
});
it("isSet/isNotSet handles null, undefined, and empty string", () => {
const isSet = compileRule(
ruleOf([{ field: "item.itemPostingGroupId", op: "isSet" }])
);
expect(isSet.predicate({ item: { itemPostingGroupId: "grp_a" } })).toBe(
true
);
expect(isSet.predicate({ item: { itemPostingGroupId: null } })).toBe(false);
expect(isSet.predicate({ item: { itemPostingGroupId: undefined } })).toBe(
false
);
expect(isSet.predicate({ item: { itemPostingGroupId: "" } })).toBe(false);
const isNot = compileRule(
ruleOf([{ field: "item.itemPostingGroupId", op: "isNotSet" }])
);
expect(isNot.predicate({ item: { itemPostingGroupId: "" } })).toBe(true);
expect(isNot.predicate({ item: { itemPostingGroupId: "grp_a" } })).toBe(
false
);
});
it("array-left semantics: eq matches if any element equals", () => {
const eqRule = compileRule(
ruleOf([{ field: "storageUnit.storageTypeId", op: "eq", value: "cold" }])
);
expect(
eqRule.predicate({ storageUnit: { storageTypeId: ["hot", "cold"] } })
).toBe(true);
expect(
eqRule.predicate({ storageUnit: { storageTypeId: ["hot", "ambient"] } })
).toBe(false);
});
it("array-left semantics: in matches if any element overlaps", () => {
const inRule = compileRule(
ruleOf([
{
field: "storageUnit.storageTypeId",
op: "in",
value: ["cold", "frozen"]
}
])
);
expect(
inRule.predicate({ storageUnit: { storageTypeId: ["hot", "cold"] } })
).toBe(true);
expect(
inRule.predicate({ storageUnit: { storageTypeId: ["hot", "ambient"] } })
).toBe(false);
});
it("array-left semantics: neq is true only when no element equals", () => {
const neqRule = compileRule(
ruleOf([{ field: "storageUnit.storageTypeId", op: "neq", value: "cold" }])
);
expect(
neqRule.predicate({ storageUnit: { storageTypeId: ["hot", "ambient"] } })
).toBe(true);
expect(
neqRule.predicate({ storageUnit: { storageTypeId: ["hot", "cold"] } })
).toBe(false);
});
it("array-left semantics: notIn requires no overlap", () => {
const notInRule = compileRule(
ruleOf([
{
field: "storageUnit.storageTypeId",
op: "notIn",
value: ["cold", "frozen"]
}
])
);
expect(
notInRule.predicate({
storageUnit: { storageTypeId: ["hot", "ambient"] }
})
).toBe(true);
expect(
notInRule.predicate({ storageUnit: { storageTypeId: ["hot", "cold"] } })
).toBe(false);
});
it("array-left semantics: isSet/isNotSet on empty vs populated array", () => {
const isSet = compileRule(
ruleOf([{ field: "storageUnit.storageTypeId", op: "isSet" }])
);
expect(isSet.predicate({ storageUnit: { storageTypeId: ["cold"] } })).toBe(
true
);
expect(isSet.predicate({ storageUnit: { storageTypeId: [] } })).toBe(false);
const isNot = compileRule(
ruleOf([{ field: "storageUnit.storageTypeId", op: "isNotSet" }])
);
expect(isNot.predicate({ storageUnit: { storageTypeId: [] } })).toBe(true);
expect(isNot.predicate({ storageUnit: { storageTypeId: ["cold"] } })).toBe(
false
);
});
it("gt/lt only compare numbers", () => {
const gt = compileRule(
ruleOf([{ field: "transaction.quantity", op: "gt", value: 100 }])
);
expect(gt.predicate({ transaction: { quantity: 200 } })).toBe(true);
expect(gt.predicate({ transaction: { quantity: 50 } })).toBe(false);
expect(gt.predicate({ transaction: { quantity: "300" } })).toBe(false);
const lt = compileRule(
ruleOf([{ field: "transaction.quantity", op: "lt", value: 100 }])
);
expect(lt.predicate({ transaction: { quantity: 50 } })).toBe(true);
expect(lt.predicate({ transaction: { quantity: 200 } })).toBe(false);
});
});
describe("compilePredicate", () => {
it("AND short-circuits on first false", () => {
let secondCondCalls = 0;
const compiled = compileRule(
ruleOf([
{ field: "item.type", op: "eq", value: "Part" },
{ field: "transaction.kind", op: "eq", value: "receipt" }
])
);
expect(
compiled.predicate({
item: { type: "Material" },
transaction: { kind: "receipt" }
})
).toBe(false);
secondCondCalls++;
expect(secondCondCalls).toBe(1);
});
it("empty conditions array → predicate true (no constraints)", () => {
const compiled = compileRule(ruleOf([]));
expect(compiled.predicate({})).toBe(true);
});
it("malformed AST → predicate false (defensive)", () => {
const compiled = compileRule({
id: "x",
targetType: "item",
severity: "error",
message: "m",
// @ts-expect-error intentionally malformed
conditionAst: { kind: "or", conditions: [] }
});
expect(compiled.predicate({})).toBe(false);
});
it("unknown root segment → resolver returns undefined → predicate false", () => {
const compiled = compileRule(
ruleOf([{ field: "garbage.path", op: "eq", value: "x" }])
);
expect(compiled.predicate({})).toBe(false);
});
it("custom field path resolves through item.customFields", () => {
const compiled = compileRule(
ruleOf([
{
field: "item.customFields.frozen",
op: "eq",
value: true
}
])
);
expect(
compiled.predicate({ item: { customFields: { frozen: true } } })
).toBe(true);
expect(
compiled.predicate({ item: { customFields: { frozen: false } } })
).toBe(false);
});
it("workCenter + operation root segments resolve", () => {
const compiled = compileRule(
ruleOf(
[
{ field: "workCenter.locationId", op: "eq", value: "loc_a" },
{ field: "operation.itemId", op: "isSet" }
],
{ targetType: "workCenter" }
)
);
expect(
compiled.predicate({
workCenter: { locationId: "loc_a" },
operation: { itemId: "item_1" }
})
).toBe(true);
expect(
compiled.predicate({
workCenter: { locationId: "loc_a" },
operation: { itemId: null }
})
).toBe(false);
});
});
describe("interpolateMessage", () => {
it("substitutes registered tokens", () => {
const ctx: RuleContext = {
item: { name: "Vanilla Ice Cream" },
shelf: { name: "A1" }
};
expect(
interpolateMessage("{item.name} cannot live on {shelf.name}", ctx)
).toBe("Vanilla Ice Cream cannot live on A1");
});
it("renders missing ctx tokens as em-dash", () => {
expect(interpolateMessage("{item.name} is bad", {})).toBe("— is bad");
});
it("does not match malformed tokens", () => {
expect(interpolateMessage("{nope", {})).toBe("{nope");
});
it("condition[N].value renders the raw value, not the label", () => {
expect(
interpolateMessage(
"{condition[0].value}",
{},
{
conditions: [
{ field: "storageUnit.storageTypeId", op: "eq", value: "cold-id" }
],
resolveConditionValue: () => "Cold storage"
}
)
).toBe("cold-id");
});
it("condition[N].name resolves the value to its label", () => {
expect(
interpolateMessage(
"{condition[0].name}",
{},
{
conditions: [
{ field: "storageUnit.storageTypeId", op: "eq", value: "cold-id" }
],
resolveConditionValue: () => "Cold storage"
}
)
).toBe("Cold storage");
});
it("condition[N].name falls back to the raw value when unresolved", () => {
expect(
interpolateMessage(
"{condition[0].name}",
{},
{
conditions: [{ field: "transaction.quantity", op: "lt", value: 1000 }]
}
)
).toBe("1000");
});
it("value and name render em-dash for set/not-set operators", () => {
const conditions = [
{ field: "storageUnit.storageTypeId", op: "isSet" as const }
];
expect(
interpolateMessage(
"{condition[0].value}/{condition[0].name}",
{},
{
conditions,
resolveConditionValue: () => "ignored"
}
)
).toBe("—/—");
});
});
describe("evaluateRules", () => {
it("returns one violation per failed rule with interpolated message", () => {
const r1 = compileRule(
ruleOf(
[
{
field: "storageUnit.storageTypeId",
op: "eq",
value: "cold"
}
],
{
id: "rule_cold",
severity: "error",
message: "{item.name} requires cold storage"
}
)
);
const r2 = compileRule(
ruleOf([{ field: "transaction.quantity", op: "lt", value: 1000 }], {
id: "rule_qty",
severity: "warn",
message: "Large receipt"
})
);
const violations = evaluateRules(
[r1, r2],
{
item: { name: "Vanilla" },
storageUnit: { storageTypeId: "ambient" },
transaction: { quantity: 2000 }
},
"receipt"
);
expect(violations).toHaveLength(2);
expect(violations[0]).toEqual({
ruleId: "rule_cold",
severity: "error",
message: "Vanilla requires cold storage"
});
expect(violations[1]?.severity).toBe("warn");
});
it("returns no violations when all rules satisfied", () => {
const r = compileRule(
ruleOf([
{
field: "storageUnit.storageTypeId",
op: "eq",
value: "cold"
}
])
);
const violations = evaluateRules(
[r],
{ storageUnit: { storageTypeId: "cold" } },
"receipt"
);
expect(violations).toEqual([]);
});
it("rule subscribed to surfaces it doesn't include is skipped", () => {
const r = compileRule(
ruleOf([{ field: "operation.itemId", op: "isSet" }], {
targetType: "workCenter",
surfaces: ["operationStart"]
})
);
const violations = evaluateRules(
[r],
{ operation: { itemId: null } },
"operationFinish"
);
expect(violations).toEqual([]);
});
});
describe("compileWithCache", () => {
beforeEach(() => __resetStorageRulesCache());
it("returns same compiled instance on cache hit", () => {
const row = ruleOf([{ field: "item.type", op: "eq", value: "Part" }]);
const a = compileWithCache(row);
const b = compileWithCache(row);
expect(a).toBe(b);
});
it("invalidates when updatedAt changes", () => {
const row1 = ruleOf([{ field: "item.type", op: "eq", value: "Part" }], {
updatedAt: "2026-05-04T00:00:00Z"
});
const row2 = ruleOf([{ field: "item.type", op: "eq", value: "Part" }], {
updatedAt: "2026-05-04T01:00:00Z"
});
const a = compileWithCache(row1);
const b = compileWithCache(row2);
expect(a).not.toBe(b);
expect(__storageRulesCacheSize()).toBe(2);
});
it("does not collide across targetTypes with identical content", () => {
// Same id, same AST, same message — different targetType must produce
// distinct compiled rules. Catches a stale cache key that omits
// targetType.
const itemRow = ruleOf([{ field: "item.type", op: "eq", value: "Part" }], {
id: "shared_id",
targetType: "item"
});
const wcRow = ruleOf([{ field: "item.type", op: "eq", value: "Part" }], {
id: "shared_id",
targetType: "workCenter"
});
const a = compileWithCache(itemRow);
const b = compileWithCache(wcRow);
expect(a).not.toBe(b);
expect(a.targetType).toBe("item");
expect(b.targetType).toBe("workCenter");
});
it("evicts oldest when over cap", () => {
for (let i = 0; i < 300; i++) {
compileWithCache(
ruleOf([{ field: "item.type", op: "eq", value: `v${i}` }], {
id: `rule_${i}`,
updatedAt: `t${i}`
})
);
}
expect(__storageRulesCacheSize()).toBeLessThanOrEqual(256);
});
});
describe("FIELD_REGISTRY", () => {
it("getFieldDef returns registered field", () => {
expect(getFieldDef("item.type")?.label).toBe("Item type");
expect(getFieldDef("storageUnit.storageTypeId")?.context).toBe("storage");
});
it("getFieldDef synthesizes definition for custom field paths", () => {
const def = getFieldDef("item.customFields.frozen");
expect(def?.label).toBe("frozen");
expect(def?.context).toBe("item");
});
it("returns undefined for unknown paths", () => {
expect(getFieldDef("garbage.path")).toBeUndefined();
});
});
describe("getFieldsForTargetType", () => {
it("item target sees item + storage + shared fields, not workCenter fields", () => {
const fields = getFieldsForTargetType("item");
const paths = fields.map((f) => f.path);
expect(paths).toContain("item.type");
expect(paths).toContain("transaction.quantity");
// storageUnit ctx is loaded for item-target surfaces when the line carries
// a storageUnitId — these fields are now visible (with nullable: true so
// authors can guard with isSet/isNotSet).
expect(paths).toContain("storageUnit.id");
expect(paths).toContain("storageUnit.locationId");
expect(paths).toContain("storageUnit.storageTypeId");
expect(paths.some((p) => p.startsWith("workCenter."))).toBe(false);
expect(paths.some((p) => p.startsWith("operation."))).toBe(false);
});
it("workCenter target sees workCenter + shared, not item.* or storageUnit.*", () => {
const fields = getFieldsForTargetType("workCenter");
const paths = fields.map((f) => f.path);
expect(paths).toContain("workCenter.locationId");
expect(paths).toContain("workCenter.active");
expect(paths).toContain("transaction.quantity");
expect(paths).not.toContain("item.type");
expect(paths.some((p) => p.startsWith("storageUnit."))).toBe(false);
});
});
describe("required-field pre-check", () => {
const coldRule = ruleOf(
[{ field: "storageUnit.storageTypeId", op: "eq", value: "cold-id" }],
{ id: "rule_cold", severity: "error", message: "must be cold storage" }
);
it("null field → hard violation, predicate skipped", () => {
const compiled = compileRule(coldRule);
const ctx: RuleContext = {};
const violations = evaluateRules([compiled], ctx, "inventoryAdjustment");
expect(violations).toHaveLength(1);
expect(violations[0]?.ruleId).toBe("rule_cold");
expect(violations[0]?.severity).toBe("error");
expect(violations[0]?.message).toBe("Storage type is required");
});
it("empty string counts as missing", () => {
const compiled = compileRule(coldRule);
const ctx: RuleContext = { storageUnit: { storageTypeId: "" } };
const violations = evaluateRules([compiled], ctx, "inventoryAdjustment");
expect(violations).toHaveLength(1);
expect(violations[0]?.message).toBe("Storage type is required");
});
it("isSet op is exempt — predicate runs, not required-field check", () => {
const rule = compileRule(
ruleOf([{ field: "storageUnit.storageTypeId", op: "isSet" }], {
id: "rule_isset",
severity: "warn",
message: "storage type must be set"
})
);
const ctx: RuleContext = {};
const violations = evaluateRules([rule], ctx, "inventoryAdjustment");
expect(violations).toHaveLength(1);
expect(violations[0]?.message).toBe("storage type must be set");
expect(violations[0]?.message).not.toContain("required");
});
it("isNotSet op is exempt — predicate runs, not required-field check", () => {
const rule = compileRule(
ruleOf([{ field: "storageUnit.storageTypeId", op: "isNotSet" }], {
id: "rule_isnotset",
severity: "warn",
message: "storage type must not be set"
})
);
const ctx: RuleContext = { storageUnit: { storageTypeId: "some-id" } };
const violations = evaluateRules([rule], ctx, "inventoryAdjustment");
expect(violations).toHaveLength(1);
expect(violations[0]?.message).toBe("storage type must not be set");
expect(violations[0]?.message).not.toContain("required");
});
it("field present but wrong value → predicate violation, not required", () => {
const compiled = compileRule(coldRule);
const ctx: RuleContext = { storageUnit: { storageTypeId: "ambient-id" } };
const violations = evaluateRules([compiled], ctx, "inventoryAdjustment");
expect(violations).toHaveLength(1);
expect(violations[0]?.message).toBe("must be cold storage");
expect(violations[0]?.message).not.toContain("required");
});
it("all required fields present and predicate passes → no violations", () => {
const compiled = compileRule(coldRule);
const ctx: RuleContext = { storageUnit: { storageTypeId: "cold-id" } };
const violations = evaluateRules([compiled], ctx, "inventoryAdjustment");
expect(violations).toEqual([]);
});
});
describe("per-surface field availability", () => {
it("every surface has an availability entry", () => {
for (const s of TRANSACTION_SURFACES) {
expect(SURFACE_CONTEXT_AVAILABILITY[s]?.length ?? 0).toBeGreaterThan(0);
}
});
it("isFieldAvailableOnSurfaces defers to targetType when no surfaces given", () => {
const itemTypeDef = getFieldDef("item.type")!;
expect(isFieldAvailableOnSurfaces(itemTypeDef, [])).toBe(true);
});
it("storage fields are not offered on operation (workCenter) surfaces", () => {
const wcFields = getFieldsForTargetTypeAndSurfaces("workCenter", [
"operationStart"
]);
expect(wcFields.some((f) => f.context === "storage")).toBe(false);
// transaction.quantity (shared) stays available everywhere.
expect(wcFields.some((f) => f.path === "transaction.quantity")).toBe(true);
});
it("item-surface fields stay offered for storage rules", () => {
const itemFields = getFieldsForTargetTypeAndSurfaces("item", ["receipt"]);
expect(itemFields.some((f) => f.path === "item.type")).toBe(true);
expect(itemFields.some((f) => f.context === "storage")).toBe(true);
});
it("narrowed set is a subset of the targetType set", () => {
const all = getFieldsForTargetType("item");
const narrowed = getFieldsForTargetTypeAndSurfaces("item", ["receipt"]);
expect(narrowed.length).toBeLessThanOrEqual(all.length);
for (const f of narrowed) {
expect(all).toContain(f);
}
});
it("every registry field is offered on at least one surface of its targetType", () => {
for (const f of FIELD_REGISTRY) {
const someSurface = TRANSACTION_SURFACES.some((s) =>
SURFACE_CONTEXT_AVAILABILITY[s].includes(f.context)
);
expect(someSurface, `field "${f.path}" offered on no surface`).toBe(true);
}
});
});
describe("ruleAppliesToItem", () => {
const part = { type: "Part", itemPostingGroupId: "grp_a" };
it("empty filters → applies to all items", () => {
expect(ruleAppliesToItem(part, {})).toBe(true);
expect(
ruleAppliesToItem(part, {
filteredItemTypes: [],
filteredItemGroupIds: []
})
).toBe(true);
});
it("single dimension (type) — OR and AND behave the same", () => {
expect(
ruleAppliesToItem(part, { filteredItemTypes: ["Part", "Material"] })
).toBe(true);
expect(ruleAppliesToItem(part, { filteredItemTypes: ["Material"] })).toBe(
false
);
expect(
ruleAppliesToItem(part, {
filteredItemTypes: ["Material"],
filteredItemMatchAll: true
})
).toBe(false);
});
it("single dimension (group)", () => {
expect(ruleAppliesToItem(part, { filteredItemGroupIds: ["grp_a"] })).toBe(
true
);
expect(ruleAppliesToItem(part, { filteredItemGroupIds: ["grp_b"] })).toBe(
false
);
});
it("OR (default) — either dimension matches", () => {
expect(
ruleAppliesToItem(part, {
filteredItemTypes: ["Material"],
filteredItemGroupIds: ["grp_a"]
})
).toBe(true);
expect(
ruleAppliesToItem(part, {
filteredItemTypes: ["Material"],
filteredItemGroupIds: ["grp_b"]
})
).toBe(false);
});
it("AND — both dimensions must match", () => {
expect(
ruleAppliesToItem(part, {
filteredItemTypes: ["Part"],
filteredItemGroupIds: ["grp_a"],
filteredItemMatchAll: true
})
).toBe(true);
expect(
ruleAppliesToItem(part, {
filteredItemTypes: ["Part"],
filteredItemGroupIds: ["grp_b"],
filteredItemMatchAll: true
})
).toBe(false);
});
it("null/absent posting group never matches a group filter", () => {
expect(
ruleAppliesToItem(
{ type: "Part", itemPostingGroupId: null },
{ filteredItemGroupIds: ["grp_a"] }
)
).toBe(false);
});
});
describe("breakQuantities", () => {
it("returns each unique positive break, falling back to 1", () => {
expect(breakQuantities([1, 50, 100, 50])).toEqual([1, 50, 100]);
expect(breakQuantities([])).toEqual([1]);
expect(breakQuantities(null)).toEqual([1]);
expect(breakQuantities([0, -5, Number.NaN])).toEqual([1]);
});
});