@supersuit/suggest-a-change 0.1.13 → 0.2.0

package/src/contract.mjs

@@ -14,54 +14,122 @@ export const CEILINGS = {
   perPersonPerDay: 20,
 };
 
-export const STATUSES = ["on-phone", "received", "with-freeda", "planned", "waiting-on-owner", "being-made", "live", "sent-to-template", "filed", "not-now"];
-export const END = ["live", "sent-to-template", "filed", "not-now"];
-// The moves the person who suggested a change hears about: the work starting, and every end. The planning steps stay quiet.
-export const TOLD = ["being-made", ...END];
-
-// actor: who PERFORMS this step (design section 7): sent by the person, received by the app, with Pluma by the Mac. A Helm on the owner's Mac posts straight into
-// the inbox, so a report may go from the phone to Pluma without the hosted app's "received". The owner may decline
-// ("not-now") before Pluma has a plan or before she asks: a report she cannot plan would otherwise have no exit.
+// A suggestion becomes one ordinary GitHub issue (suggestions-as-github-issues design, section 3), so the statuses a
+// person sees are GitHub's: not sent, received, held before filing, then the issue's own open and closed states.
+export const STATUSES = ["on-phone", "received", "held", "open", "done", "not-planned"];
+// Closed on GitHub. A closed issue can be reopened, so an end is not final: it can go back to "open".
+export const END = ["done", "not-planned"];
+// The moves the person who suggested a change hears about: the issue existing, and every close.
+export const TOLD = ["open", ...END];
+
+// actor: who PERFORMS this step. Sent by the person, received by the app, held for the owner (the privacy catch stopped
+// it, or the account cannot file yet), filed by the Mac (or an app's own server), closed or reopened on GitHub. A Helm on
+// the owner's Mac posts straight there, so a report may go from the phone to held or open without the app's "received".
 export const FLOW = {
-  "on-phone": { actor: "person", next: ["received", "with-freeda"] },
-  "received": { actor: "app", next: ["with-freeda"] },
-  "with-freeda": { actor: "mac", next: ["planned", "not-now"] },
-  "planned": { actor: "freeda", next: ["waiting-on-owner", "being-made", "not-now"] },
-  "waiting-on-owner": { actor: "owner", next: ["being-made", "filed", "not-now"] },
-  "being-made": { actor: "freeda", next: ["live", "sent-to-template", "filed", "not-now"] },
-  "live": { actor: "freeda", next: [] },
-  "sent-to-template": { actor: "freeda", next: [] },
-  "filed": { actor: "freeda", next: [] },
-  "not-now": { actor: "owner", next: [] },
+  "on-phone": { actor: "person", next: ["received", "held", "open"] },
+  "received": { actor: "app", next: ["held", "open", "not-planned"] },
+  "held": { actor: "owner", next: ["open", "not-planned"] },
+  "open": { actor: "mac", next: ["done", "not-planned"] },
+  "done": { actor: "github", next: ["open"] },
+  "not-planned": { actor: "github", next: ["open"] },
+};
+
+// THE OLD STATUSES (0.1.x) STAY READABLE. Each folds into what it now means: a report the old pipeline was still
+// working on has not been filed yet (the Mac files it), one it shipped or passed on is done, one declined is not planned.
+export const LEGACY = {
+  "with-freeda": "received",
+  "planned": "received",
+  "waiting-on-owner": "received",
+  "being-made": "received",
+  "live": "done",
+  "sent-to-template": "done",
+  "filed": "done",
+  "not-now": "not-planned",
 };
+/** The status this one means now: a legacy status folded, anything else as it is. */
+export const currentStatus = (s) => LEGACY[s] ?? s;
 
-export const mayMove = (from, to) => Boolean(FLOW[from]?.next.includes(to));
+export const mayMove = (from, to) => Boolean(FLOW[currentStatus(from)]?.next.includes(to));
 
-// The design's status table (section 2), word for word. "planned" is a step inside Pluma's work
-// that the table does not name for a person, so it reads as "With Pluma".
+// The design's status table (section 3), word for word.
+const issueWords = (issue) => (Number.isInteger(issue?.number) ? `Filed as issue #${issue.number}` : "Filed as an issue");
 const TABLE = {
-  "on-phone": ["On this phone", () => "Not sent yet; it will send when there is a connection"],
-  "received": ["Received", () => "The app has it, safely stored"],
-  "with-freeda": ["With Pluma", (o) => `${o}'s Mac has picked it up`],
-  "planned": ["With Pluma", (o) => `${o}'s Mac has picked it up`],
-  "waiting-on-owner": [null, (o) => `Pluma has a plan and is asking ${o}`],
-  "being-made": ["Being made", () => "A session is working on it; the current step shows underneath"],
-  "live": ["Done", () => "Shipped in the app, with the date it went live"],
-  "sent-to-template": ["Sent to the template", () => "It became a change to the template every copy of this app uses; it reaches this app once merged"],
-  "filed": ["Filed", () => "It was passed to whoever owns the problem"],
-  "not-now": ["Not now", (o) => `${o} decided against it, with the one-line reason if given`],
+  "on-phone": [() => "On this phone", () => "Not sent yet; it will send when there is a connection"],
+  "received": [() => "Received", () => "The app has it, safely stored"],
+  "held": [(o) => `Waiting on ${o}`, (o) => `${o} looks at it before it is filed`],
+  "open": [() => "Open", (o, issue) => issueWords(issue)],
+  "done": [() => "Done", () => "Closed as completed"],
+  "not-planned": [() => "Not planned", () => "Closed as not planned, with the reason if one was given"],
 };
 const row = (status) => {
-  if (!TABLE[status]) throw new Error(`${status} is not a status`);
-  return TABLE[status];
+  const s = currentStatus(status);
+  if (!TABLE[s]) throw new Error(`${status} is not a status`);
+  return TABLE[s];
 };
-export const wordsFor = (status, { owner } = {}) => row(status)[0] ?? `Waiting on ${owner}`;
-export const meaningFor = (status, { owner } = {}) => row(status)[1](owner);
+export const wordsFor = (status, { owner } = {}) => row(status)[0](owner);
+export const meaningFor = (status, { owner, issue } = {}) => row(status)[1](owner, issue);
+
+// HOW TO REACH THE SENDER: what the app already knows of them, so whoever fixes it can say thanks or ask a question.
+const CONTACT_EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]{2,}$/;
+const CONTACT_PHONE = /^\+?[0-9][0-9 ().-]{5,24}$/;
+export function validContact(c) {
+  if (!c || typeof c !== "object" || Array.isArray(c)) return ["who.contact is not an object"];
+  const errs = [];
+  for (const k of Object.keys(c)) if (!["email", "phone", "handle"].includes(k)) errs.push(`who.contact.${k} is not one of email, phone, handle`);
+  if (c.email !== undefined && (typeof c.email !== "string" || c.email.length > 254 || !CONTACT_EMAIL.test(c.email))) errs.push("who.contact.email is not an email address");
+  if (c.phone !== undefined && (typeof c.phone !== "string" || !CONTACT_PHONE.test(c.phone))) errs.push("who.contact.phone is not a phone number");
+  if (c.handle !== undefined && (typeof c.handle !== "string" || !c.handle.trim() || c.handle.length > 100 || /[\r\n]/.test(c.handle))) errs.push("who.contact.handle is not a short one-line handle");
+  return errs;
+}
+
+// THE CONTEXT a report carries so it can be fixed: labelled items, each with why it is shared, and the trail that led here.
+export const CONTEXT_CEILINGS = { items: 40, routes: 10, taps: 20, errors: 10 };
+const shortText = (v, max) => typeof v === "string" && v.length <= max;
+/** A time as the module writes one: ISO 8601 with a zone, at most 40 characters, so a time field can never carry text. */
+const ISO_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d{1,9})?)?(Z|[+-]\d{2}:\d{2})$/;
+export const isIsoTime = (v) => typeof v === "string" && v.length <= 40 && ISO_TIME.test(v);
+export function validContext(ctx) {
+  if (!ctx || typeof ctx !== "object" || Array.isArray(ctx)) return ["context is not an object"];
+  const errs = [];
+  const list = (name, max, check) => {
+    const v = ctx[name];
+    if (v === undefined) return;
+    if (!Array.isArray(v)) { errs.push(`context.${name} is not a list`); return; }
+    if (v.length > max) errs.push(`context.${name} has ${v.length} entries; the ceiling is ${max}`);
+    v.forEach((x, i) => { const e = x && typeof x === "object" ? check(x) : "is not an object"; if (e) errs.push(`context.${name}.${i} ${e}`); });
+  };
+  list("items", CONTEXT_CEILINGS.items, (x) =>
+    !shortText(x.key, 40) || !/^[A-Za-z0-9:_-]+$/.test(x.key) ? "has no plain key"
+      : !shortText(x.label, 80) || !x.label ? "has no short label"
+      : !shortText(x.value, 500) ? "has no value of at most 500 characters"
+      : !shortText(x.why, 200) || !x.why.trim() ? "does not say why it is shared" : null);
+  list("routes", CONTEXT_CEILINGS.routes, (x) => (!shortText(x.route, 300) || /[?#]/.test(x.route) ? "is not a route without its query" : !isIsoTime(x.at) ? "has no ISO time" : null));
+  list("taps", CONTEXT_CEILINGS.taps, (x) => (!shortText(x.label, 80) ? "has no label of at most 80 characters" : !isIsoTime(x.at) ? "has no ISO time" : null));
+  list("errors", CONTEXT_CEILINGS.errors, (x) => (!shortText(x.message, 300) ? "has no message of at most 300 characters" : x.frame !== undefined && !shortText(x.frame, 200) ? "has a frame over 200 characters" : !isIsoTime(x.at) ? "has no ISO time" : null));
+  return errs;
+}
+
+const REPO = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+/** A GitHub "owner/name": two plain segments, neither "." nor "..", so it can never walk out of /repos/ in a URL.
+ *  @param {unknown} s @returns {s is string} */
+export const isRepoName = (s) => typeof s === "string" && REPO.test(s) && !s.split("/").some((p) => p === "." || p === "..");
+/** The issue a report became: `{ repo: "owner/name", number, url }`, the url on github.com. Problems as a list. */
+export function validIssue(issue) {
+  if (!issue || typeof issue !== "object" || Array.isArray(issue)) return ["issue is not an object"];
+  const errs = [];
+  if (!isRepoName(issue.repo)) errs.push("issue.repo is not owner/name");
+  if (!Number.isInteger(issue.number) || issue.number < 1) errs.push("issue.number is not a positive whole number");
+  if (typeof issue.url !== "string" || !issue.url.startsWith("https://github.com/")) errs.push("issue.url is not a https://github.com/ link");
+  return errs;
+}
 
 const ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789";
+// The platform's secure random source where there is one (every browser and Node 19+), Math.random only where there is not.
 const randomSix = () => {
+  const c = globalThis.crypto;
+  const bytes = typeof c?.getRandomValues === "function" ? c.getRandomValues(new Uint8Array(6)) : Uint8Array.from({ length: 6 }, () => Math.floor(Math.random() * 256));
   let s = "";
-  for (let i = 0; i < 6; i++) s += ALPHABET[Math.floor(Math.random() * ALPHABET.length)];
+  for (const b of bytes) s += ALPHABET[b % ALPHABET.length];
   return s;
 };
 export function newReportId(now = new Date(), rand = randomSix) {
@@ -95,8 +163,13 @@ export function validateReport(raw, { ceilings = CEILINGS } = {}) {
   if (!ID.test(String(raw.id ?? ""))) errs.push("the id is not a report id");
   if (!KINDS.includes(raw.kind)) errs.push(`kind ${JSON.stringify(raw.kind)} is not one of ${KINDS.join(", ")}`);
   if (!ROLES.includes(raw.who?.role)) errs.push(`role ${JSON.stringify(raw.who?.role)} is not one of ${ROLES.join(", ")}`);
-  for (const p of findKey(raw, "email")) errs.push(`${p}: a report never carries an email`);
+  // The one place an email may sit is the sender's own way to be reached, who.contact.email, and only there.
+  for (const p of findKey(raw, "email")) if (p !== "report.who.contact.email") errs.push(`${p}: a report never carries an email`);
+  if (raw.who?.contact !== undefined) errs.push(...validContact(raw.who.contact));
+  if (raw.diagnostics?.at !== undefined && !isIsoTime(raw.diagnostics.at)) errs.push("diagnostics.at is not an ISO time");
+  if (raw.context !== undefined) errs.push(...validContext(raw.context));
   if (String(raw.where?.route ?? "").includes("?")) errs.push("where.route keeps a query string");
+  if (raw.issue !== undefined) errs.push(...validIssue(raw.issue));
   for (const k of Object.keys(raw.diagnostics ?? {})) {
     if (!DIAGNOSTIC_KEYS.includes(k)) errs.push(`diagnostics.${k} is not one of ${DIAGNOSTIC_KEYS.join(", ")}`);
   }

package/src/github/api.ts

@@ -0,0 +1,169 @@
+// THE GITHUB CALLS. Web-standard fetch only, injectable so tests and any runtime can pass their own. The token is the
+// filer's (`gh auth token` on a Mac) or an app server's own; it is sent to api.github.com and nowhere else.
+import { isRepoName } from '../contract.mjs'
+import { composeIssue, type ComposeOptions, type Draft } from './compose.ts'
+/** An issue carries at most this many labels (the composer writes two). */
+const MAX_LABELS = 10
+import type { AttachmentHost, AttachmentFile } from './hosts.ts'
+import { canFileDirectly, type RelayFiler } from './filer.ts'
+
+export type Fetch = typeof globalThis.fetch
+export interface GitHubConfig { repo: string; token: string; fetch?: Fetch; /** Default https://api.github.com */ api?: string }
+
+export class GitHubError extends Error {
+  status: number
+  body: unknown
+  constructor(message: string, status: number, body: unknown) { super(message); this.name = 'GitHubError'; this.status = status; this.body = body }
+}
+
+const API = 'https://api.github.com'
+function repoOf(repo: string): string {
+  if (!isRepoName(repo)) throw new Error(`${JSON.stringify(repo)} is not owner/name`)
+  return repo
+}
+
+/** One REST call. Answers the parsed body, or throws a GitHubError carrying GitHub's status. */
+export async function github(cfg: { token: string; fetch?: Fetch; api?: string }, method: string, path: string, body?: unknown): Promise<{ status: number; body: any }> {
+  const f = cfg.fetch ?? globalThis.fetch
+  const res = await f(`${cfg.api ?? API}${path}`, {
+    method,
+    headers: {
+      accept: 'application/vnd.github+json',
+      authorization: `Bearer ${cfg.token}`,
+      'x-github-api-version': '2022-11-28',
+      ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
+    },
+    ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+  })
+  const textBody = await res.text()
+  let parsed: unknown = null
+  try { parsed = textBody ? JSON.parse(textBody) : null } catch { parsed = textBody }
+  if (!res.ok) throw new GitHubError(`GitHub answered ${res.status} to ${method} ${path}`, res.status, parsed)
+  return { status: res.status, body: parsed }
+}
+
+const COLORS: Record<string, string> = { bug: 'd73a4a', enhancement: 'a2eeef', feedback: 'c5def5' }
+
+/** Opens one issue. Missing labels are created first; one that exists (422) or that this account may not create
+ *  (403/404: a read-only filer) is skipped, and GitHub then keeps only the labels the filer may set. */
+export async function fileIssue(cfg: GitHubConfig, issue: { title: string; body: string; labels: string[] }): Promise<{ number: number; url: string }> {
+  const repo = repoOf(cfg.repo)
+  const labels = issue.labels.filter((l) => typeof l === 'string' && l.length && l.length <= 50).slice(0, MAX_LABELS)
+  for (const name of labels) {
+    try { await github(cfg, 'POST', `/repos/${repo}/labels`, { name, color: COLORS[name] ?? 'ededed' }) } catch (e) {
+      if (!(e instanceof GitHubError) || ![403, 404, 422].includes(e.status)) throw e
+    }
+  }
+  const got = await github(cfg, 'POST', `/repos/${repo}/issues`, { title: issue.title, body: issue.body, labels })
+  return { number: got.body.number, url: got.body.html_url }
+}
+
+/** Replaces an issue's body (the filer's own issue: read access is enough to edit what you opened). */
+export async function updateIssue(cfg: GitHubConfig, number: number, change: { body: string }): Promise<void> {
+  await github(cfg, 'PATCH', `/repos/${repoOf(cfg.repo)}/issues/${number}`, { body: change.body })
+}
+
+/** A follow-up the person added later, as a comment on the same issue. */
+export async function addFollowUp(cfg: GitHubConfig, number: number, body: string): Promise<{ id: number; url: string }> {
+  const got = await github(cfg, 'POST', `/repos/${repoOf(cfg.repo)}/issues/${number}/comments`, { body })
+  return { id: got.body.id, url: got.body.html_url }
+}
+
+export interface IssueState { repo: string; number: number; state: string | null; stateReason: string | null; /** First line of the last comment, on a closed issue: the reason. */ reason?: string; missing?: true }
+
+/** The state of many issues in one GraphQL call (in chunks of 50). Repo names travel as variables, never in the query. */
+export async function issueStates(cfg: { token: string; fetch?: Fetch; api?: string }, issues: { repo: string; number: number }[]): Promise<IssueState[]> {
+  const out: IssueState[] = []
+  for (let start = 0; start < issues.length; start += 50) {
+    const chunk = issues.slice(start, start + 50)
+    const vars: Record<string, string | number> = {}
+    const decl: string[] = []
+    const parts: string[] = []
+    chunk.forEach((it, i) => {
+      const [owner, name] = repoOf(it.repo).split('/')
+      if (!Number.isInteger(it.number) || it.number < 1) throw new Error(`${it.number} is not an issue number`)
+      vars[`o${i}`] = owner; vars[`n${i}`] = name; vars[`k${i}`] = it.number
+      decl.push(`$o${i}: String!, $n${i}: String!, $k${i}: Int!`)
+      parts.push(`i${i}: repository(owner: $o${i}, name: $n${i}) { issue(number: $k${i}) { state stateReason comments(last: 1) { nodes { body } } } }`)
+    })
+    const query = `query(${decl.join(', ')}) { ${parts.join(' ')} }`
+    const got = await github(cfg, 'POST', '/graphql', { query, variables: vars })
+    const data = got.body?.data
+    if (!data) throw new GitHubError('GitHub answered no data to the issue state query', got.status, got.body)
+    chunk.forEach((it, i) => {
+      const issue = data[`i${i}`]?.issue
+      if (!issue) { out.push({ repo: it.repo, number: it.number, state: null, stateReason: null, missing: true }); return }
+      const row: IssueState = { repo: it.repo, number: it.number, state: issue.state, stateReason: issue.stateReason ?? null }
+      const last = issue.comments?.nodes?.at(-1)?.body
+      const line = typeof last === 'string' ? last.trim().split('\n')[0].trim() : ''
+      if (String(issue.state).toUpperCase() === 'CLOSED' && line) row.reason = line
+      out.push(row)
+    })
+  }
+  return out
+}
+
+/** GitHub's state onto the person's three: open, done (closed as completed), not planned (as not planned, or a duplicate). */
+export function issueStatus({ state, stateReason }: { state: string | null; stateReason?: string | null }): 'open' | 'done' | 'not-planned' {
+  if (String(state).toUpperCase() !== 'CLOSED') return 'open'
+  return ['NOT_PLANNED', 'DUPLICATE'].includes(String(stateReason).toUpperCase()) ? 'not-planned' : 'done'
+}
+
+export interface FileSuggestionInput {
+  /** The report (redacted already, when the privacy catch asked for it). */
+  report: Draft
+  compose?: Omit<ComposeOptions, 'attachmentUrls' | 'pending'>
+  /** The bytes of the report's media and voice files, by the names the report gives them. */
+  files: AttachmentFile[]
+  attachments?: AttachmentHost
+}
+export interface FiledSuggestion { number: number; url: string; attached: Record<string, string>; pending: string[]; /** How it was filed: with the filer's own token, or through a suggestion relay. */ via: 'direct' | 'relay' }
+/** Where to file: the repo, the filer's own token when they have one, and a relay for when that token cannot file there. */
+export type FilingConfig = Omit<GitHubConfig, 'token'> & { token?: string; relay?: RelayFiler; /** The app's id in the relay's own table, when filing through one. */ app?: string }
+
+const reportFiles = (r: Draft) => [...(r.media ?? []), ...(r.voice ?? [])].map((f) => f.file)
+
+/** Saves the files the issue is still waiting for, then edits their links into the body. Call again later with the
+ *  same `attached` to finish what failed: the issue keeps saying a file is coming until it is there. */
+export async function attachPending(cfg: GitHubConfig, input: FileSuggestionInput & { number: number; attached?: Record<string, string> }): Promise<{ attached: Record<string, string>; pending: string[] }> {
+  const attached = { ...(input.attached ?? {}) }
+  const wanted = new Set(reportFiles(input.report))
+  let added = 0
+  if (input.attachments) {
+    for (const f of input.files) {
+      if (!wanted.has(f.name) || attached[f.name]) continue
+      try {
+        attached[f.name] = (await input.attachments.put({ repo: cfg.repo, issue: input.number, reportId: String(input.report.id), }, f)).url
+        added++
+      } catch { /* left pending: the issue still says it is coming, and a later call retries it */ }
+    }
+  }
+  if (added) await updateIssue(cfg, input.number, { body: composeIssue(input.report, { ...input.compose, attachmentUrls: attached }).body })
+  return { attached, pending: [...wanted].filter((n) => !attached[n]) }
+}
+
+/** The whole filing. With a token that can see the repo it files directly, in the order that never shows an incomplete
+ *  issue as complete: open the issue saying what is being added (opening it is the proof the filer can file there),
+ *  save each file against that issue, then edit the links in. With no token, or one that cannot see the repo, and a
+ *  `relay`, the relay files it (the files, then the issue, as its App) for someone with no access at all. */
+export async function fileSuggestion(cfg: FilingConfig, input: FileSuggestionInput): Promise<FiledSuggestion> {
+  const direct = cfg.token ? (!cfg.relay || await canFileDirectly({ repo: cfg.repo, token: cfg.token, fetch: cfg.fetch, api: cfg.api })) : false
+  if (!direct) {
+    if (!cfg.relay) throw new Error('fileSuggestion needs a token that can file on the repo, or a relay')
+    const made = await cfg.relay.file({
+      repo: cfg.repo, ...(cfg.app ? { app: cfg.app } : {}), report: input.report as Record<string, unknown>, files: input.files,
+      ...(input.compose?.filerName ? { filerName: input.compose.filerName } : {}),
+      ...(input.compose?.appName ? { appName: input.compose.appName } : {}),
+      ...(input.compose?.appVersion ? { appVersion: input.compose.appVersion } : {}),
+      ...(input.compose?.transcript ? { transcript: input.compose.transcript } : {}),
+    })
+    return { ...made, attached: {}, pending: [], via: 'relay' }
+  }
+  const own = { ...cfg, token: cfg.token as string }
+  const hasFiles = reportFiles(input.report).length > 0
+  const first = composeIssue(input.report, { ...input.compose, pending: hasFiles })
+  const issue = await fileIssue(own, first)
+  if (!hasFiles) return { ...issue, attached: {}, pending: [], via: 'direct' }
+  const rest = await attachPending(own, { ...input, number: issue.number })
+  return { ...issue, ...rest, via: 'direct' }
+}