tickets

27.3 KB

1. // lib/tickets.hl — TICKETS AND THEIR RELATIONS: the central logic of tickets.worldapi.org. Statics only, the server realm.
2. // A face / an API route (components/, lib/api.hl) checks the session or token and calls one function here; every
3. // write answers the rows the push carries.
4. //
5. // CREATOR'S CONVENTIONS (2026-09-24, ticket #38): every primary key is the mpackdb UUID
6. // (`@id`, a string like '0mufbkwhlpjq'), never a `*id` counter; the files live in
7. // storage/mpackdb/. A NUMBER A PERSON SEES is a separate field: tickets are numbered PER
8. // PROJECT from 1 (`number`); tickets migrated from the old global store keep their old
9. // global number as `oldNumber` (docs and comments say "#38"). Order never comes from key
10. // order: lists sort by the stored times, a history by (created, seq).
11. //
12. // ticketsTable pk @id index project state source !path *oldNumber
13. // { project (project @id — NOT the name), number, path ('<project @id>/<number>', unique),
14. // oldNumber?, subject, summary, state, source, created, updated, events,
15. // createdBy (users @id, '' = opened before the login), assignee (users @id, '') }
16. // linksTable pk @id index @ticket @other (ticket #4, mission 017) { kind, ticket, other, user, created }
17. // kind 'parent': `ticket` is a child of `other` (at most one per ticket)
18. // kind 'blockedBy': `ticket` is blocked by `other` (waits on it)
19. // A removed relation is deleted here; the history keeps it ('link' events, lib/events.hl).
20. // Every write appends its event to the history (events.hl putEvent) and stores the ticket with the new
21. // `events` count / `updated`. Projects, members and roles: lib/projects.hl; state names and page shapes:
22. // lib/tickets-helpers.hl.
23. //
24. // WHO MAY is the role in the ticket's project (projects.hl): a refusal for a missing right has
25. // `forbidden = true` (the API answers 403). EVERY WRITE HAS A USER (ticket #7): the logged-in user of the
26. // web session or of the API token (users.hl). `source` is the import key (the ticket file's name) — an
27. // import with a known source is answered with the existing ticket, never a second one.
28. //
29. // reading ticketRowOf, ticketRecord / ticketAt / ticketByRef / ticketByKey, ticketRows, inboxRows,
30. // eventRows, ticketWithEvents, stateChoices, ticketRights
31. // writing createTicket, addComment, changeState, assignTicket, editTicket, removeMember
32. // relations relationsOf, relatedViews, setParent, changeBlocker
33. import { MPackDB } from 'hl:mpackdb'
34. import { now } from 'hl:time'
35. import { storageDir, countOf, first, merged, clean, isDigits, localStamp, newestFirst, oldestFirst, ticketHref, ticketApiHref, projectHrefOf } from './util.hl'
36. import { nameOfUser } from './users.hl'
37. import { projectRecord, projectByAnySlug, projectByRef, projectSlugOf, roleOf, rankOf, isMember, mayEditIn, memberRecord, memberRows, userByRef, assignChoices, userOk, authorMissing, removeMembership } from './projects.hl'
38. import { states, inboxStates, stateOf, slugOf, refOf, keyOf, relationViewOf } from './tickets-helpers.hl'
39. import { putEvent, eventsError, eventRowAt, historyOf, creatorNameOf } from './events.hl'
41. static ticketsTable = new MPackDB(file = storageDir + '/tickets.db', primaryKey = '@id', indexes = ['project', 'state', 'source', '!path', '*oldNumber'])
42. static linksTable = new MPackDB(file = storageDir + '/links.db', primaryKey = '@id', indexes = ['@ticket', '@other'])
44. // ---- the shapes a page and the API show ---------------------------------------------
45. // A ROW IS A PLAIN HYBRID: what the View reads is what the browser receives.
46. // `id` is the UUID; `number` + `project` (the slug) are what a person uses; `oldNumber` / `oldRef`
47. // only on tickets migrated from the global numbering.
48. static ticketRowOf = (t) => {
49. n = t.events != null ? t.events : 0
50. p = projectRecord(t.project)
51. slug = p != null ? p.slug : ''
52. byId = t.createdBy != null ? t.createdBy : ''
53. toId = t.assignee != null ? t.assignee : ''
54. row = {
55. id = t.id
56. project = slug
57. projectId = t.project
58. projectTitle = p != null ? p.title : ''
59. number = t.number
60. ref = '#' + t.number
61. subject = t.subject
62. summary = t.summary
63. state = t.state
64. stateSlug = slugOf(t.state)
65. source = t.source != null ? t.source : ''
66. created = localStamp(t.created)
67. createdMs = t.created
68. updated = localStamp(t.updated)
69. updatedMs = t.updated
70. events = n
71. href = ticketHref(slug, t.number)
72. apiHref = ticketApiHref(slug, t.number)
73. projectHref = projectHrefOf(slug)
74. hasOld = t.oldNumber != null
75. oldRef = t.oldNumber != null ? '#' + t.oldNumber : ''
76. createdById = byId
77. createdBy = byId != '' ? nameOfUser(byId) : creatorNameOf(t)
78. assigneeId = toId
79. assignee = toId != '' ? nameOfUser(toId) : ''
80. hasAssignee = toId != ''
81. }
82. if (t.oldNumber != null) { row.oldNumber = t.oldNumber }
83. // ticket #4 (mission 017): the relations, as refs with their states (relationsOf below)
84. rel = relationsOf(t)
85. row.parent = rel.parent
86. row.children = rel.children
87. row.allChildrenConfirmed = rel.allChildrenConfirmed
88. row.blockedBy = rel.blockedBy
89. row.blocks = rel.blocks
90. return row
91. }
93. // ---- finding a ticket -------------------------------------------------------------------
94. static ticketRecord = (uuid) => { return uuid == null || uuid == '' ? null : ticketsTable.fetch('' + uuid) }
95. // `project` is a slug (a former one too)
96. static ticketAt = (project, number) => {
97. if (project == null || !isDigits(number)) { return null }
98. p = projectByAnySlug(project)
99. if (p == null) { return null }
100. return first(ticketsTable.find('path', p.id + '/' + toNumber('' + number)))
101. }
102. static ticketByOld = (oldNumber) => {
103. if (!isDigits(oldNumber)) { return null }
104. return first(ticketsTable.find('oldNumber', toNumber('' + oldNumber)))
105. }
106. // what `/api/tickets/:ref` and `/tickets/:ref` accept: the OLD global number (digits)
107. // or the ticket's UUID
108. static ticketByRef = (ref) => {
109. if (ref == null) { return null }
110. if (isDigits(ref)) { return ticketByOld(ref) }
111. return ticketRecord(ref)
112. }
114. // ---- reads -------------------------------------------------------------------------
115. // newest update first; both filters optional (null = all); `project` is a slug
116. static ticketRows = (project, state) => {
117. rows = []
118. let all = null
119. if (project != null) {
120. p = projectByAnySlug(project)
121. if (p == null) { return rows }
122. all = ticketsTable.find('project', p.id)
123. } else {
124. all = ticketsTable.find(null, null)
125. }
126. if (countOf(all) == 0) { return rows }
127. for (t of all) {
128. if (state == null || t.state == state) { rows.push(ticketRowOf(t)) }
129. }
130. return newestFirst(rows, 'updatedMs')
131. }
133. // THE INBOX of a user: the tickets ASSIGNED TO THEM in pending and in review, two lists
134. static inboxRows = (user) => {
135. out = { pending = [] review = [] }
136. if (user == null || user.id == null) { return out }
137. a = []
138. b = []
139. ps = ticketsTable.find('state', 'pending')
140. if (countOf(ps) > 0) { for (t of ps) { if (t.assignee == user.id) { a.push(ticketRowOf(t)) } } }
141. rs = ticketsTable.find('state', 'review')
142. if (countOf(rs) > 0) { for (t of rs) { if (t.assignee == user.id) { b.push(ticketRowOf(t)) } } }
143. out.pending = newestFirst(a, 'updatedMs')
144. out.review = newestFirst(b, 'updatedMs')
145. return out
146. }
147. static inboxCountOf = (user) => {
148. x = inboxRows(user)
149. return x.pending.length + x.review.length
150. }
152. // the page's row of `/<project>/<number>` (ticket #25), or null
153. static ticketRowAt = (project, number) => {
154. t = ticketAt(project, number)
155. return t == null ? null : ticketRowOf(t)
156. }
158. // the event history of a ticket (UUID), oldest first (events.hl historyOf)
159. static eventRows = (ticketId) => {
160. t = ticketRecord(ticketId)
161. if (t == null) { return [] }
162. return historyOf(t)
163. }
165. // the options of a state select: [{ value, label }] — the states THIS user may move the ticket to
166. // (a `use` member: only open ⇄ review; `edit` / `admin`: every other state)
167. static stateChoices = (t, user) => {
168. out = []
169. if (t == null || user == null) { return out }
170. role = roleOf(t.project, user)
171. for (s of states) {
172. if (s != t.state && mayMoveTo(role, t.state, s)) { out.push({ value = s label = s }) }
173. }
174. return out
175. }
176. static mayMoveTo = (role, current, target) => {
177. if (rankOf(role) >= 2) { return true }
178. if (rankOf(role) == 1) { return (current == 'open' && target == 'review') || (current == 'review' && target == 'open') }
179. return false
180. }
182. // what a user may do on a ticket (a record): comment (a member), edit / assign (edit, admin), the states they
183. // may move it to, and the members it can be assigned to — the ticket page asks after a login or a change
184. static ticketRights = (t, user) => {
185. return { comment = isMember(t.project, user) edit = mayEdit(t, user) options = stateChoices(t, user) members = assignChoices(t.project) }
186. }
188. // ---- writes: each answers what the push carries --------------------------------------
189. // The author is the user — there is no free author field any more.
191. // the next per-project number: the highest one in the project + 1 (first = 1)
192. static nextNumber = (projectId) => {
193. let top = 0
194. all = ticketsTable.find('project', projectId)
195. if (countOf(all) > 0) {
196. for (t of all) { if (t.number != null && t.number > top) { top = t.number } }
197. }
198. return top + 1
199. }
201. // answers { error, field, forbidden? } or { ticket (row), event (row), existed }
202. // `project` = the slug (or id) of an existing project; `assignee` optional (a member's name / id)
203. static createTicket = (project, subject, summary, user, source, assignee) => {
204. s = clean(subject)
205. if (clean(project) == '') { return { error = 'project is required' field = 'project' } }
206. if (s == '') { return { error = 'subject is required' field = 'subject' } }
207. if (!userOk(user)) { return authorMissing }
208. p = projectByRef(clean(project))
209. if (p == null) { return { error = 'no such project: ' + clean(project) field = 'project' } }
210. if (!mayEditIn(p.id, user)) { return { error = 'you need the role edit or admin in ' + p.slug + ' to open a ticket' field = 'project' forbidden = true } }
211. let who = ''
212. if (assignee != null && clean(assignee) != '') {
213. r = userByRef(assignee, p.id)
214. if (r.error != null) { return { error = r.error field = 'assignee' } }
215. who = r.user.id
216. }
217. src = clean(source)
218. if (src != '') {
219. known = ticketsTable.find('source', src)
220. if (countOf(known) > 0) { return { ticket = ticketRowOf(known[0]) event = null existed = true } }
221. }
222. t0 = now()
223. n = nextNumber(p.id)
224. id = ticketsTable.put({ project = p.id number = n path = p.id + '/' + n subject = s summary = clean(summary) state = 'open' source = src created = t0 updated = t0 events = 1 createdBy = user.id assignee = who })
225. if (id == null) { return { error = 'could not store the ticket: ' + ticketsTable.lastError() field = '' } }
226. t = ticketsTable.fetch(id)
227. eid = putEvent({ ticket = id seq = 1 kind = 'created' author = user.name user = user.id text = src != '' ? 'imported from ' + src : '' created = t0 })
228. out = { ticket = ticketRowOf(t) event = eventRowAt(eid, t) existed = false }
229. if (who != '') {
230. let seq = 2
231. aid = putEvent({ ticket = id seq = seq kind = 'assign' author = user.name user = user.id text = '' assignee = who previous = '' created = t0 })
232. ticketsTable.update(id, merged(t, { events = seq }))
233. t2 = ticketsTable.fetch(id)
234. out.ticket = ticketRowOf(t2)
235. out.assignEvent = eventRowAt(aid, t2)
236. }
237. return out
238. }
240. // answers { error } or { ticket, event }; `ticketId` is the UUID. Any member may comment.
241. static addComment = (ticketId, user, text) => {
242. t = ticketRecord(ticketId)
243. if (t == null) { return { error = 'no such ticket' } }
244. body = clean(text)
245. if (body == '') { return { error = 'a comment needs text' field = 'text' } }
246. if (!userOk(user)) { return authorMissing }
247. if (!isMember(t.project, user)) { return { error = 'only a member of the project can comment' field = '' forbidden = true } }
248. t0 = now()
249. let seq = (t.events != null ? t.events : 0) + 1
250. eid = putEvent({ ticket = t.id seq = seq kind = 'comment' author = user.name user = user.id text = body created = t0 })
251. ticketsTable.update(t.id, merged(t, { updated = t0 events = seq }))
252. t2 = ticketsTable.fetch(t.id)
253. return { ticket = ticketRowOf(t2) event = eventRowAt(eid, t2) }
254. }
256. // the admin who gets a ticket that lands in the inbox with nobody assigned: the oldest admin
257. static defaultAssignee = (projectId) => {
258. for (m of memberRows(projectId)) { if (m.role == 'admin') { return m.user } }
259. return ''
260. }
262. // answers { error } or { ticket, event, assignEvent? }; an optional note rides on the state event.
263. // `forbidden = true` on a refusal the user may not overcome (the role does not allow that move).
264. // A ticket that goes to review / pending with nobody assigned is assigned to the project's first admin
265. // (so it reaches an inbox) — a second, 'assign' event.
266. static changeState = (ticketId, state, user, note) => {
267. t = ticketRecord(ticketId)
268. if (t == null) { return { error = 'no such ticket' } }
269. s = stateOf(state)
270. if (s == null) { return { error = 'unknown state — one of: ' + states.join(', ') field = 'state' } }
271. if (s == t.state) { return { error = 'the ticket is already ' + s field = 'state' } }
272. if (!userOk(user)) { return authorMissing }
273. role = roleOf(t.project, user)
274. if (role == null) { return { error = 'only a member of the project can change the state' field = 'state' forbidden = true } }
275. if (!mayMoveTo(role, t.state, s)) { return { error = 'the role ' + role + ' can only move a ticket between open and review' field = 'state' forbidden = true } }
276. t0 = now()
277. let seq = (t.events != null ? t.events : 0) + 1
278. eid = putEvent({ ticket = t.id seq = seq kind = 'state' author = user.name user = user.id text = clean(note) from = t.state to = s created = t0 })
279. changes = { state = s updated = t0 events = seq }
280. let aid = null
281. let auto = ''
282. if (inboxStates.includes(s) && (t.assignee == null || t.assignee == '')) { auto = defaultAssignee(t.project) }
283. if (auto != '') {
284. seq = seq + 1
285. aid = putEvent({ ticket = t.id seq = seq kind = 'assign' author = user.name user = user.id text = '' assignee = auto previous = '' created = t0 })
286. changes.assignee = auto
287. changes.events = seq
288. }
289. ticketsTable.update(t.id, merged(t, changes))
290. t2 = ticketsTable.fetch(t.id)
291. out = { ticket = ticketRowOf(t2) event = eventRowAt(eid, t2) }
292. if (aid != null) { out.assignEvent = eventRowAt(aid, t2) }
293. return out
294. }
296. // answers { error, forbidden? } or { ticket, event }; `assignee` = a member's users @id, '' = nobody
297. static assignTicket = (ticketId, user, assignee) => {
298. t = ticketRecord(ticketId)
299. if (t == null) { return { error = 'no such ticket' } }
300. if (!userOk(user)) { return authorMissing }
301. if (!mayEditIn(t.project, user)) { return { error = 'you need the role edit or admin to assign a ticket' field = 'assignee' forbidden = true } }
302. who = assignee == null ? '' : clean(assignee)
303. if (who != '' && memberRecord(t.project, who) == null) { return { error = 'the assignee must be a member of the project' field = 'assignee' } }
304. was = t.assignee != null ? t.assignee : ''
305. if (who == was) { return { error = who == '' ? 'the ticket is not assigned' : 'the ticket is already assigned to that person' field = 'assignee' } }
306. t0 = now()
307. let seq = (t.events != null ? t.events : 0) + 1
308. eid = putEvent({ ticket = t.id seq = seq kind = 'assign' author = user.name user = user.id text = '' assignee = who previous = was created = t0 })
309. ticketsTable.update(t.id, merged(t, { assignee = who updated = t0 events = seq }))
310. t2 = ticketsTable.fetch(t.id)
311. return { ticket = ticketRowOf(t2) event = eventRowAt(eid, t2) }
312. }
314. // ---- editing (ticket #8, mission 014; ticket #20: by the role) --------------------------------
315. // THE AUTHOR of a ticket is `createdBy` (users @id), or null for a ticket opened before the login
316. // existed. MAY THIS USER EDIT the ticket (a record)? Any member with the role edit or admin of
317. // its project (`use` members only comment and move it between open and review).
318. static mayEdit = (t, user) => {
319. if (t == null || !userOk(user)) { return false }
320. return mayEditIn(t.project, user)
321. }
322. static mayEditId = (ticketId, user) => { return mayEdit(ticketRecord(ticketId), user) }
324. // answers { error, field?, forbidden? } or { ticket, event }. `subject` / `summary` null = keep
325. // that one. The previous values stay in the 'edit' event (append-only history).
326. static editTicket = (ticketId, user, subject, summary) => {
327. t = ticketRecord(ticketId)
328. if (t == null) { return { error = 'no such ticket' } }
329. if (!userOk(user)) { return authorMissing }
330. if (!mayEdit(t, user)) { return { error = 'you need the role edit or admin in the project to edit a ticket' field = '' forbidden = true } }
331. if (subject == null && summary == null) { return { error = 'nothing to change: give subject and/or summary' field = '' } }
332. let oldSummary = t.summary != null ? t.summary : ''
333. s = subject != null ? clean(subject) : t.subject
334. if (s == '') { return { error = 'subject is required' field = 'subject' } }
335. sm = summary != null ? clean(summary) : oldSummary
336. if (s == t.subject && sm == oldSummary) { return { error = 'nothing changed' field = subject != null ? 'subject' : 'summary' } }
337. t0 = now()
338. let seq = (t.events != null ? t.events : 0) + 1
339. eid = putEvent({ ticket = t.id seq = seq kind = 'edit' author = user.name user = user.id text = '' oldSubject = t.subject oldSummary = oldSummary subject = s summary = sm created = t0 })
340. if (eid == null) { return { error = 'could not store the edit: ' + eventsError() field = '' } }
341. ticketsTable.update(t.id, merged(t, { subject = s summary = sm updated = t0 events = seq }))
342. t2 = ticketsTable.fetch(t.id)
343. return { ticket = ticketRowOf(t2) event = eventRowAt(eid, t2) }
344. }
346. // an admin removes a member (projects.hl removeMembership); the tickets assigned to the person are no longer
347. // assigned to anybody. Answers { members } or { error, forbidden? }
348. static removeMember = (projectId, actor, userId) => {
349. r = removeMembership(projectId, actor, userId)
350. if (r.error != null) { return r }
351. all = ticketsTable.find('project', projectId)
352. if (countOf(all) > 0) {
353. for (t of all) {
354. if (t.assignee == userId) { ticketsTable.update(t.id, merged(t, { assignee = '' })) }
355. }
356. }
357. return r
358. }
360. // the API's view of one ticket (a record): the row and its whole history
361. static ticketWithEvents = (t) => {
362. if (t == null) { return null }
363. return { ticket = ticketRowOf(t) events = eventRows(t.id) }
364. }
366. // ---- relations: parent / child and blocked-by (ticket #4, mission 017) ----------------------
367. // A ticket has at most ONE PARENT (any project); a parent lists its CHILDREN with their states.
368. // A ticket can be BLOCKED BY other tickets (any project) — it waits on them; the other side
369. // shows what it BLOCKS. The scheduler reads them from the JSON rows (`parent`, `children`,
370. // `blockedBy`, `blocks`, each a ref with the state) and the Markdown view.
371. // PARENT STATE: `allChildrenConfirmed` (the key kept for the clients; it now means DONE) is true when
372. // a ticket has children and every one of them is `done`. It is only SHOWN ("all children done") — the
373. // parent's own state is never changed by it.
374. // WHO MAY set / remove a relation (ticket #20): a member with the role edit or admin in the project of
375. // EITHER of the two tickets. Replacing a parent needs the
376. // right for the old pair AND the new pair. No loops: a ticket cannot be its own ancestor, and
377. // cannot (transitively) wait on itself.
378. // Tickets are named as `<project>#<number>` (spaces around `#` allowed) or by their UUID.
380. // the link records of one side, oldest first (stored time): field 'ticket' = this ticket's own
381. // relations (its parent, its blockers), field 'other' = the ones pointing at it (children, blocked)
382. static linkRecords = (field, ticketId, kind) => {
383. out = []
384. if (ticketId == null || ticketId == '') { return out }
385. all = linksTable.find(field, '' + ticketId)
386. if (countOf(all) == 0) { return out }
387. for (l of all) { if (l.kind == kind) { out.push(l) } }
388. return oldestFirst(out, 'created')
389. }
390. static parentLinkOf = (ticketId) => { return first(linkRecords('ticket', ticketId, 'parent')) }
391. static parentIdOf = (ticketId) => {
392. l = parentLinkOf(ticketId)
393. return l == null ? null : l.other
394. }
395. static idsOfLinks = (links, field) => {
396. out = []
397. for (l of links) { out.push(l[field]) }
398. return out
399. }
400. static childIdsOf = (ticketId) => { return idsOfLinks(linkRecords('other', ticketId, 'parent'), 'ticket') }
401. static blockerIdsOf = (ticketId) => { return idsOfLinks(linkRecords('ticket', ticketId, 'blockedBy'), 'other') }
402. static blockedIdsOf = (ticketId) => { return idsOfLinks(linkRecords('other', ticketId, 'blockedBy'), 'ticket') }
403. static refsOfIds = (ids) => {
404. out = []
405. for (i of ids) {
406. let t = ticketRecord(i)
407. if (t != null) { out.push(refOf(t)) }
408. }
409. return out
410. }
412. // { parent (ref or null), children, blockedBy, blocks (lists of refs), allChildrenConfirmed }
413. static relationsOf = (t) => {
414. pid = parentIdOf(t.id)
415. p = pid != null ? ticketRecord(pid) : null
416. kids = refsOfIds(childIdsOf(t.id))
417. let all = kids.length > 0
418. for (c of kids) { if (c.state != 'done') { all = false } }
419. return { parent = p != null ? refOf(p) : null children = kids allChildrenConfirmed = all blockedBy = refsOfIds(blockerIdsOf(t.id)) blocks = refsOfIds(blockedIdsOf(t.id)) }
420. }
422. // the relation views of a ticket AND every ticket related to it (+ `extra` ids: a parent or
423. // blocker just removed) — what a write pushes, so every open page of them follows
424. static relatedViews = (ticketId, extra) => {
425. ids = ['' + ticketId]
426. seen = {}
427. seen['' + ticketId] = true
428. more = []
429. pid = parentIdOf(ticketId)
430. if (pid != null) { more.push(pid) }
431. for (i of childIdsOf(ticketId)) { more.push(i) }
432. for (i of blockerIdsOf(ticketId)) { more.push(i) }
433. for (i of blockedIdsOf(ticketId)) { more.push(i) }
434. for (i of extra) { if (i != null) { more.push(i) } }
435. for (i of more) {
436. if (seen['' + i] != true) {
437. seen['' + i] = true
438. ids.push('' + i)
439. }
440. }
441. out = []
442. for (i of ids) {
443. let t = ticketRecord(i)
444. if (t != null) { out.push(relationViewOf(ticketRowOf(t))) }
445. }
446. return out
447. }
449. // `<project>#<number>` (spaces around '#' allowed) or a UUID → the ticket record, or null
450. static ticketByKey = (key) => {
451. k = clean(key)
452. if (k == '') { return null }
453. at = k.indexOf('#')
454. if (at < 0) { return isDigits(k) ? null : ticketRecord(k) }
455. p = k.slice(0, at).trim()
456. n = k.slice(at + 1).trim()
457. if (p == '') { return null }
458. return ticketAt(p, n)
459. }
461. static mayLink = (a, b, user) => {
462. if (!userOk(user)) { return false }
463. if (a != null && mayEditIn(a.project, user)) { return true }
464. if (b != null && mayEditIn(b.project, user)) { return true }
465. return false
466. }
467. static linkForbidden = { error = 'you need the role edit or admin in the project of either ticket to change this relation' field = '' forbidden = true }
469. // the history event of a relation change, on ticket `t`; answers { ticket, event, related }
470. static linkEvent = (t, user, linkKind, action, other, previous, extra) => {
471. t0 = now()
472. let seq = (t.events != null ? t.events : 0) + 1
473. // the values BEFORE the literal: an entry named `other` / `user` would shadow the variable
474. // for the entries after it (mission 011 lesson)
475. uname = user.name
476. uid = user.id
477. oid = other.id
478. oproject = projectSlugOf(other)
479. onumber = other.number
480. rec = { ticket = t.id seq = seq kind = 'link' author = uname user = uid text = '' linkKind = linkKind action = action other = oid otherProject = oproject otherNumber = onumber created = t0 }
481. if (previous != null) {
482. rec.previous = previous.id
483. rec.previousProject = projectSlugOf(previous)
484. rec.previousNumber = previous.number
485. }
486. eid = putEvent(rec)
487. if (eid == null) { return { error = 'could not store the event: ' + eventsError() field = '' } }
488. ticketsTable.update(t.id, merged(t, { updated = t0 events = seq }))
489. t2 = ticketsTable.fetch(t.id)
490. return { ticket = ticketRowOf(t2) event = eventRowAt(eid, t2) related = relatedViews(t.id, extra) }
491. }
493. // SET (key = `<project>#<n>` / UUID) or REMOVE (key = '') the parent of a ticket (UUID).
494. // Answers { error, field, forbidden? } or { ticket, event, related }.
495. static setParent = (ticketId, user, key) => {
496. t = ticketRecord(ticketId)
497. if (t == null) { return { error = 'no such ticket' } }
498. if (!userOk(user)) { return authorMissing }
499. k = clean(key)
500. cur = parentLinkOf(t.id)
501. curT = cur != null ? ticketRecord(cur.other) : null
502. if (k == '') {
503. if (cur == null || curT == null) { return { error = 'the ticket has no parent' field = 'parent' } }
504. if (!mayLink(t, curT, user)) { return linkForbidden }
505. linksTable.delete(cur.id)
506. return linkEvent(t, user, 'parent', 'removed', curT, null, [curT.id])
507. }
508. p = ticketByKey(k)
509. if (p == null) { return { error = 'no such ticket: ' + k + ' (name it as <project>#<number>)' field = 'parent' } }
510. if (p.id == t.id) { return { error = 'a ticket cannot be its own parent' field = 'parent' } }
511. if (curT != null && curT.id == p.id) { return { error = 'the parent is already ' + keyOf(p) field = 'parent' } }
512. // no loop: the new parent must not be this ticket's child, grandchild, …
513. let up = p.id
514. let steps = 0
515. while (up != null && steps < 1000) {
516. if (up == t.id) { return { error = 'a loop: ' + keyOf(p) + ' is below this ticket' field = 'parent' } }
517. up = parentIdOf(up)
518. steps = steps + 1
519. }
520. if (!mayLink(t, p, user)) { return linkForbidden }
521. if (curT != null && !mayLink(t, curT, user)) { return linkForbidden }
522. lid = linksTable.put({ kind = 'parent' ticket = t.id other = p.id user = user.id created = now() })
523. if (lid == null) { return { error = 'could not store the relation: ' + linksTable.lastError() field = '' } }
524. if (cur != null) { linksTable.delete(cur.id) }
525. return linkEvent(t, user, 'parent', 'set', p, curT, [curT != null ? curT.id : null])
526. }
528. // does ticket `start` (transitively) wait on ticket `target`? (blocked-by links)
529. static waitsOn = (start, target) => {
530. stack = [start]
531. seen = {}
532. let steps = 0
533. while (stack.length > 0 && steps < 10000) {
534. let cur = stack.pop()
535. steps = steps + 1
536. if (cur == target) { return true }
537. if (seen['' + cur] != true) {
538. seen['' + cur] = true
539. for (i of blockerIdsOf(cur)) { stack.push(i) }
540. }
541. }
542. return false
543. }
545. // ADD (adding = true) or REMOVE a blocker of a ticket (UUID): ticket `key` blocks it.
546. // `field` names the API field ('add' / 'remove'). Answers as setParent.
547. static changeBlocker = (ticketId, user, key, adding, field) => {
548. t = ticketRecord(ticketId)
549. if (t == null) { return { error = 'no such ticket' } }
550. if (!userOk(user)) { return authorMissing }
551. k = clean(key)
552. if (k == '') { return { error = 'name the blocking ticket as <project>#<number>' field = field } }
553. o = ticketByKey(k)
554. if (o == null) { return { error = 'no such ticket: ' + k + ' (name it as <project>#<number>)' field = field } }
555. let existing = null
556. for (l of linkRecords('ticket', t.id, 'blockedBy')) { if (l.other == o.id) { existing = l } }
557. if (adding) {
558. if (o.id == t.id) { return { error = 'a ticket cannot block itself' field = field } }
559. if (existing != null) { return { error = 'already blocked by ' + keyOf(o) field = field } }
560. if (waitsOn(o.id, t.id)) { return { error = 'a loop: ' + keyOf(o) + ' already waits on this ticket' field = field } }
561. if (!mayLink(t, o, user)) { return linkForbidden }
562. lid = linksTable.put({ kind = 'blockedBy' ticket = t.id other = o.id user = user.id created = now() })
563. if (lid == null) { return { error = 'could not store the relation: ' + linksTable.lastError() field = '' } }
564. return linkEvent(t, user, 'blockedBy', 'set', o, null, [])
565. }
566. if (existing == null) { return { error = 'not blocked by ' + keyOf(o) field = field } }
567. if (!mayLink(t, o, user)) { return linkForbidden }
568. linksTable.delete(existing.id)
569. return linkEvent(t, user, 'blockedBy', 'removed', o, null, [o.id])
570. }