@preventive/triage 1.0.0-alpha.4 → 1.0.0-alpha.40

package/common/dependency-reviews.js

@@ -0,0 +1,81 @@
+import { npmMalwareAdvisory } from '../risk/npm/malware.js'
+
+export const REVIEW_VERDICTS = {
+  accept: 'Accept',
+  'accept-with-nits': 'Accept with nits (non-blocking)',
+  'request-changes': 'Request changes',
+  reject: 'Reject',
+}
+
+// Keep non-text files in the diff and its denominator. Verdicts for them are
+// disabled for now, including when either side of a change is non-text.
+export function isReviewableFile(before, after) {
+  return [before, after].every(content => content === undefined || typeof content === 'string')
+    && [before, after].some(content => typeof content === 'string')
+}
+
+// Publication saves all changed paths and their non-text subset. Null means
+// an older snapshot without type evidence: it cannot certify full coverage.
+export function summarizeReview(entries, files, nonTextFiles = []) {
+  const verdicts = Object.keys(REVIEW_VERDICTS)
+  const excluded = new Set(nonTextFiles ?? [])
+  const checks = entries.filter(entry => nonTextFiles !== null && !excluded.has(entry.file) && verdicts.includes(entry.status))
+  const verdictLimit = verdicts.findLast(verdict => checks.some(entry => entry.status === verdict)) ?? 'accept'
+  if (files === null) return { coverage: null, checkedFiles: null, totalFiles: null, verdictLimit }
+  const checked = new Set(checks.map(entry => entry.file))
+  const checkedFiles = files.filter(file => checked.has(file)).length
+  return { coverage: checkedFiles === files.length ? 'full' : 'partial', checkedFiles, totalFiles: files.length, verdictLimit }
+}
+
+export function allowedReviewVerdicts(entries, limit = 'accept') {
+  const verdicts = Object.keys(REVIEW_VERDICTS)
+  return verdicts.slice(Math.max(verdicts.indexOf(limit), verdicts.indexOf(summarizeReview(entries, null).verdictLimit)))
+}
+
+// npm's security placeholder, identified by its provenance as well as its name.
+export function npmTakenDown({ npm: { version, manifest = {} } }) {
+  const npms = manifest.description === 'security holding package' || manifest.github?.github?.toLowerCase() === 'npm/security-holder'
+  return npms && (manifest.publisher === 'npm' || /-security(?:\.\d+)?$/u.test(version))
+}
+
+// Only findings affecting the version being reviewed constrain its verdict.
+// Socket's aggregate scores also fall for other reasons; use explicit alerts.
+// Alert identifiers: https://docs.socket.dev/docs/rule-conditions
+export function npmReviewVerdictLimit(npm, advisoryList, socket, risk) {
+  if (!npm) return 'accept'
+  const index = advisoryList?.versions?.indexOf(npm.version) ?? -1
+  const advisories = index < 0 ? [] : advisoryList.advisories.filter(advisory => advisory.affected.includes(index))
+  const alerts = npm.private ? [] : socket?.alerts ?? []
+  if (risk?.findings?.some(finding => finding.id === 'malware') || npmTakenDown({ npm }) || alerts.some(alert => alert.type === 'malware')
+    || advisories.some(advisory => npmMalwareAdvisory(advisory) || advisory.id?.startsWith('MAL-') || /^Malicious package\b/iu.test(advisory.title ?? ''))) return 'reject'
+  if (advisories.some(advisory => advisory.severity === 'critical') || alerts.some(alert => alert.type === 'criticalCVE')) return 'request-changes'
+  return 'accept'
+}
+
+export function needsPackageJsonReview(entries, files, nonTextFiles = []) {
+  return summarizeReview(entries, files, nonTextFiles).coverage === 'partial'
+    && (nonTextFiles === null || nonTextFiles.includes('package.json')
+      || !entries.some(entry => entry.file === 'package.json' && Object.keys(REVIEW_VERDICTS).includes(entry.status)))
+}
+
+const markdownText = text => text.replaceAll(/[\\`*_{}[\]<>]/gu, '\\$&').replaceAll(/\r\n?/gu, '\n').replaceAll('\n', '\n  ')
+
+export function parseReviewNotes(comment) {
+  return comment.replaceAll(/\r\n?/gu, '\n').split(/(?:^|\n)[\t ]*\*[\t ]+/u)
+    .map((text, index) => ({ text: text.trim(), bullet: index > 0 })).filter(note => note.text)
+}
+
+function auditNotes(comment, prefix = '') {
+  return parseReviewNotes(comment).map(note => `* ${prefix}${note.text.replaceAll('\n', '\n  ')}`)
+}
+
+export function auditMarkdown(review) {
+  if (review.publishedAt === null || review.revokedAt !== null || review.coverage !== 'full'
+    || !['accept', 'accept-with-nits'].includes(review.status)) return null
+  const target = `${review.package} ${review.version} ${review.integrity}`
+  const dependency = review.basePackage === null ? target
+    : review.basePackage === review.package ? `${review.package} ${review.baseVersion} -> ${review.version} ${review.integrity}`
+    : `${review.basePackage} ${review.baseVersion} -> ${target}`
+  const notes = [...review.entries.filter(entry => entry.status).flatMap(entry => auditNotes(entry.comment, `In ${markdownText(entry.file)}: `)), ...auditNotes(review.comment)]
+  return `Audited:\n\`\`\`\n${dependency}\n\`\`\`${notes.length > 0 ? `\n\nNotes:\n${notes.join('\n')}` : ''}`
+}

package/common/finding-duplicates.js

@@ -0,0 +1,58 @@
+import { effectiveSeverity, revalidateKindOf } from '@preventive/report'
+import { recordRevalidationCopies } from './revalidation-conflicts.js'
+
+// Gap-fill a derived finding only within a mergeable row. Raw report copies
+// remain intact so App and code modes can use different row partitions.
+// Provenance stays with the first copy; corrected severity keeps per-report
+// variants. Missing/null fields are gaps, never disagreements.
+const KEEPS_ITS_OWN = new Set(['correctedSeverity', 'correctedSeverityReason', 'isApp', 'isUpstream', 'isSecurity', 'source'])
+
+// Contradictory revalidate* answers disable App mode for this loaded set.
+// Retain the first answer on the derived copy; the conflict dialog exposes all
+// answers instead of presenting that arbitrary choice as the pass's verdict.
+export function mergeDuplicateFields(survivor, dup) {
+  if (!survivor || !dup || survivor === dup) return false
+  let conflicted = false
+  for (const [key, value] of Object.entries(dup)) {
+    if (key.startsWith('_') || KEEPS_ITS_OWN.has(key)) continue
+    if (value === undefined || value === null) continue
+    // The stamp is compared as the app READS it, not as the file
+    // wrote it: the reader trims and case-folds, and answers "no
+    // stamp" for anything it doesn't recognise (@preventive/report/src/finding.js
+    // revalidateKindOf). So `confirmed` and ` Confirmed ` agree, and
+    // a value the app can't read is no answer at all — it neither
+    // blocks the other copy's real stamp from landing nor takes the
+    // layer off a whole workspace for a typo.
+    if (key === 'revalidate') {
+      const theirs = revalidateKindOf(dup)
+      if (!theirs) continue
+      const mine = revalidateKindOf(survivor)
+      if (!mine) survivor[key] = value
+      else if (mine !== theirs) conflicted = true
+      continue
+    }
+    const own = survivor[key]
+    if (own === undefined || own === null) { survivor[key] = value; continue }
+    // The pass's prose either side of the stamp, compared past the
+    // whitespace two writers can differ on for the same words.
+    if (key.startsWith('revalidate') && String(own).trim() !== String(value).trim()) conflicted = true
+  }
+  return conflicted
+}
+
+// The row merger also retains the evidence behind a conflict. This must
+// run for every duplicate, including agreeing copies and missing-field fills,
+// so the eventual dialog can name the reports that actually supplied a value.
+export function mergeReportDuplicateFields(survivor, dup, reportName, conflicts) {
+  if (!survivor || !dup || survivor === dup) return
+  if (survivor.correctedSeverity || dup.correctedSeverity) {
+    survivor._correctedByReport ??= {
+      [survivor._reportName ?? '']: { severity: effectiveSeverity(survivor), reason: survivor.correctedSeverityReason },
+    }
+    survivor._correctedByReport[reportName] = { severity: effectiveSeverity(dup), reason: dup.correctedSeverityReason }
+  }
+  const copies = recordRevalidationCopies(survivor, dup, reportName)
+  if (mergeDuplicateFields(survivor, dup) || conflicts.has(survivor.id)) {
+    conflicts.set(survivor.id, { finding: survivor, copies })
+  }
+}

package/common/finding-filters.js

@@ -0,0 +1,274 @@
+// What the confidence range, the Confirmed outcome and a workspace's basic
+// App view mean for a set of rows. Pure: the view passes its current lens
+// (filters.js), and the managed server classifies team workspaces with it.
+import { displayedSeverity, revalidateKindOf } from '@preventive/report'
+
+// `tabKey` identifies an individual tab (= finding) across the view.
+export function tabKey(f) { return f.id ?? String(f._id) }
+
+// Does this row carry a judgement the pass made ABOUT a finding —
+// any stamp but `revalidation`, which names the pass's own row and
+// judges nothing. Raw for the same reason as the two above: it gates
+// the switch, and a gate that stopped seeing the stamps the moment
+// the layer came off would take the way back with it.
+export function hasRevalidateStamp(f) {
+  const kind = revalidateKindOf(f)
+  return kind !== '' && kind !== 'revalidation'
+}
+
+// What the toolbar dropdown offers, in the order it lists them —
+// answers to "did the pass leave this standing", running from yes to
+// no. Fewer options than the field has values:
+//
+//   * the `revalidation` row rides CONFIRMED — it is the pass itself,
+//     re-examining a finding it did not knock down, which is the same
+//     answer to that question;
+//   * `partial` rides it too. A partial confirmation is a yes to
+//     "does this still stand" — the pass narrowed the finding rather
+//     than knocking it down — and an option of its own would slice
+//     the standing findings in two for a distinction the reader wants
+//     the STAMP for, not a filter. It keeps its own stamp on the card.
+//   * `unknown` gets no option — a pass that couldn't tell hasn't
+//     answered it at all, so there is nothing to filter to. Those rows
+//     stay visible with no filter on, like every other row.
+export const REVALIDATE_FILTERS = [
+  { value: 'confirmed', label: 'Confirmed', kinds: ['confirmed', 'partial', 'revalidation'] },
+  { value: 'unreachable', label: 'Unreachable', kinds: ['unreachable'] },
+  { value: 'refuted', label: 'Refuted', kinds: ['refuted'] },
+]
+
+// The kinds one dropdown value covers, or null when the value names no
+// option — filters.js reads that as "no filter" rather than hiding
+// every finding behind a value it can't interpret.
+export function revalidateFilterKinds(value) {
+  return REVALIDATE_FILTERS.find((o) => o.value === value)?.kinds ?? null
+}
+
+// How finely Confirmed is drawn, once it has taken the partial rows
+// in. The toolbar cycles a chip through these inside the Confirmed row
+// (revalidate-filter.js), because "did this survive" and "how
+// completely" are one question asked twice, not two filters — and the
+// second only has an answer once the first is Confirmed.
+export const PARTIAL_MODES = ['', 'exclude', 'only']
+
+// The kinds an outcome selection ACTUALLY matches, with that switch
+// applied. All three are the same shape as every other filter here —
+// a list of kinds, matched existentially over the group — so the chip
+// narrows what Confirmed reaches rather than subtracting from it:
+//
+//   ''         everything the pass left standing: the row that IS the
+//              pass, the full confirmations, the partial ones;
+//   'exclude'  the full confirmations only. NOT "everything but the
+//              partials": a group is shown for carrying a `confirmed`
+//              row, not for lacking a `partial` one, so the pass row
+//              on its own no longer stands in for a verdict;
+//   'only'     the partial ones.
+//
+// It bites only on an option that took the partial rows in —
+// Confirmed — so a mode left set from an earlier selection can't
+// silently narrow Refuted or Unreachable, and callers can pass it
+// through without checking which option is up.
+export function activeRevalidateKinds(value, partialMode) {
+  const kinds = revalidateFilterKinds(value)
+  if (!kinds?.includes('partial')) return kinds
+  if (partialMode === 'only') return ['partial']
+  if (partialMode === 'exclude') return ['confirmed']
+  return kinds
+}
+
+// A finding's place on the 0—10 confidence scale, or undefined when it
+// has none. The one reader every confidence question goes through:
+// what the range matches, what the auto-tune counts, and whether the
+// control is offered at all (render.js hasAnyConfidence).
+//
+// Three ways to have a place:
+//
+//   * a `confidence` the analyzer scored it with;
+//   * `critical: true` — the boolean, NOT `severity: 'critical'` —
+//     which stands in for a top score;
+//   * coming from another producer at all. An import carries no
+//     confidence because its producer doesn't emit one (Claude
+//     Security's parser reads none), not because anyone was unsure —
+//     there is no doubt here for a floor to act on. Reading it as 10
+//     keeps it on screen under any floor and out only under a cap
+//     that excludes the top: `8—10` and `2—10` show it, `0—5` and
+//     `7—9` don't. It also stops one imported report from taking the
+//     range away from a workspace: an unscored finding DISABLES the
+//     control for everyone (render.js), which left the range filtering
+//     nothing and every low-confidence row on screen.
+//
+// A row the pass knocked down reads as 0 instead, where that matters
+// (voidsConfidence) — applied by the callers, since whether a finding
+// has a place at all is about the finding, not about the pass.
+export function confidenceOnScale(f) {
+  if (f.confidence !== undefined) return f.confidence
+  if (f.critical === true || f._source) return 10
+  return undefined
+}
+
+// Does this finding put itself on the scale, rather than ride the
+// stand-in confidenceOnScale hands a row that carries no score? A
+// number its producer wrote, or the `critical: true` that stands in
+// for one.
+const scoresItself = (f) => f.confidence !== undefined || f.critical === true
+
+// Is the confidence range a live control over these rows — offered,
+// and actually filtering? Two conditions, which the toolbar reads as
+// one (render.js hasAnyConfidence):
+//
+//   * every row has a place on the scale, or the first lift off 0
+//     would silently drop the ones that don't. A single analyzer
+//     finding with no confidence and no `critical: true` disables the
+//     control for the whole set;
+//   * something on screen puts ITSELF on that scale. A row riding the
+//     stand-in doesn't: a set of nothing but unscored imports is all
+//     10s by definition, and a range over one value says nothing.
+//     There the control isn't disabled, it isn't offered at all — the
+//     toolbar drops the whole block when the outcome dropdown beside
+//     it has nothing to offer either.
+//
+//     What answers this is the SCORE, not who wrote it. Asked as "not
+//     an import" it gave the same answer for every producer that emits
+//     no confidence — and the wrong one for DeepSec, which rates every
+//     finding it reports and whose words this app places on the scale
+//     itself (@preventive/report/src/parse-deepsec.js). A workspace of nothing but
+//     DeepSec reports is a real range over real numbers, and asking
+//     for a non-import took the slider, the confidence sort and the
+//     opening floor away from exactly the load whose producer had
+//     scored every row in it.
+//
+// Both halves are asked of the rows ON SCREEN by every caller, since
+// this is about a control in front of a reader.
+export function rangeApplies(groups) {
+  return groups.every((g) => g.every((f) => confidenceOnScale(f) !== undefined))
+    && groups.some((g) => g.some(scoresItself))
+}
+
+// Does the confidence floor leave this group on screen? The rule
+// matchesFilters applies (filters.js), with the upper bound at 10 so only the
+// floor bites, hoisted to the group because that is the unit the list
+// shows: a group is on screen when ANY of its rows clears the floor —
+// an unscored row only at floor 0 unless it is flagged `critical`, and
+// a row the pass knocked down reading as 0 whatever number it carries.
+function showsAtConfidence(g, min, kindOf) {
+  return g.some((f) => {
+    const conf = ['refuted', 'unreachable'].includes(kindOf(f)) ? 0 : confidenceOnScale(f)
+    return conf === undefined ? min === 0 : conf >= min
+  })
+}
+
+// The confidence floor a freshly-loaded set should OPEN on, tuned so
+// the initial view fits ~25 groups. Step up 6 → 7 → 8 until the
+// visible count is within budget; cap at 8 (the old static default).
+// Nothing carrying a confidence at all means no floor — without that
+// guard countAtMin(6) = 0 ≤ 25 lands it at 6, which then excludes
+// every finding; 0 lets the filter no-op instead, and the toolbar
+// hides the control anyway (see toolbarHtml in render.js).
+//
+// After picking the base, walk DOWN while each lower step surfaces no
+// new groups — i.e. there's a "gap" in the confidence distribution
+// below the chosen floor. Lowering for free puts the slider at the
+// natural break: e.g. picked 8, nothing at 7 or 6 but some at 5 →
+// settle at 6 (the lowest step revealing nothing new). Down to 0.
+//
+// Pure in its argument, and paired with defaultRevalidateFilter below:
+// together they are "what does this set open on", asked by ingest.js
+// on a first load and again by the App switch (events.js), which
+// reshapes the set and so has to ask again rather than keep an answer
+// that was about a different one.
+export function defaultConfidenceFloor(groups, tabs) {
+  // App mode folds the source tabs a revalidation pass already answered
+  // under its App tab. Those hidden copies must not lower the opening floor
+  // for a workspace that otherwise has the same visible rows as its App
+  // report. Keep source-only rows intact; they are real rows in the App view.
+  const visible = groups.map(tabs).filter((g) => g.length > 0)
+  if (!visible.some((g) => g.some((f) => confidenceOnScale(f) !== undefined))) return 0
+  const countAtMin = (min) => visible.reduce((n, g) =>
+    n + (g.some((f) => (confidenceOnScale(f) ?? -1) >= min) ? 1 : 0), 0)
+  let base
+  if (countAtMin(6) <= 25) base = 6
+  else if (countAtMin(7) <= 25) base = 7
+  else base = 8
+  while (base > 0 && countAtMin(base - 1) === countAtMin(base)) base--
+  return base
+}
+
+// The floor the default view will REALLY apply. The range is a
+// whole-set control: one finding on screen with no confidence and no
+// `critical: true` and render.js disables it and resets the bounds to
+// 0—10 (hasAnyConfidence there), so the auto-tuned floor never bites
+// and every row is on screen — an unscored finding is not hidden by a
+// filter that isn't running. Measuring the comparison below against a
+// floor the view is about to throw away would be measuring a screen
+// nobody sees.
+//
+// `critical: true` rides the 10 bucket in place of a score
+// (matchesFilters), so it doesn't block the range any more than a
+// number does.
+//
+// render.js asks this of the on-screen bucket and we ask it of the
+// whole set; at open time, before anything is triaged away, they are
+// the same groups.
+function effectiveFloor(groups, confMin) {
+  return rangeApplies(groups) ? confMin : 0
+}
+
+// Both the opening default and the dropdown lock use the same coverage:
+// findings represented by Confirmed rows, plus findings explicitly ruled out.
+// Read the original groups before `tabs` folds away their source members.
+export function confirmedCoverage(groups, tabs, kindOf) {
+  // A workspace may carry an un-stamped source copy from report A while
+  // report B explicitly ruled out the same id. The ruled-out copy is
+  // removed before workspace rows are merged, so it cannot vouch for its
+  // source copy during the coverage check below. Remember those ids before
+  // that projection disappears: Confirmed may hide the source copy too,
+  // even when the App finding that caused the ruling has no
+  // `revalidateInputs` list of its own.
+  const covered = new Set(groups.ruledOutIds ?? [])
+  for (const raw of groups) {
+    for (const f of raw) if (['refuted', 'unreachable'].includes(kindOf(f))) covered.add(tabKey(f))
+  }
+  for (const raw of groups) {
+    const g = tabs(raw)
+    if (g.length === 0) continue
+    if (!g.some((f) => activeRevalidateKinds('confirmed', '').includes(
+      kindOf(f) || (f._source && !f._sourcePass ? 'revalidation' : '')))) continue
+    // A folded source copy is not a cost of Confirmed, but its id is still
+    // represented by the App row. Keep all raw members in the coverage set
+    // so a duplicate source-only row from another report is recognized as
+    // the same issue rather than making Confirmed look lossy.
+    for (const f of raw) {
+      covered.add(tabKey(f))
+      // App reports can carry the source findings they represent only as
+      // `revalidateInputs`, rather than as members of the same physical row.
+      // Those inputs are still present in the App row's visible result, so a
+      // duplicate source-only row from another report must not keep the
+      // workspace on Confidence.
+      if (f.isApp && Array.isArray(f.revalidateInputs)) {
+        for (const id of f.revalidateInputs) if (id) covered.add(id)
+      }
+    }
+  }
+  return covered
+}
+
+export function confirmedIsDefault(visible, confMin, covered, kindOf) {
+  const floor = effectiveFloor(visible, confMin)
+  const shown = visible.filter((g) => showsAtConfidence(g, floor, kindOf))
+  if (shown.length === 0) return false
+  const kinds = new Set(activeRevalidateKinds('confirmed', ''))
+  if (!visible.some((g) => g.some((f) => kinds.has(kindOf(f))))) return false
+  return shown.every((g) => g.every((f) => covered.has(tabKey(f))))
+}
+
+// The same coverage test evaluates a workspace's basic App view without the
+// reader's current lens: the view and the managed server pass the lens to use.
+export function canLockConfirmed(groups, { tabs, kindOf, severityMode }) {
+  const visible = groups.map(tabs).filter((g) => g.length > 0)
+  const covered = confirmedCoverage(groups, tabs, kindOf)
+  if (!confirmedIsDefault(visible, defaultConfidenceFloor(groups, tabs), covered, kindOf)) return false
+  const floor = effectiveFloor(visible, 6)
+  return visible.every((g) => !showsAtConfidence(g, floor, kindOf)
+    || !g.some((f) => displayedSeverity(f, severityMode) !== 'low')
+    || g.every((f) => covered.has(tabKey(f))))
+}

package/common/finding-id.js

@@ -0,0 +1,47 @@
+// Session-local finding ids (see `client/triage.js`'s SESSION_ID_RE:
+// purely numeric `_id` fallbacks, handed out by an in-memory counter
+// for findings whose id couldn't be derived) are re-assigned on every
+// load, so a link built on one would point at an arbitrary other
+// finding after a reload — including in the SENDER's own tab. Those are
+// refused up front rather than silently mis-resolving. Everything else
+// the app treats as persistent — the analyzer's uuids, the deterministic
+// uuids `@preventive/report/src/finding-id.js` derives, and the codex importer's
+// finding-URL ids — is linkable, which is why this is a
+// "not session-local" test rather than a uuid-shape test.
+const SESSION_ID_RE = /^\d+$/u
+
+// Control characters can't appear in a uuid, a URL, or an OPFS filename
+// the app will hand out, so their presence means a mangled / hand-crafted
+// fragment. Rejecting them keeps a stray `\n` out of an `alert()` and out
+// of the `[data-gid]` selector the reveal path builds. A scan rather than
+// a character-class regex: matching control characters in a literal is a
+// lint error (`no-control-regex`), and spelling the range out in code is
+// clearer than the escaped equivalent anyway.
+function hasControlChar(value) {
+  for (let i = 0; i < value.length; i++) {
+    const code = value.codePointAt(i)
+    if (code < 0x20 || code === 0x7f) return true
+  }
+  return false
+}
+
+// Per-component cap. The longest legitimate value is a codex finding-URL
+// id; report names and workspace ids no longer travel in the fragment at
+// all. The cap exists so a hostile fragment can't push a megabyte of
+// text through `decodeURIComponent` + the "couldn't find it" alert.
+export const MAX_FINDING_ID_LENGTH = 512
+
+function isUsablePart(value) {
+  return typeof value === 'string'
+    && value.length > 0
+    && value.length <= MAX_FINDING_ID_LENGTH
+    && !hasControlChar(value)
+}
+
+// Whether a finding id survives a reload, i.e. whether a link built on
+// it means anything tomorrow. Callers use this to decide whether to
+// OFFER a link at all (the per-finding Link button hides itself for a
+// session-local id) rather than handing out one that silently rots.
+export function isLinkableFindingId(id) {
+  return isUsablePart(id) && !SESSION_ID_RE.test(id)
+}

package/common/github-issue-labels.d.ts

@@ -0,0 +1 @@
+export function newIssueLabels(isSecurity?: boolean, configured?: string): string[]

package/common/github-issue-labels.js

@@ -0,0 +1,11 @@
+// Shared by GitHub's prefilled form and managed API issue creation.
+export function newIssueLabels(isSecurity = false, configured = '') {
+  const seen = new Set()
+  return ['deepview', ...(isSecurity ? ['security'] : []), ...configured.split(',')]
+    .map(label => label.trim()).filter(label => {
+      const key = label.toLowerCase()
+      if (!label || seen.has(key)) return false
+      seen.add(key)
+      return true
+    })
+}

package/common/github-pr.ts

@@ -0,0 +1,56 @@
+const MAX_PULL_REQUEST_URL = 2048
+
+export interface PullRequestRef { repo: string; number: number }
+export type GithubFixRef = PullRequestRef & { kind: 'pull' | 'issue' }
+export type GithubFixStatus = 'open' | 'draft' | 'closed' | 'merged'
+export type GithubIssueClosedReason = 'completed' | 'not_planned' | 'duplicate' | 'unknown'
+export type GithubFixResult = { url: string } & (
+  { title: string; description: string | null; status: GithubFixStatus; stateReason: GithubIssueClosedReason | null } | { error: 'unavailable' }
+)
+
+// Unknown closure reasons must never imply that an issue was completed.
+export function githubIssueClosedReason(value: unknown): GithubIssueClosedReason {
+  return value === 'completed' || value === 'not_planned' || value === 'duplicate' ? value : 'unknown'
+}
+
+export function isGithubRepoName(value: string): boolean {
+  const [owner, repo, extra] = value.split('/')
+  return extra === undefined && owner !== undefined && repo !== undefined
+    && owner.length <= 39 && /^[a-zA-Z\d](?:-?[a-zA-Z\d])*$/u.test(owner)
+    && repo.length <= 100 && repo !== '.' && repo !== '..' && /^[a-zA-Z\d._-]+$/u.test(repo)
+}
+
+// Only identify the repository and PR number. This never supplies an API URL:
+// the server must match a team repository and use its stored full name.
+function parseGithubNumberedUrl(value: unknown, path: RegExp): PullRequestRef | null {
+  if (typeof value !== 'string' || value.length > MAX_PULL_REQUEST_URL) return null
+  let url: URL
+  try { url = new URL(value) } catch { return null }
+  if (url.href !== value || url.origin !== 'https://github.com' || url.username || url.password) return null
+  const match = path.exec(url.pathname)
+  if (!match) return null
+  const repo = `${match[1]}/${match[2]}`
+  const number = Number(match[3])
+  if (!isGithubRepoName(repo) || !Number.isSafeInteger(number) || number <= 0) return null
+  return { repo, number }
+}
+
+export function parseGithubPrUrl(value: unknown): PullRequestRef | null {
+  return parseGithubNumberedUrl(value, /^\/([^/]+)\/([^/]+)\/pull\/(\d+)(?:\/(?:files|commits|checks))?\/?$/u)
+}
+
+export function parseGithubIssueUrl(value: unknown): PullRequestRef | null {
+  return parseGithubNumberedUrl(value, /^\/([^/]+)\/([^/]+)\/issues\/(\d+)\/?$/u)
+}
+
+export function parseGithubFixUrl(value: unknown): GithubFixRef | null {
+  const pr = parseGithubPrUrl(value)
+  if (pr) return { ...pr, kind: 'pull' }
+  const issue = parseGithubIssueUrl(value)
+  return issue ? { ...issue, kind: 'issue' } : null
+}
+
+// Browser-only deduplication key; never used to construct a server API call.
+export function githubFixKey(ref: GithubFixRef): string {
+  return `${ref.repo.toLowerCase()}#${ref.kind}:${ref.number}`
+}

package/common/gzip.js

@@ -0,0 +1,59 @@
+// Gzip helpers built on the platform CompressionStream /
+// DecompressionStream. Centralised so the half-dozen call sites
+// (storage, triage / workspace export + import, sync-crypto) share
+// one implementation of the Blob → stream → Response plumbing instead
+// of hand-copying it. Bytes in / bytes out is the primitive; the text
+// helpers run the bytes through `common/utf8.js` so the same
+// fatal-on-invalid / BOM-preserving decode rules apply everywhere.
+//
+// `deflate` (raw, no gzip framing) is intentionally NOT covered here —
+// `triage.js` uses it for its own at-rest blob and must stay distinct
+// from the gzip-magic sniffing the bundles / import paths rely on.
+
+import { decodeUtf8, encodeUtf8 } from './utf8.js'
+
+export async function gzipBytes(bytes) {
+  const stream = new Blob([bytes]).stream().pipeThrough(new CompressionStream('gzip'))
+  return new Uint8Array(await new Response(stream).arrayBuffer())
+}
+
+// `maxBytes` (optional) caps the DECOMPRESSED size: gzip expands up to
+// ~1032:1, so a small hostile payload can balloon to GiBs and OOM the
+// process before any content validation runs. Callers decompressing
+// peer-controlled bytes (sync-crypto's inbound changesets) pass a cap;
+// the read then aborts with a RangeError the moment the budget is crossed,
+// instead of materialising the full expansion. Uncapped callers keep
+// the one-shot Response read.
+export async function gunzipBytes(bytes, { maxBytes } = {}) {
+  const stream = new Blob([bytes]).stream().pipeThrough(new DecompressionStream('gzip'))
+  if (maxBytes == null) return new Uint8Array(await new Response(stream).arrayBuffer())
+  const reader = stream.getReader()
+  const chunks = []
+  let total = 0
+  for (;;) {
+    const { value, done } = await reader.read()
+    if (done) break
+    total += value.length
+    if (total > maxBytes) {
+      // Cancel so the DecompressionStream stops inflating the rest.
+      try { await reader.cancel() } catch {}
+      throw new RangeError(`gunzipBytes: decompressed size exceeds ${maxBytes}-byte cap`)
+    }
+    chunks.push(value)
+  }
+  const out = new Uint8Array(total)
+  let offset = 0
+  for (const chunk of chunks) {
+    out.set(chunk, offset)
+    offset += chunk.length
+  }
+  return out
+}
+
+export async function gzipText(text) {
+  return await gzipBytes(encodeUtf8(text))
+}
+
+export async function gunzipToText(bytes) {
+  return decodeUtf8(await gunzipBytes(bytes))
+}

package/common/line-diff.d.ts

@@ -0,0 +1,8 @@
+// Type declarations for `common/line-diff.js`, for `.ts` callers.
+
+// Lines `a[a0..a1)` replaced by `b[b0..b1)`.
+export interface ChangeBlock { a0: number; a1: number; b0: number; b1: number }
+
+export function textLines(text: string): string[]
+export function changeBlocks(before: string, after: string, ignoreWhitespace?: boolean): ChangeBlock[]
+export function blocksHold(before: string, after: string, blocks: unknown, ignoreWhitespace?: boolean): boolean