sanity-plugin-taxonomy-manager 4.7.2 → 5.0.0

package/src/core/ids.ts

@@ -0,0 +1,61 @@
+import {
+  DocumentId,
+  getDraftId,
+  getVersionId,
+  getVersionNameFromId,
+  isPublishedId,
+  isVersionId,
+  type VersionId,
+} from '@sanity/id-utils'
+
+/** The `_strengthenOnPublish` template applied to weak skosConcept references. */
+export const SKOS_CONCEPT_STRENGTHEN = {type: 'skosConcept', template: {id: 'skosConcept'}} as const
+
+export type SchemeMutationTarget = {
+  isInRelease: boolean
+  releaseName: string | undefined
+  schemeId: string
+}
+
+/**
+ * Resolve the document id a scheme mutation should write to, from the displayed
+ * scheme id: the matching version id when the scheme is being edited inside a
+ * release, otherwise its draft id. Shared by concept create/remove.
+ */
+export function deriveSchemeMutationTarget(displayedId: string): SchemeMutationTarget {
+  const docId = DocumentId(displayedId)
+  const isInRelease = isVersionId(docId)
+  const releaseName = isInRelease ? getVersionNameFromId(docId as VersionId) : undefined
+  const schemeId = isInRelease ? getVersionId(docId, releaseName as string) : getDraftId(docId)
+  return {isInRelease, releaseName, schemeId}
+}
+
+/**
+ * The id for a newly created concept, in the same release/draft context as its
+ * scheme. `uuid` is supplied by the caller (kept pure/deterministic here).
+ */
+export function deriveNewConceptId(
+  uuid: string,
+  context: {isInRelease: boolean; releaseName: string | undefined},
+): string {
+  const docId = DocumentId(uuid)
+  return context.isInRelease
+    ? getVersionId(docId, context.releaseName as string)
+    : getDraftId(docId)
+}
+
+export type ReferenceStrength = {
+  _weak: boolean
+  _strengthenOnPublish?: typeof SKOS_CONCEPT_STRENGTHEN
+}
+
+/**
+ * Weak-reference flags for a reference to a concept that may not be published
+ * yet. When the referenced concept is a draft or version (not published), the
+ * reference must be weak and strengthened on publish so it survives until the
+ * target is published.
+ */
+export function conceptReferenceStrength(referencedOriginalId: string): ReferenceStrength {
+  const published = isPublishedId(DocumentId(referencedOriginalId))
+  return published ? {_weak: false} : {_weak: true, _strengthenOnPublish: SKOS_CONCEPT_STRENGTHEN}
+}

package/src/core/mutations.test.ts

@@ -0,0 +1,114 @@
+import {describe, expect, it} from 'vitest'
+
+import type {ConceptSchemeDocument} from '../types'
+
+import {SKOS_CONCEPT_STRENGTHEN} from './ids'
+import {planCreateConcept, planRemoveConcept} from './mutations'
+
+const scheme = (id: string): ConceptSchemeDocument['displayed'] =>
+  ({_id: id, _type: 'skosConceptScheme', title: 'Test Scheme'}) as ConceptSchemeDocument['displayed']
+
+describe('planCreateConcept', () => {
+  it('plans a top concept on a published scheme (draft target, no broader)', () => {
+    expect(
+      planCreateConcept({
+        scheme: scheme('scheme-1'),
+        conceptType: 'topConcept',
+        newConceptUuid: 'new-1',
+        conceptId: 'abc123',
+        schemeBaseIri: 'https://example.com/',
+        newConceptKey: 'ref-key',
+        broaderKey: 'broader-key',
+      }),
+    ).toEqual({
+      kind: 'create',
+      schemeId: 'drafts.scheme-1',
+      newConceptId: 'drafts.new-1',
+      createIfNotExists: {_id: 'drafts.scheme-1', _type: 'skosConceptScheme', title: 'Test Scheme'},
+      create: {
+        _id: 'drafts.new-1',
+        _type: 'skosConcept',
+        conceptId: 'abc123',
+        prefLabel: '',
+        baseIri: 'https://example.com/',
+        broader: [],
+        related: [],
+      },
+      appendField: 'topConcepts',
+      reference: {
+        _ref: 'new-1',
+        _type: 'reference',
+        _key: 'ref-key',
+        _strengthenOnPublish: SKOS_CONCEPT_STRENGTHEN,
+        _weak: true,
+      },
+    })
+  })
+
+  it('plans a child concept on a draft scheme with a published broader (strong broader ref)', () => {
+    const plan = planCreateConcept({
+      scheme: scheme('drafts.scheme-1'),
+      conceptType: 'concept',
+      broaderConcept: {id: 'broader-1', _originalId: 'broader-1'},
+      newConceptUuid: 'new-2',
+      conceptId: 'def456',
+      schemeBaseIri: undefined,
+      newConceptKey: 'ref-key',
+      broaderKey: 'broader-key',
+    })
+    expect(plan.schemeId).toBe('drafts.scheme-1')
+    expect(plan.newConceptId).toBe('drafts.new-2')
+    expect(plan.appendField).toBe('concepts')
+    expect(plan.create.broader).toEqual([
+      {_key: 'broader-key', _ref: 'broader-1', _type: 'reference', _weak: false},
+    ])
+  })
+
+  it('plans a child concept in a release with a draft broader (weak broader ref)', () => {
+    const plan = planCreateConcept({
+      scheme: scheme('versions.rel1.scheme-1'),
+      conceptType: 'concept',
+      broaderConcept: {id: 'broader-2', _originalId: 'drafts.broader-2'},
+      newConceptUuid: 'new-3',
+      conceptId: 'ghi789',
+      schemeBaseIri: 'https://example.com/',
+      newConceptKey: 'ref-key',
+      broaderKey: 'broader-key',
+    })
+    expect(plan.schemeId).toBe('versions.rel1.scheme-1')
+    expect(plan.newConceptId).toBe('versions.rel1.new-3')
+    expect(plan.reference._ref).toBe('new-3')
+    expect(plan.create.broader).toEqual([
+      {
+        _key: 'broader-key',
+        _ref: 'broader-2',
+        _type: 'reference',
+        _weak: true,
+        _strengthenOnPublish: SKOS_CONCEPT_STRENGTHEN,
+      },
+    ])
+  })
+})
+
+describe('planRemoveConcept', () => {
+  it('plans removal of a top concept from a published scheme (draft target)', () => {
+    expect(
+      planRemoveConcept({scheme: scheme('scheme-1'), conceptRef: 'concept-9', conceptType: 'topConcept'}),
+    ).toEqual({
+      kind: 'remove',
+      schemeId: 'drafts.scheme-1',
+      createIfNotExists: {_id: 'drafts.scheme-1', _type: 'skosConceptScheme', title: 'Test Scheme'},
+      unsetPaths: ['topConcepts[_ref=="concept-9"]'],
+    })
+  })
+
+  it('plans removal of a concept from a scheme in a release (version target)', () => {
+    const plan = planRemoveConcept({
+      scheme: scheme('versions.rel1.scheme-1'),
+      conceptRef: 'concept-9',
+      conceptType: 'concept',
+    })
+    expect(plan.schemeId).toBe('versions.rel1.scheme-1')
+    expect(plan.unsetPaths).toEqual(['concepts[_ref=="concept-9"]'])
+  })
+})

package/src/core/mutations.ts

@@ -0,0 +1,105 @@
+import {DocumentId, getPublishedId} from '@sanity/id-utils'
+
+import type {ConceptSchemeDocument, SkosConceptDocument, SkosConceptReference} from '../types'
+
+import {
+  conceptReferenceStrength,
+  deriveNewConceptId,
+  deriveSchemeMutationTarget,
+  SKOS_CONCEPT_STRENGTHEN,
+} from './ids'
+
+type SchemeDisplayed = ConceptSchemeDocument['displayed']
+
+/**
+ * "Describe, don't execute": the create/remove planners below compute a pure
+ * description of the transaction a concept mutation should run. The hooks stay
+ * thin — they generate the random ids/keys, pass them in, and replay the plan
+ * onto client.transaction(). This makes the release/version-aware mutation logic
+ * exhaustively unit-testable without a Studio.
+ */
+
+export type CreateConceptPlan = {
+  kind: 'create'
+  schemeId: string
+  newConceptId: string
+  createIfNotExists: SchemeDisplayed & {_id: string}
+  create: SkosConceptDocument
+  appendField: 'topConcepts' | 'concepts'
+  reference: SkosConceptReference
+}
+
+export function planCreateConcept(input: {
+  scheme: SchemeDisplayed
+  conceptType: 'topConcept' | 'concept'
+  broaderConcept?: {id: string; _originalId: string}
+  newConceptUuid: string
+  conceptId: string
+  schemeBaseIri: string | undefined
+  newConceptKey: string
+  broaderKey: string
+}): CreateConceptPlan {
+  const target = deriveSchemeMutationTarget(input.scheme._id)
+  const newConceptId = deriveNewConceptId(input.newConceptUuid, target)
+
+  const create: SkosConceptDocument = {
+    _id: newConceptId,
+    _type: 'skosConcept',
+    conceptId: input.conceptId,
+    prefLabel: '',
+    baseIri: input.schemeBaseIri,
+    broader: [],
+    related: [],
+  }
+
+  if (input.broaderConcept) {
+    create.broader = [
+      {
+        _key: input.broaderKey,
+        _ref: getPublishedId(DocumentId(input.broaderConcept.id)),
+        _type: 'reference',
+        ...conceptReferenceStrength(input.broaderConcept._originalId),
+      },
+    ]
+  }
+
+  const reference: SkosConceptReference = {
+    _ref: getPublishedId(DocumentId(newConceptId)),
+    _type: 'reference',
+    _key: input.newConceptKey,
+    _strengthenOnPublish: SKOS_CONCEPT_STRENGTHEN,
+    _weak: true,
+  }
+
+  return {
+    kind: 'create',
+    schemeId: target.schemeId,
+    newConceptId,
+    createIfNotExists: {...input.scheme, _id: target.schemeId},
+    create,
+    appendField: input.conceptType === 'topConcept' ? 'topConcepts' : 'concepts',
+    reference,
+  }
+}
+
+export type RemoveConceptPlan = {
+  kind: 'remove'
+  schemeId: string
+  createIfNotExists: SchemeDisplayed & {_id: string}
+  unsetPaths: string[]
+}
+
+export function planRemoveConcept(input: {
+  scheme: SchemeDisplayed
+  conceptRef: string
+  conceptType: string
+}): RemoveConceptPlan {
+  const field = input.conceptType === 'topConcept' ? 'topConcepts' : 'concepts'
+  const {schemeId} = deriveSchemeMutationTarget(input.scheme._id)
+  return {
+    kind: 'remove',
+    schemeId,
+    createIfNotExists: {...input.scheme, _id: schemeId},
+    unsetPaths: [`${field}[_ref=="${input.conceptRef}"]`],
+  }
+}

package/src/core/ports.ts

@@ -0,0 +1,59 @@
+import type {CreateConceptPlan, RemoveConceptPlan} from './mutations'
+import type {ConceptRecommendation, DocumentConcepts, SemanticSearchConfig} from '../types'
+
+/**
+ * #### Taxonomy Data Port
+ * The single internal seam for everything that touches Sanity Studio or the
+ * network: the live concept-tree query, concept-mutation transactions, and
+ * semantic term recommendations. Components and mutation hooks talk to this
+ * interface instead of `useListeningQuery`/`useClient` directly, so the render
+ * tree can be exercised against an in-memory fake (`test/FakeDataPort`) and the
+ * implementation can be swapped later (e.g. the App SDK) without touching
+ * components.
+ *
+ * Members are hooks (`use*`): the tree seam wraps Studio's
+ * `documentStore.listenQuery` and the mutation/embeddings seams read the Studio
+ * client from React context, so they obey the rules of hooks. They are reached
+ * via `useTaxonomyDataPort()` — default is the real `StudioDataAdapter`, and
+ * tests inject a fake through `TaxonomyPortProvider`.
+ */
+export interface TaxonomyDataPort {
+  /** Live concept tree for a scheme document (`trunk`) or a branch within it (`input`). */
+  useWatchTree(params: ConceptTreeParams): WatchResult<DocumentConcepts>
+  /** Replay a pure create/remove plan (`core/mutations`) onto a Studio transaction. */
+  useApplyConceptPlan(): (plan: ConceptPlan) => Promise<void>
+  /** Semantic term recommendations for the input components (GROQ `text::semanticSimilarity()`). */
+  useSemanticRecommendations(config?: SemanticSearchConfig): SemanticRecommendationsResult
+}
+
+/**
+ * Perspective intent, mirroring `ReleaseContext` (`selectedPerspectiveName` from
+ * `usePerspective()`): `undefined` ⇒ drafts, otherwise the named perspective.
+ */
+export type TaxonomyPerspective = string | undefined
+
+/**
+ * Which tree to watch. `trunk` is the full scheme hierarchy (the structure Tree
+ * View); `input` is a (possibly branch-scoped) tree for the field input dialog.
+ */
+export type ConceptTreeParams =
+  | {mode: 'trunk'; documentId: string; perspective: TaxonomyPerspective}
+  | {mode: 'input'; documentId: string; branchId: string | null; perspective: TaxonomyPerspective}
+
+/** Result shape of a live query: mirrors `useListeningQuery`, with `error` normalized to `Error | null`. */
+export interface WatchResult<T> {
+  data: T | null
+  loading: boolean
+  error: Error | null
+}
+
+/** A create or remove transaction plan, discriminated by `kind` (see `core/mutations`). */
+export type ConceptPlan = CreateConceptPlan | RemoveConceptPlan
+
+/** Return shape of the semantic-recommendations seam. */
+export interface SemanticRecommendationsResult {
+  conceptRecs: ConceptRecommendation[]
+  recsError: string | null
+  /** Run the search, scoping recommendations to the given scheme; a no-op without a `schemeId`. */
+  triggerSearch: (schemeId?: string) => void
+}

package/src/core/queries.test.ts

@@ -0,0 +1,50 @@
+import {describe, expect, it} from 'vitest'
+
+import {inputBuilder, trunkBuilder} from './queries'
+
+// Characterization tests: pin the exact GROQ the builders emit today so the
+// Stage 3 extraction into core/ (and making the depth cap configurable) cannot
+// silently change behavior. The full strings are snapshotted; the structural
+// assertions document the load-bearing parts.
+
+describe('trunkBuilder', () => {
+  const query = trunkBuilder()
+
+  it('matches the characterized GROQ output', () => {
+    expect(query).toMatchSnapshot()
+  })
+
+  it('selects the scheme by $id and projects topConcepts + concepts, ordered by prefLabel', () => {
+    expect(query).toContain('*[_id == $id][0]')
+    expect(query).toContain('"topConcepts": topConcepts[]->|order(prefLabel)')
+    expect(query).toContain('"concepts": concepts[]->|order(prefLabel)')
+  })
+
+  it('computes isOrphan via array::intersects of broader refs against the scheme refs', () => {
+    expect(query).toContain('"isOrphan":')
+    expect(query).toContain('array::intersects')
+  })
+
+  it('recurses childConcepts to a depth cap of 6 levels', () => {
+    expect(query).toContain('"level": 6')
+    expect(query).not.toContain('"level": 7')
+  })
+})
+
+describe('inputBuilder', () => {
+  const query = inputBuilder()
+
+  it('matches the characterized GROQ output', () => {
+    expect(query).toMatchSnapshot()
+  })
+
+  it('branches on the presence of $branchId via select()', () => {
+    expect(query).toContain('select($branchId != null =>')
+    expect(query).toContain('$branchId in @->broader[]->.conceptId')
+  })
+
+  it('recurses childConcepts to a depth cap of 6 levels', () => {
+    expect(query).toContain('"level": 6')
+    expect(query).not.toContain('"level": 7')
+  })
+})

package/src/{queries.ts → core/queries.ts}

@@ -1,13 +1,14 @@
 /**
- * ### Tree Builder
- * Recursive function to build out successive branches of the hierarchy
- * up to five levels deep.
+ * Maximum hierarchy depth the builders recurse to. This is the single knob for
+ * the depth cap — raising it later (if performance permits and use cases
+ * warrant) is a one-line change. Kept at its long-standing value of 6.
  */
+const MAX_TREE_DEPTH = 6
 
 /**
  * #### Branch Builder
- * Recursive function to build out successive branches of the hierarchy
- * up to five levels deep.
+ * Recursive builder for successive branches of the concept hierarchy, down to
+ * `MAX_TREE_DEPTH` levels deep.
  */
 const branchBuilder = (level = 1): string | void => {
   let reference = '^.^.concepts[]._ref'
@@ -16,7 +17,7 @@ const branchBuilder = (level = 1): string | void => {
     reference = `^.${reference}`
     i++
   }
-  if (level > 6) {
+  if (level > MAX_TREE_DEPTH) {
     return ''
   }
   return `"childConcepts": *[_id in ${reference} && ^._id in broader[]._ref]|order(prefLabel)

package/src/core/semanticRecommendations.test.ts

@@ -0,0 +1,160 @@
+import {describe, expect, it} from 'vitest'
+
+import {
+  assembleQueryText,
+  recommendationsErrorMessage,
+  recommendationsQuery,
+  recommendedConceptIds,
+  toConceptRecommendations,
+} from './semanticRecommendations'
+
+describe('recommendationsQuery', () => {
+  const query = recommendationsQuery()
+
+  it('matches the characterized GROQ output', () => {
+    expect(query).toMatchSnapshot()
+  })
+
+  it('scores skosConcepts by semanticSimilarity and returns the top $maxResults', () => {
+    expect(query).toContain('_type == "skosConcept"')
+    expect(query).toContain('score(text::semanticSimilarity($searchQuery))')
+    expect(query).toContain('order(_score desc)')
+    expect(query).toContain('[0...$maxResults]')
+    expect(query).toContain('"conceptId": _id')
+    expect(query).toContain('"score": _score')
+  })
+
+  it("scopes candidates to the field's scheme via $schemeId membership", () => {
+    expect(query).toContain('_type == "skosConceptScheme" && schemeId == $schemeId')
+    expect(query).toContain('topConcepts[]._ref')
+    expect(query).toContain('concepts[]._ref')
+    expect(query).toContain('_id in')
+  })
+
+  it('uses no part of the deprecated Embeddings Index API', () => {
+    expect(query).not.toContain('text::embedding')
+    expect(query).not.toContain('embeddings-index')
+  })
+})
+
+describe('assembleQueryText', () => {
+  it('joins the non-empty field values with a space, in order', () => {
+    const text = assembleQueryText([
+      {name: 'title', value: 'Summer'},
+      {name: 'description', value: 'reading list'},
+    ])
+    expect(text).toBe('Summer reading list')
+  })
+
+  it('throws naming the single empty field', () => {
+    expect(() =>
+      assembleQueryText([
+        {name: 'title', value: 'Summer'},
+        {name: 'description', value: ''},
+      ])
+    ).toThrowError('Please fill out the description field to enable match scores.')
+  })
+
+  it('throws listing every empty field when more than one is empty', () => {
+    expect(() =>
+      assembleQueryText([
+        {name: 'title', value: ''},
+        {name: 'description', value: '   '},
+      ])
+    ).toThrowError(
+      'The following fields must be filled out to enable match scores: title, description'
+    )
+  })
+
+  it('treats whitespace-only and non-string values as empty', () => {
+    expect(() =>
+      assembleQueryText([
+        {name: 'title', value: '  '},
+        {name: 'count', value: 42},
+      ])
+    ).toThrowError(
+      'The following fields must be filled out to enable match scores: title, count'
+    )
+  })
+})
+
+describe('toConceptRecommendations', () => {
+  it('maps rows to {conceptId, score}', () => {
+    const recs = toConceptRecommendations([
+      {conceptId: 'concept-a', score: 0.9},
+      {conceptId: 'concept-b', score: 0.4},
+    ])
+    expect(recs).toEqual([
+      {conceptId: 'concept-a', score: 0.9},
+      {conceptId: 'concept-b', score: 0.4},
+    ])
+  })
+
+  it('normalizes draft and version ids to their published form', () => {
+    const recs = toConceptRecommendations([
+      {conceptId: 'drafts.concept-a', score: 0.9},
+      {conceptId: 'versions.rABC.concept-b', score: 0.4},
+    ])
+    expect(recs).toEqual([
+      {conceptId: 'concept-a', score: 0.9},
+      {conceptId: 'concept-b', score: 0.4},
+    ])
+  })
+
+  it('drops rows missing a string id or numeric score', () => {
+    const recs = toConceptRecommendations([
+      {conceptId: 'concept-a', score: 0.9},
+      {conceptId: '', score: 0.5},
+      {conceptId: 'concept-c', score: null as unknown as number},
+      null as unknown as {conceptId: string; score: number},
+    ])
+    expect(recs).toEqual([{conceptId: 'concept-a', score: 0.9}])
+  })
+
+  it('returns an empty array for null or undefined input', () => {
+    expect(toConceptRecommendations(null)).toEqual([])
+    expect(toConceptRecommendations(undefined)).toEqual([])
+  })
+})
+
+describe('recommendedConceptIds', () => {
+  it('collects the recommended concept ids as a set', () => {
+    const ids = recommendedConceptIds([
+      {conceptId: 'a', score: 0.9},
+      {conceptId: 'b', score: 0.4},
+    ])
+    expect(ids).toEqual(new Set(['a', 'b']))
+  })
+
+  it('de-duplicates repeated concept ids', () => {
+    const ids = recommendedConceptIds([
+      {conceptId: 'a', score: 0.9},
+      {conceptId: 'a', score: 0.3},
+      {conceptId: 'b', score: 0.5},
+    ])
+    expect(ids).toEqual(new Set(['a', 'b']))
+  })
+
+  it('returns an empty set for no recommendations', () => {
+    expect(recommendedConceptIds([]).size).toBe(0)
+  })
+})
+
+describe('recommendationsErrorMessage', () => {
+  it('flags an embeddings-related error as the dataset not being enabled', () => {
+    const message = recommendationsErrorMessage(
+      new Error('text::semanticSimilarity requires embeddings to be enabled')
+    )
+    expect(message).toBe("Semantic recommendations aren't enabled for this dataset.")
+  })
+
+  it('falls back to a generic message for any other failure', () => {
+    expect(recommendationsErrorMessage(new Error('Network request failed'))).toBe(
+      'Unable to load semantic recommendations.'
+    )
+    expect(recommendationsErrorMessage('socket hang up')).toBe(
+      'Unable to load semantic recommendations.'
+    )
+    expect(recommendationsErrorMessage(undefined)).toBe('Unable to load semantic recommendations.')
+  })
+})