tickets

50.5 KB

1. // store.hl — THE SERVER REALM of tickets.worldapi.org. Five hl:mpackdb tables and
2. // the functions that read and write them; statics only (a component member imports
3. // what it reads by brace, a face / an API route what it writes).
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. // PROJECTS ARE OWN DATA (ticket #20, 2026-09-26):
13. // projectsTable pk @id index !slug { title, slug, description (Markdown), oldSlugs ('a,b' — the
14. // slugs it had before; they still resolve), created }
15. // membersTable pk @id index project user { project (project @id), user (users @id), role, created }
16. // role = 'use' | 'edit' | 'admin' (below). One row per (project, user).
17. // ticketsTable pk @id index project state source !path *oldNumber
18. // { project (project @id — NOT the name), number, path ('<project @id>/<number>', unique),
19. // oldNumber?, subject, summary, state, source, created, updated, events,
20. // createdBy (users @id, '' = opened before the login), assignee (users @id, '') }
21. // eventsTable pk @id index @ticket APPEND ONLY: { ticket (ticket @id), seq
22. // (1, 2, … per ticket), kind, author, user?, text, from, to, created, oldId? }
23. // kind = 'created' | 'comment' | 'state' | 'edit' | 'link' | 'assign'
24. // 'assign' (ticket #20): { assignee (users @id, '' = unassigned), previous (users @id, '') }
25. // 'link' (ticket #4, mission 017): { linkKind ('parent' | 'blockedBy'), action
26. // ('set' | 'removed'), other, otherProject, otherNumber, previous?, previousProject?,
27. // previousNumber? } — on the CHILD / the BLOCKED ticket (the one whose relation changed).
28. // 'edit' (ticket #8, mission 014): { oldSubject, oldSummary, subject, summary } —
29. // the values before AND after; the ticket record then carries the new ones.
30. // `user` (users @id, users.hl) since ticket #7: the event's author is that
31. // user's CURRENT display name; `author` keeps the name at writing time.
32. // linksTable pk @id index @ticket @other (ticket #4, mission 017) { kind, ticket, other, user, created }
33. // kind 'parent': `ticket` is a child of `other` (at most one per ticket)
34. // kind 'blockedBy': `ticket` is blocked by `other` (waits on it)
35. // A removed relation is deleted here; the history keeps it ('link' events).
36. //
37. // THE THREE ROLES (a member of a project; anybody else only reads):
38. // use = comment, and move a ticket between open and review
39. // edit = use + create, edit, assign, any state, relations
40. // admin = edit + the project's settings and its members
41. // THE PROJECT SLUG (the URL part) is generated from the title and only holds letters,
42. // digits, '.', '_' and '-' (URL-safe); an admin can change it, the old one keeps resolving.
43. //
44. // Nothing here knows who is looking except where a function takes a `user`; a write answers
45. // the rows the push carries. `source` is the import key (the ticket file's name) — an import
46. // with a known source is answered with the existing ticket, never a second one.
47. import { MPackDB } from 'hl:mpackdb'
48. import { env } from 'hl:proc'
49. import { now } from 'hl:time'
50. import { localStamp } from './localtime.hl'
51. import { nameOfUser, userRecord, usersTable, ensureUser, ensureCreatorUser, countOfList } from './users.hl'
52. import { markdownBlocks } from './markdown.hl'
54. // TICKETS_STORAGE names another table DIRECTORY (the gate runs on its own). Relative
55. // paths resolve against the ENTRY SCRIPT's directory — tools must pass an absolute one.
56. static dir = env('TICKETS_STORAGE') != null ? env('TICKETS_STORAGE') : './storage/mpackdb'
57. static projectsTable = new MPackDB(file = dir + '/projects.db', primaryKey = '@id', indexes = ['!slug'])
58. static membersTable = new MPackDB(file = dir + '/members.db', primaryKey = '@id', indexes = ['project', 'user'])
59. static ticketsTable = new MPackDB(file = dir + '/tickets.db', primaryKey = '@id', indexes = ['project', 'state', 'source', '!path', '*oldNumber'])
60. static eventsTable = new MPackDB(file = dir + '/events.db', primaryKey = '@id', indexes = ['@ticket'])
61. static linksTable = new MPackDB(file = dir + '/links.db', primaryKey = '@id', indexes = ['@ticket', '@other'])
63. // THE STATES, in the order a ticket usually walks them; the state's name is also its URL form.
64. // The OLD names are still accepted (the scheduler and the tools use them): stateOf() maps them.
65. static states = ['open' 'progress' 'pending' 'review' 'reopened' 'done' 'canceled']
66. static stateAliases = { 'in progress' = 'progress' 'awaiting creator' = 'review' 'confirmed' = 'done' 'rejected' = 'reopened' 'on hold' = 'pending' }
67. static roles = ['use' 'edit' 'admin']
68. static rankOf = (role) => { return role == 'admin' ? 3 : (role == 'edit' ? 2 : (role == 'use' ? 1 : 0)) }
70. // an empty list written to hl:mpackdb comes back as an empty hybrid (`.length` null):
71. // every read of a found list goes through here
72. static countOf = (list) => { return countOfList(list) }
74. // the state a name stands for (a new name, an old one, or its URL form with '-' / '+'), or null
75. static stateOf = (name) => {
76. if (name == null || hlTypeName(name) != 'String') { return null }
77. let s = name.replaceAll('-', ' ').replaceAll('+', ' ').trim().toLowerCase()
78. if (states.includes(s)) { return s }
79. let a = stateAliases[s]
80. return a != null ? a : null
81. }
82. static slugOf = (state) => { return state == null ? '' : state.replaceAll(' ', '-') }
83. static stateOfSlug = (slug) => { return stateOf(slug) }
84. static validState = (s) => { return stateOf(s) != null }
85. // the states a person moves a ticket to: the inbox ones
86. static inboxStates = ['pending' 'review']
88. // a string of ASCII digits only (a ticket number in a URL); '' is not
89. static isDigits = (s) => {
90. if (s == null) { return false }
91. let t = '' + s
92. if (t.length == 0 || t.length > 12) { return false }
93. let i = 0
94. while (i < t.length) {
95. let c = t.charCodeAt(i)
96. if (c < 48 || c > 57) { return false }
97. i = i + 1
98. }
99. return true
100. }
102. // a project slug that a URL carries as is: letters, digits, . _ -
103. static isSlugChar = (c) => {
104. return (c >= 48 && c <= 57) || (c >= 65 && c <= 90) || (c >= 97 && c <= 122) || c == 46 || c == 95 || c == 45
105. }
106. static validProjectName = (p) => {
107. if (p == null || hlTypeName(p) != 'String' || p.length == 0 || p.length > 100) { return false }
108. let i = 0
109. while (i < p.length) {
110. if (!isSlugChar(p.charCodeAt(i))) { return false }
111. i = i + 1
112. }
113. return true
114. }
116. // what a person reads: Europe/Vienna wall time (storage stays epoch ms, UTC)
117. static stamp = (ms) => { return localStamp(ms) }
119. // every record is written as a whole (hl:mpackdb's update replaces it)
120. static merged = (rec, changes) => {
121. let out = {}
122. for (k of rec.keys()) { out[k] = rec[k] }
123. for (k of changes.keys()) { out[k] = changes[k] }
124. return out
125. }
127. static clean = (s) => { return s == null ? '' : ('' + s).trim() }
129. static first = (list) => { return countOf(list) > 0 ? list[0] : null }
131. // ---- the URLs ---------------------------------------------------------------------------
132. static ticketHref = (project, number) => { return '/projects/' + project + '/' + number }
133. static ticketApiHref = (project, number) => { return '/api/projects/' + project + '/tickets/' + number }
134. static projectHrefOf = (project) => { return '/projects/' + project }
135. static settingsHrefOf = (project) => { return '/projects/' + project + '/settings' }
137. // ---- projects ------------------------------------------------------------------------------
138. static projectRecord = (id) => { return id == null || id == '' || hlTypeName(id) != 'String' ? null : projectsTable.fetch(id) }
139. static projectBySlug = (slug) => { return slug == null || hlTypeName(slug) != 'String' ? null : first(projectsTable.find('slug', slug)) }
141. // projects in the order they were created (stored time, not key order)
142. static projectRecords = () => {
143. let all = projectsTable.find(null, null)
144. let ps = []
145. if (countOf(all) == 0) { return ps }
146. for (p of all) { ps.push(p) }
147. let i = 1
148. while (i < ps.length) {
149. let cur = ps[i]
150. let j = i - 1
151. while (j >= 0 && ps[j].created > cur.created) {
152. ps[j + 1] = ps[j]
153. j = j - 1
154. }
155. ps[j + 1] = cur
156. i = i + 1
157. }
158. return ps
159. }
161. static oldSlugsOf = (p) => {
162. let out = []
163. if (p.oldSlugs == null || p.oldSlugs == '') { return out }
164. for (s of p.oldSlugs.split(',')) { if (s != '') { out.push(s) } }
165. return out
166. }
168. // a project by its CURRENT slug, or by a slug it once had (old links keep working)
169. static projectByAnySlug = (slug) => {
170. let p = projectBySlug(slug)
171. if (p != null) { return p }
172. if (slug == null || hlTypeName(slug) != 'String' || slug == '') { return null }
173. for (q of projectRecords()) { if (oldSlugsOf(q).includes(slug)) { return q } }
174. return null
175. }
177. // what the API takes for a project: its slug (also an old one) or its id
178. static projectByRef = (ref) => {
179. if (ref == null || hlTypeName(ref) != 'String' || ref == '') { return null }
180. let p = projectByAnySlug(ref)
181. return p != null ? p : projectRecord(ref)
182. }
184. static projectNames = () => {
185. let out = []
186. for (p of projectRecords()) { out.push(p.slug) }
187. return out
188. }
189. static projectExists = (slug) => { return projectByAnySlug(slug) != null }
191. static projectRowOf = (p) => {
192. return { id = p.id title = p.title slug = p.slug description = p.description != null ? p.description : '' href = projectHrefOf(p.slug) settingsHref = settingsHrefOf(p.slug) created = stamp(p.created) createdMs = p.created }
193. }
195. // the slug a title proposes: lower case letters and digits, other runs become one '-'
196. static slugFromTitle = (title) => {
197. let t = clean(title).toLowerCase()
198. let out = ''
199. let i = 0
200. while (i < t.length && out.length < 60) {
201. let c = t.charCodeAt(i)
202. if ((c >= 48 && c <= 57) || (c >= 97 && c <= 122)) { out = out + t[i] } else if (out != '' && !out.endsWith('-')) { out = out + '-' }
203. i = i + 1
204. }
205. while (out.endsWith('-')) { out = out.slice(0, out.length - 1) }
206. return out == '' ? 'project' : out
207. }
208. // is this slug free? (`except` = the project that may keep it)
209. static slugFree = (slug, except) => {
210. for (q of projectRecords()) {
211. if (except == null || q.id != except) {
212. if (q.slug == slug || oldSlugsOf(q).includes(slug)) { return false }
213. }
214. }
215. return true
216. }
217. static uniqueSlug = (base) => {
218. if (slugFree(base, null)) { return base }
219. let n = 2
220. while (!slugFree(base + '-' + n, null) && n < 10000) { n = n + 1 }
221. return base + '-' + n
222. }
224. // ---- members and roles ------------------------------------------------------------------------
225. static memberRecord = (projectId, userId) => {
226. if (projectId == null || userId == null || userId == '') { return null }
227. let all = membersTable.find('project', projectId)
228. if (countOf(all) == 0) { return null }
229. for (m of all) { if (m.user == userId) { return m } }
230. return null
231. }
232. // the role of a user in a project ('use' | 'edit' | 'admin'), or null
233. static roleOf = (projectId, user) => {
234. if (user == null || user.id == null) { return null }
235. let m = memberRecord(projectId, user.id)
236. return m == null ? null : m.role
237. }
238. static atLeast = (projectId, user, role) => { return rankOf(roleOf(projectId, user)) >= rankOf(role) }
239. static isMember = (projectId, user) => { return roleOf(projectId, user) != null }
240. static mayEditIn = (projectId, user) => { return atLeast(projectId, user, 'edit') }
241. static isAdminOf = (projectId, user) => { return atLeast(projectId, user, 'admin') }
243. // the member rows of a project: [{ id, user (users @id), name, role, rank, created }], the oldest first
244. static memberRows = (projectId) => {
245. let out = []
246. let all = membersTable.find('project', projectId)
247. if (countOf(all) == 0) { return out }
248. for (m of all) { out.push({ id = m.id user = m.user name = nameOfUser(m.user) role = m.role rank = rankOf(m.role) created = m.created }) }
249. let i = 1
250. while (i < out.length) {
251. let cur = out[i]
252. let j = i - 1
253. while (j >= 0 && out[j].created > cur.created) {
254. out[j + 1] = out[j]
255. j = j - 1
256. }
257. out[j + 1] = cur
258. i = i + 1
259. }
260. return out
261. }
263. // makes `userId` a member with `role` (no permission check: the caller decided); an existing
264. // member keeps the HIGHER of the two roles. Answers the member record.
265. static addMember = (projectId, userId, role) => {
266. let m = memberRecord(projectId, userId)
267. if (m != null) {
268. if (rankOf(role) > rankOf(m.role)) { membersTable.update(m.id, merged(m, { role = role })) }
269. return membersTable.fetch(m.id)
270. }
271. let id = membersTable.put({ project = projectId user = userId role = role created = now() })
272. return id == null ? null : membersTable.fetch(id)
273. }
275. static adminCount = (projectId) => {
276. let n = 0
277. for (m of memberRows(projectId)) { if (m.role == 'admin') { n = n + 1 } }
278. return n
279. }
280. static notAdmin = { error = 'only an admin of the project can do that' field = '' forbidden = true }
282. // an admin sets a member's role, or adds a person by the ident id / display name of a user that
283. // has logged in here. `who` = { user (users @id) }. Answers { members } or { error, forbidden? }
284. static setMemberRole = (projectId, actor, userId, role) => {
285. let p = projectRecord(projectId)
286. if (p == null) { return { error = 'no such project' } }
287. if (!isAdminOf(p.id, actor)) { return notAdmin }
288. if (!roles.includes(role)) { return { error = 'role must be one of: ' + roles.join(', ') field = 'role' } }
289. if (userRecord(userId) == null) { return { error = 'no such user' field = 'user' } }
290. let m = memberRecord(p.id, userId)
291. if (m != null && m.role == 'admin' && role != 'admin' && adminCount(p.id) < 2) { return { error = 'a project needs at least one admin' field = 'role' } }
292. if (m == null) { addMember(p.id, userId, role) } else { membersTable.update(m.id, merged(m, { role = role })) }
293. return { members = memberRows(p.id) }
294. }
295. static removeMember = (projectId, actor, userId) => {
296. let p = projectRecord(projectId)
297. if (p == null) { return { error = 'no such project' } }
298. if (!isAdminOf(p.id, actor)) { return notAdmin }
299. let m = memberRecord(p.id, userId)
300. if (m == null) { return { error = 'not a member' field = 'user' } }
301. if (m.role == 'admin' && adminCount(p.id) < 2) { return { error = 'a project needs at least one admin' field = 'user' } }
302. membersTable.delete(m.id)
303. // the tickets assigned to the person are no longer assigned to anybody
304. let all = ticketsTable.find('project', p.id)
305. if (countOf(all) > 0) {
306. for (t of all) {
307. if (t.assignee == userId) { ticketsTable.update(t.id, merged(t, { assignee = '' })) }
308. }
309. }
310. return { members = memberRows(p.id) }
311. }
313. // the user a name (exact display name), an ident id (identity) or a users @id stands for, among
314. // the members of a project when `projectId` is given; { user } | { error }
315. static userByRef = (ref, projectId) => {
316. let r = clean(ref)
317. if (r == '') { return { error = 'name a person' } }
318. let found = []
319. let all = usersTable.find(null, null)
320. if (countOf(all) > 0) {
321. for (u of all) {
322. if (projectId == null || memberRecord(projectId, u.id) != null) {
323. if (u.id == r || u.identity == r || (u.name != '' && u.name == r)) { found.push(u) }
324. }
325. }
326. }
327. if (found.length == 0) { return { error = 'no such person' + (projectId != null ? ' among the members' : '') + ': ' + r } }
328. if (found.length > 1) { return { error = 'more than one person is called ' + r } }
329. return { user = found[0] }
330. }
332. // the members a ticket can be assigned to: [{ value (users @id), label (display name) }]
333. static assignChoices = (projectId) => {
334. let out = []
335. for (m of memberRows(projectId)) { out.push({ value = m.user label = m.name }) }
336. return out
337. }
339. // projects a user may create tickets in: [{ slug, title }] (creation order)
340. static editableProjects = (user) => {
341. let out = []
342. if (user == null) { return out }
343. for (p of projectRecords()) { if (mayEditIn(p.id, user)) { out.push({ slug = p.slug title = p.title }) } }
344. return out
345. }
346. // the projects a user is a member of, with the role: [{ slug, title, role, href }]
347. static projectsOfUser = (user) => {
348. let out = []
349. if (user == null) { return out }
350. for (p of projectRecords()) {
351. let r = roleOf(p.id, user)
352. if (r != null) { out.push({ slug = p.slug title = p.title role = r href = projectHrefOf(p.slug) }) }
353. }
354. return out
355. }
357. static userOk = (u) => { return u != null && u.id != null && u.name != null && u.name != '' }
358. static authorMissing = { error = 'a write needs a logged-in user' field = 'author' }
359. static notMember = (what) => { return { error = what field = '' forbidden = true } }
361. // answers { error, field } or { project (row), members }. ANY logged-in user with a display name
362. // opens a project and is its first admin. A slug is generated from the title unless one is given.
363. static createProject = (user, title, slug, description) => {
364. if (!userOk(user)) { return authorMissing }
365. let t = clean(title)
366. if (t == '') { return { error = 'the title is required' field = 'title' } }
367. if (t.length > 100) { return { error = 'the title is too long (at most 100 characters)' field = 'title' } }
368. let s = clean(slug)
369. if (s == '') { s = uniqueSlug(slugFromTitle(t)) }
370. if (!validProjectName(s)) { return { error = "a slug has no spaces or slashes: letters, digits, '.', '_' and '-' only" field = 'slug' } }
371. if (!slugFree(s, null)) { return { error = 'the slug ' + s + ' is already used by a project' field = 'slug' } }
372. let id = projectsTable.put({ title = t slug = s description = clean(description) oldSlugs = '' created = now() })
373. if (id == null) { return { error = 'could not store the project: ' + projectsTable.lastError() field = '' } }
374. addMember(id, user.id, 'admin')
375. return { project = projectRowOf(projectsTable.fetch(id)) members = memberRows(id) }
376. }
378. // an admin changes title / slug / description (null = keep). A new slug keeps the old one working.
379. static updateProject = (projectId, actor, title, slug, description) => {
380. let p = projectRecord(projectId)
381. if (p == null) { return { error = 'no such project' } }
382. if (!userOk(actor)) { return authorMissing }
383. if (!isAdminOf(p.id, actor)) { return notAdmin }
384. if (title == null && slug == null && description == null) { return { error = 'nothing to change: give title, slug and/or description' field = '' } }
385. let t = title != null ? clean(title) : p.title
386. if (t == '') { return { error = 'the title is required' field = 'title' } }
387. if (t.length > 100) { return { error = 'the title is too long (at most 100 characters)' field = 'title' } }
388. let s = slug != null ? clean(slug) : p.slug
389. if (s == '') { return { error = 'the slug is required' field = 'slug' } }
390. if (!validProjectName(s)) { return { error = "a slug has no spaces or slashes: letters, digits, '.', '_' and '-' only" field = 'slug' } }
391. if (!slugFree(s, p.id)) { return { error = 'the slug ' + s + ' is already used by another project' field = 'slug' } }
392. let d = description != null ? clean(description) : (p.description != null ? p.description : '')
393. let olds = oldSlugsOf(p)
394. if (s != p.slug) {
395. let kept = []
396. for (o of olds) { if (o != s) { kept.push(o) } }
397. kept.push(p.slug)
398. olds = kept
399. }
400. projectsTable.update(p.id, merged(p, { title = t slug = s description = d oldSlugs = olds.join(',') }))
401. return { project = projectRowOf(projectsTable.fetch(p.id)) }
402. }
404. // ---- the shapes a page and the API show ---------------------------------------------
405. // A ROW IS A PLAIN HYBRID: what the View reads is what the browser receives.
406. // `id` is the UUID; `number` + `project` (the slug) are what a person uses; `oldNumber` / `oldRef`
407. // only on tickets migrated from the global numbering.
408. static ticketRowOf = (t) => {
409. let n = t.events != null ? t.events : 0
410. let p = projectRecord(t.project)
411. let slug = p != null ? p.slug : ''
412. let byId = t.createdBy != null ? t.createdBy : ''
413. let toId = t.assignee != null ? t.assignee : ''
414. let row = {
415. id = t.id
416. project = slug
417. projectId = t.project
418. projectTitle = p != null ? p.title : ''
419. number = t.number
420. ref = '#' + t.number
421. subject = t.subject
422. summary = t.summary
423. state = t.state
424. stateSlug = slugOf(t.state)
425. source = t.source != null ? t.source : ''
426. created = stamp(t.created)
427. createdMs = t.created
428. updated = stamp(t.updated)
429. updatedMs = t.updated
430. events = n
431. href = ticketHref(slug, t.number)
432. apiHref = ticketApiHref(slug, t.number)
433. projectHref = projectHrefOf(slug)
434. hasOld = t.oldNumber != null
435. oldRef = t.oldNumber != null ? '#' + t.oldNumber : ''
436. createdById = byId
437. createdBy = byId != '' ? nameOfUser(byId) : creatorNameOf(t)
438. assigneeId = toId
439. assignee = toId != '' ? nameOfUser(toId) : ''
440. hasAssignee = toId != ''
441. }
442. if (t.oldNumber != null) { row.oldNumber = t.oldNumber }
443. // ticket #4 (mission 017): the relations, as refs with their states (relationsOf below)
444. let rel = relationsOf(t)
445. row.parent = rel.parent
446. row.children = rel.children
447. row.allChildrenConfirmed = rel.allChildrenConfirmed
448. row.blockedBy = rel.blockedBy
449. row.blocks = rel.blocks
450. return row
451. }
453. // a ticket from before the login has no createdBy: the free-text author of its 'created' event
454. static creatorNameOf = (t) => {
455. let all = eventsTable.find('ticket', t.id)
456. if (countOf(all) == 0) { return '' }
457. for (e of all) { if (e.kind == 'created') { return e.author != null ? e.author : '' } }
458. return ''
459. }
461. static eventRowOf = (e, t) => {
462. let kind = e.kind
463. // computed BEFORE the literal: inside a literal that has an `id` entry, a called function's
464. // parameter named `id` read that entry instead (mission 011, reported as a Hybriel issue)
465. let who = e.user != null ? nameOfUser(e.user) : e.author
466. let label = kind == 'created' ? 'opened the ticket' : (kind == 'state' ? 'changed the state' : (kind == 'edit' ? 'edited the ticket' : 'commented'))
467. if (kind == 'link') { label = linkLabelOf(e) }
468. let assignedTo = ''
469. let assignedWas = ''
470. if (kind == 'assign') {
471. assignedTo = e.assignee != null && e.assignee != '' ? nameOfUser(e.assignee) : ''
472. assignedWas = e.previous != null && e.previous != '' ? nameOfUser(e.previous) : ''
473. label = assignedTo != '' ? 'assigned the ticket to ' + assignedTo : 'unassigned the ticket' + (assignedWas != '' ? ' (was ' + assignedWas + ')' : '')
474. }
475. let row = {
476. id = e.id
477. ticket = e.ticket
478. project = t != null ? projectSlugOf(t) : ''
479. number = t != null ? t.number : 0
480. seq = e.seq != null ? e.seq : 0
481. kind = kind
482. author = who
483. userId = e.user != null ? e.user : ''
484. text = e.text != null ? e.text : ''
485. hasText = e.text != null && e.text != ''
486. from = e.from != null ? e.from : ''
487. to = e.to != null ? e.to : ''
488. toSlug = slugOf(e.to)
489. isState = kind == 'state'
490. isComment = kind == 'comment'
491. isCreated = kind == 'created'
492. label = label
493. when = stamp(e.created)
494. createdMs = e.created
495. }
496. // ticket #8: only an edit event carries these (the JSON of every other event is unchanged)
497. if (kind == 'edit') {
498. row.isEdit = true
499. row.oldSubject = e.oldSubject != null ? e.oldSubject : ''
500. row.oldSummary = e.oldSummary != null ? e.oldSummary : ''
501. row.newSubject = e.subject != null ? e.subject : ''
502. row.newSummary = e.summary != null ? e.summary : ''
503. row.subjectChanged = row.oldSubject != row.newSubject
504. row.summaryChanged = row.oldSummary != row.newSummary
505. }
506. // ticket #4: only a link event carries these
507. if (kind == 'link') {
508. row.isLink = true
509. row.linkKind = e.linkKind
510. row.linkAction = e.action
511. row.otherRef = e.otherProject + ' #' + e.otherNumber
512. row.otherHref = ticketHref(e.otherProject, e.otherNumber)
513. row.previousRef = e.previous != null ? e.previousProject + ' #' + e.previousNumber : ''
514. }
515. // ticket #20: only an assign event carries these
516. if (kind == 'assign') {
517. row.isAssign = true
518. row.assignee = assignedTo
519. row.previousAssignee = assignedWas
520. }
521. return row
522. }
523. static projectSlugOf = (t) => {
524. let p = projectRecord(t.project)
525. return p != null ? p.slug : ''
526. }
528. // "set the parent to ident.worldapi.org #1", "removed the blocker tickets.worldapi.org #6", …
529. static linkLabelOf = (e) => {
530. let other = e.otherProject + ' #' + e.otherNumber
531. if (e.linkKind == 'parent') {
532. if (e.action == 'removed') { return 'removed the parent ' + other }
533. let was = e.previous != null ? ' (was ' + e.previousProject + ' #' + e.previousNumber + ')' : ''
534. return 'set the parent to ' + other + was
535. }
536. if (e.action == 'removed') { return 'removed the blocker ' + other }
537. return 'marked it blocked by ' + other
538. }
540. // THE PAGE'S EVENT ROW (ticket #6): the API row + its text as Markdown blocks (`md`), and for an
541. // edit the previous summary's blocks (`oldSummaryMd`) and the new one's (`summaryMd`, the ticket
542. // page takes it over live). Only pages and pushes carry these — the JSON API does not.
543. static pageEventOf = (ev) => {
544. let out = {}
545. for (k of ev.keys()) { out[k] = ev[k] }
546. out.md = markdownBlocks(ev.text)
547. if (ev.isEdit == true) {
548. out.oldSummaryMd = markdownBlocks(ev.oldSummary)
549. out.summaryMd = markdownBlocks(ev.newSummary)
550. }
551. return out
552. }
553. static pageEventsOf = (evs) => {
554. let out = []
555. for (ev of evs) { out.push(pageEventOf(ev)) }
556. return out
557. }
559. // ---- finding a ticket -------------------------------------------------------------------
560. static ticketRecord = (uuid) => { return uuid == null || uuid == '' ? null : ticketsTable.fetch('' + uuid) }
561. // `project` is a slug (a former one too)
562. static ticketAt = (project, number) => {
563. if (project == null || !isDigits(number)) { return null }
564. let p = projectByAnySlug(project)
565. if (p == null) { return null }
566. return first(ticketsTable.find('path', p.id + '/' + toNumber('' + number)))
567. }
568. static ticketByOld = (oldNumber) => {
569. if (!isDigits(oldNumber)) { return null }
570. return first(ticketsTable.find('oldNumber', toNumber('' + oldNumber)))
571. }
572. // what `/api/tickets/:ref` and `/tickets/:ref` accept: the OLD global number (digits)
573. // or the ticket's UUID
574. static ticketByRef = (ref) => {
575. if (ref == null) { return null }
576. if (isDigits(ref)) { return ticketByOld(ref) }
577. return ticketRecord(ref)
578. }
580. // ---- reads -------------------------------------------------------------------------
581. static sortByUpdated = (rows) => {
582. // insertion sort by updated, descending (lists are short)
583. let i = 1
584. while (i < rows.length) {
585. let cur = rows[i]
586. let j = i - 1
587. while (j >= 0 && rows[j].updatedMs < cur.updatedMs) {
588. rows[j + 1] = rows[j]
589. j = j - 1
590. }
591. rows[j + 1] = cur
592. i = i + 1
593. }
594. return rows
595. }
597. // newest update first; both filters optional (null = all); `project` is a slug
598. static ticketRows = (project, state) => {
599. let rows = []
600. let all = null
601. if (project != null) {
602. let p = projectByAnySlug(project)
603. if (p == null) { return rows }
604. all = ticketsTable.find('project', p.id)
605. } else {
606. all = ticketsTable.find(null, null)
607. }
608. if (countOf(all) == 0) { return rows }
609. for (t of all) {
610. if (state == null || t.state == state) { rows.push(ticketRowOf(t)) }
611. }
612. return sortByUpdated(rows)
613. }
615. // THE INBOX of a user: the tickets ASSIGNED TO THEM in pending and in review, two lists
616. static inboxRows = (user) => {
617. let out = { pending = [] review = [] }
618. if (user == null || user.id == null) { return out }
619. let a = []
620. let b = []
621. let ps = ticketsTable.find('state', 'pending')
622. if (countOf(ps) > 0) { for (t of ps) { if (t.assignee == user.id) { a.push(ticketRowOf(t)) } } }
623. let rs = ticketsTable.find('state', 'review')
624. if (countOf(rs) > 0) { for (t of rs) { if (t.assignee == user.id) { b.push(ticketRowOf(t)) } } }
625. out.pending = sortByUpdated(a)
626. out.review = sortByUpdated(b)
627. return out
628. }
629. static inboxCountOf = (user) => {
630. let x = inboxRows(user)
631. return x.pending.length + x.review.length
632. }
634. // the page's row of `/projects/<project>/<number>`, or null
635. static ticketRowAt = (project, number) => {
636. let t = ticketAt(project, number)
637. return t == null ? null : ticketRowOf(t)
638. }
640. // the event history of a ticket (UUID), oldest first: by stored time, then seq
641. static eventRows = (ticketId) => {
642. let out = []
643. let t = ticketRecord(ticketId)
644. if (t == null) { return out }
645. let all = eventsTable.find('ticket', t.id)
646. if (countOf(all) == 0) { return out }
647. for (e of all) { out.push(eventRowOf(e, t)) }
648. let i = 1
649. while (i < out.length) {
650. let cur = out[i]
651. let j = i - 1
652. while (j >= 0 && (out[j].createdMs > cur.createdMs || (out[j].createdMs == cur.createdMs && out[j].seq > cur.seq))) {
653. out[j + 1] = out[j]
654. j = j - 1
655. }
656. out[j + 1] = cur
657. i = i + 1
658. }
659. return out
660. }
662. // the filter links of the list page: [{ label, href, cls }] — `cls` is 'selected' on
663. // the one in effect. The href keeps the OTHER filter.
664. static projectLinks = (project, state) => {
665. let tail = state != null ? '/state/' + slugOf(state) : ''
666. let out = [{ label = 'all projects' href = state != null ? tail : '/' cls = project == null ? 'selected' : '' }]
667. for (p of projectRecords()) {
668. out.push({ label = p.title href = '/project/' + p.slug + tail cls = p.slug == project ? 'selected' : '' })
669. }
670. return out
671. }
673. static stateLinks = (project, state) => {
674. let head = project != null ? '/project/' + project : ''
675. let out = [{ label = 'all states' href = project != null ? head : '/' cls = state == null ? 'selected' : '' }]
676. for (s of states) {
677. out.push({ label = s href = head + '/state/' + slugOf(s) cls = s == state ? 'selected ' + slugOf(s) : slugOf(s) })
678. }
679. return out
680. }
682. // the options of a state select: [{ value, label }] — the states THIS user may move the ticket to
683. // (a `use` member: only open ⇄ review; `edit` / `admin`: every other state)
684. static stateChoices = (t, user) => {
685. let out = []
686. if (t == null || user == null) { return out }
687. let role = roleOf(t.project, user)
688. for (s of states) {
689. if (s != t.state && mayMoveTo(role, t.state, s)) { out.push({ value = s label = s }) }
690. }
691. return out
692. }
693. static mayMoveTo = (role, current, target) => {
694. if (rankOf(role) >= 2) { return true }
695. if (rankOf(role) == 1) { return (current == 'open' && target == 'review') || (current == 'review' && target == 'open') }
696. return false
697. }
699. // ---- writes: each answers what the push carries --------------------------------------
700. // EVERY WRITE HAS A USER (ticket #7): the logged-in user of the web session or of the API
701. // token (users.hl). The author is that user — there is no free author field any more.
702. // WHO MAY is the role in the ticket's project (see the top): a refusal for a missing right has
703. // `forbidden = true` (the API answers 403).
705. // the next per-project number: the highest one in the project + 1 (first = 1)
706. static nextNumber = (projectId) => {
707. let top = 0
708. let all = ticketsTable.find('project', projectId)
709. if (countOf(all) > 0) {
710. for (t of all) { if (t.number != null && t.number > top) { top = t.number } }
711. }
712. return top + 1
713. }
715. // answers { error, field, forbidden? } or { ticket (row), event (row), existed }
716. // `project` = the slug (or id) of an existing project; `assignee` optional (a member's name / id)
717. static createTicket = (project, subject, summary, user, source, assignee) => {
718. let s = clean(subject)
719. if (clean(project) == '') { return { error = 'project is required' field = 'project' } }
720. if (s == '') { return { error = 'subject is required' field = 'subject' } }
721. if (!userOk(user)) { return authorMissing }
722. let p = projectByRef(clean(project))
723. if (p == null) { return { error = 'no such project: ' + clean(project) field = 'project' } }
724. 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 } }
725. let who = ''
726. if (assignee != null && clean(assignee) != '') {
727. let r = userByRef(assignee, p.id)
728. if (r.error != null) { return { error = r.error field = 'assignee' } }
729. who = r.user.id
730. }
731. let src = clean(source)
732. if (src != '') {
733. let known = ticketsTable.find('source', src)
734. if (countOf(known) > 0) { return { ticket = ticketRowOf(known[0]) event = null existed = true } }
735. }
736. let t0 = now()
737. let n = nextNumber(p.id)
738. let 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 })
739. if (id == null) { return { error = 'could not store the ticket: ' + ticketsTable.lastError() field = '' } }
740. let t = ticketsTable.fetch(id)
741. let eid = eventsTable.put({ ticket = id seq = 1 kind = 'created' author = user.name user = user.id text = src != '' ? 'imported from ' + src : '' created = t0 })
742. let out = { ticket = ticketRowOf(t) event = eventRowOf(eventsTable.fetch(eid), t) existed = false }
743. if (who != '') {
744. let seq = 2
745. let aid = eventsTable.put({ ticket = id seq = seq kind = 'assign' author = user.name user = user.id text = '' assignee = who previous = '' created = t0 })
746. ticketsTable.update(id, merged(t, { events = seq }))
747. let t2 = ticketsTable.fetch(id)
748. out.ticket = ticketRowOf(t2)
749. out.assignEvent = eventRowOf(eventsTable.fetch(aid), t2)
750. }
751. return out
752. }
754. // answers { error } or { ticket, event }; `ticketId` is the UUID. Any member may comment.
755. static addComment = (ticketId, user, text) => {
756. let t = ticketRecord(ticketId)
757. if (t == null) { return { error = 'no such ticket' } }
758. let body = clean(text)
759. if (body == '') { return { error = 'a comment needs text' field = 'text' } }
760. if (!userOk(user)) { return authorMissing }
761. if (!isMember(t.project, user)) { return { error = 'only a member of the project can comment' field = '' forbidden = true } }
762. let t0 = now()
763. let seq = (t.events != null ? t.events : 0) + 1
764. let eid = eventsTable.put({ ticket = t.id seq = seq kind = 'comment' author = user.name user = user.id text = body created = t0 })
765. ticketsTable.update(t.id, merged(t, { updated = t0 events = seq }))
766. let t2 = ticketsTable.fetch(t.id)
767. return { ticket = ticketRowOf(t2) event = eventRowOf(eventsTable.fetch(eid), t2) }
768. }
770. // the admin who gets a ticket that lands in the inbox with nobody assigned: the oldest admin
771. static defaultAssignee = (projectId) => {
772. for (m of memberRows(projectId)) { if (m.role == 'admin') { return m.user } }
773. return ''
774. }
776. // answers { error } or { ticket, event, assignEvent? }; an optional note rides on the state event.
777. // `forbidden = true` on a refusal the user may not overcome (the role does not allow that move).
778. // A ticket that goes to review / pending with nobody assigned is assigned to the project's first admin
779. // (so it reaches an inbox) — a second, 'assign' event.
780. static changeState = (ticketId, state, user, note) => {
781. let t = ticketRecord(ticketId)
782. if (t == null) { return { error = 'no such ticket' } }
783. let s = stateOf(state)
784. if (s == null) { return { error = 'unknown state — one of: ' + states.join(', ') field = 'state' } }
785. if (s == t.state) { return { error = 'the ticket is already ' + s field = 'state' } }
786. if (!userOk(user)) { return authorMissing }
787. let role = roleOf(t.project, user)
788. if (role == null) { return { error = 'only a member of the project can change the state' field = 'state' forbidden = true } }
789. if (!mayMoveTo(role, t.state, s)) { return { error = 'the role ' + role + ' can only move a ticket between open and review' field = 'state' forbidden = true } }
790. let t0 = now()
791. let seq = (t.events != null ? t.events : 0) + 1
792. let eid = eventsTable.put({ ticket = t.id seq = seq kind = 'state' author = user.name user = user.id text = clean(note) from = t.state to = s created = t0 })
793. let changes = { state = s updated = t0 events = seq }
794. let aid = null
795. let auto = ''
796. if (inboxStates.includes(s) && (t.assignee == null || t.assignee == '')) { auto = defaultAssignee(t.project) }
797. if (auto != '') {
798. seq = seq + 1
799. aid = eventsTable.put({ ticket = t.id seq = seq kind = 'assign' author = user.name user = user.id text = '' assignee = auto previous = '' created = t0 })
800. changes.assignee = auto
801. changes.events = seq
802. }
803. ticketsTable.update(t.id, merged(t, changes))
804. let t2 = ticketsTable.fetch(t.id)
805. let out = { ticket = ticketRowOf(t2) event = eventRowOf(eventsTable.fetch(eid), t2) }
806. if (aid != null) { out.assignEvent = eventRowOf(eventsTable.fetch(aid), t2) }
807. return out
808. }
810. // answers { error, forbidden? } or { ticket, event }; `assignee` = a member's users @id, '' = nobody
811. static assignTicket = (ticketId, user, assignee) => {
812. let t = ticketRecord(ticketId)
813. if (t == null) { return { error = 'no such ticket' } }
814. if (!userOk(user)) { return authorMissing }
815. if (!mayEditIn(t.project, user)) { return { error = 'you need the role edit or admin to assign a ticket' field = 'assignee' forbidden = true } }
816. let who = assignee == null ? '' : clean(assignee)
817. if (who != '' && memberRecord(t.project, who) == null) { return { error = 'the assignee must be a member of the project' field = 'assignee' } }
818. let was = t.assignee != null ? t.assignee : ''
819. if (who == was) { return { error = who == '' ? 'the ticket is not assigned' : 'the ticket is already assigned to that person' field = 'assignee' } }
820. let t0 = now()
821. let seq = (t.events != null ? t.events : 0) + 1
822. let eid = eventsTable.put({ ticket = t.id seq = seq kind = 'assign' author = user.name user = user.id text = '' assignee = who previous = was created = t0 })
823. ticketsTable.update(t.id, merged(t, { assignee = who updated = t0 events = seq }))
824. let t2 = ticketsTable.fetch(t.id)
825. return { ticket = ticketRowOf(t2) event = eventRowOf(eventsTable.fetch(eid), t2) }
826. }
828. // ---- editing (ticket #8, mission 014; ticket #20: by the role) --------------------------------
829. // THE AUTHOR of a ticket is `createdBy` (users @id), or null for a ticket opened before the login
830. // existed. MAY THIS USER EDIT the ticket (a record)? Any member with the role edit or admin of
831. // its project (`use` members only comment and move it between open and review).
832. static ownerOf = (t) => { return t.createdBy != null && t.createdBy != '' ? t.createdBy : null }
833. static mayEdit = (t, user) => {
834. if (t == null || !userOk(user)) { return false }
835. return mayEditIn(t.project, user)
836. }
837. static mayEditId = (ticketId, user) => { return mayEdit(ticketRecord(ticketId), user) }
839. // answers { error, field?, forbidden? } or { ticket, event }. `subject` / `summary` null = keep
840. // that one. The previous values stay in the 'edit' event (append-only history).
841. static editTicket = (ticketId, user, subject, summary) => {
842. let t = ticketRecord(ticketId)
843. if (t == null) { return { error = 'no such ticket' } }
844. if (!userOk(user)) { return authorMissing }
845. if (!mayEdit(t, user)) { return { error = 'you need the role edit or admin in the project to edit a ticket' field = '' forbidden = true } }
846. if (subject == null && summary == null) { return { error = 'nothing to change: give subject and/or summary' field = '' } }
847. let oldSummary = t.summary != null ? t.summary : ''
848. let s = subject != null ? clean(subject) : t.subject
849. if (s == '') { return { error = 'subject is required' field = 'subject' } }
850. let sm = summary != null ? clean(summary) : oldSummary
851. if (s == t.subject && sm == oldSummary) { return { error = 'nothing changed' field = subject != null ? 'subject' : 'summary' } }
852. let t0 = now()
853. let seq = (t.events != null ? t.events : 0) + 1
854. let eid = eventsTable.put({ 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 })
855. if (eid == null) { return { error = 'could not store the edit: ' + eventsTable.lastError() field = '' } }
856. ticketsTable.update(t.id, merged(t, { subject = s summary = sm updated = t0 events = seq }))
857. let t2 = ticketsTable.fetch(t.id)
858. return { ticket = ticketRowOf(t2) event = eventRowOf(eventsTable.fetch(eid), t2) }
859. }
861. // the API's view of one ticket (a record): the row and its whole history
862. static ticketWithEvents = (t) => {
863. if (t == null) { return null }
864. return { ticket = ticketRowOf(t) events = eventRows(t.id) }
865. }
867. // ---- relations: parent / child and blocked-by (ticket #4, mission 017) ----------------------
868. // A ticket has at most ONE PARENT (any project); a parent lists its CHILDREN with their states.
869. // A ticket can be BLOCKED BY other tickets (any project) — it waits on them; the other side
870. // shows what it BLOCKS. The scheduler reads them from the JSON rows (`parent`, `children`,
871. // `blockedBy`, `blocks`, each a ref with the state) and the Markdown view.
872. // PARENT STATE: `allChildrenConfirmed` (the key kept for the clients; it now means DONE) is true when
873. // a ticket has children and every one of them is `done`. It is only SHOWN ("all children done") — the
874. // parent's own state is never changed by it.
875. // WHO MAY set / remove a relation (ticket #20): a member with the role edit or admin in the project of
876. // EITHER of the two tickets. Replacing a parent needs the
877. // right for the old pair AND the new pair. No loops: a ticket cannot be its own ancestor, and
878. // cannot (transitively) wait on itself.
879. // Tickets are named as `<project>#<number>` (spaces around `#` allowed) or by their UUID.
881. // what a relation shows of a ticket (no relations of its own — no recursion)
882. static refOf = (t) => {
883. let slug = slugOf(t.state)
884. let pslug = projectSlugOf(t)
885. let href = ticketHref(pslug, t.number)
886. let apiHref = ticketApiHref(pslug, t.number)
887. let key = pslug + '#' + t.number
888. return { id = t.id project = pslug number = t.number ref = '#' + t.number key = key subject = t.subject state = t.state stateSlug = slug href = href apiHref = apiHref }
889. }
891. // the link records of one side, oldest first (stored time): field 'ticket' = this ticket's own
892. // relations (its parent, its blockers), field 'other' = the ones pointing at it (children, blocked)
893. static linkRecords = (field, ticketId, kind) => {
894. let out = []
895. if (ticketId == null || ticketId == '') { return out }
896. let all = linksTable.find(field, '' + ticketId)
897. if (countOf(all) == 0) { return out }
898. for (l of all) { if (l.kind == kind) { out.push(l) } }
899. let i = 1
900. while (i < out.length) {
901. let cur = out[i]
902. let j = i - 1
903. while (j >= 0 && out[j].created > cur.created) {
904. out[j + 1] = out[j]
905. j = j - 1
906. }
907. out[j + 1] = cur
908. i = i + 1
909. }
910. return out
911. }
912. static parentLinkOf = (ticketId) => { return first(linkRecords('ticket', ticketId, 'parent')) }
913. static parentIdOf = (ticketId) => {
914. let l = parentLinkOf(ticketId)
915. return l == null ? null : l.other
916. }
917. static idsOfLinks = (links, field) => {
918. let out = []
919. for (l of links) { out.push(l[field]) }
920. return out
921. }
922. static childIdsOf = (ticketId) => { return idsOfLinks(linkRecords('other', ticketId, 'parent'), 'ticket') }
923. static blockerIdsOf = (ticketId) => { return idsOfLinks(linkRecords('ticket', ticketId, 'blockedBy'), 'other') }
924. static blockedIdsOf = (ticketId) => { return idsOfLinks(linkRecords('other', ticketId, 'blockedBy'), 'ticket') }
925. static refsOfIds = (ids) => {
926. let out = []
927. for (i of ids) {
928. let t = ticketRecord(i)
929. if (t != null) { out.push(refOf(t)) }
930. }
931. return out
932. }
934. // { parent (ref or null), children, blockedBy, blocks (lists of refs), allChildrenConfirmed }
935. static relationsOf = (t) => {
936. let pid = parentIdOf(t.id)
937. let p = pid != null ? ticketRecord(pid) : null
938. let kids = refsOfIds(childIdsOf(t.id))
939. let all = kids.length > 0
940. for (c of kids) { if (c.state != 'done') { all = false } }
941. return { parent = p != null ? refOf(p) : null children = kids allChildrenConfirmed = all blockedBy = refsOfIds(blockerIdsOf(t.id)) blocks = refsOfIds(blockedIdsOf(t.id)) }
942. }
944. // what the ticket PAGE shows of a row's relations (SSR members and the `ticketsRelated` push)
945. static noRef = { id = '' project = '' number = 0 ref = '' key = '' subject = '' state = '' stateSlug = '' href = '/' apiHref = '' }
946. static relationViewOf = (row) => {
947. let total = row.children.length
948. let done = 0
949. for (c of row.children) { if (c.state == 'done') { done = done + 1 } }
950. let note = ''
951. if (total > 0) { note = done == total ? 'all children done (' + total + ')' : done + ' of ' + total + ' children done' }
952. let hasParent = row.parent != null
953. let hasChildren = total > 0
954. let hasBlockedBy = row.blockedBy.length > 0
955. let hasBlocks = row.blocks.length > 0
956. return { id = row.id parent = hasParent ? row.parent : noRef hasParent = hasParent children = row.children hasChildren = hasChildren
957. childNote = note childClass = row.allChildrenConfirmed ? 'done' : '' allChildrenConfirmed = row.allChildrenConfirmed
958. blockedBy = row.blockedBy hasBlockedBy = hasBlockedBy blocks = row.blocks hasBlocks = hasBlocks
959. hasRelations = hasParent || hasChildren || hasBlockedBy || hasBlocks }
960. }
962. // the relation views of a ticket AND every ticket related to it (+ `extra` ids: a parent or
963. // blocker just removed) — what a write pushes, so every open page of them follows
964. static relatedViews = (ticketId, extra) => {
965. let ids = ['' + ticketId]
966. let seen = {}
967. seen['' + ticketId] = true
968. let more = []
969. let pid = parentIdOf(ticketId)
970. if (pid != null) { more.push(pid) }
971. for (i of childIdsOf(ticketId)) { more.push(i) }
972. for (i of blockerIdsOf(ticketId)) { more.push(i) }
973. for (i of blockedIdsOf(ticketId)) { more.push(i) }
974. for (i of extra) { if (i != null) { more.push(i) } }
975. for (i of more) {
976. if (seen['' + i] != true) {
977. seen['' + i] = true
978. ids.push('' + i)
979. }
980. }
981. let out = []
982. for (i of ids) {
983. let t = ticketRecord(i)
984. if (t != null) { out.push(relationViewOf(ticketRowOf(t))) }
985. }
986. return out
987. }
989. // `<project>#<number>` (spaces around '#' allowed) or a UUID → the ticket record, or null
990. static ticketByKey = (key) => {
991. let k = clean(key)
992. if (k == '') { return null }
993. let at = k.indexOf('#')
994. if (at < 0) { return isDigits(k) ? null : ticketRecord(k) }
995. let p = k.slice(0, at).trim()
996. let n = k.slice(at + 1).trim()
997. if (p == '') { return null }
998. return ticketAt(p, n)
999. }
1001. static mayLink = (a, b, user) => {
1002. if (!userOk(user)) { return false }
1003. if (a != null && mayEditIn(a.project, user)) { return true }
1004. if (b != null && mayEditIn(b.project, user)) { return true }
1005. return false
1006. }
1007. static linkForbidden = { error = 'you need the role edit or admin in the project of either ticket to change this relation' field = '' forbidden = true }
1008. static keyOf = (t) => { return projectSlugOf(t) + '#' + t.number }
1010. // the history event of a relation change, on ticket `t`; answers { ticket, event, related }
1011. static linkEvent = (t, user, linkKind, action, other, previous, extra) => {
1012. let t0 = now()
1013. let seq = (t.events != null ? t.events : 0) + 1
1014. // the values BEFORE the literal: an entry named `other` / `user` would shadow the variable
1015. // for the entries after it (mission 011 lesson)
1016. let uname = user.name
1017. let uid = user.id
1018. let oid = other.id
1019. let oproject = projectSlugOf(other)
1020. let onumber = other.number
1021. let 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 }
1022. if (previous != null) {
1023. rec.previous = previous.id
1024. rec.previousProject = projectSlugOf(previous)
1025. rec.previousNumber = previous.number
1026. }
1027. let eid = eventsTable.put(rec)
1028. if (eid == null) { return { error = 'could not store the event: ' + eventsTable.lastError() field = '' } }
1029. ticketsTable.update(t.id, merged(t, { updated = t0 events = seq }))
1030. let t2 = ticketsTable.fetch(t.id)
1031. return { ticket = ticketRowOf(t2) event = eventRowOf(eventsTable.fetch(eid), t2) related = relatedViews(t.id, extra) }
1032. }
1034. // SET (key = `<project>#<n>` / UUID) or REMOVE (key = '') the parent of a ticket (UUID).
1035. // Answers { error, field, forbidden? } or { ticket, event, related }.
1036. static setParent = (ticketId, user, key) => {
1037. let t = ticketRecord(ticketId)
1038. if (t == null) { return { error = 'no such ticket' } }
1039. if (!userOk(user)) { return authorMissing }
1040. let k = clean(key)
1041. let cur = parentLinkOf(t.id)
1042. let curT = cur != null ? ticketRecord(cur.other) : null
1043. if (k == '') {
1044. if (cur == null || curT == null) { return { error = 'the ticket has no parent' field = 'parent' } }
1045. if (!mayLink(t, curT, user)) { return linkForbidden }
1046. linksTable.delete(cur.id)
1047. return linkEvent(t, user, 'parent', 'removed', curT, null, [curT.id])
1048. }
1049. let p = ticketByKey(k)
1050. if (p == null) { return { error = 'no such ticket: ' + k + ' (name it as <project>#<number>)' field = 'parent' } }
1051. if (p.id == t.id) { return { error = 'a ticket cannot be its own parent' field = 'parent' } }
1052. if (curT != null && curT.id == p.id) { return { error = 'the parent is already ' + keyOf(p) field = 'parent' } }
1053. // no loop: the new parent must not be this ticket's child, grandchild, …
1054. let up = p.id
1055. let steps = 0
1056. while (up != null && steps < 1000) {
1057. if (up == t.id) { return { error = 'a loop: ' + keyOf(p) + ' is below this ticket' field = 'parent' } }
1058. up = parentIdOf(up)
1059. steps = steps + 1
1060. }
1061. if (!mayLink(t, p, user)) { return linkForbidden }
1062. if (curT != null && !mayLink(t, curT, user)) { return linkForbidden }
1063. let lid = linksTable.put({ kind = 'parent' ticket = t.id other = p.id user = user.id created = now() })
1064. if (lid == null) { return { error = 'could not store the relation: ' + linksTable.lastError() field = '' } }
1065. if (cur != null) { linksTable.delete(cur.id) }
1066. return linkEvent(t, user, 'parent', 'set', p, curT, [curT != null ? curT.id : null])
1067. }
1069. // does ticket `start` (transitively) wait on ticket `target`? (blocked-by links)
1070. static waitsOn = (start, target) => {
1071. let stack = [start]
1072. let seen = {}
1073. let steps = 0
1074. while (stack.length > 0 && steps < 10000) {
1075. let cur = stack.pop()
1076. steps = steps + 1
1077. if (cur == target) { return true }
1078. if (seen['' + cur] != true) {
1079. seen['' + cur] = true
1080. for (i of blockerIdsOf(cur)) { stack.push(i) }
1081. }
1082. }
1083. return false
1084. }
1086. // ADD (adding = true) or REMOVE a blocker of a ticket (UUID): ticket `key` blocks it.
1087. // `field` names the API field ('add' / 'remove'). Answers as setParent.
1088. static changeBlocker = (ticketId, user, key, adding, field) => {
1089. let t = ticketRecord(ticketId)
1090. if (t == null) { return { error = 'no such ticket' } }
1091. if (!userOk(user)) { return authorMissing }
1092. let k = clean(key)
1093. if (k == '') { return { error = 'name the blocking ticket as <project>#<number>' field = field } }
1094. let o = ticketByKey(k)
1095. if (o == null) { return { error = 'no such ticket: ' + k + ' (name it as <project>#<number>)' field = field } }
1096. let existing = null
1097. for (l of linkRecords('ticket', t.id, 'blockedBy')) { if (l.other == o.id) { existing = l } }
1098. if (adding) {
1099. if (o.id == t.id) { return { error = 'a ticket cannot block itself' field = field } }
1100. if (existing != null) { return { error = 'already blocked by ' + keyOf(o) field = field } }
1101. if (waitsOn(o.id, t.id)) { return { error = 'a loop: ' + keyOf(o) + ' already waits on this ticket' field = field } }
1102. if (!mayLink(t, o, user)) { return linkForbidden }
1103. let lid = linksTable.put({ kind = 'blockedBy' ticket = t.id other = o.id user = user.id created = now() })
1104. if (lid == null) { return { error = 'could not store the relation: ' + linksTable.lastError() field = '' } }
1105. return linkEvent(t, user, 'blockedBy', 'set', o, null, [])
1106. }
1107. if (existing == null) { return { error = 'not blocked by ' + keyOf(o) field = field } }
1108. if (!mayLink(t, o, user)) { return linkForbidden }
1109. linksTable.delete(existing.id)
1110. return linkEvent(t, user, 'blockedBy', 'removed', o, null, [o.id])
1111. }