@x12i/memorix-retrieval 1.5.1 → 1.6.2

package/dist/tests/collection-inventory.test.js

@@ -0,0 +1,207 @@
+import { describe, expect, it, vi } from "vitest";
+import { createMemorixRetrieval } from "../client/create-client.js";
+import { MEMORIX_ENTITY_DESCRIPTORS_CATALOG } from "../descriptors/catalog-ids.js";
+import { buildMemorixCollectionInventory, orphanNodesFromInventory, parseOrphanCollection, } from "../explorer/collection-inventory.js";
+import { assetsEntity, vulnerabilitiesEntity } from "./fixtures.js";
+const variabilitiesGroupsEntity = {
+    id: "variabilities-groups",
+    entityName: "variabilities-groups",
+    defaultListDescriptorId: "variabilities-groups-main-list",
+    defaultItemDescriptorId: "variabilities-groups-detail-item",
+    target: "entity",
+    collectionPrefix: "variabilities-groups",
+    identity: {
+        allowedIdFields: ["entityId"],
+        requiredExactlyOne: true,
+        defaultIdField: "entityId",
+    },
+    defaults: {
+        canonicalContentType: "snapshots",
+        dataRoot: "data",
+        effectiveDatePath: "modifiedAt",
+        fallbackEffectiveDatePaths: ["capturedAt"],
+    },
+    contentTypes: {
+        snapshots: {
+            postfix: "snapshots",
+            collection: "variabilities-groups-snapshots",
+            dataRoot: "data",
+            isCanonical: true,
+        },
+    },
+    properties: {},
+};
+function mockInventoryCatalox() {
+    const entityItems = [
+        { id: "assets", data: assetsEntity, title: "Assets" },
+        { id: "vulnerabilities", data: vulnerabilitiesEntity, title: "Vulnerabilities" },
+        {
+            id: "variabilities-groups",
+            data: variabilitiesGroupsEntity,
+            title: "Variabilities Groups",
+        },
+    ];
+    return {
+        getCatalogItem: vi.fn(async (_ctx, catalogId, itemId) => {
+            const map = {
+                assets: assetsEntity,
+                vulnerabilities: vulnerabilitiesEntity,
+                "variabilities-groups": variabilitiesGroupsEntity,
+            };
+            if (catalogId === MEMORIX_ENTITY_DESCRIPTORS_CATALOG && map[itemId]) {
+                return { outcome: "found", item: { data: map[itemId] } };
+            }
+            return { outcome: "not_found" };
+        }),
+        listCatalogItems: vi.fn(async () => ({
+            items: entityItems,
+            hasMore: false,
+        })),
+    };
+}
+function mockInventoryXronox() {
+    const entityCollections = [
+        "assets-snapshots",
+        "assets-analysis",
+        "variabilities-groups-snapshots",
+        "orphan-entity-records",
+    ];
+    const eventCollections = ["vulnerabilities-snapshots", "unknown-event-bucket"];
+    const counts = {
+        "assets-snapshots": 5,
+        "assets-analysis": 0,
+        "vulnerabilities-snapshots": 2,
+        "variabilities-groups-snapshots": 0,
+        "orphan-entity-records": 12,
+        "unknown-event-bucket": 0,
+    };
+    return {
+        listCollections: vi.fn(async (params) => {
+            if (params.role === "memorix_events") {
+                return {
+                    database: "memorix-events",
+                    collections: eventCollections.map((name) => ({ name })),
+                };
+            }
+            return {
+                database: "memorix-entities",
+                collections: entityCollections.map((name) => ({ name })),
+            };
+        }),
+        countDocuments: vi.fn(async (params) => {
+            void params.estimated;
+            return counts[params.source] ?? 0;
+        }),
+        read: vi.fn(async () => []),
+    };
+}
+describe("parseOrphanCollection", () => {
+    it("matches longest known prefix for hyphenated entity names", () => {
+        const prefixes = ["assets", "variabilities-groups", "vulnerabilities"].sort((a, b) => b.length - a.length);
+        expect(parseOrphanCollection("variabilities-groups-snapshots", prefixes)).toEqual({
+            entityName: "variabilities-groups",
+            contentType: "snapshots",
+            confidence: "heuristic",
+        });
+    });
+    it("falls back to last-hyphen split when no prefix matches", () => {
+        expect(parseOrphanCollection("custom-orphan-data", ["assets"])).toEqual({
+            entityName: "custom-orphan",
+            contentType: "data",
+            confidence: "heuristic",
+        });
+    });
+});
+describe("buildMemorixCollectionInventory", () => {
+    it("throws when xronox.listCollections is not available", async () => {
+        const client = createMemorixRetrieval({
+            catalox: mockInventoryCatalox(),
+            xronox: {
+                countDocuments: vi.fn(async () => 0),
+                read: vi.fn(async () => []),
+            },
+            processEnv: {
+                MEMORIX_ENTITIES_DB: "memorix-entities",
+                MEMORIX_EVENTS_DB: "memorix-events",
+            },
+        });
+        await expect(buildMemorixCollectionInventory(client)).rejects.toMatchObject({
+            code: "XRONOX_LIST_COLLECTIONS_UNSUPPORTED",
+        });
+    });
+    it("reconciles declared slots and orphan collections across both databases via Xronox", async () => {
+        const client = createMemorixRetrieval({
+            catalox: mockInventoryCatalox(),
+            xronox: mockInventoryXronox(),
+            processEnv: {
+                MEMORIX_ENTITIES_DB: "memorix-entities",
+                MEMORIX_EVENTS_DB: "memorix-events",
+            },
+        });
+        const inventory = await buildMemorixCollectionInventory(client);
+        expect(inventory.memorixDatabases).toEqual({
+            entity: "memorix-entities",
+            event: "memorix-events",
+        });
+        const assetsSnapshots = inventory.entries.find((e) => e.collection === "assets-snapshots");
+        expect(assetsSnapshots).toMatchObject({
+            matchStatus: "matched",
+            matchConfidence: "descriptor",
+            target: "entity",
+            listable: true,
+        });
+        const assetsAnalysis = inventory.entries.find((e) => e.collection === "assets-analysis");
+        expect(assetsAnalysis).toMatchObject({
+            matchStatus: "empty",
+            documentCount: 0,
+        });
+        const orphan = inventory.entries.find((e) => e.collection === "orphan-entity-records");
+        expect(orphan).toMatchObject({
+            matchStatus: "orphan",
+            entityName: "orphan-entity",
+            contentType: "records",
+            target: "entity",
+        });
+        expect(inventory.summary.byTarget.entity.matchedPopulated).toBe(inventory.entries.filter((e) => e.target === "entity" && e.matchStatus === "matched").length);
+        expect(inventory.summary.byTarget.event.matchedPopulated).toBe(inventory.entries.filter((e) => e.target === "event" && e.matchStatus === "matched").length);
+    });
+});
+describe("orphanNodesFromInventory", () => {
+    it("groups orphan entries by target and entity name", () => {
+        const nodes = orphanNodesFromInventory([
+            {
+                collection: "orphan-entity-records",
+                database: "memorix-entities",
+                target: "entity",
+                documentCount: 12,
+                entityName: "orphan-entity",
+                contentType: "records",
+                matchStatus: "orphan",
+                matchConfidence: "heuristic",
+                listable: false,
+            },
+            {
+                collection: "orphan-entity-notes",
+                database: "memorix-entities",
+                target: "entity",
+                documentCount: 3,
+                entityName: "orphan-entity",
+                contentType: "notes",
+                matchStatus: "orphan",
+                matchConfidence: "heuristic",
+                listable: false,
+            },
+        ]);
+        expect(nodes).toHaveLength(1);
+        expect(nodes[0]).toMatchObject({
+            entityName: "orphan-entity",
+            inventoryStatus: "orphan",
+            totalDocuments: 15,
+            contentTypesWithData: 2,
+            listable: false,
+            drillable: false,
+        });
+        expect(nodes[0]?.contentTypes).toHaveLength(2);
+    });
+});
+//# sourceMappingURL=collection-inventory.test.js.map

package/dist/tests/collection-inventory.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection-inventory.test.js","sourceRoot":"","sources":["../../src/tests/collection-inventory.test.ts"],"names":[],"mappings":"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"}

package/dist/tests/entity-graph.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=entity-graph.test.d.ts.map

package/dist/tests/entity-graph.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-graph.test.d.ts","sourceRoot":"","sources":["../../src/tests/entity-graph.test.ts"],"names":[],"mappings":""}

package/dist/tests/entity-graph.test.js

@@ -0,0 +1,148 @@
+import { describe, expect, it, vi } from "vitest";
+import { createMemorixRetrieval } from "../client/create-client.js";
+import { MEMORIX_ENTITY_DESCRIPTORS_CATALOG } from "../descriptors/catalog-ids.js";
+import { buildMemorixEntityGraph, buildMemorixEntitySlices, } from "../explorer/entity-graph.js";
+import { assetsEntity, vulnerabilitiesEntity, } from "./fixtures.js";
+function mockEntityCatalox() {
+    const entityItems = [
+        { id: "assets", data: assetsEntity, title: "Assets" },
+        { id: "vulnerabilities", data: vulnerabilitiesEntity, title: "Vulnerabilities" },
+    ];
+    return {
+        getCatalogItem: vi.fn(async (_ctx, catalogId, itemId) => {
+            if (catalogId === MEMORIX_ENTITY_DESCRIPTORS_CATALOG && itemId === "assets") {
+                return { outcome: "found", item: { data: assetsEntity } };
+            }
+            if (catalogId === MEMORIX_ENTITY_DESCRIPTORS_CATALOG &&
+                itemId === "vulnerabilities") {
+                return {
+                    outcome: "found",
+                    item: { data: vulnerabilitiesEntity },
+                };
+            }
+            return { outcome: "not_found" };
+        }),
+        listCatalogItems: vi.fn(async () => ({
+            items: entityItems,
+            hasMore: false,
+        })),
+    };
+}
+function mockXronox(counts) {
+    return {
+        countDocuments: vi.fn(async (params) => counts[params.source] ?? 0),
+        read: vi.fn(async () => []),
+    };
+}
+describe("buildMemorixEntityGraph", () => {
+    it("includes target, memorixDatabase, contentTypes, and memorixDatabases", async () => {
+        const client = createMemorixRetrieval({
+            catalox: mockEntityCatalox(),
+            xronox: mockXronox({
+                "assets-snapshots": 3,
+                "assets-analysis": 0,
+                "vulnerabilities-snapshots": 7,
+            }),
+            processEnv: {
+                MEMORIX_ENTITIES_DB: "memorix-entities",
+                MEMORIX_EVENTS_DB: "memorix-events",
+            },
+        });
+        const graph = await buildMemorixEntityGraph(client);
+        expect(graph.discovery.memorixDatabases).toEqual({
+            entity: "memorix-entities",
+            event: "memorix-events",
+        });
+        expect(graph.memorixDb).toBe("memorix-entities + memorix-events");
+        const assets = graph.entities.find((e) => e.entityName === "assets");
+        expect(assets).toMatchObject({
+            target: "entity",
+            memorixDatabase: "memorix-entities",
+            count: 3,
+            listable: true,
+        });
+        expect(assets?.contentTypes).toEqual([
+            expect.objectContaining({
+                key: "snapshots",
+                collection: "assets-snapshots",
+                database: "memorix-entities",
+                target: "entity",
+                count: 3,
+                status: "populated",
+            }),
+            expect.objectContaining({
+                key: "analysis",
+                collection: "assets-analysis",
+                count: 0,
+                status: "empty",
+            }),
+        ]);
+        const vulns = graph.entities.find((e) => e.entityName === "vulnerabilities");
+        expect(vulns).toMatchObject({
+            target: "event",
+            memorixDatabase: "memorix-events",
+            count: 7,
+        });
+    });
+    it("uses content-type keys for countErrors", async () => {
+        const client = createMemorixRetrieval({
+            catalox: mockEntityCatalox(),
+            xronox: {
+                countDocuments: vi.fn(async (params) => {
+                    if (params.source === "assets-analysis") {
+                        throw new Error("count failed");
+                    }
+                    return params.source === "assets-snapshots" ? 1 : 0;
+                }),
+                read: vi.fn(async () => []),
+            },
+            processEnv: {
+                MEMORIX_ENTITIES_DB: "memorix-entities",
+                MEMORIX_EVENTS_DB: "memorix-events",
+            },
+        });
+        const graph = await buildMemorixEntityGraph(client);
+        const assets = graph.entities.find((e) => e.entityName === "assets");
+        expect(assets?.countErrors).toEqual({ analysis: "count failed" });
+        expect(assets?.contentTypes.find((c) => c.key === "analysis")).toMatchObject({
+            status: "error",
+            error: "count failed",
+        });
+    });
+});
+describe("buildMemorixEntitySlices", () => {
+    it("includes all content types including zero counts", async () => {
+        const client = createMemorixRetrieval({
+            catalox: mockEntityCatalox(),
+            xronox: mockXronox({
+                "assets-snapshots": 2,
+                "assets-analysis": 0,
+            }),
+            processEnv: {
+                MEMORIX_ENTITIES_DB: "memorix-entities",
+                MEMORIX_EVENTS_DB: "memorix-events",
+            },
+        });
+        const result = await buildMemorixEntitySlices(client, "assets");
+        expect(result).toMatchObject({
+            entityName: "assets",
+            target: "entity",
+            memorixDatabase: "memorix-entities",
+        });
+        expect(result.slices).toHaveLength(2);
+        expect(result.slices[0]).toMatchObject({
+            contentType: "snapshots",
+            collection: "assets-snapshots",
+            target: "entity",
+            count: 2,
+            status: "populated",
+        });
+        expect(result.slices[1]).toMatchObject({
+            contentType: "analysis",
+            collection: "assets-analysis",
+            count: 0,
+            status: "empty",
+        });
+    });
+});
+//# sourceMappingURL=entity-graph.test.js.map

package/dist/tests/entity-graph.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-graph.test.js","sourceRoot":"","sources":["../../src/tests/entity-graph.test.ts"],"names":[],"mappings":"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"}

package/docs/DATA-TIER-CONTRACT.md

@@ -10,6 +10,7 @@ See also:
 - [MEMORIX-DATABASE-CONVENTIONS.md](./MEMORIX-DATABASE-CONVENTIONS.md) — Mongo layout and env vars
 - [EXPLORER-HOST-APIS.md](./EXPLORER-HOST-APIS.md) — graph, raw reads, scoped workspace (Explorer-oriented)
 - [XRONOX-DATA-TIER-REQUIREMENTS.md](./XRONOX-DATA-TIER-REQUIREMENTS.md) — what `@x12i/xronox` must provide as Memorix data tier
+- [fr/README.md](./fr/README.md) — **open feature requests for `@x12i/xronox`** (implement there first)
 
 ---
 
@@ -66,8 +67,10 @@ List descriptor `filters` with `operator` + `value` are **always applied**; requ
 
 | Export | Purpose |
 |--------|---------|
-| `buildMemorixEntityGraph(client, options?)` | Discovery + counts + relation graph |
-| `buildMemorixEntitySlices(client, entityName)` | Per–content-type counts for drill-down |
+| `buildMemorixEntityGraph(client, options?)` | Discovery + counts + relation graph (per–content-type metadata, both DBs) |
+| `buildMemorixEntitySlices(client, entityName)` | Per–content-type counts for drill-down (includes zero counts) |
+| `buildMemorixCollectionInventory(client, options?)` | Reconcile Catalox-declared collections with Mongo in both databases via Xronox `listCollections` (≥ 3.9.0) |
+| `orphanNodesFromInventory(entries)` | Group inventory orphans for entity graph canvas |
 | `getMemorixRetrievalHealth(client)` | Mongo ping + discovery sample |
 | `countMemorixEntityContentTypeDocuments` | Count by entity + content type (descriptor-resolved collection) |
 | `listMemorixEntityContentTypeDocuments` | Paginated raw documents (descriptor-resolved) |
@@ -117,7 +120,7 @@ Scripts (not imported by hosts at runtime):
 |--------|---------|
 | `memorixRead` | Routed read via Xronox (entity context + collection + role) |
 | `memorixCount` | Routed count via Xronox (`countDocuments` on adapter) |
-| `readMemorixCollection` / `countMemorixCollection` / `connectMemorixMongo` | **Advanced** — direct Mongo when injecting `mongo` client |
+| `readMemorixCollection` / `countMemorixCollection` / `connectMemorixMongo` | **Test-only** — not used by production inventory or list/item paths |
 | `resolveMemorixCollectionName` / `resolveMemorixDbNameForEntity` | Resolution utilities |
 | Env helpers: `resolveMemorixDbName`, `resolveMongoUri`, `targetCollectionEnvKey` | Advanced overrides |
 

package/docs/EXPLORER-HOST-APIS.md

@@ -19,8 +19,22 @@ Uses `createCataloxFromEnv` + `createCataloxAdapterFromBound` + `createMemorixRe
 ## Entity discovery
 
 - `discoverMemorixEntities(client)` — lists `memorix-entity-descriptors` via Catalox only (`source: "catalox" | "none"`). No env entity list fallback.
-- `buildMemorixEntityGraph(client)` — discovery + per–content-type counts + **relations from entity descriptors**.
-- `buildMemorixEntitySlices(client, entityName)` — slice counts for canvas drill-down.
+- `buildMemorixEntityGraph(client)` — discovery + per–content-type counts + **relations from entity descriptors**. Each entity includes `target`, `memorixDatabase`, and `contentTypes[]` (collection, database, count, status). `discovery.memorixDatabases` names both entity and event stores.
+- `buildMemorixEntitySlices(client, entityName)` — slice counts for canvas drill-down; includes **all** declared content types (zero counts use `status: "empty"`).
+- `buildMemorixCollectionInventory(client, options?)` — bidirectional Mongo ↔ Catalox inventory across both databases (`matched`, `empty`, `orphan`, `unresolved`). Options: `includeExactCounts`, `scopedNamespace`.
+- `orphanNodesFromInventory(entries)` — group orphan inventory rows into graph nodes for Explorer entities canvas.
+
+## Collection inventory
+
+Requires `@x12i/xronox` ≥ 3.9.0 (`listCollections`).
+
+- Declared counts: `countMemorixEntityContentTypeDocuments` (Xronox)
+- DB scan: `xronox.listCollections({ role })` for `memorix_entities` and `memorix_events`
+- Orphan counts: `xronox.countDocuments({ estimated: true })`
+
+Smoke: `npm run smoke:retrieval -- --inventory`
+
+Response: `entries`, `summary.byTarget`, `discovery`.
 
 ## Raw collection reads (Explorer compatibility)
 

package/docs/MEMORIX-CATALOX-CONTRACTS.md

@@ -481,12 +481,16 @@ When `discovery.source` is `"none"`, returns empty rows with a hint — no env e
 5. Resolve `includeRelations` and optional full content fetches.
 6. Return `{ identity, sections, relations?, issues? }`.
 
-### 5.6 Entity graph (Explorer)
+### 5.6 Entity graph and collection inventory (Explorer)
 
-`buildMemorixEntityGraph` uses discovery + entity descriptors only:
+Retrieval exports (see [EXPLORER-HOST-APIS.md](./EXPLORER-HOST-APIS.md)):
 
-- Per entity: label, counts, content-type labels, **`relations` → connections**, default list/item ids.
-- `discovery.source` is `"catalox"` or `"none"` — never `"env"`.
+- `buildMemorixEntityGraph` — discovery + entity descriptors; per entity: label, counts, **`contentTypes[]`**, **`relations` → connections**, default list/item ids, `target`, `memorixDatabase`.
+- `buildMemorixEntitySlices` — all declared content types including zero counts.
+- `buildMemorixCollectionInventory` — reconcile declared collections with Mongo in both databases.
+- `orphanNodesFromInventory` — orphan groups for entities canvas.
+
+`discovery.source` is `"catalox"` or `"none"` — never `"env"`. `discovery.memorixDatabases` names both entity and event stores.
 
 ---