@shidesheng0218/dsh-plugin-lint 0.0.0-stage → 0.4.0

package/src/core/mask.js

@@ -0,0 +1,207 @@
+/**
+ * Comment- and string-aware scanner.
+ *
+ * Rules must never match text inside a comment (real plugins document the very
+ * patterns we look for, e.g. "this listener returns next()"). Two views:
+ *
+ *   masked     comments blanked, string literals INTACT — for matching quoted
+ *              event names and reading literal values with exact line numbers.
+ *   structural masked AND string interiors blanked — for brace-depth analysis.
+ */
+
+const BACKTICK = '\u0060';
+
+/** @returns {{ masked: string, structural: string, strings: Array<{value:string,start:number,end:number,line:number}>, lineStarts: number[] }} */
+export function maskSource(text) {
+  const maskedChars = text.split('');
+  const structuralChars = text.slice().split('');
+  const strings = [];
+  const lineStarts = [0];
+  for (let k = 0; k < text.length; k++) if (text[k] === '\n') lineStarts.push(k + 1);
+
+  const NL = '\n';
+  const SP = ' ';
+  const blank = (from, to, chars) => {
+    for (let k = from; k < to; k++) if (chars[k] !== NL) chars[k] = SP;
+  };
+  // A '/' starts a regex only where a value may begin; otherwise it is division.
+  // Two cases the naive "previous character" test gets wrong:
+  //   a++ / b   - the first slash is division, and treating it as a regex would
+  //               swallow the following "//" comment into the masked view.
+  //   return /re/ - the previous character is a letter, but a keyword allows a
+  //               regex here.
+  const REGEX_KEYWORDS = /(?:^|[^\w$])(?:return|typeof|instanceof|case|delete|void|throw|new|in|of|do|else|yield|await)$/;
+  const regexAllowed = (idx) => {
+    let k = idx - 1;
+    while (k >= 0 && (maskedChars[k] === SP || maskedChars[k] === NL || maskedChars[k] === '\t')) k -= 1;
+    if (k < 0) return true;
+    const prev = maskedChars[k];
+    if ('(,=:[!&|?{};+-*%<>~^'.indexOf(prev) >= 0) {
+      if ((prev === '+' || prev === '-') && maskedChars[k - 1] === prev) return false;
+      return true;
+    }
+    if (!/[\w$]/.test(prev)) return false;
+    let wordStart = k;
+    while (wordStart >= 0 && /[\w$]/.test(maskedChars[wordStart])) wordStart -= 1;
+    return REGEX_KEYWORDS.test(maskedChars.slice(wordStart + 1, k + 1).join(''));
+  };
+
+  let i = 0;
+  const n = text.length;
+  while (i < n) {
+    const c = text[i];
+    const next = text[i + 1];
+
+    if (c === '/' && next === '/') {
+      const from = i;
+      while (i < n && text[i] !== NL) i++;
+      blank(from, i, maskedChars);
+      blank(from, i, structuralChars);
+      continue;
+    }
+    if (c === '/' && next === '*') {
+      const from = i;
+      i += 2;
+      while (i < n && !(text[i] === '*' && text[i + 1] === '/')) i++;
+      i = Math.min(n, i + 2);
+      blank(from, i, maskedChars);
+      blank(from, i, structuralChars);
+      continue;
+    }
+
+    // The literal delimiter itself, not a boolean: the closing delimiter must
+    // compare equal to it.
+    const quote = c === '"' ? '"' : c === "'" ? "'" : c === BACKTICK ? BACKTICK : undefined;
+    if (quote !== undefined) {
+      const from = i;
+      i += 1;
+      const contentFrom = i;
+      while (i < n) {
+        if (text[i] === '\\') { i += 2; continue; }
+        if (text[i] === quote) break;
+        if (text[i] === NL && quote !== BACKTICK) break; // unterminated literal
+        i += 1;
+      }
+      const contentTo = Math.min(i, n);
+      const end = Math.min(i + 1, n);
+      strings.push({ value: text.slice(contentFrom, contentTo), start: from, end, line: lineOfIndex(lineStarts, from) });
+      blank(contentFrom, contentTo, structuralChars);
+      i = end;
+      continue;
+    }
+
+    if (c === '/' && regexAllowed(i)) {
+      const from = i;
+      i += 1;
+      let inClass = false;
+      while (i < n) {
+        if (text[i] === '\\') { i += 2; continue; }
+        if (text[i] === '[') inClass = true;
+        else if (text[i] === ']') inClass = false;
+        else if (text[i] === '/' && !inClass) { i += 1; break; }
+        else if (text[i] === NL) break;
+        i += 1;
+      }
+      // A regex body is data, not code: braces and quotes inside it must not
+      // reach the structural view, and a literal "session.append(" inside it
+      // must not look like a call site.
+      blank(from, i, maskedChars);
+      blank(from, i, structuralChars);
+      continue;
+    }
+    i += 1;
+  }
+  return { masked: maskedChars.join(''), structural: structuralChars.join(''), strings, lineStarts };
+}
+
+export function lineOfIndex(lineStarts, index) {
+  let lo = 0;
+  let hi = lineStarts.length - 1;
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1;
+    if (lineStarts[mid] <= index) lo = mid;
+    else hi = mid - 1;
+  }
+  return lo + 1;
+}
+
+/** The first string literal starting at or after \`from\` within \`window\` characters. */
+export function stringAfter(strings, from, window) {
+  for (const s of strings) {
+    if (s.start >= from) return s.start - from <= window ? s : undefined;
+  }
+  return undefined;
+}
+
+/** Literal types passed to Session.append(type, data). */
+export function appendCallSites(masked, strings) {
+  const out = [];
+  // Session receivers the host exposes: bare `session`, ctx.session,
+  // agent.session and this.session. A property named `session` on an unrelated
+  // object (formData.session) is not a Session, so only these names count.
+  const re = /(?<![\w$.])(?:(?:ctx|agent|this)\s*\.\s*)?session\s*\.\s*append\s*\(\s*/g;
+  let m;
+  while ((m = re.exec(masked)) !== null) {
+    if (insideString(strings, m.index)) continue;
+    const s = stringAt(strings, m.index + m[0].length);
+    if (!s) continue;
+    if (s.value.includes('${')) continue;
+    out.push({ type: s.value, index: s.start, line: s.line });
+  }
+  return out;
+}
+
+/** True when `index` falls inside a string literal (where the text is data). */
+function insideString(strings, index) {
+  let lo = 0;
+  let hi = strings.length - 1;
+  while (lo <= hi) {
+    const mid = (lo + hi) >> 1;
+    const s = strings[mid];
+    if (index < s.start) hi = mid - 1;
+    else if (index >= s.end) lo = mid + 1;
+    else return true;
+  }
+  return false;
+}
+
+/** The string literal whose opening quote is exactly at `index`, if any. */
+function stringAt(strings, index) {
+  let lo = 0;
+  let hi = strings.length - 1;
+  while (lo <= hi) {
+    const mid = (lo + hi) >> 1;
+    const s = strings[mid];
+    if (s.start < index) lo = mid + 1;
+    else if (s.start > index) hi = mid - 1;
+    else return s;
+  }
+  return undefined;
+}
+
+/** The balanced brace block that starts at or after `index`, on the structural view. */
+export function blockAfter(structural, index) {
+  const open = structural.indexOf('{', index);
+  if (open < 0) return undefined;
+  let depth = 0;
+  for (let i = open; i < structural.length; i++) {
+    const c = structural[i];
+    if (c === '{') depth += 1;
+    else if (c === '}') {
+      depth -= 1;
+      if (depth === 0) return { start: open, end: i + 1, body: structural.slice(open + 1, i) };
+    }
+  }
+  return undefined;
+}
+
+/** Brace depth at a character index, computed on the structural view. */
+export function braceDepthAt(structural, index) {
+  let depth = 0;
+  for (let k = 0; k < index && k < structural.length; k++) {
+    const c = structural[k];
+    if (c === '{' || c === '(' || c === '[') depth += 1;
+    else if (c === '}' || c === ')' || c === ']') depth -= 1;
+  }
+  return depth;
+}

package/src/core/pack.js

@@ -0,0 +1,95 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { extractTarball } from './tarball.js';
+
+export function detectPackageManager(dir) {
+  if (existsSync(join(dir, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (existsSync(join(dir, 'yarn.lock'))) return 'yarn';
+  if (existsSync(join(dir, 'bun.lockb')) || existsSync(join(dir, 'bun.lock'))) return 'bun';
+  return 'npm';
+}
+
+function run(command, args, cwd) {
+  const env = { ...process.env, npm_config_ignore_scripts: 'true', YARN_ENABLE_SCRIPTS: 'false' };
+  // Package managers are Node programs; under NODE_V8_COVERAGE they would add
+  // their own internals to the caller's coverage report.
+  delete env.NODE_V8_COVERAGE;
+  return execFileSync(command, args, {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env,
+  });
+}
+
+function findTarball(dir) {
+  const names = readdirSync(dir).filter((name) => name.endsWith('.tgz'));
+  if (names.length === 0) throw new Error('the package manager did not produce a .tgz');
+  return join(dir, names[0]);
+}
+
+/** Pack a local package and return the tarball path plus a cleanup handle. */
+export function packDirectory(dir, { manager = 'auto', ignoreScripts = true } = {}) {
+  const pm = manager === 'auto' ? detectPackageManager(dir) : manager;
+  const out = mkdtempSync(join(tmpdir(), 'dsh-pack-'));
+  const flags = ignoreScripts ? ['--ignore-scripts'] : [];
+  try {
+    if (pm === 'npm') run('npm', ['pack', ...flags, '--pack-destination', out], dir);
+    else if (pm === 'pnpm') {
+      // pnpm pack has no --ignore-scripts flag; the config form is the supported switch.
+      const noScripts = ignoreScripts ? ['--config.ignore-scripts=true'] : [];
+      run('pnpm', ['pack', ...noScripts, '--pack-destination', out], dir);
+    } else if (pm === 'bun') run('bun', ['pm', 'pack', ...flags, '--destination', out], dir);
+    else if (pm === 'yarn') {
+      // Yarn Berry disables lifecycle scripts through YARN_ENABLE_SCRIPTS (set in run()).
+      const target = join(out, 'package.tgz');
+      try {
+        run('yarn', ['pack', '--filename', target], dir);
+      } catch {
+        run('yarn', ['pack', '--out', target], dir);
+      }
+    } else {
+      throw new Error('unknown package manager: ' + pm);
+    }
+    return { tarball: findTarball(out), manager: pm, cleanup: () => rmSync(out, { recursive: true, force: true }) };
+  } catch (error) {
+    rmSync(out, { recursive: true, force: true });
+    throw new Error('pack failed with ' + pm + ': ' + String(error.stderr || error.message).trim().slice(0, 400));
+  }
+}
+
+/** Download a published package with npm pack and return the tarball. */
+export function packFromNpm(spec) {
+  const out = mkdtempSync(join(tmpdir(), 'dsh-npm-pack-'));
+  try {
+    run('npm', ['pack', spec, '--ignore-scripts', '--pack-destination', out], process.cwd());
+    return { tarball: findTarball(out), source: 'npm:' + spec, cleanup: () => rmSync(out, { recursive: true, force: true }) };
+  } catch (error) {
+    rmSync(out, { recursive: true, force: true });
+    throw new Error('npm pack ' + spec + ' failed: ' + String(error.stderr || error.message).trim().slice(0, 400));
+  }
+}
+
+export function findPackageRoot(dir) {
+  if (existsSync(join(dir, 'package.json'))) return dir;
+  const children = readdirSync(dir, { withFileTypes: true }).filter((entry) => entry.isDirectory());
+  for (const child of children) {
+    const path = join(dir, child.name);
+    if (existsSync(join(path, 'package.json'))) return path;
+  }
+  throw new Error('the tarball contains no package.json');
+}
+
+/** Extract a tarball into a fresh temp directory and return the package root. */
+export function extractTarballTo(dir) {
+  const out = mkdtempSync(join(tmpdir(), 'dsh-tarball-'));
+  try {
+    extractTarball(readFileSync(dir), out);
+    return { root: findPackageRoot(out), cleanup: () => rmSync(out, { recursive: true, force: true }) };
+  } catch (error) {
+    rmSync(out, { recursive: true, force: true });
+    throw error;
+  }
+}

package/src/core/packlist.js

@@ -0,0 +1,186 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { basename, join, relative } from 'node:path';
+
+const SKIP_DIRS = new Set(['.git', 'node_modules', 'CVS', '.svn', '.hg']);
+const REGEX_SPECIAL = new Set(['.', '+', '^', '$', '(', ')', '|', '{', '}', '\\', '/']);
+
+function normalizePath(value) {
+  return String(value).replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+/, '').replace(/\/+$/, '');
+}
+
+export function globToRegExp(pattern) {
+  const glob = normalizePath(pattern);
+  let source = '^';
+  for (let index = 0; index < glob.length; index += 1) {
+    const char = glob[index];
+    if (char === '*') {
+      if (glob[index + 1] === '*') {
+        while (glob[index + 1] === '*') index += 1;
+        if (glob[index + 1] === '/') {
+          index += 1;
+          source += '(?:.*/)?';
+        } else {
+          source += '.*';
+        }
+      } else {
+        source += '[^/]*';
+      }
+      continue;
+    }
+    if (char === '?') {
+      source += '[^/]';
+      continue;
+    }
+    if (char === '[') {
+      const close = glob.indexOf(']', index + 1);
+      if (close < 0) throw new Error(`unsupported glob: ${pattern}`);
+      let content = glob.slice(index + 1, close);
+      if (content.startsWith('!')) content = '^' + content.slice(1);
+      source += '[' + content + ']';
+      index = close;
+      continue;
+    }
+    source += REGEX_SPECIAL.has(char) ? '\\' + char : char;
+  }
+  return new RegExp(source + '$');
+}
+
+function matches(pattern, relPath) {
+  const normalized = normalizePath(pattern);
+  if (!normalized) return false;
+  if (normalized === relPath || relPath.startsWith(normalized + '/')) return true;
+  return normalized.includes('*') || normalized.includes('?') || normalized.includes('[')
+    ? globToRegExp(normalized).test(relPath)
+    : false;
+}
+
+function ruleState(rules, relPath, initial) {
+  let state = initial;
+  for (const raw of rules) {
+    let pattern = String(raw).trim();
+    if (!pattern) continue;
+    const negated = pattern.startsWith('!');
+    if (negated) pattern = pattern.slice(1);
+    if (matches(pattern, relPath)) state = !negated;
+  }
+  return state;
+}
+
+function intrinsic(relPath, main) {
+  if (relPath === 'package.json' || relPath === main) return true;
+  return /^(?:readme|license|licence|copying|notice)(?:\.|$)/i.test(relPath);
+}
+
+function alwaysIgnored(relPath) {
+  const name = basename(relPath);
+  return name === '.npmrc'
+    || name === '.gitignore'
+    || name === '.npmignore'
+    || name === '.DS_Store'
+    || name === 'npm-debug.log'
+    || name === 'yarn-error.log'
+    || name === 'package-lock.json'
+    || name === 'config.gypi'
+    || name === '.lock-wscript'
+    || /^\.wafpickle-/.test(name)
+    || /^\..*\.swp$/.test(name)
+    || name.endsWith('.orig');
+}
+
+function readIgnoreFile(path) {
+  try {
+    return readFileSync(path, 'utf8').split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter((line) => line && !line.startsWith('#'));
+  } catch {
+    return null;
+  }
+}
+
+/** npm uses .npmignore in a directory, falling back to .gitignore. */
+function ignoreFileIn(dir) {
+  const npmignore = join(dir, '.npmignore');
+  if (existsSync(npmignore)) return npmignore;
+  const gitignore = join(dir, '.gitignore');
+  if (existsSync(gitignore)) return gitignore;
+  return undefined;
+}
+
+export function buildPacklist(dir, manifest) {
+  const paths = new Set();
+  let complete = true;
+  if (manifest.files !== undefined && !Array.isArray(manifest.files)) complete = false;
+  if ((manifest.bundleDependencies || manifest.bundledDependencies || []).length > 0) complete = false;
+  const main = typeof manifest.main === 'string' && manifest.main ? normalizePath(manifest.main) : undefined;
+  if (main?.startsWith('../')) complete = false;
+
+  // npm-packlist disables the ROOT .npmignore/.gitignore as soon as package.json
+  // has a `files` array (the array is the complete selection). Nested ignore
+  // files still apply, which is why the groups are collected per directory below.
+  const hasFiles = Array.isArray(manifest.files);
+  const rootGroups = [];
+  if (!hasFiles) {
+    const rootFile = ignoreFileIn(dir);
+    if (rootFile) {
+      const rules = readIgnoreFile(rootFile);
+      if (rules === null) complete = false;
+      else rootGroups.push({ base: dir, rules });
+    }
+  }
+
+  function walk(current, inherited) {
+    let entries;
+    try {
+      entries = readdirSync(current, { withFileTypes: true });
+    } catch {
+      complete = false;
+      return;
+    }
+    let groups = inherited;
+    if (current !== dir) {
+      const nested = ignoreFileIn(current);
+      if (nested) {
+        const rules = readIgnoreFile(nested);
+        if (rules === null) complete = false;
+        else groups = [...inherited, { base: current, rules }];
+      }
+    }
+    for (const entry of entries) {
+      const absolute = join(current, entry.name);
+      const relPath = normalizePath(relative(dir, absolute));
+      if (entry.isSymbolicLink()) {
+        complete = false;
+        continue;
+      }
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRS.has(entry.name)) walk(absolute, groups);
+        continue;
+      }
+      if (!entry.isFile() || alwaysIgnored(relPath)) continue;
+      try {
+        const included = manifest.files === undefined
+          ? true
+          : Array.isArray(manifest.files) && ruleState(manifest.files, relPath, false);
+        let ignored = false;
+        for (const group of groups) {
+          const rel = normalizePath(relative(group.base, absolute));
+          if (rel === '' || rel.startsWith('..')) continue;
+          if (ruleState(group.rules, rel, false)) {
+            ignored = true;
+            break;
+          }
+        }
+        if (intrinsic(relPath, main) || (included && !ignored)) paths.add(relPath);
+      } catch {
+        complete = false;
+      }
+    }
+  }
+
+  walk(dir, rootGroups);
+  return { paths, complete };
+}
+
+export function hasPackedFile(packlist, relPath) {
+  return packlist.paths.has(normalizePath(relPath));
+}

package/src/core/peer.js

@@ -0,0 +1,39 @@
+import { satisfies } from './semver.js';
+
+/** DSH peer declarations the host checks before importing a plugin. */
+export function dshPeers(manifest) {
+  return Object.entries((manifest && manifest.peerDependencies) || {})
+    .filter(([name]) => name === '@deepseek-ai/dsh' || name.startsWith('@deepseek-ai/dsh-'))
+    .map(([name, range]) => ({ name, range: String(range) }));
+}
+
+/**
+ * Evaluate the host's admission rule for one target runtime.
+ *
+ * The host requires every DSH peer range to accept the single runtime version
+ * and lets prereleases participate. Missing peers impose no constraint; a range
+ * this module cannot decide is reported as 'unknown', never as a rejection.
+ */
+export function evaluatePeers(manifest, runtime) {
+  const peers = dshPeers(manifest);
+  const result = {
+    runtime: runtime || null,
+    peers,
+    verdict: 'no-constraint',
+    unsatisfied: [],
+    undecidable: [],
+  };
+  if (!runtime || peers.length === 0) return result;
+  for (const peer of peers) {
+    // The host substitutes the runtime version for workspace:^/~/* before
+    // comparing, so those ranges always match.
+    if (['workspace:^', 'workspace:~', 'workspace:*'].includes(peer.range)) continue;
+    const verdict = satisfies(runtime, peer.range);
+    if (verdict === null) result.undecidable.push(peer);
+    else if (verdict === false) result.unsatisfied.push(peer);
+  }
+  result.verdict = result.unsatisfied.length > 0 ? 'will-reject'
+    : result.undecidable.length > 0 ? 'unknown'
+      : 'will-load';
+  return result;
+}

package/src/core/profile-scan.js

@@ -0,0 +1,121 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { evaluatePeers } from './peer.js';
+
+function readJson(path) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return undefined; }
+}
+
+/** The host gates on the app-boot package version; fall back to the dsh package. */
+export function profileRuntimeVersion(profileDir, override) {
+  if (override) return override;
+  for (const path of [
+    join(profileDir, 'node_modules', '@deepseek-ai', 'dsh-app-boot', 'package.json'),
+    join(profileDir, 'node_modules', '@deepseek-ai', 'dsh', 'package.json'),
+  ]) {
+    const version = readJson(path)?.version;
+    if (typeof version === 'string' && version) return version;
+  }
+  return undefined;
+}
+
+function declaredBundles(manifest) {
+  const declared = manifest?.dsh?.profile?.bundles;
+  if (!Array.isArray(declared)) return [];
+  const names = [];
+  for (const entry of declared) {
+    const name = typeof entry === 'string'
+      ? entry
+      : entry?.name || entry?.id || entry?.package || entry?.bundle || entry?.plugin;
+    if (typeof name === 'string' && name && !names.includes(name)) names.push(name);
+  }
+  return names;
+}
+
+/** dsh.profile.bundles when present, otherwise every package in node_modules. */
+export function installedBundles(profileDir) {
+  const manifest = readJson(join(profileDir, 'package.json'));
+  const declared = declaredBundles(manifest);
+  if (declared.length > 0) return declared;
+  const nodeModules = join(profileDir, 'node_modules');
+  if (!existsSync(nodeModules)) return [];
+  const names = [];
+  for (const entry of readdirSync(nodeModules, { withFileTypes: true })) {
+    if (entry.name.startsWith('.')) continue;
+    const path = join(nodeModules, entry.name);
+    if (entry.name.startsWith('@')) {
+      let children = [];
+      try { children = readdirSync(path, { withFileTypes: true }); } catch { children = []; }
+      for (const child of children) names.push(entry.name + '/' + child.name);
+    } else {
+      names.push(entry.name);
+    }
+  }
+  return names;
+}
+
+function allowCommand(profileDir, name, version, runtime) {
+  if (!version || !runtime) return undefined;
+  return 'dsh plugin --profile ' + basename(profileDir)
+    + ' allow-version ' + name + '@' + version
+    + ' --dsh-version ' + runtime + ' --accept-risk';
+}
+
+/**
+ * Offline admission scan of an installed profile. It reads manifests only; it
+ * never imports a plugin or touches the running host.
+ */
+export function scanProfile(profileDir, { dshVersion } = {}) {
+  if (!existsSync(join(profileDir, 'package.json'))) {
+    throw new Error('not a profile directory (no package.json): ' + profileDir);
+  }
+  const runtime = profileRuntimeVersion(profileDir, dshVersion);
+  const plugins = [];
+  for (const name of installedBundles(profileDir)) {
+    const manifest = readJson(join(profileDir, 'node_modules', ...name.split('/'), 'package.json'));
+    if (!manifest) continue;
+    const peers = evaluatePeers(manifest, runtime);
+    plugins.push({
+      name,
+      version: typeof manifest.version === 'string' ? manifest.version : null,
+      firstParty: name.startsWith('@deepseek-ai/'),
+      runtime: runtime || null,
+      verdict: runtime ? peers.verdict : 'unknown',
+      unsatisfied: peers.unsatisfied,
+      undecidable: peers.undecidable,
+      allowCommand: peers.verdict === 'will-reject' ? allowCommand(profileDir, name, manifest.version, runtime) : undefined,
+    });
+  }
+  const summary = {
+    total: plugins.length,
+    willReject: plugins.filter((plugin) => plugin.verdict === 'will-reject').length,
+    willLoad: plugins.filter((plugin) => plugin.verdict === 'will-load').length,
+    noConstraint: plugins.filter((plugin) => plugin.verdict === 'no-constraint').length,
+    unknown: plugins.filter((plugin) => plugin.verdict === 'unknown').length,
+    firstParty: plugins.filter((plugin) => plugin.firstParty).length,
+  };
+  return { schemaVersion: 1, mode: 'profile-scan', profile: profileDir, runtime: runtime || null, plugins, summary };
+}
+
+export function formatProfileScan(scan) {
+  const lines = [
+    'profile ' + scan.profile + ' · runtime ' + (scan.runtime || 'unknown'),
+    '  ' + scan.summary.total + ' bundle(s) · ' + scan.summary.willReject + ' will-reject · '
+      + scan.summary.willLoad + ' will-load · ' + scan.summary.unknown + ' unknown',
+  ];
+  for (const plugin of scan.plugins) {
+    if (plugin.firstParty && plugin.verdict !== 'will-reject') continue;
+    if (plugin.verdict === 'will-reject') {
+      lines.push('  ✗ ' + plugin.name + '@' + (plugin.version || '?') + '  will-reject');
+      for (const peer of plugin.unsatisfied) {
+        lines.push('      ' + peer.name + ' "' + peer.range + '" does not accept ' + scan.runtime);
+      }
+      if (plugin.allowCommand) lines.push('      grant an exact exemption: ' + plugin.allowCommand);
+    } else if (plugin.verdict === 'unknown') {
+      lines.push('  ? ' + plugin.name + '@' + (plugin.version || '?') + '  unknown (no runtime version or an undecidable range)');
+    } else {
+      lines.push('  ✓ ' + plugin.name + '@' + (plugin.version || '?') + '  ' + plugin.verdict);
+    }
+  }
+  return lines.join('\n');
+}