@elytracms/core 0.0.6

package/dist/persistence/reference-extraction.js

@@ -0,0 +1,204 @@
+import { documentKey, isAssetNode, isReferenceNode } from '@elytracms/core/cms-core';
+/**
+ * Reference extraction (EC-155, vision AD-6 — reshaped by EC-277/AD-15).
+ *
+ * Self-describing content makes extraction a **schema-free, manifest-free walk** over
+ * the stored value: every reference-bearing node carries an explicit `type`
+ * discriminator (`{ type:'reference', … }`, `{ type:'asset', … }`), and composition
+ * nodes self-type via `componentId`. So a single pure function reads the value and
+ * needs neither the collection schema nor the component manifest — which is exactly
+ * what lets the same walk run in the studio, the CLI, or a Convex mutation (AD-6,
+ * "maintained on write, every writer caught by construction").
+ *
+ * The `kind` is derived from *walk context*: a reference/asset node in a normal value
+ * position → `relation-field`/`asset-field`; inside a rich-text mark → `rich-text-link`;
+ * in a rich-text node's attrs → `rich-text-node`; a composition node's `componentId` →
+ * `component-usage`. Bindings are out of scope (v1 is static-only; see EC-278): a
+ * binding has no self-typed value, so it contributes no reference.
+ */
+// --- Shared helpers ----------------------------------------------------------------
+/** Join `/`-separated path tokens (numbers are array indices). */
+export function referencePath(...segments) {
+    return segments.map(String).join('/');
+}
+function documentTarget(ref) {
+    return { type: 'document', id: documentKey(ref) };
+}
+function asRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function isPlainRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * The rich-text storage `node.type` for an embedded registry component (EC-189).
+ * Defined locally so persistence stays free of an `@elytracms/core/rich-text` import
+ * (mirroring the structural rich-text walk) — it matches `COMPONENT_EMBED_NODE_TYPE`
+ * in `@elytracms/core/rich-text` by value, guarded by a test.
+ */
+const COMPONENT_EMBED_NODE_TYPE = 'componentEmbed';
+/**
+ * Structurally detect a stored rich-text value (`{ version, doc: { type: 'doc' } }`,
+ * the EC-025 storage format). Plain strings / HTML / anything else yields nothing.
+ */
+function asRichTextValue(value) {
+    const record = asRecord(value);
+    if (!record)
+        return undefined;
+    const doc = asRecord(record.doc);
+    if (!doc || doc.type !== 'doc')
+        return undefined;
+    return { doc };
+}
+/** Structural test for a stored composition node (id + componentId). */
+function isComponentNodeShape(value) {
+    return isPlainRecord(value) && typeof value.id === 'string' && typeof value.componentId === 'string';
+}
+// --- The self-typed walk -----------------------------------------------------------
+/** Emit the target a self-typed reference/asset node points at (or nothing). */
+function selfTypedTarget(value) {
+    if (isReferenceNode(value))
+        return documentTarget(value);
+    if (isAssetNode(value))
+        return { type: 'asset', id: value.id };
+    return undefined;
+}
+/** Walk a composition node: component usage + self-typed static props + slots. */
+function walkSelfTypedComponentNode(node, basePath, out) {
+    out.push({
+        path: referencePath(basePath, 'componentId'),
+        target: { type: 'component', id: node.componentId },
+        kind: 'component-usage',
+    });
+    for (const [name, prop] of Object.entries(node.props ?? {})) {
+        // Only STATIC props carry self-typed values (EC-190 picked refs); bindings parked.
+        if (prop.kind !== 'static')
+            continue;
+        walkSelfTypedValue(prop.value, referencePath(basePath, 'props', name), out);
+    }
+    for (const [slot, children] of Object.entries(node.slots ?? {})) {
+        children.forEach((child, index) => {
+            walkSelfTypedComponentNode(child, referencePath(basePath, 'slots', slot, index), out);
+        });
+    }
+}
+/** Walk a rich-text node (EC-025 storage format): self-typed link/inline refs + embeds. */
+function walkSelfTypedRichTextNode(node, basePath, out) {
+    // Inline reference / asset-pinned nodes carry the envelope under `attrs.ref`.
+    const nodeTarget = selfTypedTarget(asRecord(node.attrs)?.ref);
+    if (nodeTarget)
+        out.push({ path: basePath, target: nodeTarget, kind: 'rich-text-node' });
+    // Link (and any reference-carrying) marks carry the envelope under `attrs.ref`.
+    if (Array.isArray(node.marks)) {
+        node.marks.forEach((markValue, markIndex) => {
+            const markTarget = selfTypedTarget(asRecord(asRecord(markValue)?.attrs)?.ref);
+            if (markTarget) {
+                out.push({
+                    path: referencePath(basePath, 'marks', markIndex),
+                    target: markTarget,
+                    kind: 'rich-text-link',
+                });
+            }
+        });
+    }
+    // EC-189: a `componentEmbed` embeds a single ComponentNode — walked the same way.
+    if (node.type === COMPONENT_EMBED_NODE_TYPE) {
+        const embedded = asRecord(node.attrs)?.node;
+        if (isComponentNodeShape(embedded)) {
+            walkSelfTypedComponentNode(embedded, referencePath(basePath, 'attrs', 'node'), out);
+        }
+    }
+    if (Array.isArray(node.content)) {
+        node.content.forEach((childValue, childIndex) => {
+            const child = asRecord(childValue);
+            if (child)
+                walkSelfTypedRichTextNode(child, referencePath(basePath, 'content', childIndex), out);
+        });
+    }
+}
+/**
+ * Recursively walk any stored value, dispatching on the self-typed shape it carries.
+ * Order matters: the richer typed shapes (rich-text region, composition node, typed
+ * envelope) are tested before the generic array/object recursion so a node is never
+ * double-counted as both an envelope and a plain bag.
+ */
+function walkSelfTypedValue(value, basePath, out) {
+    if (value === undefined || value === null)
+        return;
+    // A rich-text region (`{ doc: { type: 'doc' } }`) — walk its node tree.
+    const richText = asRichTextValue(value);
+    if (richText) {
+        walkSelfTypedRichTextNode(richText.doc, referencePath(basePath, 'doc'), out);
+        return;
+    }
+    // A composition node (`{ id, componentId }`).
+    if (isComponentNodeShape(value)) {
+        walkSelfTypedComponentNode(value, basePath, out);
+        return;
+    }
+    // A self-typed reference / asset envelope.
+    const target = selfTypedTarget(value);
+    if (target) {
+        out.push({
+            path: basePath,
+            target,
+            kind: target.type === 'asset' ? 'asset-field' : 'relation-field',
+        });
+        return;
+    }
+    // A list — recurse by index (`<path>/<i>`), preserving the indexed-path taxonomy.
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => walkSelfTypedValue(item, referencePath(basePath, index), out));
+        return;
+    }
+    // A plain object / repeater item — recurse each key (`<path>/<key>`).
+    if (isPlainRecord(value)) {
+        for (const [key, child] of Object.entries(value)) {
+            walkSelfTypedValue(child, referencePath(basePath, key), out);
+        }
+    }
+}
+/**
+ * Extract every outbound reference held by one self-describing CMS document — no
+ * schema, no manifest, no binding context (EC-277). Walks `values/<field>` and
+ * `localized/<locale>/<field>` (just object keys), then descends each value by its
+ * self-typed shape. The returned order is walk order; callers that compare must sort
+ * (the index repository sorts via `compareReferenceEntries`), so this stays
+ * drift-tolerant: a reference in a field the schema no longer declares is still found.
+ */
+export function extractReferences(document) {
+    const out = [];
+    for (const [field, value] of Object.entries(document.values ?? {})) {
+        walkSelfTypedValue(value, referencePath('values', field), out);
+    }
+    for (const locale of Object.keys(document.localized ?? {}).sort()) {
+        const localeValues = document.localized?.[locale] ?? {};
+        for (const [field, value] of Object.entries(localeValues)) {
+            walkSelfTypedValue(value, referencePath('localized', locale, field), out);
+        }
+    }
+    return out;
+}
+/**
+ * Extract every outbound reference held by one self-describing layout root (EC-277).
+ * The graph (EC-187) is layouts-only; pages live in the `page` collection's `body`.
+ */
+export function extractLayoutReferences(layout) {
+    const refs = [];
+    walkSelfTypedComponentNode(layout.root, 'root', refs);
+    return refs.map((ref) => ({ source: { type: 'layout', id: layout.id }, ...ref }));
+}
+/**
+ * Schema-free, manifest-free graph extraction (EC-277): component usage + self-typed
+ * static props across every layout, in deterministic (id-sorted) order.
+ */
+export function extractSelfTypedGraphReferences(graph) {
+    const entries = [];
+    for (const layout of [...graph.layouts].sort((a, b) => (a.id < b.id ? -1 : 1))) {
+        entries.push(...extractLayoutReferences(layout));
+    }
+    return entries;
+}
+//# sourceMappingURL=reference-extraction.js.map

package/dist/persistence/reference-extraction.js.map

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

package/dist/persistence/reference-indexing.d.ts

@@ -0,0 +1,68 @@
+import type { DocumentRef } from '@elytracms/core/cms-core';
+import type { PersistenceAdapter } from './adapter';
+import type { ReferenceEntryRecord, ReferenceSource, ReferenceVariant } from './references';
+/**
+ * Reference-index maintenance (EC-155): recompute-on-save routines shared by
+ * the operations-layer event subscriber (`@elytracms/core/operations` `references.ts`)
+ * and the backfill command. All writes are replace-all-for-source, so they are
+ * idempotent and never leave stale entries.
+ *
+ * Variant semantics:
+ * - **Documents** — the editable content *is* the draft variant, so a document
+ *   always (re)indexes its draft entries; its published entries exist only
+ *   while its version pointer (`publishedVersion`) is set. A draft-only document referencing a
+ *   published target is therefore queryable as exactly that (the Sanity
+ *   "hidden draft reference" failure case, vision AD-6).
+ * - **Graphs** — draft entries come from the latest revision; published entries
+ *   from the revisions pinned live by the publishing states (union across
+ *   environments, deterministic order).
+ */
+/**
+ * Options for the reindex routines. EC-277: extraction is now a schema-free,
+ * manifest-free walk over self-describing content, so no binding-source resolver or
+ * manifest lookup is threaded — the interface is retained (empty) as a stable seam
+ * for future per-reindex options.
+ */
+export type ReferenceIndexingOptions = Record<never, never>;
+/** The index source entity for a document. */
+export declare function documentReferenceSource(ref: DocumentRef): ReferenceSource;
+/**
+ * Recompute the index entries held by one document (both variants). A missing
+ * document (deleted) simply drops all of its entries.
+ */
+export declare function reindexDocumentReferences(adapter: PersistenceAdapter, projectId: string, ref: DocumentRef, options?: ReferenceIndexingOptions): Promise<void>;
+/** Recompute the entries of every document in a project (deterministic order). */
+export declare function reindexAllDocumentReferences(adapter: PersistenceAdapter, projectId: string, options?: ReferenceIndexingOptions): Promise<void>;
+/** Recompute the draft graph entries (pages + layouts) from the latest revision. */
+export declare function reindexGraphDraftReferences(adapter: PersistenceAdapter, projectId: string, options?: ReferenceIndexingOptions): Promise<void>;
+/**
+ * Recompute the published graph entries from the revision pinned live by the
+ * deployment's publishing state (unpublishing drops all published graph
+ * entries). Single-environment (EC-179): one deployment pins one revision.
+ */
+export declare function reindexGraphPublishedReferences(adapter: PersistenceAdapter, projectId: string, options?: ReferenceIndexingOptions): Promise<void>;
+/** Recompute both graph variants (a graph save can move what "latest" means). */
+export declare function reindexGraphReferences(adapter: PersistenceAdapter, projectId: string, variant: ReferenceVariant | 'both', options?: ReferenceIndexingOptions): Promise<void>;
+/**
+ * Backfill: rebuild the complete reference index of a project from its current
+ * data — every document (both variants) and the graph (draft + published).
+ * Deterministic and idempotent: running it twice yields identical entries.
+ * Returns the full resulting index for inspection/verification.
+ */
+export declare function backfillReferenceIndex(adapter: PersistenceAdapter, projectId: string, options?: ReferenceIndexingOptions): Promise<ReferenceEntryRecord[]>;
+/**
+ * Ensure the project's reference index has been backfilled at least once
+ * (EC-269). The index is maintained on write, so the (clear + rebuild) backfill
+ * is only needed to *seed* a never-built index — a fresh import/seed. A persisted
+ * marker records completion; when present this is a single read with **zero
+ * mutations**, so opening the References panel no longer rewrites the whole index
+ * every session (the normal Convex case — the EC-233 import already backfilled).
+ *
+ * Pass `force: true` to ignore the marker and rebuild unconditionally (the
+ * explicit "rebuild index" maintenance path).
+ */
+export declare function ensureReferenceIndexBackfilled(adapter: PersistenceAdapter, projectId: string, options?: ReferenceIndexingOptions & {
+    force?: boolean;
+}): Promise<{
+    backfilled: boolean;
+}>;

package/dist/persistence/reference-indexing.js

@@ -0,0 +1,112 @@
+import { documentKey } from '@elytracms/core/cms-core';
+import { extractReferences, extractSelfTypedGraphReferences } from './reference-extraction';
+/** The index source entity for a document. */
+export function documentReferenceSource(ref) {
+    return { type: 'document', id: documentKey(ref) };
+}
+/**
+ * Recompute the index entries held by one document (both variants). A missing
+ * document (deleted) simply drops all of its entries.
+ */
+export async function reindexDocumentReferences(adapter, projectId, ref, options = {}) {
+    const source = documentReferenceSource(ref);
+    const record = await adapter.cms.findDocument(projectId, ref);
+    if (!record) {
+        await adapter.references.removeForSource(projectId, source);
+        return;
+    }
+    // EC-277: self-describing content — extraction is a schema-free, manifest-free walk
+    // over the stored value (no `findSchema`, no binding/manifest context). Static
+    // relation/asset props inside a `blocks` composition self-describe, so they are
+    // found without the manifest the old field-type-driven extractor required.
+    const references = extractReferences(record.document);
+    await adapter.references.replaceForSource(projectId, 'draft', source, references);
+    // EC-224: a document is published when its version pointer (`publishedVersion`)
+    // is set — mirrors delivery and the EC-173 integrity guard
+    // `collectStrictReferrers`. A pointer-published doc keeps its live row as the
+    // working draft, so published reference entries are extracted from that live
+    // draft (matching the guard's draft-content model), not the pinned snapshot;
+    // revisit only if published-reference resolution must mirror the snapshot exactly.
+    const referrerPublished = record.publishedVersion !== undefined;
+    await adapter.references.replaceForSource(projectId, 'published', source, referrerPublished ? references : []);
+}
+/** Recompute the entries of every document in a project (deterministic order). */
+export async function reindexAllDocumentReferences(adapter, projectId, options = {}) {
+    const records = await adapter.cms.listDocuments(projectId);
+    for (const record of records) {
+        await reindexDocumentReferences(adapter, projectId, { collection: record.document.collection, id: record.document.id }, options);
+    }
+}
+/** Recompute the draft graph entries (pages + layouts) from the latest revision. */
+export async function reindexGraphDraftReferences(adapter, projectId, options = {}) {
+    const hasGraph = await adapter.graphs.hasGraph(projectId);
+    const entries = hasGraph
+        ? extractSelfTypedGraphReferences((await adapter.graphs.getLatest(projectId)).graph)
+        : [];
+    await adapter.references.replaceForSourceTypes(projectId, 'draft', ['page', 'layout'], entries);
+}
+/**
+ * Recompute the published graph entries from the revision pinned live by the
+ * deployment's publishing state (unpublishing drops all published graph
+ * entries). Single-environment (EC-179): one deployment pins one revision.
+ */
+export async function reindexGraphPublishedReferences(adapter, projectId, options = {}) {
+    const state = await adapter.publishing.findState(projectId);
+    const revisions = state?.status === 'published' && state.publishedRevision !== undefined
+        ? [state.publishedRevision]
+        : [];
+    const entries = [];
+    for (const revision of revisions) {
+        const loaded = await adapter.graphs.getRevision(projectId, revision);
+        entries.push(...extractSelfTypedGraphReferences(loaded.graph));
+    }
+    await adapter.references.replaceForSourceTypes(projectId, 'published', ['page', 'layout'], entries);
+}
+/** Recompute both graph variants (a graph save can move what "latest" means). */
+export async function reindexGraphReferences(adapter, projectId, variant, options = {}) {
+    if (variant === 'draft' || variant === 'both') {
+        await reindexGraphDraftReferences(adapter, projectId, options);
+    }
+    if (variant === 'published' || variant === 'both') {
+        await reindexGraphPublishedReferences(adapter, projectId, options);
+    }
+}
+/**
+ * Backfill: rebuild the complete reference index of a project from its current
+ * data — every document (both variants) and the graph (draft + published).
+ * Deterministic and idempotent: running it twice yields identical entries.
+ * Returns the full resulting index for inspection/verification.
+ */
+export async function backfillReferenceIndex(adapter, projectId, options = {}) {
+    await adapter.references.clearProject(projectId);
+    await reindexAllDocumentReferences(adapter, projectId, options);
+    await reindexGraphReferences(adapter, projectId, 'both', options);
+    const records = await adapter.references.listEntries(projectId);
+    // EC-269: record completion so the read path can skip the rebuild next time.
+    // `clearProject` above cleared any prior marker, so it is set exactly once the
+    // rebuild has fully settled — never present over a partial index.
+    await adapter.references.setBuildMarker(projectId, { entryCount: records.length });
+    return records;
+}
+/**
+ * Ensure the project's reference index has been backfilled at least once
+ * (EC-269). The index is maintained on write, so the (clear + rebuild) backfill
+ * is only needed to *seed* a never-built index — a fresh import/seed. A persisted
+ * marker records completion; when present this is a single read with **zero
+ * mutations**, so opening the References panel no longer rewrites the whole index
+ * every session (the normal Convex case — the EC-233 import already backfilled).
+ *
+ * Pass `force: true` to ignore the marker and rebuild unconditionally (the
+ * explicit "rebuild index" maintenance path).
+ */
+export async function ensureReferenceIndexBackfilled(adapter, projectId, options = {}) {
+    const { force, ...indexing } = options;
+    if (!force) {
+        const marker = await adapter.references.getBuildMarker(projectId);
+        if (marker)
+            return { backfilled: false };
+    }
+    await backfillReferenceIndex(adapter, projectId, indexing);
+    return { backfilled: true };
+}
+//# sourceMappingURL=reference-indexing.js.map

package/dist/persistence/reference-indexing.js.map

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