@shidesheng0218/dsh-plugin-lint 0.1.0 → 0.4.0

package/src/rules.js

@@ -1,379 +1 @@
-import { readFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { appendCallSites, blockAfter, braceDepthAt, lineOfIndex, stringAfter } from './mask.js';
-import { filesCover } from './load.js';
-
-const CATALOG = JSON.parse(readFileSync(new URL('./data/event-types.json', import.meta.url), 'utf8'));
-export const EVENT_TYPES = new Set(CATALOG.types);
-
-/** Upstream documents that ship inside a DSH installation. */
-export const DOC = {
-  practices: 'dsh plugin-development / references/practices.md',
-  host: 'dsh plugin-development / references/host-plugin.md',
-  ui: 'dsh plugin-development / references/ui-plugin.md',
-};
-
-const EVENT_TYPE_RE = /^[a-z][a-z0-9-]*\/[a-z0-9-]+$/;
-const HARNESS_CLIENT_PKG = /@deepseek-ai\/dsh-client[a-z0-9-]*/g;
-
-export const RULES = [
-  {
-    id: 'E1',
-    level: 'error',
-    title: 'appends a session event type that appears nowhere in the official packages',
-    doc: DOC.practices,
-    check(ctx, options, push) {
-      for (const file of ctx.jsFiles) {
-        for (const site of appendCallSites(file.masked, file.strings)) {
-          if (!EVENT_TYPE_RE.test(site.type)) continue;
-          if (EVENT_TYPES.has(site.type)) continue;
-          push({
-            file: file.path,
-            line: site.line,
-            message: 'session.append("' + site.type + '", ...): this type does not appear anywhere in the official Harness packages (' + EVENT_TYPES.size + ' types observed).',
-            evidence: '.append("' + site.type + '", ...)',
-            hint: 'The reference asks plugins not to append session events with a new type: a live Session.append() cannot set ignorable: true, so a log holding an unknown type can refuse to reopen. The allowlist is harvested, not authoritative — if this type is legitimate, it is a gap in the rule, not in your plugin.',
-          });
-        }
-      }
-    },
-  },
-
-  {
-    id: 'E2',
-    level: 'error',
-    title: 'client bundle factory id matches nothing the loader can ask for',
-    doc: DOC.ui,
-    check(ctx, options, push) {
-      if (ctx.entries.client === undefined || !ctx.exists(ctx.entries.client)) return;
-      const file = ctx.byPath(ctx.entries.client);
-      if (!file) return;
-
-      // The loader keys the browser module table by an id and throws when a bundle
-      // registers a different one (dsh-client-modules: "bundle … loaded without
-      // registering \"id\""). What it asks for is either the package name or a row
-      // name from the plugin's own patch, so both are acceptable. Asserting only the
-      // package name produced a false accusation against @roarpeng/graphflow, whose
-      // patch mounts the row "@roarpeng/graphflow/dsh".
-      const acceptable = new Set();
-      if (ctx.manifest.name) acceptable.add(ctx.manifest.name);
-      const patchRows = [];
-      if (ctx.entries.patch !== undefined && ctx.exists(ctx.entries.patch)) {
-        const patch = ctx.text(ctx.entries.patch) || '';
-        for (const m of patch.matchAll(/^\s*name:\s*['"]?([^'"\s#]+)['"]?/gm)) {
-          acceptable.add(m[1]);
-          patchRows.push(m[1]);
-        }
-      }
-
-      const re = /__ModuleLoader__\s*\.\s*load\s*\(\s*\{\s*id\s*:\s*/g;
-      let m;
-      while ((m = re.exec(file.masked)) !== null) {
-        const s = stringAfter(file.strings, m.index + m[0].length, 8);
-        if (!s || acceptable.has(s.value)) continue;
-        push({
-          file: file.path,
-          line: s.line,
-          message: 'factory id "' + s.value + '" is neither the package name "' + ctx.manifest.name + '" nor a row name in ' + (ctx.entries.patch || 'the bundle patch') + (patchRows.length ? ' (' + [...new Set(patchRows)].join(', ') + ')' : '') + '.',
-          evidence: '__ModuleLoader__.load({ id: "' + s.value + '" })',
-          hint: 'The browser module table keys the factory by the id it asks for and the loader throws when a bundle registers another one, leaving the client half unreachable.',
-        });
-      }
-    },
-  },
-
-  {
-    id: 'E3',
-    level: 'error',
-    title: 'manifest references a file that is not in the package',
-    doc: DOC.host,
-    check(ctx, options, push) {
-      const declared = [
-        ['host entry', ctx.entries.hostDeclared ? ctx.entries.host : undefined, 'manifest.main or exports["."]'],
-        ['client entry', ctx.entries.client, 'exports["./client"]'],
-        ['bundle patch', ctx.entries.patch, 'dsh.bundle.patch'],
-        ['icon', ctx.entries.icon, 'icon'],
-      ];
-      for (const [label, rel, source] of declared) {
-        if (rel === undefined) continue;
-        if (ctx.exists(rel)) continue;
-        push({
-          file: 'package.json',
-          line: manifestLine(ctx.manifestText, source),
-          message: label + ' points at "' + rel + '", which does not exist.',
-          evidence: source + ' -> ' + rel,
-          hint: 'Management pages read these paths without activating the plugin; a missing file is reported as a broken package.',
-        });
-      }
-    },
-  },
-
-  {
-    id: 'E4',
-    level: 'error',
-    title: 'declares a client half without a client entry',
-    doc: DOC.ui,
-    check(ctx, options, push) {
-      const hasClientSection = Boolean(ctx.manifest.dsh && ctx.manifest.dsh.client);
-      if (!hasClientSection) return;
-      if (ctx.entries.client !== undefined && ctx.exists(ctx.entries.client)) return;
-      push({
-        file: 'package.json',
-        line: manifestLine(ctx.manifestText, 'dsh.client'),
-        message: 'dsh.client is declared but exports["./client"] does not resolve to a file.',
-        evidence: 'dsh.client present, no ./client export',
-        hint: 'The platform resolves the browser artifact through the ./client export.',
-      });
-    },
-  },
-
-  {
-    id: 'E5',
-    level: 'error',
-    title: 'published files omit an artifact the manifest depends on',
-    doc: DOC.host,
-    check(ctx, options, push) {
-      if (ctx.files === undefined || ctx.files.length === 0) return;
-      const artifacts = [
-        ['host entry', ctx.entries.host],
-        ['client entry', ctx.entries.client],
-        ['bundle patch', ctx.entries.patch],
-        ['icon', ctx.entries.icon],
-      ];
-      for (const [label, rel] of artifacts) {
-        if (rel === undefined || !ctx.exists(rel)) continue;
-        if (filesCover(ctx.files, rel)) continue;
-        push({
-          file: 'package.json',
-          line: manifestLine(ctx.manifestText, '"files"'),
-          message: label + ' "' + rel + '" is not covered by "files", so it is absent from the published tarball.',
-          evidence: 'files: ' + JSON.stringify(ctx.files),
-          hint: 'This class of bug passes local testing and only appears after publish.',
-        });
-      }
-    },
-  },
-
-  {
-    id: 'W1',
-    level: 'warn',
-    title: 'couples the plugin to a Harness Client package',
-    doc: DOC.ui,
-    check(ctx, options, push) {
-      // First-party packages ship in the same release as the browser module table,
-      // so the coupling this rule warns about does not apply to them. Measured on
-      // 2026-10-13: every official client bundle loads ui-primitives / store / slots.
-      if (/^@deepseek-ai\//.test(ctx.manifest.name || '')) return;
-
-      // One finding per surface, not per package: a plugin that lists six client
-      // packages is one decision to review, not six defects.
-      const loaded = new Map();
-      if (ctx.entries.client !== undefined && ctx.exists(ctx.entries.client)) {
-        const file = ctx.byPath(ctx.entries.client);
-        if (file) {
-          const re = /(?:from\s*|require\s*\(\s*|[A-Za-z_$][\w$]*\s*\(\s*)["'](@deepseek-ai\/dsh-client[a-z0-9-]*)["']/g;
-          let m;
-          while ((m = re.exec(file.masked)) !== null) {
-            if (loaded.has(m[1])) continue;
-            loaded.set(m[1], { line: file.strings.find((s) => s.start >= m.index && s.start - m.index < 80)?.line, evidence: m[0].trim() });
-          }
-        }
-      }
-      if (loaded.size > 0) {
-        const first = loaded.values().next().value;
-        push({
-          file: ctx.entries.client,
-          line: first.line,
-          message: 'loads ' + loaded.size + ' Harness Client package' + (loaded.size === 1 ? '' : 's') + ' from the browser module table: ' + [...loaded.keys()].join(', ') + '.',
-          evidence: first.evidence,
-          hint: 'The reference advises copying the primitive instead: these packages change without notice and a throwing component blanks the slot. Official first-party bundles do the same, so treat this as a coupling risk to watch at upgrade time, not as a defect.',
-        });
-      }
-
-      const coupled = [];
-      for (const depField of ['dependencies', 'peerDependencies', 'optionalDependencies']) {
-        for (const name of Object.keys(ctx.manifest[depField] || {})) {
-          if (/^@deepseek-ai\/dsh-client/.test(name)) coupled.push(depField + ':' + name);
-        }
-      }
-      if (coupled.length > 0) {
-        push({
-          file: 'package.json',
-          line: 1,
-          message: 'declares ' + coupled.length + ' Harness Client package dependenc' + (coupled.length === 1 ? 'y' : 'ies') + ': ' + coupled.join(', ') + '.',
-          evidence: coupled.join(' '),
-          hint: 'dsh.client.inject entries only order activation and stay allowed; a dependency means the code loads it.',
-        });
-      }
-    },
-  },
-
-  {
-    id: 'W2',
-    level: 'warn',
-    title: 'folds session state by rescanning the log',
-    doc: DOC.practices,
-    check(ctx, options, push) {
-      for (const file of ctx.jsFiles) {
-        const registration = file.strings.find((s) => s.value === 'session/event');
-        if (registration === undefined) continue;
-        if (file.masked.includes('sessionProjections')) continue;
-        // Scope the check to the listener body: another object's `.events` in the
-        // same file is not a rescan. (Measured against official packages.)
-        const block = blockAfter(file.structural, registration.end);
-        if (block === undefined) continue;
-        const rescans = /\.events\b/.test(block.body) || /eventsBackwards\s*\(/.test(block.body);
-        if (!rescans) continue;
-        push({
-          file: file.path,
-          line: registration.line,
-          message: 'subscribes to session/event and reads the whole event log.',
-          evidence: "ctx.on('session/event', ...) with a full-log read",
-          hint: 'A ctx.sessionProjections unit folds events incrementally and returns the same reference for ignored events; per-event rescans cost the whole session on every append.',
-        });
-      }
-    },
-  },
-
-  {
-    id: 'W3',
-    level: 'info',
-    title: 'creates a timer with no visible owner (review hint)',
-    doc: DOC.practices,
-    check(ctx, options, push) {
-      for (const file of ctx.jsFiles) {
-        // Only timers at module top level are unambiguous leaks: a timer created
-        // inside a request handler may well be cleared by the surrounding code.
-        const re = /set(Interval|Timeout)\s*\(/g;
-        let m;
-        while ((m = re.exec(file.structural)) !== null) {
-          if (braceDepthAt(file.structural, m.index) !== 0) continue;
-          push({
-            file: file.path,
-            line: lineOfIndex(file.lineStarts, m.index),
-            message: 'appears to start a timer outside any function scope, with no context effect nearby.',
-            evidence: m[0],
-            hint: 'Registration on a context owns its cleanup: unload and hot reload dispose what the effect returned. Brace depth is approximate on bundled or minified output, so confirm this one by reading the code.',
-          });
-          break;
-        }
-      }
-    },
-  },
-
-  {
-    id: 'I1',
-    level: 'info',
-    title: 'declares no DSH compatibility range',
-    doc: DOC.host,
-    check(ctx, options, push) {
-      const declared = ctx.manifest.dsh && ctx.manifest.dsh.compatibility && ctx.manifest.dsh.compatibility.dshReleases;
-      if (declared && Object.keys(declared).length > 0) {
-        if (options.dshVersion && !(options.dshVersion in declared)) {
-          push({
-            file: 'package.json',
-            line: manifestLine(ctx.manifestText, 'dshReleases'),
-            message: 'does not list the running DSH version "' + options.dshVersion + '" in dsh.compatibility.dshReleases.',
-            evidence: 'declared: ' + Object.keys(declared).join(', '),
-            hint: 'An unlisted version is unknown, not incompatible: verify it before publishing a compatibility claim.',
-          });
-        }
-        return;
-      }
-      push({
-        file: 'package.json',
-        line: manifestLine(ctx.manifestText, '"dsh"'),
-        message: 'has no dsh.compatibility.dshReleases entry.',
-        evidence: 'dsh.compatibility absent',
-        hint: 'Most published plugins omit this today, which is why empirical verification matters more than self-declaration.',
-      });
-    },
-  },
-
-  {
-    id: 'I2',
-    level: 'info',
-    title: 'ships no display metadata',
-    doc: DOC.host,
-    check(ctx, options, push) {
-      if (ctx.entries.icon === undefined) {
-        push({
-          file: 'package.json',
-          line: 1,
-          message: 'declares no top-level "icon".',
-          evidence: 'icon absent',
-          hint: 'Management cards and the settings inventory read title, description and icon without activating the plugin.',
-        });
-      }
-      const dir = ctx.entries.localeDir;
-      if (dir === undefined) {
-        push({
-          file: 'package.json',
-          line: 1,
-          message: 'ships no locale/<lang>.json metadata.',
-          evidence: 'locale/ absent',
-          hint: 'Title and description live under the "meta" key of locale/en.json, not in package.json.',
-        });
-        return;
-      }
-      const candidates = ctx.localeFiles();
-      const withMeta = candidates.filter((c) => c.meta && (c.meta.title || c.meta.description));
-      if (withMeta.length === 0) {
-        push({
-          file: dir + '/',
-          line: 1,
-          message: 'locale files declare no "meta" title or description.',
-          evidence: 'locale files: ' + candidates.length,
-          hint: 'Expected shape: { "meta": { "title": "...", "description": "..." } }.',
-        });
-      }
-    },
-  },
-
-  {
-    id: 'I3',
-    level: 'warn',
-    title: 'locale metadata is not published',
-    doc: DOC.host,
-    check(ctx, options, push) {
-      const dir = ctx.entries.localeDir;
-      if (dir === undefined) return;
-      const exported = Object.keys(ctx.manifest.exports || {}).some((k) => k.includes('locale'));
-      if (!exported) {
-        push({
-          file: 'package.json',
-          line: manifestLine(ctx.manifestText, '"exports"'),
-          message: 'a locale/ directory exists but exports declares no locale subpath.',
-          evidence: 'exports: ' + JSON.stringify(Object.keys(ctx.manifest.exports || {})),
-          hint: 'Display metadata is read through the locale subpath.',
-        });
-      }
-      if (ctx.files && ctx.files.length > 0 && !filesCover(ctx.files, dir + '/en.json')) {
-        push({
-          file: 'package.json',
-          line: manifestLine(ctx.manifestText, '"files"'),
-          message: 'locale files are not covered by "files".',
-          evidence: 'files: ' + JSON.stringify(ctx.files),
-          hint: 'Metadata missing from the tarball shows as a fallback title and default artwork.',
-        });
-      }
-    },
-  },
-];
-
-function manifestLine(text, needle) {
-  if (!text || !needle) return 1;
-  const idx = text.indexOf(needle.replace(/^"|"$/g, ''));
-  if (idx < 0) return 1;
-  return text.slice(0, idx).split('\n').length;
-}
-
-export function localeMeta(dir, localeDir) {
-  const out = [];
-  for (const lang of ['en', 'zh', 'zh-CN', 'ja', 'ru']) {
-    const p = join(dir, localeDir, lang + '.json');
-    if (!existsSync(p)) continue;
-    try { out.push({ lang, ...JSON.parse(readFileSync(p, 'utf8')) }); } catch { /* ignored: malformed locale file */ }
-  }
-  return out;
-}
+export * from './core/rules.js';

package/src/security.js

@@ -0,0 +1 @@
+export * from './experimental/security.js';

package/src/shared/errors.js

@@ -0,0 +1,7 @@
+export class ToolError extends Error {
+  constructor(code, message, { cause } = {}) {
+    super(message, { cause });
+    this.name = 'ToolError';
+    this.code = code;
+  }
+}

package/src/shared/hash.js

@@ -0,0 +1,31 @@
+import { createHash } from 'node:crypto';
+import { isPlainObject } from './validate.js';
+
+export function stableStringify(value) {
+  return JSON.stringify(normalizeJson(value, new Set()));
+}
+
+export function sha256(value) {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function normalizeJson(value, ancestors) {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) throw new TypeError('stableStringify only accepts JSON data');
+    return value;
+  }
+  if (!Array.isArray(value) && !isPlainObject(value)) {
+    throw new TypeError('stableStringify only accepts JSON data');
+  }
+  if (ancestors.has(value)) throw new TypeError('stableStringify cannot encode a JSON cycle');
+  ancestors.add(value);
+  try {
+    if (Array.isArray(value)) return value.map((entry) => normalizeJson(entry, ancestors));
+    const normalized = {};
+    for (const key of Object.keys(value).sort()) normalized[key] = normalizeJson(value[key], ancestors);
+    return normalized;
+  } finally {
+    ancestors.delete(value);
+  }
+}

package/src/shared/status.js

@@ -0,0 +1,12 @@
+export const STATUS = Object.freeze({
+  ACTIVE: 'active',
+  AWAITING_SERVICE: 'awaiting-service',
+  INACTIVE_ERROR: 'inactive-error',
+});
+
+export const TRUST = Object.freeze({
+  SELF_REPORTED: 'self-reported',
+  VERIFIED: 'verified',
+  DISPUTED: 'disputed',
+  LEGACY_UNPINNED: 'legacy-unpinned',
+});

package/src/shared/validate.js

@@ -0,0 +1,14 @@
+export function isPlainObject(value) {
+  if (value === null || typeof value !== 'object') return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+export function requireFields(value, fields, path) {
+  if (!isPlainObject(value)) return [`${path} must be an object`];
+  const errors = [];
+  for (const field of fields) {
+    if (!Object.hasOwn(value, field) || value[field] === undefined) errors.push(`${path}.${field} is required`);
+  }
+  return errors;
+}

package/src/shared/version.js

@@ -0,0 +1,4 @@
+export const CELL_SCHEMA_VERSION = 2;
+export const EXPERIMENTAL_SCHEMA_VERSION = 2;
+export const PANEL_PAYLOAD_SCHEMA_VERSION = 2;
+export const PROBE_VERSION = '0.4.0';

package/src/upgrade/compatibility.js

@@ -0,0 +1,14 @@
+const INCOMPATIBLE = /incompatible|unsupported|broken|failed|rejected|inactive|boot/i;
+
+export function classifyCompatibilityDeclaration(value) {
+  if (value === true || value === 'compatible') return 'compatible';
+  if (value === false || value === 'incompatible') return 'incompatible';
+  if (typeof value === 'string') return INCOMPATIBLE.test(value) ? 'incompatible' : 'unknown';
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    if (value.compatible === true) return 'compatible';
+    if (value.compatible === false) return 'incompatible';
+    const status = value.status ?? value.verdict;
+    if (typeof status === 'string' && INCOMPATIBLE.test(status)) return 'incompatible';
+  }
+  return 'unknown';
+}

package/src/upgrade/planner.js

@@ -0,0 +1,119 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { ToolError } from '../shared/errors.js';
+import { readCells } from '../matrix/cells.js';
+import { recommendationEligible, selectCells } from '../matrix/cell.js';
+import { readProfile } from './profile.js';
+
+function readMatrix(matrixDir, targetDsh) {
+  if (!existsSync(matrixDir)) throw new ToolError('MATRIX_INPUT_INVALID', 'matrix directory not found: ' + matrixDir);
+  const cellsDir = existsSync(join(matrixDir, 'cells')) ? join(matrixDir, 'cells') : matrixDir;
+  const reads = readCells(cellsDir);
+  const damaged = reads.filter((entry) => !entry.ok);
+  if (damaged.length > 0) throw new ToolError('MATRIX_INPUT_INVALID', `cannot read ${damaged.length} matrix cell(s), first: ${damaged[0].path}`);
+  const cells = reads.filter((entry) => entry.kind === 'v2' || entry.kind === 'legacy-v1').map((entry) => entry.cell);
+  if (cells.length === 0) throw new ToolError('MATRIX_INPUT_INVALID', `no matrix cells found under ${cellsDir} (no data for ${targetDsh})`);
+  const dshVersions = [...new Set(cells.map((cell) => cell.dsh.version))].sort((a, b) => a.localeCompare(b, undefined, { numeric: true }));
+  if (!dshVersions.includes(targetDsh)) {
+    throw new ToolError('MATRIX_INPUT_INVALID', `the matrix has no cells for DSH ${targetDsh} (it covers: ${dshVersions.join(', ') || 'nothing'})`);
+  }
+  const byPlugin = new Map();
+  for (const cell of cells) {
+    if (!byPlugin.has(cell.plugin.name)) byPlugin.set(cell.plugin.name, []);
+    byPlugin.get(cell.plugin.name).push(cell);
+  }
+  return { byPlugin, dshVersions, count: cells.length };
+}
+
+function classifyPlugin(plugin, matrix, targetDsh, composition) {
+  const base = { name: plugin.name, version: plugin.version ?? null, firstParty: false };
+  if (!plugin.version) return { ...base, category: 'unknown', status: 'unknown', reason: 'installed version unknown' };
+  const own = matrix.byPlugin.get(plugin.name) || [];
+  const testedVersions = [...new Set(own.map((cell) => cell.plugin.resolvedVersion || cell.plugin.version))].sort((a, b) => a.localeCompare(b, undefined, { numeric: true }));
+  const current = own.filter((cell) => (cell.plugin.resolvedVersion || cell.plugin.version) === plugin.version);
+  if (current.length === 0) {
+    return {
+      ...base,
+      category: 'unknown',
+      status: 'unknown',
+      testedVersions,
+      reason: own.length === 0
+        ? 'plugin is not covered by the matrix'
+        : `version ${plugin.version} is not covered for DSH ${targetDsh} (tested versions: ${testedVersions.join(', ')})`,
+    };
+  }
+  const selection = selectCells(current, { dshVersion: targetDsh, composition });
+  if (selection.kind !== 'cells') {
+    return {
+      ...base,
+      category: selection.kind,
+      status: selection.kind,
+      testedVersions,
+      reason: selection.kind === 'mixed'
+        ? 'multiple compositions are present but the current profile composition is unknown'
+        : selection.kind === 'unknown'
+          ? 'the current profile composition or trust evidence is unknown'
+          : 'no exact cell exists for the installed version, target DSH, and composition',
+    };
+  }
+
+  const statuses = new Set(selection.cells.map((cell) => cell.result.status));
+  const allActiveAndEligible = selection.cells.every((cell) => cell.result.status === 'active' && recommendationEligible(cell));
+  if (allActiveAndEligible) return { ...base, category: 'compatible', status: 'active', composition };
+  if (statuses.size > 1) return { ...base, category: 'mixed', status: 'mixed', testedVersions, reason: 'observations disagree within the selected composition' };
+
+  const currentStatus = selection.cells[0].result.status;
+  const alternatives = testedVersions.filter((version) => version !== plugin.version).filter((version) => {
+    const candidate = selectCells(own.filter((cell) => (cell.plugin.resolvedVersion || cell.plugin.version) === version), { dshVersion: targetDsh, composition });
+    return candidate.kind === 'cells' && candidate.cells.every((cell) => cell.result.status === 'active' && recommendationEligible(cell));
+  }).sort((a, b) => b.localeCompare(a, undefined, { numeric: true }));
+  const negative = !['active', 'awaiting-service'].includes(currentStatus);
+  if (alternatives.length > 0 && negative) {
+    return { ...base, category: 'needsUpdate', status: currentStatus, composition, recommendedVersion: alternatives[0], reason: `version ${alternatives[0]} has verified active evidence on the same DSH and composition` };
+  }
+  if (negative) {
+    return { ...base, category: 'noCompatibleVersion', status: currentStatus, composition, testedVersions, reason: 'no verified active version exists for this DSH and composition' };
+  }
+  return { ...base, category: 'untested', status: currentStatus, composition, testedVersions, reason: 'active evidence is missing, self-reported, legacy, stale, or composition-incomplete' };
+}
+
+export async function planUpgrade({ profileDir, matrixDir, from, to, composition }) {
+  if (composition !== undefined && !['headless', 'web'].includes(composition)) throw new ToolError('MATRIX_INPUT_INVALID', 'composition must be headless or web');
+  const profile = readProfile(profileDir);
+  const matrix = readMatrix(matrixDir, to);
+  const selectedComposition = composition || profile.composition;
+  const categories = { compatible: [], untested: [], needsUpdate: [], noCompatibleVersion: [], unknown: [], mixed: [], firstParty: [] };
+  for (const plugin of profile.plugins) {
+    if (plugin.firstParty) {
+      categories.firstParty.push({ name: plugin.name, version: plugin.version ?? null, firstParty: true, category: 'firstParty', status: 'not-covered', reason: 'first-party bundle; the community matrix does not cover it' });
+      continue;
+    }
+    const classified = classifyPlugin(plugin, matrix, to, selectedComposition);
+    categories[classified.category].push(classified);
+  }
+  const installTargets = categories.needsUpdate.filter((plugin) => plugin.recommendedVersion).map((plugin) => `${plugin.name}@${plugin.recommendedVersion}`);
+  const summary = {
+    total: profile.plugins.length,
+    community: profile.plugins.length - categories.firstParty.length,
+    compatible: categories.compatible.length,
+    untested: categories.untested.length,
+    needsUpdate: categories.needsUpdate.length,
+    noCompatibleVersion: categories.noCompatibleVersion.length,
+    unknown: categories.unknown.length,
+    mixed: categories.mixed.length,
+    firstParty: categories.firstParty.length,
+    needAction: categories.needsUpdate.length + categories.noCompatibleVersion.length,
+  };
+  return {
+    schemaVersion: 2,
+    mode: 'upgrade-plan',
+    from,
+    to,
+    composition: selectedComposition || null,
+    profile: { path: profile.path, source: profile.source, bundles: profile.plugins.length, composition: profile.composition || null },
+    matrix: { dir: matrixDir, cells: matrix.count, dshVersions: matrix.dshVersions },
+    categories,
+    summary,
+    installCommand: installTargets.length ? 'npm install ' + installTargets.join(' ') : null,
+  };
+}