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

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@shidesheng0218/dsh-plugin-lint",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.0",
+  "description": "Conformance checks and a compatibility matrix for DeepSeek Harness plugins: what the code declares, what it publishes, and what the host does with it.",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "lint",
+    "conformance",
+    "compatibility"
+  ],
+  "homepage": "https://github.com/shidesheng0218/dsh-plugin-lint",
+  "license": "Apache-2.0",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./experimental": "./src/experimental/index.js",
+    "./schema/dsh-manifest.schema.json": "./schema/dsh-manifest.schema.json",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "dsh-plugin-lint": "bin/dsh-plugin-lint.mjs",
+    "dsh-plugin-probe": "scripts/probe-boot.mjs",
+    "dsh-plugin-analyze": "bin/dsh-plugin-analyze.mjs",
+    "dsh-plugin-upgrade-plan": "bin/dsh-plugin-upgrade-plan.mjs",
+    "dsh-plugin-matrix": "bin/dsh-plugin-matrix.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "schema/",
+    "scripts/probe-boot.mjs",
+    "scripts/lib/",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "test:coverage": "node --experimental-test-coverage --test --test-coverage-lines=85 --test-coverage-branches=80 --test-coverage-functions=80 --test-coverage-exclude=\"**/node_modules/**\" --test-coverage-exclude=\"**/.cache/**\" test/*.test.js",
+    "package:smoke": "node scripts/package-smoke.mjs",
+    "e2e:official": "node scripts/e2e-official.mjs --expect 80",
+    "harvest:events": "node scripts/harvest-event-types.mjs",
+    "fetch:official": "node scripts/fetch-official-from-npm.mjs",
+    "matrix": "node scripts/matrix/run.mjs",
+    "site": "node scripts/matrix/site.mjs",
+    "panel": "node scripts/matrix/bundle-panel-data.mjs",
+    "notify": "node scripts/build-notification-pack.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shidesheng0218/dsh-plugin-lint.git"
+  },
+  "bugs": {
+    "url": "https://github.com/shidesheng0218/dsh-plugin-lint/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/schema/dsh-manifest.schema.json

@@ -0,0 +1,134 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/shidesheng0218/dsh-plugin-lint/main/schema/dsh-manifest.schema.json",
+  "title": "DeepSeek Harness plugin package.json",
+  "description": "The package.json fields a DSH plugin author declares. Unknown fields are allowed; editors validate the parts the host reads before CI runs dsh-plugin-lint.",
+  "$comment": "schemaVersion 1, shipped with @shidesheng0218/dsh-plugin-lint 0.4.0",
+  "type": "object",
+  "required": ["name", "version"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^(?:@[a-z0-9-~][a-z0-9-._~]*/)?[a-z0-9-~][a-z0-9-._~]*$"
+    },
+    "version": {
+      "type": "string"
+    },
+    "private": {
+      "type": "boolean"
+    },
+    "type": {
+      "type": "string",
+      "enum": ["module", "commonjs"]
+    },
+    "main": {
+      "type": "string"
+    },
+    "exports": {
+      "$ref": "#/definitions/exports"
+    },
+    "files": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "bin": {
+      "oneOf": [
+        { "type": "string" },
+        { "type": "object", "additionalProperties": { "type": "string" } }
+      ]
+    },
+    "icon": {
+      "type": "string"
+    },
+    "peerDependencies": {
+      "type": "object",
+      "additionalProperties": { "type": "string" }
+    },
+    "dsh": {
+      "$ref": "#/definitions/dsh"
+    }
+  },
+  "additionalProperties": true,
+  "definitions": {
+    "exports": {
+      "oneOf": [
+        { "type": "string" },
+        { "type": "array", "items": { "$ref": "#/definitions/exports" } },
+        { "type": "object", "additionalProperties": { "$ref": "#/definitions/exports" } }
+      ]
+    },
+    "dsh": {
+      "type": "object",
+      "description": "Everything the DSH host reads from package.json.",
+      "properties": {
+        "bundle": {
+          "type": "object",
+          "properties": {
+            "patch": {
+              "oneOf": [
+                { "type": "string" },
+                { "type": "array", "items": { "type": "string" } }
+              ]
+            }
+          },
+          "additionalProperties": true
+        },
+        "client": {
+          "description": "Declares a browser half; the host resolves exports[\"./client\"].",
+          "oneOf": [
+            { "type": "boolean" },
+            {
+              "type": "object",
+              "properties": {
+                "platform": { "type": "string" },
+                "immediately": { "type": "boolean" },
+                "inject": { "type": "array", "items": { "type": "string" } },
+                "external": { "type": "array", "items": { "type": "string" } }
+              },
+              "additionalProperties": true
+            }
+          ]
+        },
+        "profile": {
+          "type": "object",
+          "properties": {
+            "bundles": {
+              "type": "array",
+              "items": {
+                "oneOf": [
+                  { "type": "string" },
+                  {
+                    "type": "object",
+                    "properties": {
+                      "name": { "type": "string" },
+                      "id": { "type": "string" },
+                      "package": { "type": "string" },
+                      "bundle": { "type": "string" },
+                      "plugin": { "type": "string" }
+                    },
+                    "additionalProperties": true
+                  }
+                ]
+              }
+            }
+          },
+          "additionalProperties": true
+        },
+        "compatibility": {
+          "type": "object",
+          "properties": {
+            "dshReleases": {
+              "description": "A declaration, not the host gate; the host checks peerDependencies on @deepseek-ai/dsh*.",
+              "type": "object",
+              "additionalProperties": {
+                "oneOf": [{ "type": "string" }, { "type": "boolean" }]
+              }
+            }
+          },
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": true
+    }
+  }
+}

package/scripts/lib/probe.mjs

@@ -0,0 +1,34 @@
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { resolveArtifact } from '../../src/probe/artifact-resolver.js';
+import { createProbeEnvironment } from '../../src/probe/environment.js';
+import { probePackage as probePinnedPackage } from '../../src/probe/probe.js';
+
+export { WEB_READY, resolveDsh, runDsh, runUntilReady, startStub } from '../../src/probe/dsh-adapter.js';
+export { classify } from '../../src/probe/classify.js';
+export {
+  capture,
+  redact,
+  parseInactive,
+  awaitedServices,
+  rejectionOf,
+  noteOf,
+  payloadOf,
+} from '../../src/probe/probe.js';
+
+export async function probePackage(options) {
+  const artifact = options.artifact || await resolveArtifact(options.target);
+  const environment = options.environment || await createProbeEnvironment({
+    backend: options.backend || 'auto',
+    workDir: options.workDir,
+  });
+  return probePinnedPackage({
+    ...options,
+    artifact,
+    environment,
+    composition: options.composition || options.mode || 'headless',
+  });
+}
+
+export const tmpHome = () => mkdtempSync(join(tmpdir(), 'dsh-probe-'));

package/scripts/probe-boot.mjs

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { downloadArtifact, resolveArtifact } from '../src/probe/artifact-resolver.js';
+import { resolveDsh, startStub } from '../src/probe/dsh-adapter.js';
+import { createProbeEnvironment } from '../src/probe/environment.js';
+import { probePackage } from '../src/probe/probe.js';
+
+const USAGE = [
+  'dsh-plugin-probe — isolated host-half probe for DeepSeek Harness plugins',
+  '',
+  'Usage',
+  '  dsh-plugin-probe <npm-package|path> [...] [options]',
+  '',
+  'Options',
+  '  --dsh <version>       use @deepseek-ai/dsh at an exact npm version (required for the Docker backend)',
+  '  --mode <mode>         headless, web, or both (default: headless)',
+  '  --cache <dir>         cache root for DSH installs and temporary environments (default: system temp)',
+  '  --tools               capture tool inventory through the isolated stub',
+  '  --audit               include the static capability inventory',
+  '  --keep                accepted for CLI compatibility; isolation is always destroyed',
+  '  --unsafe-host         run the desktop DSH without isolation; results remain self-reported',
+  '  -h, --help            show this message',
+  '',
+  'There is no silent host fallback: the Docker backend requires --dsh <version>,',
+  'and the desktop DSH can only be probed with --unsafe-host.',
+  '',
+  'Exit codes: 0 all observations completed · 2 an infrastructure error occurred',
+].join('\n');
+
+const argv = process.argv.slice(2);
+if (argv.includes('-h') || argv.includes('--help')) {
+  console.log(USAGE);
+  process.exit(0);
+}
+const argOf = (name, fallback) => {
+  const index = argv.indexOf(name);
+  return index >= 0 ? argv[index + 1] : fallback;
+};
+const keep = argv.includes('--keep');
+const withTools = argv.includes('--tools');
+const withAudit = argv.includes('--audit');
+const backend = argv.includes('--unsafe-host') ? 'host-unsafe' : 'auto';
+const dshVersion = argOf('--dsh', undefined);
+const modeArg = argOf('--mode', 'headless');
+if (!['headless', 'web', 'both'].includes(modeArg)) {
+  console.error('dsh-plugin-probe: --mode must be headless, web, or both');
+  process.exit(2);
+}
+const modes = modeArg === 'both' ? ['headless', 'web'] : [modeArg];
+const valueFlags = ['--dsh', '--mode', '--cache'];
+const packages = argv.filter((arg, index) => !arg.startsWith('--') && !valueFlags.includes(argv[index - 1]));
+if (packages.length === 0) {
+  console.error(USAGE);
+  process.exit(2);
+}
+
+const cacheRoot = argOf('--cache', process.env.DSH_PROBE_CACHE || join(tmpdir(), 'dsh-plugin-lint-cache'));
+let dsh;
+try {
+  dsh = dshVersion
+    ? { id: 'npm:' + dshVersion, kind: 'npm', version: dshVersion, extraArgs: [] }
+    : await resolveDsh(undefined, cacheRoot);
+} catch (error) {
+  console.error((error.code || 'PROBE_FAILED') + ': ' + (error.message || 'The DSH runtime could not be resolved.'));
+  process.exit(2);
+}
+if (dsh.kind === 'desktop' && backend !== 'host-unsafe') {
+  console.error('dsh-plugin-probe: the desktop DSH can only be probed with --unsafe-host '
+    + '(no container isolation), or pass --dsh <npm-version> to use the Docker backend.');
+  process.exit(2);
+}
+console.log('probing with ' + dsh.id + ' [' + backend + ']' + (withTools ? ' + isolated stub' : ''));
+
+const results = [];
+let failures = 0;
+for (const name of packages) {
+  try {
+    let artifact = await resolveArtifact(name);
+    if (!artifact.local) artifact = await downloadArtifact(artifact);
+    for (const mode of modes) {
+      const environment = await createProbeEnvironment({
+        backend,
+        workDir: cacheRoot,
+        dshDir: dsh.kind === 'npm' && dsh.version !== 'desktop' ? join(cacheRoot, 'dsh', dsh.version) : undefined,
+      });
+      const stub = withTools && mode !== 'web' && backend === 'host-unsafe' ? await startStub() : undefined;
+      try {
+        const observation = await probePackage({ artifact, dsh, environment, stub, tools: withTools, keep, composition: mode, audit: withAudit });
+        results.push({ package: name, mode, ...observation });
+        if (observation.outcome === 'error') {
+          failures += 1;
+          console.error(`${observation.error.code}: ${observation.error.message}`);
+          continue;
+        }
+        console.log(observation.status.padEnd(16) + name + ' [' + mode + ']  (' + observation.durationMs + ' ms)');
+        for (const entry of observation.entries) console.log('                 ' + entry.id + ': ' + entry.reason);
+        if (observation.tools && !observation.tools.error) {
+          console.log('                 tools ' + observation.tools.baseline + ' -> ' + observation.tools.total
+            + (observation.tools.added.length ? '  +' + observation.tools.added.length + ': ' + observation.tools.added.join(', ') : '  (none)'));
+          console.log('                 system prompt ' + observation.systemPrompt.baselineChars + ' -> ' + observation.systemPrompt.chars + ' chars');
+        }
+        if (observation.audit) {
+          console.log('                 audit: ' + observation.audit.observed.length + ' capabilities observed');
+          for (const item of observation.audit.observed) {
+            console.log('                   ' + item.capability + '  (' + item.sites + ' site' + (item.sites === 1 ? '' : 's') + ', first: ' + item.first.file + ')');
+          }
+        }
+      } finally {
+        if (stub) stub.server.close();
+      }
+    }
+  } catch (error) {
+    failures += 1;
+    const code = error.code || 'PROBE_FAILED';
+    const message = code === 'PROBE_FAILED' ? 'The probe could not complete.' : error.message;
+    console.error(`${code}: ${message}`);
+    results.push({ package: name, outcome: 'error', error: { code, message } });
+  }
+}
+
+console.log('\n' + JSON.stringify(results, null, 2));
+process.exitCode = failures > 0 ? 2 : 0;

package/src/composition.js

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

package/src/core/baseline.js

@@ -0,0 +1,98 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { sha256, stableStringify } from '../shared/hash.js';
+import { EVENT_CATALOG, RULES } from './rules.js';
+
+export const BASELINE_SCHEMA_VERSION = 1;
+
+/** Evidence strings can move with formatting; keep the stable part only. */
+export function normalizeEvidence(value) {
+  return String(value ?? '').replace(/\s+/g, ' ').trim();
+}
+
+/** A fingerprint deliberately excludes the line number. */
+export function fingerprint(finding) {
+  return 'sha256:' + sha256(stableStringify({
+    rule: finding.rule,
+    file: finding.file || 'package.json',
+    evidence: normalizeEvidence(finding.evidence),
+  }));
+}
+
+export function rulesetIdentity() {
+  return {
+    hash: sha256(stableStringify(RULES.map((rule) => ({ id: rule.id, level: rule.level })))),
+    rules: RULES.map((rule) => rule.id),
+    eventCatalog: { harvestedAt: EVENT_CATALOG.harvestedAt, dshVersions: EVENT_CATALOG.dshVersions },
+  };
+}
+
+export function createBaseline(reports, { generatedAt = new Date().toISOString() } = {}) {
+  const seen = new Set();
+  const findings = [];
+  for (const report of reports) {
+    for (const finding of report.findings) {
+      const print = fingerprint(finding);
+      if (seen.has(print)) continue;
+      seen.add(print);
+      findings.push({
+        fingerprint: print,
+        rule: finding.rule,
+        level: finding.level,
+        file: finding.file || 'package.json',
+        evidence: normalizeEvidence(finding.evidence),
+      });
+    }
+  }
+  return {
+    schemaVersion: BASELINE_SCHEMA_VERSION,
+    generatedAt,
+    ruleset: rulesetIdentity(),
+    findings,
+  };
+}
+
+export function readBaseline(path) {
+  const value = JSON.parse(readFileSync(path, 'utf8'));
+  if (!value || value.schemaVersion !== BASELINE_SCHEMA_VERSION || !Array.isArray(value.findings)) {
+    throw new Error('not a dsh-plugin-lint baseline: ' + path);
+  }
+  for (const entry of value.findings) {
+    if (typeof entry.fingerprint !== 'string' || typeof entry.rule !== 'string') {
+      throw new Error('baseline entry is missing fingerprint/rule: ' + path);
+    }
+  }
+  return value;
+}
+
+export function writeBaseline(path, baseline) {
+  writeFileSync(path, JSON.stringify(baseline, null, 2) + '\n');
+}
+
+/** Filter baseline fingerprints out of each report and recompute its summary. */
+export function applyBaseline(reports, baseline, { path } = {}) {
+  const known = new Set(baseline.findings.map((entry) => entry.fingerprint));
+  let suppressed = 0;
+  const filtered = reports.map((report) => {
+    const findings = [];
+    for (const finding of report.findings) {
+      if (known.has(fingerprint(finding))) suppressed += 1;
+      else findings.push(finding);
+    }
+    const summary = { error: 0, warn: 0, info: 0 };
+    for (const finding of findings) summary[finding.level] += 1;
+    return { ...report, findings, summary, baseline: { suppressed: report.findings.length - findings.length, path: path || null } };
+  });
+  return { reports: filtered, suppressed };
+}
+
+/** Keep only baseline entries that still occur in the current run. */
+export function pruneBaseline(baseline, reports, { generatedAt = baseline.generatedAt } = {}) {
+  const current = new Set();
+  for (const report of reports) for (const finding of report.findings) current.add(fingerprint(finding));
+  return {
+    ...baseline,
+    generatedAt,
+    ruleset: rulesetIdentity(),
+    findings: baseline.findings.filter((entry) => current.has(entry.fingerprint)),
+  };
+}

package/src/core/changed.js

@@ -0,0 +1,41 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+
+/** Files changed against `ref` (default HEAD) or staged in the index. */
+export function changedFiles({ cwd = process.cwd(), ref, staged = false } = {}) {
+  const args = ['diff', '--name-only', '--diff-filter=ACMR'];
+  if (staged) args.push('--cached');
+  args.push(ref || 'HEAD');
+  const output = execFileSync('git', args, { cwd, encoding: 'utf8' });
+  return output.split('\n').map((line) => line.trim()).filter(Boolean);
+}
+
+/**
+ * Map changed files to the nearest enclosing package.json. Deleted files map
+ * to their former directory; files outside any package are ignored.
+ */
+export function packageRoots(files, cwd = process.cwd()) {
+  const base = resolve(cwd);
+  const roots = new Set();
+  for (const file of files) {
+    let dir = resolve(base, file);
+    try {
+      if (!statSync(dir).isDirectory()) dir = dirname(dir);
+    } catch {
+      dir = dirname(dir);
+    }
+    while (true) {
+      const rel = relative(base, dir);
+      if (rel.startsWith('..') || isAbsolute(rel)) break;
+      if (existsSync(join(dir, 'package.json'))) {
+        roots.add(dir);
+        break;
+      }
+      const parent = dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  }
+  return [...roots].sort();
+}

package/src/core/load.js

@@ -0,0 +1,145 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import { maskSource } from './mask.js';
+import { globToRegExp } from './packlist.js';
+
+/** Directories that never hold shipped plugin code. */
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', '.github', '.husky', '.dsh-testkit', 'coverage', 'fixtures',
+  'test', 'tests', '__tests__', '__snapshots__', 'dist-test',
+]);
+
+/** Guard rails so one huge vendored file cannot stall a run. */
+const MAX_FILE_BYTES = 3 * 1024 * 1024;
+const MAX_FILES = 3000;
+
+export function loadPackage(dir, options = {}) {
+  const manifestPath = join(dir, 'package.json');
+  if (!existsSync(manifestPath)) throw new Error('not a package directory (no package.json): ' + dir);
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+
+  const norm = (p) => (p === undefined ? undefined : String(p).replace(/^\.\//, ''));
+  // Node resolves an undeclared package entry to index.js, so the fallback is
+  // correct for resolution — but "nothing was declared" is not the same as
+  // "index.js was declared and is missing". A static asset package (measured:
+  // @deepseek-ai/dsh-web-frontend exports only ./dist/*) has no host entry at all,
+  // and flagging it would be a false positive.
+  // Node resolves exports["."] before main; the loader imports the package by
+  // name and follows the same order. Keeping main first made a stale main an
+  // error even when exports["."] was the entry that actually loaded.
+  const mainEntry = firstString(manifest.main);
+  const declaredHost = exportTarget(manifest.exports, '.') || mainEntry;
+  const entries = {
+    host: norm(declaredHost || 'index.js'),
+    // A configuration-only bundle (dsh.bundle) needs no host entry at all
+    // (references/mcp-bundle.md): only exports["."]/main make the host file
+    // mandatory, and only they may turn a missing index.js into an E3 error.
+    hostDeclared: Boolean(declaredHost),
+    main: norm(mainEntry),
+    mainDeclared: Boolean(mainEntry),
+    // The browser half resolves only a string or a string default; import and
+    // require conditions are Node-only and the client registry rejects them.
+    client: norm(clientExportTarget(manifest.exports, './client') || (manifest.dsh && manifest.dsh.client ? 'client.js' : undefined)),
+    patch: norm(manifest.dsh && manifest.dsh.bundle ? firstString(manifest.dsh.bundle.patch) : undefined),
+    icon: norm(firstString(manifest.icon)),
+    localeDir: existsSync(join(dir, 'locale')) ? 'locale' : undefined,
+  };
+
+  const jsFiles = [];
+  const authorPhase = options.phase === 'author';
+  collect(dir, dir, jsFiles, authorPhase);
+
+  return {
+    dir,
+    manifest,
+    manifestPath,
+    phase: options.phase || 'publish',
+    buildScripts: Boolean(manifest.scripts && (manifest.scripts.build || manifest.scripts.prepack || manifest.scripts.prepare)),
+    entries,
+    jsFiles,
+    files: Array.isArray(manifest.files) ? manifest.files : undefined,
+    exists: (rel) => rel !== undefined && existsSync(join(dir, rel)),
+    text: (rel) => (existsSync(join(dir, rel)) ? readFileSync(join(dir, rel), 'utf8') : undefined),
+    json: (rel) => {
+      const t = existsSync(join(dir, rel)) ? readFileSync(join(dir, rel), 'utf8') : undefined;
+      if (t === undefined) return undefined;
+      try { return JSON.parse(t); } catch { return undefined; }
+    },
+  };
+}
+
+/** Artifacts a build step produces; an author-phase run may legitimately lack them. */
+export function isBuildOutput(rel) {
+  const value = String(rel || '').replace(/^\.\//, '');
+  return /^(lib|dist|build|out)\//.test(value) || /\.(js|mjs|cjs|jsx)$/.test(value);
+}
+
+function collect(root, current, out, authorPhase = false) {
+  const pattern = authorPhase ? /\.(js|mjs|cjs|jsx|ts|tsx|mts|cts)$/ : /\.(js|mjs|cjs|jsx)$/;
+  let names;
+  try { names = readdirSync(current, { withFileTypes: true }); } catch { return; }
+  for (const dirent of names) {
+    const abs = join(current, dirent.name);
+    if (dirent.isDirectory()) {
+      if (SKIP_DIRS.has(dirent.name)) continue;
+      collect(root, abs, out, authorPhase);
+      continue;
+    }
+    if (!pattern.test(dirent.name)) continue;
+    let size = 0;
+    try { size = statSync(abs).size; } catch { continue; }
+    if (size > MAX_FILE_BYTES) continue;
+    if (out.length >= MAX_FILES) return;
+    const text = readFileSync(abs, 'utf8');
+    const rel = relative(root, abs).split(sep).join('/');
+    const { masked, structural, strings, lineStarts } = maskSource(text);
+    out.push({ path: rel, text, masked, structural, strings, lineStarts, bytes: size });
+  }
+}
+
+function firstString(value) {
+  return typeof value === 'string' && value !== '' ? value : undefined;
+}
+
+/** Resolve an exports subpath to a file path, accepting the Node entry forms. */
+export function exportTarget(exportsField, subpath) {
+  if (exportsField === undefined || exportsField === null) return undefined;
+  if (typeof exportsField === 'string') return subpath === '.' ? exportsField : undefined;
+  const entry = exportsField[subpath];
+  if (entry === undefined) return undefined;
+  if (typeof entry === 'string') return entry;
+  if (entry && typeof entry === 'object') return firstString(entry.default) || firstString(entry.import) || firstString(entry.require);
+  return undefined;
+}
+
+/**
+ * Resolve the browser client entry the way the host's ClientModuleRegistry does:
+ * a string, or an object with a string `default`. import/require are Node-only
+ * conditions and are rejected by the client resolver.
+ */
+export function clientExportTarget(exportsField, subpath = './client') {
+  if (exportsField === undefined || exportsField === null) return undefined;
+  if (typeof exportsField === 'string') return subpath === '.' ? exportsField : undefined;
+  const entry = exportsField[subpath];
+  if (entry === undefined) return undefined;
+  if (typeof entry === 'string') return entry;
+  if (entry && typeof entry === 'object') return firstString(entry.default);
+  return undefined;
+}
+
+export function filesCover(files, relPath) {
+  if (files === undefined || files.length === 0) return true;
+  relPath = String(relPath).replace(/^\.\//, '');
+  let covered = false;
+  for (const raw of files) {
+    let pattern = String(raw).trim().replace(/^\.\//, '').replace(/\/+$/, '');
+    const negated = pattern.startsWith('!');
+    if (negated) pattern = pattern.slice(1);
+    if (!pattern) continue;
+    const matches = pattern === relPath
+      || relPath.startsWith(pattern + '/')
+      || ((pattern.includes('*') || pattern.includes('?') || pattern.includes('[')) && globToRegExp(pattern).test(relPath));
+    if (matches) covered = !negated;
+  }
+  return covered;
+}