@preventive/triage 1.0.0-alpha.2 → 1.0.0-alpha.20

package/common/bundle-sources.d.ts

@@ -0,0 +1,3 @@
+import type { BundleDetails } from './bundle-metadata.js'
+export function bundleSourcesAsMap(details: BundleDetails): Map<string, string>
+export function bundlePackageVersions(details: BundleDetails, paths?: Iterable<string> | null): Map<string, Set<string>>

package/common/bundle-sources.js

@@ -0,0 +1,284 @@
+// Shared helper: given a parsed bundle `details`, return a
+// Map<file, content-string> of its source files. Stasis bundles
+// expose sources via `@exodus/stasis-core`'s `Bundle.sources` getter
+// (flat Map<projectRelPath, content> from `.modules`); sourcemaps
+// split them across parallel `sources` / `sourcesContent` arrays on
+// the raw .map JSON. Sourcemap sources whose `sourcesContent[i]` was
+// omitted are skipped.
+//
+// What a stasis bundle records is not all source: `Bundle.formats`
+// marks each entry, and three of those formats are files only in the
+// sense that they occupy a path. `Bundle.sources` hands back the raw
+// stored content for every one of them, so the format is what has to
+// be asked — the content's JS type cannot tell them apart:
+//
+//   directory        a readdir capture, content `["a.js","b.js"]`
+//   resource:base64  an image or font, content its base64 text
+//   resource         raw bytes, the one case not a string already
+//
+// A directory capture is the one that does real damage, because it
+// claims a path a directory also occupies: hand it to the terminal
+// and `ls` lists the name twice and stops listing what is under it.
+// The base64 resources are quieter but equally wrong — a PNG read as
+// a wall of text, counted toward the language shares that
+// render-bundle.js says resources are kept out of.
+//
+// Own module so `render-bundle.js` (Code tab, finding tree, graph
+// data) and `terminal-attach.js` (in-shell FS) read one definition —
+// a new bundle kind or field handled here is visible to both.
+
+import { Bundle } from '@exodus/stasis-core/bundle'
+import { utf8ByteLength } from './utf8.js'
+
+const sourcesCache = new WeakMap()
+const filesCache = new WeakMap()
+const sizesCache = new WeakMap()
+const sourceSizesCache = new WeakMap()
+const kindsCache = new WeakMap()
+const unsizedCache = new WeakMap()
+
+export function bundleSourcesAsMap(details) {
+  if (details?.metadataOnly) return new Map()
+  const key = details?.bundle ?? details?.json
+  if (key && sourcesCache.has(key)) return sourcesCache.get(key)
+  const result = new Map()
+  if (!details) return result
+  if (details.kind === 'stasis') {
+    if (!details.bundle) return result
+    const formats = details.bundle.formats
+    for (const [file, content] of details.bundle.sources) {
+      if (typeof content !== 'string') continue
+      // `isResourceFormat` is the package's own list, so a format it
+      // adds later is excluded here without this needing to know. A v0
+      // bundle records no formats at all: `get` returns undefined,
+      // which is not a resource format, and every entry is kept as
+      // before.
+      if (Bundle.isResourceFormat(formats?.get(file))) continue
+      result.set(file, content)
+    }
+  } else if (details.kind === 'sourcemap') {
+    if (!details.json) return result
+    const srcs = details.json.sources ?? []
+    const contents = details.json.sourcesContent ?? []
+    for (let i = 0; i < srcs.length; i++) {
+      if (typeof contents[i] === 'string') result.set(srcs[i], contents[i])
+    }
+  }
+  if (key) sourcesCache.set(key, result)
+  return result
+}
+
+// Every file the bundle carries, for a reader that wants the filesystem
+// rather than the source: what `bundleSourcesAsMap` returns, plus the
+// resources it leaves out, each in the form that is true to it.
+//
+// The two resource formats are not two encodings of the same thing.
+// Stasis picks between them by whether the bytes are valid UTF-8:
+// `resource` is that text, stored verbatim, so it stays a string and a
+// reader sees the SVG or the licence file it is. `resource:base64` is
+// the other case — bytes no string spells — and it is handed over
+// still spelt that way, as `{ format: 'base64', data }`. The terminal
+// takes that form since 2.0 and decodes it the first time the file is
+// read, so a bundle carrying a hundred images costs a hundred strings
+// rather than a hundred decoded buffers, and pays for the one that is
+// opened. Either way it knows what it is holding: `ls -l` and `wc -c`
+// report the real byte count rather than the length of the base64, and
+// `cat` declines instead of printing mojibake.
+//
+// Decoding there also puts the diagnostic where the file is named: a
+// spelling that does not decode is reported by the command that read
+// it, under the detail `base64 source`. Decoding here could only drop
+// the file and say nothing.
+//
+// Directory captures stay out. They are the one entry that is not a
+// file in any encoding, and mounting one puts a second `lib` beside
+// the directory it names.
+export function bundleFilesAsMap(details) {
+  const key = details?.bundle ?? details?.json
+  if (key && filesCache.has(key)) return filesCache.get(key)
+  const files = new Map(bundleSourcesAsMap(details))
+  if (details?.kind === 'stasis' && details.bundle) {
+    const formats = details.bundle.formats
+    for (const [file, content] of details.bundle.sources) {
+      if (typeof content !== 'string') continue
+      const format = formats?.get(file)
+      if (format === 'resource') files.set(file, content)
+      else if (format === 'resource:base64') files.set(file, { format: 'base64', data: content })
+    }
+  }
+  if (key) filesCache.set(key, files)
+  return files
+}
+
+const BASE64_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'
+
+// The length of the bytes a base64 spelling decodes to — three for every
+// four characters, less what the padding stands for — or null when it
+// decodes to none. The terminal decodes strictly (`@exodus/bytes`): RFC
+// 4648's alphabet, no whitespace, padding present or left off but never
+// wrong, and no stray bits in the last character. A spelling it refuses is
+// a file `wc -c` cannot read, so it gets no size here rather than an
+// invented one. Checked without decoding: a bundle's images are not worth
+// a buffer each just to be weighed.
+function base64ByteLength(text) {
+  const padded = text.endsWith('=')
+  if (padded ? text.length % 4 !== 0 || text.at(-3) === '=' : text.length % 4 === 1) return null
+  const data = padded ? text.slice(0, text.endsWith('==') ? -2 : -1) : text
+  if (/[^A-Za-z0-9+/]/u.test(data)) return null
+  // A trailing group of 2 or 3 characters spells 1 or 2 bytes; the bits of
+  // its last character past those bytes must be zero.
+  const tail = data.length % 4
+  if (tail > 1 && BASE64_ALPHABET.indexOf(data.at(-1)) & (tail === 2 ? 0x0f : 0x03)) return null
+  return Math.floor(data.length * 3 / 4)
+}
+
+// The byte size of one entry of `bundleFilesAsMap`, as `wc -c` reports it
+// in the terminal: text weighs the UTF-8 it encodes to, and a base64
+// declaration the bytes it decodes to — null when it decodes to none.
+// Anything else is no file, and null too. The Compare tab sizes both
+// bundles' files by this, so its totals are the Overview's.
+export function bundleFileByteLength(content) {
+  if (typeof content === 'string') return utf8ByteLength(content)
+  return content?.format === 'base64' ? base64ByteLength(content.data) : null
+}
+
+// Every path the bundle records, keyed to the byte size of the file it
+// holds — the size `wc -c` reports for it in the terminal, which is to
+// say the size of the entry in `bundleFilesAsMap`: a source or `resource`
+// weighs the UTF-8 its text encodes to, a `resource:base64` the bytes its
+// base64 decodes to. Null is a path with no size to give: a directory
+// capture, which is no file; a sourcemap source whose body was left out;
+// or a `resource:base64` whose spelling does not decode.
+//
+// The Overview and the Treemap weigh a bundle by this, so what they show
+// adds up to what `du` does. Neither the source-only view nor the base64
+// text will do: the first drops every image and font, the second
+// inflates them by a third.
+//
+// Metadata views need byte sizes and paths, never the bodies. The
+// persistent index supplies this map directly; full parses compute it once.
+export function bundleFileSizes(details) {
+  if (details?.fileSizes) return details.fileSizes
+  const key = details?.bundle ?? details?.json
+  if (key && sizesCache.has(key)) return sizesCache.get(key)
+  const sizes = new Map()
+  const files = bundleFilesAsMap(details)
+  const paths = details?.kind === 'stasis' ? details.bundle?.sources.keys() : details?.json?.sources
+  for (const path of paths ?? []) sizes.set(path, bundleFileByteLength(files.get(path)))
+  if (key) sizesCache.set(key, sizes)
+  return sizes
+}
+
+// The files the terminal mounts that have no size: a `resource:base64`
+// whose spelling does not decode. The terminal lists such a file, and says
+// why it cannot read it when asked, so the views list it too — but a null
+// size alone cannot tell it from an entry that is no file at all, so it is
+// named here. A metadata-only open reads the set from the index, which is
+// the one thing a size and a format cannot say about a path.
+export function bundleUnsizedFiles(details) {
+  if (details?.metadataOnly) return details.unsizedFiles ?? new Set()
+  const sizes = bundleFileSizes(details)
+  if (unsizedCache.has(sizes)) return unsizedCache.get(sizes)
+  const unsized = new Set()
+  for (const path of bundleFilesAsMap(details).keys()) if (sizes.get(path) === null) unsized.add(path)
+  unsizedCache.set(sizes, unsized)
+  return unsized
+}
+
+// What each file the terminal mounts is, for a view that lists files:
+// 'source', or 'resource' for an image, font or other asset — a file, sized
+// like any other, but none the source viewer can show. Its keys are
+// `bundleFilesAsMap`'s, and nothing else: a directory capture, or an entry
+// with no body to mount (a sourcemap source whose `sourcesContent` was left
+// out, a body that is no string), is no file and is absent. It reads sizes
+// and formats, not bodies, so it answers for a metadata-only open as it
+// does for a parsed one: a sized path is a mounted file, and so is one
+// `bundleUnsizedFiles` names.
+export function bundleFileKinds(details) {
+  const sizes = bundleFileSizes(details)
+  if (kindsCache.has(sizes)) return kindsCache.get(sizes)
+  const unsized = bundleUnsizedFiles(details)
+  const formats = details?.kind === 'stasis' ? details.bundle?.formats : null
+  const kinds = new Map()
+  for (const [path, size] of sizes) {
+    if (size === null && !unsized.has(path)) continue
+    kinds.set(path, Bundle.isResourceFormat(formats?.get(path)) ? 'resource' : 'source')
+  }
+  kindsCache.set(sizes, kinds)
+  return kinds
+}
+
+// `bundleFileSizes` narrowed to source: a resource's size is nulled, as a
+// directory capture's already is. The import graph draws this, and stays
+// source-only: an image or a font imports nothing and carries no finding.
+export function bundleSourceSizes(details) {
+  const sizes = bundleFileSizes(details)
+  const formats = details?.kind === 'stasis' ? details.bundle?.formats : null
+  if (!formats || formats.size === 0) return sizes
+  if (sourceSizesCache.has(sizes)) return sourceSizesCache.get(sizes)
+  const result = new Map()
+  for (const [path, size] of sizes) result.set(path, Bundle.isResourceFormat(formats.get(path)) ? null : size)
+  sourceSizesCache.set(sizes, result)
+  return result
+}
+
+// Map each stasis bundle source path to the package directory that
+// owns it. A stasis `Bundle` already records authoritative package
+// boundaries in `.modules` (a `Map<dir, { name, version, files }>`
+// covering both `node_modules` deps and workspace packages — the
+// PHP `vendor/<vendor>/<pkg>` case, monorepo workspaces, etc.); this
+// mirrors the `Bundle.sources` getter's path construction (`dir/rel`,
+// or just `rel` for the `.` root) so the returned keys line up exactly
+// with `bundleSourcesAsMap`'s.
+//
+// The package views (overview, treemap, graph) otherwise classify
+// paths with `bundlePkgOf`'s string heuristic, which only knows
+// `node_modules/`/`dependencies/` and buckets everything else by
+// top-level dir — collapsing sibling workspace packages under their
+// shared parent (`vendor/aws/aws-crt-php` + `vendor/aws/aws-sdk-php`
+// both fall under `vendor`). Feeding each path's dir into
+// `bundlePkgOf` (`packageDir` option) keeps those packages separate.
+//
+// Returns null for sourcemap bundles (and anything without parsed
+// modules) — they carry no package metadata, so callers fall back to
+// the path heuristic alone.
+export function bundlePackageDirs(details) {
+  if (details?.kind !== 'stasis' || !details.bundle?.modules) return null
+  const map = new Map()
+  for (const [dir, info] of details.bundle.modules) {
+    for (const rel of Object.keys(info.files)) {
+      map.set(dir === '.' ? rel : `${dir}/${rel}`, dir)
+    }
+  }
+  return map
+}
+
+// Map each named npm dependency a (stasis) bundle carries to the set of
+// concrete versions present for it: `Map<name, Set<version>>`. Only
+// `node_modules/...` modules that carry both a name and a non-empty
+// version string count — stasis v1 `scope: 'full'` bundles merge
+// workspace / own-source entries into the same `Bundle.modules` Map
+// (often `version: '0.0.0'` or null), and those aren't upstream
+// dependencies, so they're filtered out by the directory key. A package
+// can map to more than one version (pnpm keeps duplicate majors side by
+// side), hence the Set.
+//
+// Shared by the Advisories tab (a bulk registry lookup keyed on these
+// pairs) and the Compare slide (the dependency version-update diff).
+// Returns an empty Map for sourcemaps and v0 stasis bundles — neither
+// carries per-module version metadata.
+export function bundlePackageVersions(details, paths = null) {
+  const versions = new Map()
+  if (details?.kind !== 'stasis' || !details.bundle?.modules) return versions
+  const packageDirs = paths === null ? null : bundlePackageDirs(details)
+  const selectedDirs = paths === null ? null : new Set([...paths].map(path => packageDirs?.get(path)))
+  for (const [dir, info] of details.bundle.modules) {
+    if (selectedDirs && !selectedDirs.has(dir)) continue
+    if (!dir.includes('node_modules')) continue
+    if (!info?.name || typeof info.version !== 'string' || !info.version) continue
+    let set = versions.get(info.name)
+    if (!set) { set = new Set(); versions.set(info.name, set) }
+    set.add(info.version)
+  }
+  return versions
+}

package/common/bundle-stats.js

@@ -0,0 +1,41 @@
+import { langForPath } from './code-language.js'
+
+const BUNDLE_LANGUAGE_LABELS = Object.freeze({
+  javascript: 'JavaScript', jsx: 'JSX', typescript: 'TypeScript', tsx: 'TSX',
+  json: 'JSON', css: 'CSS', markup: 'HTML', yaml: 'YAML', bash: 'Shell',
+  markdown: 'Markdown', solidity: 'Solidity', php: 'PHP', rust: 'Rust',
+  ruby: 'Ruby', java: 'Java', cpp: 'C++', c: 'C', objectivec: 'Objective-C',
+  python: 'Python', go: 'Go', kotlin: 'Kotlin', swift: 'Swift', dart: 'Dart',
+  sql: 'SQL', lua: 'Lua', csharp: 'C#', scala: 'Scala', vue: 'Vue', svelte: 'Svelte',
+})
+const BUNDLE_EXTENSION_LANGUAGES = Object.freeze({
+  py: 'python', pyw: 'python', go: 'go', kt: 'kotlin', kts: 'kotlin', swift: 'swift',
+  dart: 'dart', sql: 'sql', lua: 'lua', cs: 'csharp', scala: 'scala', sc: 'scala',
+  vue: 'vue', svelte: 'svelte',
+})
+
+function bundleLanguageOf(path) {
+  const basename = typeof path === 'string' ? path.slice(path.lastIndexOf('/') + 1) : ''
+  const dot = basename.lastIndexOf('.')
+  const ext = dot > 0 ? basename.slice(dot + 1).trim().toLowerCase() : ''
+  const lang = langForPath(path) ?? BUNDLE_EXTENSION_LANGUAGES[ext]
+  if (lang) return { key: lang, label: BUNDLE_LANGUAGE_LABELS[lang] ?? lang }
+  return ext ? { key: `extension:${ext}`, label: `.${ext}` } : { key: 'other', label: 'Other' }
+}
+
+export function bundleCodeStats(lineCounts, fileSizes) {
+  const languages = new Map()
+  let bytes = 0, lines = 0
+  for (const [path, count] of lineCounts) {
+    const language = bundleLanguageOf(path)
+    const stat = languages.get(language.key) ?? { ...language, files: 0, lines: 0, bytes: 0 }
+    stat.files++
+    stat.lines += count
+    stat.bytes += fileSizes.get(path) ?? 0
+    languages.set(language.key, stat)
+    lines += count
+    bytes += fileSizes.get(path) ?? 0
+  }
+  return { files: lineCounts.size, lines, bytes, languages: [...languages.values()]
+    .toSorted((a, b) => b.lines - a.lines || a.label.localeCompare(b.label)) }
+}

package/common/bundle-tabs.js

@@ -0,0 +1 @@
+export const BUNDLE_TABS = new Set(['overview', 'graph', 'treemap', 'compare', 'advisories', 'issues', 'code', 'search', 'terminal'])

package/common/code-language.js

@@ -0,0 +1,36 @@
+const EXT_TO_LANG = {
+  js: 'javascript', mjs: 'javascript', cjs: 'javascript',
+  jsx: 'jsx',
+  ts: 'typescript', mts: 'typescript', cts: 'typescript',
+  tsx: 'tsx',
+  json: 'json',
+  css: 'css',
+  html: 'markup', htm: 'markup', xml: 'markup', svg: 'markup',
+  yml: 'yaml', yaml: 'yaml',
+  sh: 'bash', bash: 'bash',
+  md: 'markdown', markdown: 'markdown',
+  sol: 'solidity',
+  php: 'php', phtml: 'php',
+  rs: 'rust',
+  rb: 'ruby',
+  java: 'java',
+  // .h is claimed by C, C++ and Objective-C alike. The C++ grammar
+  // extends the C one, so it is the superset that colours a header
+  // from any of the three; the C grammar would leave a C++ header's
+  // class/template/namespace keywords plain.
+  cpp: 'cpp', cc: 'cpp', cxx: 'cpp', 'c++': 'cpp',
+  hpp: 'cpp', hh: 'cpp', hxx: 'cpp', 'h++': 'cpp', h: 'cpp',
+  c: 'c',
+  m: 'objectivec', mm: 'objectivec',
+}
+
+export function langForPath(path) {
+  if (typeof path !== 'string') return null
+  // Only the filename can contribute an extension. A dotted directory such
+  // as `.abc/edf` is a path segment, not an extension on `edf`.
+  const basename = path.slice(path.lastIndexOf('/') + 1)
+  const dot = basename.lastIndexOf('.')
+  if (dot <= 0) return null
+  return EXT_TO_LANG[basename.slice(dot + 1).toLowerCase()] ?? null
+}
+

package/common/default-scan-models.ts

@@ -0,0 +1,30 @@
+// Shared starting catalogue for the UI and managed server until scan-service
+// discovery supplies supported models and effort limits. Use undated aliases.
+export function defaultScanModels(provider: string | null = null) {
+  const ids = [
+    'anthropic/claude-opus-5.5',
+    'anthropic/claude-fable-5.1',
+    'anthropic/claude-sonnet-5',
+    'anthropic/claude-haiku-4.5',
+    'openai/gpt-6-astra',
+    'openai/gpt-6-astra-pro',
+    'openai/gpt-6-sol',
+    'openai/gpt-6-sol-pro',
+    'openai/gpt-6-luna',
+    'openai/gpt-6-luna-pro',
+    'moonshotai/kimi-k3',
+    'google/gemini-3.8-flash',
+    'google/gemma-4-31b-it',
+    'x-ai/grok-4.7',
+    'z-ai/glm-5.3',
+    'qwen/qwen3.8-max',
+    'deepseek/deepseek-v4.1-flash',
+    'deepseek/deepseek-v4-pro',
+  ]
+  // OpenRouter routes all listed providers. Direct-provider credentials only
+  // expose that provider's models; no selection leaves the catalogue intact.
+  const prefix = provider === 'moonshot' ? 'moonshotai' : provider
+  const models = ids.filter(id => !['anthropic', 'openai', 'moonshot'].includes(provider ?? '') || id.startsWith(`${prefix}/`))
+    .map(id => ({ id, efforts: ['low', 'medium', 'high', 'xhigh', 'max'] }))
+  return { models, defaultModel: models[0]!.id }
+}

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 `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-pr.ts

@@ -0,0 +1,56 @@
+export 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/managed/comments.ts

@@ -0,0 +1,34 @@
+// Managed comments are independent records, shared by reports containing the
+// same finding. Imported and legacy comments may lack attribution or dates.
+export interface ManagedComment {
+  id: string
+  findingId: string
+  body: string
+  authorId: string | null
+  authorLogin: string | null
+  createdAt: number | null
+  updatedAt: number | null
+  version: number
+}
+
+export const MAX_COMMENT_TEXT = 10_000
+
+// Callers also enforce write access to the report containing the finding.
+// Admins can remove comments with no linked user, but cannot claim authorship.
+export function canDeleteComment(comment: Pick<ManagedComment, 'authorId'>, actor: { id: string; role: string } | null | undefined): boolean {
+  return actor != null && (comment.authorId === actor.id || (comment.authorId == null && actor.role === 'admin'))
+}
+
+export function compareManagedComments(a: ManagedComment, b: ManagedComment): number {
+  if (a.createdAt == null && b.createdAt != null) return -1
+  if (a.createdAt != null && b.createdAt == null) return 1
+  const byDate = (a.createdAt ?? 0) - (b.createdAt ?? 0)
+  if (byDate !== 0) return byDate
+  if (a.id === b.id) return 0
+  return a.id < b.id ? -1 : 1
+}
+
+export function parseCommentBody(value: unknown): string | null {
+  if (typeof value !== 'string' || value.length > MAX_COMMENT_TEXT) return null
+  return value.trim() || null
+}

package/common/managed/permissions.ts

@@ -0,0 +1,35 @@
+// Per-membership visibility permissions for a team's users — shared by the
+// managed server (which stores + validates them) and the admin client (the
+// team-member checkboxes). Each is an independent opt-in, BOTH DEFAULT OFF:
+//   dependencies — scan findings in dependencies' own code; App impact stays visible
+//   security     — security findings and published bundle advisories
+// The managed server filters report responses and authorizes advisory lookups
+// using these independent permissions.
+export type VisibilityPermission = 'dependencies' | 'security'
+
+export const VISIBILITY_PERMISSIONS: readonly VisibilityPermission[] = ['dependencies', 'security']
+
+// Human labels for the admin checkboxes (keyed by permission).
+export const VISIBILITY_PERMISSION_LABELS: Record<VisibilityPermission, string> = {
+  dependencies: 'Dependencies',
+  security: 'Security',
+}
+
+// A membership's resolved permission set; every key present (false = off).
+export type TeamUserPermissions = Record<VisibilityPermission, boolean>
+
+// All-off — the default for a fresh membership.
+export const DEFAULT_TEAM_USER_PERMISSIONS: TeamUserPermissions = { dependencies: false, security: false }
+
+export function isVisibilityPermission(x: unknown): x is VisibilityPermission {
+  return typeof x === 'string' && (VISIBILITY_PERMISSIONS as readonly string[]).includes(x)
+}
+
+// Coerce arbitrary input (a request body) into a full permission set: a key is
+// granted only when explicitly `true`; anything else (absent, non-bool) is off.
+export function parseTeamUserPermissions(x: unknown): TeamUserPermissions {
+  const o = (x == null || typeof x !== 'object') ? {} : x as Record<string, unknown>
+  const out = { ...DEFAULT_TEAM_USER_PERMISSIONS }
+  for (const p of VISIBILITY_PERMISSIONS) out[p] = o[p] === true
+  return out
+}

package/common/managed/report-content.ts

@@ -0,0 +1,42 @@
+import { parseLinkedFindings } from '../../client/linked-findings.js'
+import { detectFormat, loadFindings, parseCodexCsvToScans, readReport } from '../../report/index.js'
+
+// A managed blob retains one server identity even when a CSV contains several
+// scans. Keep all their findings (and upstream ids) under that identity. CSV
+// repository columns describe findings, not an embedded report-level location.
+export function readManagedReport(content: string, filename: string): ReturnType<typeof readReport> {
+  const links = content.trimStart().startsWith('[') ? parseLinkedFindings(content) : null
+  if (links) return { data: { source: 'links', findings: [], links: links.groups }, format: 'links', reason: null }
+  const parsed = readReport(content)
+  // Permission-filtered responses can be JSON under the original CSV filename.
+  if (parsed.data != null || detectFormat(content, filename) !== 'codex') return parsed
+  try {
+    const scans = parseCodexCsvToScans(content)
+    return {
+      data: { type: 'security', source: 'codex-security', findings: scans.flatMap((scan) => scan.data.findings) },
+      format: 'codex', reason: null,
+    }
+  } catch (err) {
+    return { data: null, format: null, reason: err instanceof Error ? err.message : 'Invalid Codex CSV' }
+  }
+}
+
+export function loadManagedFindings(content: string, filename: string): ReturnType<typeof loadFindings> {
+  const parsed = readManagedReport(content, filename)
+  return parsed.data == null ? Promise.resolve(null) : loadFindings(JSON.stringify(parsed.data))
+}
+
+// Source access follows individual visible members, not their shared finding
+// IDs: another member with the same ID can cite files the viewer cannot see.
+export function managedFindingSourcePaths(findings: unknown[]): Set<string> {
+  const paths = new Set<string>()
+  for (const finding of findings) {
+    if (!finding || typeof finding !== 'object') continue
+    const f = finding as { file?: unknown; evidence?: { file?: unknown }[] }
+    if (typeof f.file === 'string' && f.file) paths.add(f.file)
+    for (const evidence of Array.isArray(f.evidence) ? f.evidence : []) {
+      if (typeof evidence?.file === 'string' && evidence.file) paths.add(evidence.file)
+    }
+  }
+  return paths
+}