tickets

6.7 KB

1. // mdview.hl — THE MARKDOWN READ VIEW FOR LLM READERS (ticket #6, mission 014; CONCEPT.md "Data
2. // formats": a Markdown read view for LLM readers). The ticket GET endpoints answer
3. // `Accept: text/markdown` with a compact Markdown document instead of JSON (project.hl
4. // `wantsMarkdown`); JSON stays the default and is unchanged. Statics only.
5. //
6. // one ticket → # <project> #<n>: <subject>
7. // state · opened (by) · updated · formerly · URL
8. // the summary as written (it IS Markdown)
9. // ## History — one `### <seq> · <when> · <author> <what>` per event, its text below
10. // a list → # Tickets (<filters>): <count>
11. // one line per ticket: `- <project> #<n> [<state>] <subject> · updated <when> · <url>`
12. // Texts are embedded as written (they are Markdown already), so a text's own headings sit
13. // inside the document — readers should take the `### <seq> ·` lines as the event boundaries.
14. import { Response } from 'hl:http1'
15. import { publicUrl } from './users.hl'
17. static NL = "
18. "
20. // does the request ask for Markdown? `Accept` names text/markdown with q > 0 and prefers it to
21. // application/json (a higher q, or the same q and listed first). No Accept / */* → JSON.
22. static qOf = (part) => {
23. let q = 1
24. for (p of part.split(';')) {
25. let kv = p.trim()
26. if (kv.startsWith('q=')) { q = toNumber(kv.slice(2)) }
27. }
28. return q == null ? 0 : q
29. }
30. static wantsMarkdown = (req) => {
31. let h = req.headers['accept']
32. if (h == null || hlTypeName(h) != 'String') { return false }
33. let md = -1
34. let js = -1
35. let mdAt = -1
36. let jsAt = -1
37. let i = 0
38. for (part of h.toLowerCase().split(',')) {
39. let type = part.split(';')[0].trim()
40. if (type == 'text/markdown' && mdAt < 0) {
41. md = qOf(part)
42. mdAt = i
43. }
44. if (type == 'application/json' && jsAt < 0) {
45. js = qOf(part)
46. jsAt = i
47. }
48. i = i + 1
49. }
50. if (md <= 0) { return false }
51. if (js < 0) { return true }
52. return md > js || (md == js && mdAt < jsAt)
53. }
55. static markdownReply = (text) => {
56. return new Response(text, { status = 200 headers = { 'Content-Type' = 'text/markdown; charset=utf-8' 'Vary' = 'Accept' } })
57. }
59. // one line: line breaks and runs of spaces become one space
60. static oneLine = (s) => {
61. if (s == null) { return '' }
62. let parts = []
63. for (w of ('' + s).replaceAll(NL, ' ').split(' ')) { if (w != '') { parts.push(w) } }
64. return parts.join(' ')
65. }
67. // `> ` in front of every line (a previous summary inside an edit event)
68. static quoted = (s) => {
69. let out = []
70. for (l of ('' + s).split(NL)) { out.push(l == '' ? '>' : '> ' + l) }
71. return out.join(NL)
72. }
74. static ticketLine = (row) => {
75. return '- ' + row.project + ' ' + row.ref + ' [' + row.state + '] ' + oneLine(row.subject) + ' · updated ' + row.updated + ' · ' + publicUrl + row.href + relationTail(row)
76. }
78. // ---- relations (ticket #4, mission 017) --------------------------------------------------------
79. // one ticket's document gets "Parent:", "Children (k of n done):", "Blocked by:", "Blocks:"
80. // blocks under its URL; a list line gets ` · parent … · children n, k done · blocked by … · blocks …`
81. static refName = (r) => { return r.project + ' ' + r.ref }
82. static refLine = (r) => { return '- ' + refName(r) + ' [' + r.state + '] ' + oneLine(r.subject) + ' · ' + publicUrl + r.href }
83. static confirmedOf = (refs) => {
84. let n = 0
85. for (r of refs) { if (r.state == 'done') { n = n + 1 } }
86. return n
87. }
88. static relationTail = (row) => {
89. let parts = []
90. if (row.parent != null) { parts.push('parent ' + refName(row.parent)) }
91. let total = row.children.length
92. if (total > 0) { parts.push('children ' + total + (row.allChildrenConfirmed ? ', all done' : ', ' + confirmedOf(row.children) + ' done')) }
93. if (row.blockedBy.length > 0) {
94. let bs = []
95. for (r of row.blockedBy) { bs.push(refName(r) + ' [' + r.state + ']') }
96. parts.push('blocked by ' + bs.join(', '))
97. }
98. if (row.blocks.length > 0) {
99. let bs = []
100. for (r of row.blocks) { bs.push(refName(r)) }
101. parts.push('blocks ' + bs.join(', '))
102. }
103. return parts.length == 0 ? '' : ' · ' + parts.join(' · ')
104. }
105. static relationLines = (t) => {
106. let lines = []
107. if (t.parent != null) {
108. lines.push('')
109. lines.push('Parent: ' + refName(t.parent) + ' [' + t.parent.state + '] ' + oneLine(t.parent.subject) + ' · ' + publicUrl + t.parent.href)
110. }
111. let total = t.children.length
112. if (total > 0) {
113. lines.push('')
114. lines.push('Children (' + (t.allChildrenConfirmed ? 'all ' + total + ' done' : confirmedOf(t.children) + ' of ' + total + ' done') + '):')
115. for (r of t.children) { lines.push(refLine(r)) }
116. }
117. if (t.blockedBy.length > 0) {
118. lines.push('')
119. lines.push('Blocked by:')
120. for (r of t.blockedBy) { lines.push(refLine(r)) }
121. }
122. if (t.blocks.length > 0) {
123. lines.push('')
124. lines.push('Blocks:')
125. for (r of t.blocks) { lines.push(refLine(r)) }
126. }
127. return lines
128. }
130. // a list: { tickets } (rows, as the JSON answer) + a label of its filters ('' = all)
131. static listDocument = (rows, filters) => {
132. let lines = []
133. lines.push('# Tickets' + (filters != '' ? ' (' + filters + ')' : '') + ': ' + rows.length)
134. lines.push('')
135. for (r of rows) { lines.push(ticketLine(r)) }
136. return lines.join(NL) + NL
137. }
139. static eventHeadline = (e) => {
140. let what = e.label
141. if (e.kind == 'state') { what = 'changed the state: ' + (e.from != '' ? e.from : '?') + ' → ' + e.to }
142. if (e.kind == 'edit') {
143. let parts = []
144. if (e.subjectChanged) { parts.push('subject') }
145. if (e.summaryChanged) { parts.push('summary') }
146. what = 'edited the ' + parts.join(' and ')
147. }
148. return '### ' + e.seq + ' · ' + e.when + ' · ' + oneLine(e.author) + ' ' + what
149. }
151. // one ticket: { ticket (row), events (rows, oldest first) } as the JSON answer
152. static ticketDocument = (data) => {
153. let t = data.ticket
154. let opener = ''
155. for (e of data.events) { if (e.kind == 'created' && opener == '') { opener = oneLine(e.author) } }
156. let lines = []
157. lines.push('# ' + t.project + ' ' + t.ref + ': ' + oneLine(t.subject))
158. lines.push('')
159. let meta = 'state: ' + t.state + ' · opened ' + t.created + (opener != '' ? ' by ' + opener : '') + ' · updated ' + t.updated
160. if (t.hasOld) { meta = meta + ' · formerly ' + t.oldRef }
161. lines.push(meta)
162. lines.push(publicUrl + t.href)
163. for (l of relationLines(t)) { lines.push(l) }
164. lines.push('')
165. lines.push(t.summary != '' ? t.summary : '(no summary)')
166. lines.push('')
167. lines.push('## History')
168. for (e of data.events) {
169. lines.push('')
170. lines.push(eventHeadline(e))
171. if (e.kind == 'edit') {
172. if (e.subjectChanged) {
173. lines.push('')
174. lines.push('Subject before: ' + oneLine(e.oldSubject))
175. }
176. if (e.summaryChanged) {
177. lines.push('')
178. lines.push('Summary before:')
179. lines.push('')
180. lines.push(e.oldSummary != '' ? quoted(e.oldSummary) : '> (empty)')
181. }
182. }
183. if (e.hasText) {
184. lines.push('')
185. lines.push(e.text)
186. }
187. }
188. return lines.join(NL) + NL
189. }