@preventive/triage 1.0.0-alpha.3 → 1.0.0-alpha.30

package/common/managed/triage.ts

@@ -0,0 +1,83 @@
+// Per-finding triage annotations on a managed server — shared by the server
+// (which stores one row per finding id, validates the wire shape, and decides
+// per report which ids a viewer may read or write) and the managed client
+// (which mirrors entries into its local triage map). Keyed by finding id
+// alone, like that map: reports mostly repeat one another (a re-scan of the
+// same code carries the same finding ids), and a finding's triage is shared by
+// every report that carries it. A wire entry carries the four server-persisted
+// fields below, or is null for a cleared entry (the server's tombstone); the
+// client's `ignoredReports` deliberately does NOT ride this wire — the
+// per-report ignore is a client-local concept keyed by report name.
+export type TriageBucket = 'inprogress' | 'fixed' | 'invalid' | 'deleted'
+
+export const TRIAGE_BUCKETS: readonly TriageBucket[] = ['inprogress', 'fixed', 'invalid', 'deleted']
+
+// One finding's server-side triage entry (also the write shape — writes
+// replace the whole entry). Absent fields are unset; `flagged` is tri-state:
+// absent = never set, `true` = flagged, `false` = an explicit un-flag
+// tombstone that must round-trip (see client/state.ts TriageEntry).
+export type TriageEntryPatch = {
+  color?: string
+  triage?: TriageBucket
+  // Legacy triage history/migration only. New comments use separate records;
+  // the managed triage write endpoint rejects this field.
+  comment?: string
+  fix?: string
+  flagged?: boolean
+}
+
+// Length caps enforced at the write endpoint so one entry can't balloon a row.
+export const MAX_TRIAGE_TEXT = 10_000
+export const MAX_TRIAGE_COLOR = 50
+
+// Caps on one write request as a whole — shared with the client, which batches
+// within them: entries per request, the finding-id length (real ids are 36-char
+// uuids), and the JSON body (the server's small default is too small for entry
+// batches, which carry free text).
+export const MAX_TRIAGE_ENTRIES = 200
+export const MAX_FINDING_ID = 100
+export const MAX_TRIAGE_BODY_BYTES = 262_144
+
+// The most trail events one history read returns (newest first). Retention is
+// the server's: everything is kept unless its TRIAGE_HISTORY_LIMIT says
+// otherwise.
+export const MAX_TRIAGE_HISTORY = 200
+
+export function isTriageBucket(x: unknown): x is TriageBucket {
+  return typeof x === 'string' && (TRIAGE_BUCKETS as readonly string[]).includes(x)
+}
+
+// Coerce one wire entry (a request-body value) into a clean patch. `null`
+// means "clear the entry"; a malformed value (wrong type, unknown bucket,
+// over-cap string, non-boolean flagged) is 'invalid' so the endpoint 400s
+// rather than store garbage. Null/empty-string fields count as absent (an
+// absent field is cleared anyway under whole-entry replace); unknown keys are
+// ignored.
+export function parseTriageEntryPatch(x: unknown): TriageEntryPatch | null | 'invalid' {
+  if (x === null) return null
+  if (typeof x !== 'object' || Array.isArray(x)) return 'invalid'
+  const o = x as Record<string, unknown>
+  const out: TriageEntryPatch = {}
+  const color = o['color']
+  if (color != null) {
+    if (typeof color !== 'string' || color.length > MAX_TRIAGE_COLOR) return 'invalid'
+    if (color !== '') out.color = color
+  }
+  const triage = o['triage']
+  if (triage != null) {
+    if (!isTriageBucket(triage)) return 'invalid'
+    out.triage = triage
+  }
+  for (const key of ['comment', 'fix'] as const) {
+    const v = o[key]
+    if (v == null) continue
+    if (typeof v !== 'string' || v.length > MAX_TRIAGE_TEXT) return 'invalid'
+    if (v !== '') out[key] = v
+  }
+  const flagged = o['flagged']
+  if (flagged != null) {
+    if (typeof flagged !== 'boolean') return 'invalid'
+    out.flagged = flagged
+  }
+  return out
+}

package/common/save-error-reason.ts

@@ -15,8 +15,11 @@
 //                   `session.error` until `dismissError()`.
 //   `busy`        — per-socket inflight cap dropped the save
 //                   (transport backpressure). Recoverable; the
-//                   client clears `pending` and re-arms
-//                   `pendingSave` for the next natural trigger.
+//                   client clears `pending`, re-arms `pendingSave`,
+//                   and schedules a short timed retry — without the
+//                   timer an idle client (no further edit /
+//                   broadcast / reconnect) would strand its last
+//                   edit unsynced indefinitely.
 //   `stale-base`  — concurrent commit advanced the head past the
 //                   client's claimed base. The server emits the
 //                   typed frame AFTER a `workspace-state` catch-up
@@ -25,11 +28,21 @@
 //                   and this frame's handler then early-returns
 //                   on the missing pending. So `stale-base` is
 //                   NOT in the recoverable set: in the happy path
-//                   the recoverable branch is unreachable; in the
-//                   pathological case where wire order flipped,
-//                   we'd rather mark the session errored (visible
-//                   via UI + recoverable via `dismissError()`)
-//                   than silently swallow a state divergence.
+//                   the recoverable branch is unreachable. When
+//                   `pending` DOES survive to this frame — the
+//                   catch-up was empty (chain gone: wiped /
+//                   migrated DB) or didn't apply (chain rebuilt
+//                   past the client's base) — the client answers
+//                   with ONE full-state-push reset per recovery
+//                   cycle (re-anchor at base=null; safe because
+//                   the server's null-safe head CAS rejects a
+//                   base=null root against any non-empty chain;
+//                   see `staleResetAttempted` in triage-sync.ts).
+//                   A repeat within the cycle marks the session
+//                   errored (visible via UI + recoverable via
+//                   `dismissError()`) rather than looping
+//                   full-state saves against a relay that keeps
+//                   rejecting them.
 
 export type SaveErrorReason = 'too-large' | 'busy' | 'stale-base'
 

package/common/scan-server.ts

@@ -0,0 +1,13 @@
+export const DEFAULT_SCAN_SERVER = 'http://127.0.0.1:3123/'
+
+// Discovery is optional: malformed scan configuration must never prevent
+// opening local data or recognizing the server's sync protocol.
+export function normalizeScanServer(value: unknown): string | null {
+  if (typeof value !== 'string' || !value.trim()) return null
+  try {
+    const url = new URL(value)
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) return null
+    url.pathname = url.pathname.replace(/\/+$/u, '') + '/'
+    return url.href
+  } catch { return null }
+}

package/common/server-info.ts

@@ -0,0 +1,35 @@
+// The sync-protocol mode a server advertises — shared by the server (which
+// emits it) and the client (which parses + caches it) so a change to the
+// shape surfaces as a compile error on BOTH sides, the same single-source
+// discipline as ./save-error-reason.ts.
+//
+// Delivered to the client as the first `server-info` frame on a sync
+// connection (the WS plane and the SSE+POST fallback share one send path).
+// A client uses it to detect whether a deployment speaks the end-to-end
+// (`e2e`, zero-knowledge) protocol, the trusted `managed` protocol, or both.
+// Combined discovery modes put the default protocol first.
+
+export type ServerMode = 'e2e' | 'managed'
+
+// Managed-mode entry points the server advertises; null for an e2e server.
+export interface ManagedServerInfo {
+  loginPath: string
+  cookieName: string
+  uploadChunkBytes?: number
+  uploadMaxBytes?: { reports: number; bundles: number }
+  allowShare?: boolean
+}
+
+// The `server-info` frame payload (the `type` discriminant is added at the
+// send site). `managed` is null on e2e-only deployments.
+export interface ServerInfo {
+  mode: ServerMode | 'managed+e2e' | 'e2e+managed'
+  managed: ManagedServerInfo | null
+  deepviewScanServer?: string
+  githubNewIssueLabels?: string
+}
+
+// The mode-probe route. A client GETs this to learn a server's protocol up
+// front — a managed server has no WS plane to carry the connect frame — and
+// the response body is the same `ServerInfo` shape emitted as that frame.
+export const CONFIG_PATH = '/api/config'

package/common/utf8.d.ts

@@ -11,3 +11,6 @@
 // narrower declaration is safe.
 export function encodeUtf8(str: string): Uint8Array<ArrayBuffer>
 export function decodeUtf8(bytes: Uint8Array | ArrayBuffer | ArrayBufferView): string
+// Bytes `str` takes in UTF-8, measured without encoding when no character
+// is past \xFF. A lone surrogate counts as the U+FFFD it encodes to.
+export function utf8ByteLength(str: string): number

package/common/utf8.js

@@ -43,6 +43,51 @@ export function encodeUtf8(str) {
   return encoder.encode(str)
 }
 
+// ASCII characters in a row after which the count hands back to the
+// native scan. A jump costs a call and a step does not, so it pays only
+// across a real gap: at 1, alternating text (`aéaé…`) takes a jump per
+// character, and past 2, text with an accent every few words steps
+// through ASCII the scan crosses faster. Measured on 50 MB of each, 2 was
+// never more than 1.5x the best of the thresholds tried, 1 to 32.
+const ASCII_RUN = 2
+
+// The number of bytes `str` takes in UTF-8, without encoding it where
+// that can be helped. A string with no character past \xFF is Latin-1:
+// ASCII takes a byte and \x80-\xFF two, so its size is its length plus
+// its high characters. An engine stores such a string a byte per
+// character, where no character past \xFF can be, so the first test is
+// answered without reading it. Only a string with a wider character is
+// encoded to be measured.
+//
+// The high characters are counted without collecting them: a match array
+// takes an entry apiece, which for Latin-1-heavy text outweighs the
+// encoding this avoids. A native scan jumps to the next one — for ASCII
+// it finds none — and a loop counts on from there while they keep coming,
+// handing back to the scan after a run of ASCII. Sparse text is read
+// natively, dense text by the loop, and neither allocates.
+//
+// This sizes text for display, so unlike `encodeUtf8` it does not refuse
+// a lone surrogate: it counts the U+FFFD that TextEncoder writes for one.
+export function utf8ByteLength(str) {
+  if (typeof str !== 'string') {
+    throw new TypeError(`utf8ByteLength expects a string, got ${typeof str}`)
+  }
+  // Code units, not code points: a `u` regexp reads a two-byte string by
+  // code point, several times slower, and a surrogate is past \xFF either way.
+  // eslint-disable-next-line require-unicode-regexp
+  if (/[\u0100-\uFFFF]/.test(str)) return encoder.encode(str).byteLength
+  const high = /[\u0080-\u00FF]/gu
+  let bytes = str.length
+  while (high.test(str)) {
+    let i = high.lastIndex - 1
+    for (let ascii = 0; i < str.length && ascii < ASCII_RUN; i++) {
+      if (str.codePointAt(i) > 0x7F) { bytes++; ascii = 0 } else ascii++
+    }
+    high.lastIndex = i
+  }
+  return bytes
+}
+
 export function decodeUtf8(bytes) {
   // Reject non-BufferSource so a missed destructure / optional field /
   // misnamed property surfaces here instead of silently defaulting to