@estiva-app/interop 0.44.0 → 0.46.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,57 @@
1
+ /**
2
+ * The files `[` offers, as @estiva-app/conversation ranks them (PEE-21).
3
+ *
4
+ * conversation's `rankReferences` orders candidates and knows nothing of a
5
+ * relay; this is the half that turns what a relay holds into candidates — a
6
+ * resolved object into a row, and typed text into the search tier — so Peek
7
+ * and Ship draw the same rows from the same reads.
8
+ *
9
+ * A row is the type word and the current title; an issue is captioned with its
10
+ * project's title, and nothing names a Folder (Miky, 2026-10-03). Only what the
11
+ * reader resolved is offered: an object the relay did not hand back to them is
12
+ * never a row, so nothing unreadable is offered. An archived file is offered
13
+ * at the lowest priority, and so is an issue in an archived project.
14
+ */
15
+ import { type ReferenceCandidate, type ReferenceType } from '@estiva-app/conversation';
16
+ import { type ForeignObject, type ProjectionCache, type QueryFn } from './projection.js';
17
+ /** The kinds `[` offers as files, and the type word each draws as. */
18
+ export declare const REFERENCE_FILE_TYPES: Readonly<Record<number, ReferenceType>>;
19
+ export interface FileCandidatesOptions {
20
+ cache?: ProjectionCache;
21
+ /** When each address was last written or read, in seconds — newer first within a tier. */
22
+ at?: ReadonlyMap<string, number>;
23
+ }
24
+ /**
25
+ * Rows for resolved files, all in one tier.
26
+ *
27
+ * An issue's caption is its project's title, and an issue in an archived
28
+ * project is archived with it: the project is taken from `objects` when it is
29
+ * among them, and otherwise read in one more batch for every missing project
30
+ * at once (roots and changes only). A project that cannot be read leaves the
31
+ * caption empty rather than dropping the issue. Objects that are not
32
+ * offerable — unreachable, untitled, or of a kind `[` does not offer — are
33
+ * left out.
34
+ */
35
+ export declare function fileCandidates(objects: readonly (ForeignObject | null | undefined)[], tier: number, query: QueryFn, { cache, at }?: FileCandidatesOptions): Promise<ReferenceCandidate[]>;
36
+ export interface SearchFileReferencesOptions extends Omit<FileCandidatesOptions, 'at'> {
37
+ /** How many roots, and separately how many renames, the relay is asked for. Default 32. */
38
+ limit?: number;
39
+ }
40
+ /**
41
+ * The files whose **current** title holds `text`, as the search tier.
42
+ *
43
+ * The relay indexes a root's `title` and a rename's `value` (relay ticket
44
+ * 6fea004e); neither is the current title on its own — a root keeps the name
45
+ * it was created with, and a rename found by an old word may since have been
46
+ * renamed again. So a hit is only an address: each is read back as its root
47
+ * and changes, folded through its app's manifest, and kept only when what it
48
+ * is called now matches what was typed.
49
+ *
50
+ * Roots and renames are asked for separately, so a burst of renames cannot
51
+ * crowd every root out of the answer, and with buzz's prefix mode, so the word
52
+ * being typed matches before it is finished. A relay that indexes none of these
53
+ * kinds answers nothing, and so does this. A failed read rejects, for
54
+ * `referenceSearch` to answer no hits for a while.
55
+ */
56
+ export declare function searchFileReferences(text: string, query: QueryFn, { limit, ...options }?: SearchFileReferencesOptions): Promise<ReferenceCandidate[]>;
57
+ //# sourceMappingURL=references.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"references.d.ts","sourceRoot":"","sources":["../src/references.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAKL,KAAK,kBAAkB,EACvB,KAAK,aAAa,EACnB,MAAM,0BAA0B,CAAA;AACjC,OAAO,EAIL,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,OAAO,EACb,MAAM,iBAAiB,CAAA;AAKxB,sEAAsE;AACtE,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAIxE,CAAA;AAcD,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,EAAE,eAAe,CAAA;IACvB,0FAA0F;IAC1F,EAAE,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACjC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,SAAS,CAAC,aAAa,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,EACtD,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,EACd,EAAE,KAAK,EAAE,EAAE,EAAE,GAAE,qBAA0B,GACxC,OAAO,CAAC,kBAAkB,EAAE,CAAC,CA0B/B;AAED,MAAM,WAAW,2BAA4B,SAAQ,IAAI,CAAC,qBAAqB,EAAE,IAAI,CAAC;IACpF,2FAA2F;IAC3F,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAID;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,EACd,EAAE,KAAU,EAAE,GAAG,OAAO,EAAE,GAAE,2BAAgC,GAC3D,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAuB/B"}
@@ -0,0 +1,117 @@
1
+ /**
2
+ * The files `[` offers, as @estiva-app/conversation ranks them (PEE-21).
3
+ *
4
+ * conversation's `rankReferences` orders candidates and knows nothing of a
5
+ * relay; this is the half that turns what a relay holds into candidates — a
6
+ * resolved object into a row, and typed text into the search tier — so Peek
7
+ * and Ship draw the same rows from the same reads.
8
+ *
9
+ * A row is the type word and the current title; an issue is captioned with its
10
+ * project's title, and nothing names a Folder (Miky, 2026-10-03). Only what the
11
+ * reader resolved is offered: an object the relay did not hand back to them is
12
+ * never a row, so nothing unreadable is offered. An archived file is offered
13
+ * at the lowest priority, and so is an issue in an archived project.
14
+ */
15
+ import { FILE_TIER, fileReference, KIND_CHANGE, referenceMatch, } from '@estiva-app/conversation';
16
+ import { isClosedStatus, KIND_BARE_FILE, resolveForeignRoots, } from './projection.js';
17
+ const KIND_PROJECT = 30850;
18
+ const KIND_ISSUE = 30851;
19
+ /** The kinds `[` offers as files, and the type word each draws as. */
20
+ export const REFERENCE_FILE_TYPES = {
21
+ [KIND_PROJECT]: 'project',
22
+ [KIND_ISSUE]: 'issue',
23
+ [KIND_BARE_FILE]: 'topic',
24
+ };
25
+ const typeOf = (kind) => REFERENCE_FILE_TYPES[kind];
26
+ /** An object `[` may offer: a file kind it knows, resolved, with a title. */
27
+ const offerable = (object) => !!object &&
28
+ !!object.address &&
29
+ !object.unreachable &&
30
+ typeOf(object.kind) !== undefined &&
31
+ !!object.slots.title?.value.trim();
32
+ /**
33
+ * Rows for resolved files, all in one tier.
34
+ *
35
+ * An issue's caption is its project's title, and an issue in an archived
36
+ * project is archived with it: the project is taken from `objects` when it is
37
+ * among them, and otherwise read in one more batch for every missing project
38
+ * at once (roots and changes only). A project that cannot be read leaves the
39
+ * caption empty rather than dropping the issue. Objects that are not
40
+ * offerable — unreachable, untitled, or of a kind `[` does not offer — are
41
+ * left out.
42
+ */
43
+ export async function fileCandidates(objects, tier, query, { cache, at } = {}) {
44
+ const files = objects.filter(offerable);
45
+ const parents = new Map();
46
+ for (const o of objects)
47
+ if (o?.address && !o.unreachable)
48
+ parents.set(o.address, o);
49
+ const missing = [
50
+ ...new Set(files.flatMap((o) => (o.kind === KIND_ISSUE && o.parentRef && !parents.has(o.parentRef) ? [o.parentRef] : []))),
51
+ ];
52
+ if (missing.length) {
53
+ const read = await resolveForeignRoots(missing, query, cache).catch(() => []);
54
+ for (const parent of read)
55
+ if (parent.address)
56
+ parents.set(parent.address, parent);
57
+ }
58
+ return files.map((o) => {
59
+ const parent = o.kind === KIND_ISSUE && o.parentRef ? parents.get(o.parentRef) : undefined;
60
+ return {
61
+ id: o.address,
62
+ uri: fileReference(o.address),
63
+ type: typeOf(o.kind),
64
+ kind: o.kind,
65
+ title: o.slots.title.value,
66
+ caption: parent?.slots.title?.value ?? '',
67
+ tier,
68
+ ...(isClosedStatus(o.slots.status) ? { closed: true } : {}),
69
+ ...(o.archived || parent?.archived ? { archived: true } : {}),
70
+ ...(at?.has(o.address) ? { at: at.get(o.address) } : {}),
71
+ };
72
+ });
73
+ }
74
+ const tagOf = (event, name) => event.tags.find((t) => t[0] === name)?.[1];
75
+ /**
76
+ * The files whose **current** title holds `text`, as the search tier.
77
+ *
78
+ * The relay indexes a root's `title` and a rename's `value` (relay ticket
79
+ * 6fea004e); neither is the current title on its own — a root keeps the name
80
+ * it was created with, and a rename found by an old word may since have been
81
+ * renamed again. So a hit is only an address: each is read back as its root
82
+ * and changes, folded through its app's manifest, and kept only when what it
83
+ * is called now matches what was typed.
84
+ *
85
+ * Roots and renames are asked for separately, so a burst of renames cannot
86
+ * crowd every root out of the answer, and with buzz's prefix mode, so the word
87
+ * being typed matches before it is finished. A relay that indexes none of these
88
+ * kinds answers nothing, and so does this. A failed read rejects, for
89
+ * `referenceSearch` to answer no hits for a while.
90
+ */
91
+ export async function searchFileReferences(text, query, { limit = 32, ...options } = {}) {
92
+ const wanted = text.trim();
93
+ if (!wanted)
94
+ return [];
95
+ const asked = { search: wanted, search_mode: 'prefix', limit };
96
+ const hits = await query([
97
+ { kinds: Object.keys(REFERENCE_FILE_TYPES).map(Number), ...asked },
98
+ { kinds: [KIND_CHANGE], ...asked },
99
+ ]);
100
+ const at = new Map();
101
+ for (const hit of hits) {
102
+ const address = hit.kind === KIND_CHANGE
103
+ ? tagOf(hit, 'field') === 'title'
104
+ ? tagOf(hit, 'a')
105
+ : undefined
106
+ : typeOf(hit.kind) && `${hit.kind}:${hit.pubkey}:${tagOf(hit, 'd') ?? ''}`;
107
+ if (!address || !typeOf(Number(address.split(':')[0])))
108
+ continue;
109
+ at.set(address, Math.max(at.get(address) ?? 0, hit.created_at));
110
+ }
111
+ if (at.size === 0)
112
+ return [];
113
+ const objects = await resolveForeignRoots([...at.keys()], query, options.cache);
114
+ const matching = objects.filter((o) => o.slots.title && referenceMatch(o.slots.title.value, wanted) > 0);
115
+ return fileCandidates(matching, FILE_TIER.search, query, { ...options, at });
116
+ }
117
+ //# sourceMappingURL=references.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"references.js","sourceRoot":"","sources":["../src/references.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@estiva-app/interop",
3
- "version": "0.44.0",
3
+ "version": "0.46.0",
4
4
  "description": "Render and act on another app's objects from its published NIP-89 manifest. The owner defines the projection; the consumer decides how it looks.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -47,11 +47,11 @@
47
47
  "prepublishOnly": "npm run build"
48
48
  },
49
49
  "peerDependencies": {
50
- "@estiva-app/conversation": ">=0.1.0",
50
+ "@estiva-app/conversation": ">=0.5.0",
51
51
  "@estiva-app/protocol": ">=0.24.0"
52
52
  },
53
53
  "devDependencies": {
54
- "@estiva-app/conversation": ">=0.1.0",
54
+ "@estiva-app/conversation": ">=0.5.0",
55
55
  "@estiva-app/protocol": ">=0.24.0",
56
56
  "typescript": "~5.9.3"
57
57
  }
package/src/index.ts CHANGED
@@ -29,6 +29,8 @@ export {
29
29
  resolveActingManifest,
30
30
  resolveForeignObject,
31
31
  resolveForeignObjects,
32
+ resolveForeignRoots,
33
+ projectEvents,
32
34
  resolveParents,
33
35
  resolveForeignEvent,
34
36
  resolveFolderProject,
@@ -37,6 +39,7 @@ export {
37
39
  topLevelFolders,
38
40
  ARCHIVED_FIELD,
39
41
  isArchived,
42
+ isClosedStatus,
40
43
  archiveImpact,
41
44
  type Archive,
42
45
  type ArchiveImpact,
@@ -102,6 +105,18 @@ export {
102
105
  */
103
106
  export { nestingOf, type Nestable, type Nesting } from './nesting.js'
104
107
 
108
+ /**
109
+ * The files `[` offers (PEE-21): resolved objects as rows, and typed text as
110
+ * the search tier, both folded to the current title. conversation ranks them.
111
+ */
112
+ export {
113
+ fileCandidates,
114
+ REFERENCE_FILE_TYPES,
115
+ searchFileReferences,
116
+ type FileCandidatesOptions,
117
+ type SearchFileReferencesOptions,
118
+ } from './references.js'
119
+
105
120
  /**
106
121
  * Folder writes as unsigned events in publish order — create, rename, place,
107
122
  * unlist, move. Each takes `hasState` from the caller, because a `kind:1852`
package/src/projection.ts CHANGED
@@ -3146,6 +3146,157 @@ export async function resolveForeignObjects(
3146
3146
  return results
3147
3147
  }
3148
3148
 
3149
+ /**
3150
+ * Every object in a set of events the caller already holds, projected — PER-21.
3151
+ * **No requests.**
3152
+ *
3153
+ * {@link resolveForeignObjects} reads each object's own filters, which is the
3154
+ * right price for a sidebar holding a few dozen and the wrong one for a reader
3155
+ * that wants a whole app's workspace: interop's own measurement put 110 issues
3156
+ * at 20 POSTs and a megabyte (FOL-50), and estiva-agent re-reads its workspace
3157
+ * on every command. A reader like that can fetch the roots and the app's change
3158
+ * kind in bulk — a few paged queries — and hand them here.
3159
+ *
3160
+ * Each root of a kind the manifest projects becomes exactly the object
3161
+ * `resolveForeignObject` builds for it: the same fold (`records`, §6.2–6.3),
3162
+ * the same archive read, the same slots, meta, parent and actions. What is
3163
+ * deliberately absent is everything that would need another read:
3164
+ *
3165
+ * - **`comments` is `[]`.** A comment is a separate event in a Folder, and
3166
+ * which comments the caller fetched says nothing about which it did not.
3167
+ * Read conversations with {@link conversationsOf} and {@link threadsOf}.
3168
+ * - **No `children`.** A `list` slot is containment, and the children are
3169
+ * other objects in the same answer: nest them by `parentRef`.
3170
+ * - **No `people`, and no borrowed actions** (MAN-8) — both are reads.
3171
+ *
3172
+ * - **No archive inherited from a parent.** `archived` is the object's own
3173
+ * change; `resolveForeignObjects`'s `archivedWith` reads the parents' too,
3174
+ * and here the parent is simply another object in the answer, whose
3175
+ * `archived` the consumer can read by `parentRef`.
3176
+ *
3177
+ * Two versions of one root (a replay, two relays) collapse by NIP-01's rule,
3178
+ * as the relay's own replacement does: later `created_at`, then the lower id.
3179
+ * Objects come back in no particular order; sort them as the consumer draws.
3180
+ *
3181
+ * Linear in the events: the changes are grouped by target once, so a
3182
+ * workspace of hundreds of roots does not rescan thousands of changes per root.
3183
+ */
3184
+ export function projectEvents(
3185
+ events: readonly SignedEvent[],
3186
+ /**
3187
+ * The manifest each root is read through, **per author** — what
3188
+ * {@link resolveManifest} answered for that root's `kind:pubkey`, from the
3189
+ * caller's own resolution (a {@link ProjectionCache} keeps it to one read per
3190
+ * author). Per author, not one for all, because that is the trust anchor
3191
+ * `resolveForeignObject` keeps: an object is drawn by the app *its author*
3192
+ * recommended, and `viaRecommendation` says whether they did. A root this
3193
+ * answers `undefined` for, or whose kind its manifest does not project, is
3194
+ * not an object here.
3195
+ */
3196
+ manifestFor: (pointer: AddressPointer) => ResolvedManifest | undefined,
3197
+ ): ForeignObject[] {
3198
+ const roots = new Map<string, { root: SignedEvent; pointer: AddressPointer; resolved: ResolvedManifest }>()
3199
+ for (const event of events) {
3200
+ const identifier = tagValue(event, 'd')
3201
+ if (identifier === undefined) continue
3202
+ const pointer: AddressPointer = { kind: event.kind, pubkey: event.pubkey, identifier, relays: [] }
3203
+ const resolved = manifestFor(pointer)
3204
+ if (!resolved?.manifest.projections?.[String(event.kind)]) continue
3205
+ const address = `${event.kind}:${event.pubkey}:${identifier}`
3206
+ const held = roots.get(address)?.root
3207
+ if (!held || event.created_at > held.created_at || (event.created_at === held.created_at && event.id < held.id)) {
3208
+ roots.set(address, { root: event, pointer, resolved })
3209
+ }
3210
+ }
3211
+
3212
+ // Each helper still applies its own kind and target test to what it is
3213
+ // handed; grouping by target once only narrows what it has to look at.
3214
+ const grouped = new Map<string, Map<string, SignedEvent[]>>()
3215
+ const byTarget = (targetTag: string) => {
3216
+ let byAddress = grouped.get(targetTag)
3217
+ if (byAddress) return byAddress
3218
+ byAddress = new Map()
3219
+ for (const event of events) {
3220
+ const target = tagValue(event, targetTag)
3221
+ if (target === undefined || !roots.has(target)) continue
3222
+ const list = byAddress.get(target)
3223
+ if (list) list.push(event)
3224
+ else byAddress.set(target, [event])
3225
+ }
3226
+ grouped.set(targetTag, byAddress)
3227
+ return byAddress
3228
+ }
3229
+
3230
+ return [...roots].map(([address, { root, pointer, resolved }]) => {
3231
+ const { manifest } = resolved
3232
+ const archiveRule = archiveRuleOf(manifest)
3233
+ return buildObject({
3234
+ root,
3235
+ pointer,
3236
+ manifest,
3237
+ projection: manifest.projections![String(root.kind)],
3238
+ folded: foldOf(byTarget(foldRuleOf(manifest).targetTag).get(address) ?? [], address, manifest),
3239
+ viaRecommendation: resolved.viaRecommendation,
3240
+ webTemplate: resolved.webTemplate,
3241
+ archived: archiveOf(byTarget(archiveRule.targetTag).get(address) ?? [], address, archiveRule),
3242
+ })
3243
+ })
3244
+ }
3245
+
3246
+ /**
3247
+ * The objects at a set of addresses, as their roots and changes alone draw
3248
+ * them — PEE-21.
3249
+ *
3250
+ * For a reader that needs what a file *is* now (its folded title, status,
3251
+ * parent, own archive) and not what is said about it: {@link projectEvents}
3252
+ * over each address's root and change filters — the same two
3253
+ * {@link resolveForeignObjects} sends — without the comments, children and
3254
+ * people that make up most of that call's bytes. `[` reads a search answer's
3255
+ * hits through this on every pause in typing.
3256
+ *
3257
+ * An address whose root the reader is not handed is simply absent, so a file
3258
+ * in a Folder they cannot read never comes back. A failed read rejects.
3259
+ */
3260
+ export async function resolveForeignRoots(
3261
+ references: readonly string[],
3262
+ query: QueryFn,
3263
+ cache?: ProjectionCache,
3264
+ ): Promise<ForeignObject[]> {
3265
+ const pointers = new Map<string, AddressPointer>()
3266
+ for (const reference of references) {
3267
+ const pointer = addressPointerOf(reference)
3268
+ if (pointer) pointers.set(`${pointer.kind}:${pointer.pubkey}:${pointer.identifier}`, pointer)
3269
+ }
3270
+ if (pointers.size === 0) return []
3271
+
3272
+ const manifests = new Map<string, ResolvedManifest>()
3273
+ const byApp = new Map<string, AddressPointer>()
3274
+ for (const pointer of pointers.values()) byApp.set(manifestKeyOf(pointer), pointer)
3275
+ await Promise.all(
3276
+ [...byApp].map(async ([key, pointer]) => {
3277
+ const resolved = await resolveManifest(pointer, query, cache)
3278
+ if (resolved) manifests.set(key, resolved)
3279
+ }),
3280
+ )
3281
+
3282
+ const filters: Record<string, unknown>[] = []
3283
+ for (const [address, pointer] of pointers) {
3284
+ const resolved = manifests.get(manifestKeyOf(pointer))
3285
+ if (!resolved?.manifest.projections?.[String(pointer.kind)]) continue
3286
+ // A manifest without `records` folds by a placeholder kind 0, never sent.
3287
+ const changeKinds = new Set(
3288
+ [foldRuleOf(resolved.manifest).changeKind, archiveRuleOf(resolved.manifest).changeKind].filter((k) => k !== 0),
3289
+ )
3290
+ filters.push(
3291
+ { kinds: [pointer.kind], authors: [pointer.pubkey], '#d': [pointer.identifier], limit: 1 },
3292
+ { kinds: [...changeKinds], '#a': [address], limit: 500 },
3293
+ )
3294
+ }
3295
+ if (filters.length === 0) return []
3296
+ const events = await queryChunked(filters, query)
3297
+ return projectEvents(events, (pointer) => manifests.get(manifestKeyOf(pointer)))
3298
+ }
3299
+
3149
3300
  /**
3150
3301
  * The parent each file sits under, and nothing else — FOL-50.
3151
3302
  *
@@ -4139,6 +4290,17 @@ function isDone(stage: Stage | undefined, raw: string | undefined, label: string
4139
4290
  return isDoneStatusByLabel(raw, label)
4140
4291
  }
4141
4292
 
4293
+ /**
4294
+ * Is a resolved `status` slot finished work — done or dropped — by its words?
4295
+ *
4296
+ * For a consumer holding only the object, not its manifest: the declared stage
4297
+ * is not on a {@link ResolvedSlot}, so this is the word-list fallback alone.
4298
+ * `[` uses it to put a closed issue after an open one (PEE-21).
4299
+ */
4300
+ export function isClosedStatus(slot: ResolvedSlot | undefined): boolean {
4301
+ return slot !== undefined && isDoneStatusByLabel(slot.value, slot.label)
4302
+ }
4303
+
4142
4304
  function isOpen(stage: Stage | undefined, raw: string | undefined, label: string | undefined) {
4143
4305
  if (stage) return stage === 'open' || stage === 'started'
4144
4306
  return isOpenStatusByLabel(raw, label)
@@ -0,0 +1,154 @@
1
+ /**
2
+ * The files `[` offers, as @estiva-app/conversation ranks them (PEE-21).
3
+ *
4
+ * conversation's `rankReferences` orders candidates and knows nothing of a
5
+ * relay; this is the half that turns what a relay holds into candidates — a
6
+ * resolved object into a row, and typed text into the search tier — so Peek
7
+ * and Ship draw the same rows from the same reads.
8
+ *
9
+ * A row is the type word and the current title; an issue is captioned with its
10
+ * project's title, and nothing names a Folder (Miky, 2026-10-03). Only what the
11
+ * reader resolved is offered: an object the relay did not hand back to them is
12
+ * never a row, so nothing unreadable is offered. An archived file is offered
13
+ * at the lowest priority, and so is an issue in an archived project.
14
+ */
15
+ import {
16
+ FILE_TIER,
17
+ fileReference,
18
+ KIND_CHANGE,
19
+ referenceMatch,
20
+ type ReferenceCandidate,
21
+ type ReferenceType,
22
+ } from '@estiva-app/conversation'
23
+ import {
24
+ isClosedStatus,
25
+ KIND_BARE_FILE,
26
+ resolveForeignRoots,
27
+ type ForeignObject,
28
+ type ProjectionCache,
29
+ type QueryFn,
30
+ } from './projection.js'
31
+
32
+ const KIND_PROJECT = 30850
33
+ const KIND_ISSUE = 30851
34
+
35
+ /** The kinds `[` offers as files, and the type word each draws as. */
36
+ export const REFERENCE_FILE_TYPES: Readonly<Record<number, ReferenceType>> = {
37
+ [KIND_PROJECT]: 'project',
38
+ [KIND_ISSUE]: 'issue',
39
+ [KIND_BARE_FILE]: 'topic',
40
+ }
41
+
42
+ const typeOf = (kind: number): ReferenceType | undefined => REFERENCE_FILE_TYPES[kind]
43
+
44
+ type Addressed = ForeignObject & { address: string }
45
+
46
+ /** An object `[` may offer: a file kind it knows, resolved, with a title. */
47
+ const offerable = (object: ForeignObject | null | undefined): object is Addressed =>
48
+ !!object &&
49
+ !!object.address &&
50
+ !object.unreachable &&
51
+ typeOf(object.kind) !== undefined &&
52
+ !!object.slots.title?.value.trim()
53
+
54
+ export interface FileCandidatesOptions {
55
+ cache?: ProjectionCache
56
+ /** When each address was last written or read, in seconds — newer first within a tier. */
57
+ at?: ReadonlyMap<string, number>
58
+ }
59
+
60
+ /**
61
+ * Rows for resolved files, all in one tier.
62
+ *
63
+ * An issue's caption is its project's title, and an issue in an archived
64
+ * project is archived with it: the project is taken from `objects` when it is
65
+ * among them, and otherwise read in one more batch for every missing project
66
+ * at once (roots and changes only). A project that cannot be read leaves the
67
+ * caption empty rather than dropping the issue. Objects that are not
68
+ * offerable — unreachable, untitled, or of a kind `[` does not offer — are
69
+ * left out.
70
+ */
71
+ export async function fileCandidates(
72
+ objects: readonly (ForeignObject | null | undefined)[],
73
+ tier: number,
74
+ query: QueryFn,
75
+ { cache, at }: FileCandidatesOptions = {},
76
+ ): Promise<ReferenceCandidate[]> {
77
+ const files = objects.filter(offerable)
78
+ const parents = new Map<string, ForeignObject>()
79
+ for (const o of objects) if (o?.address && !o.unreachable) parents.set(o.address, o)
80
+ const missing = [
81
+ ...new Set(files.flatMap((o) => (o.kind === KIND_ISSUE && o.parentRef && !parents.has(o.parentRef) ? [o.parentRef] : []))),
82
+ ]
83
+ if (missing.length) {
84
+ const read = await resolveForeignRoots(missing, query, cache).catch(() => [])
85
+ for (const parent of read) if (parent.address) parents.set(parent.address, parent)
86
+ }
87
+ return files.map((o) => {
88
+ const parent = o.kind === KIND_ISSUE && o.parentRef ? parents.get(o.parentRef) : undefined
89
+ return {
90
+ id: o.address,
91
+ uri: fileReference(o.address),
92
+ type: typeOf(o.kind)!,
93
+ kind: o.kind,
94
+ title: o.slots.title!.value,
95
+ caption: parent?.slots.title?.value ?? '',
96
+ tier,
97
+ ...(isClosedStatus(o.slots.status) ? { closed: true } : {}),
98
+ ...(o.archived || parent?.archived ? { archived: true } : {}),
99
+ ...(at?.has(o.address) ? { at: at.get(o.address) } : {}),
100
+ }
101
+ })
102
+ }
103
+
104
+ export interface SearchFileReferencesOptions extends Omit<FileCandidatesOptions, 'at'> {
105
+ /** How many roots, and separately how many renames, the relay is asked for. Default 32. */
106
+ limit?: number
107
+ }
108
+
109
+ const tagOf = (event: { tags: string[][] }, name: string) => event.tags.find((t) => t[0] === name)?.[1]
110
+
111
+ /**
112
+ * The files whose **current** title holds `text`, as the search tier.
113
+ *
114
+ * The relay indexes a root's `title` and a rename's `value` (relay ticket
115
+ * 6fea004e); neither is the current title on its own — a root keeps the name
116
+ * it was created with, and a rename found by an old word may since have been
117
+ * renamed again. So a hit is only an address: each is read back as its root
118
+ * and changes, folded through its app's manifest, and kept only when what it
119
+ * is called now matches what was typed.
120
+ *
121
+ * Roots and renames are asked for separately, so a burst of renames cannot
122
+ * crowd every root out of the answer, and with buzz's prefix mode, so the word
123
+ * being typed matches before it is finished. A relay that indexes none of these
124
+ * kinds answers nothing, and so does this. A failed read rejects, for
125
+ * `referenceSearch` to answer no hits for a while.
126
+ */
127
+ export async function searchFileReferences(
128
+ text: string,
129
+ query: QueryFn,
130
+ { limit = 32, ...options }: SearchFileReferencesOptions = {},
131
+ ): Promise<ReferenceCandidate[]> {
132
+ const wanted = text.trim()
133
+ if (!wanted) return []
134
+ const asked = { search: wanted, search_mode: 'prefix', limit }
135
+ const hits = await query([
136
+ { kinds: Object.keys(REFERENCE_FILE_TYPES).map(Number), ...asked },
137
+ { kinds: [KIND_CHANGE], ...asked },
138
+ ])
139
+ const at = new Map<string, number>()
140
+ for (const hit of hits) {
141
+ const address =
142
+ hit.kind === KIND_CHANGE
143
+ ? tagOf(hit, 'field') === 'title'
144
+ ? tagOf(hit, 'a')
145
+ : undefined
146
+ : typeOf(hit.kind) && `${hit.kind}:${hit.pubkey}:${tagOf(hit, 'd') ?? ''}`
147
+ if (!address || !typeOf(Number(address.split(':')[0]))) continue
148
+ at.set(address, Math.max(at.get(address) ?? 0, hit.created_at))
149
+ }
150
+ if (at.size === 0) return []
151
+ const objects = await resolveForeignRoots([...at.keys()], query, options.cache)
152
+ const matching = objects.filter((o) => o.slots.title && referenceMatch(o.slots.title.value, wanted) > 0)
153
+ return fileCandidates(matching, FILE_TIER.search, query, { ...options, at })
154
+ }