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

package/src/data/event-types.json

@@ -0,0 +1,291 @@
+{
+  "$comment": "Session event types observed in the official DeepSeek Harness packages. Regenerate with scripts/harvest-event-types.mjs against an installed DSH.",
+  "source": "DeepSeek Harness (MIT); harvested from @deepseek-ai/* lib bundles",
+  "harvestedAt": "2026-10-13",
+  "filesScanned": 470,
+  "appendSiteTypes": 45,
+  "observedTypes": 280,
+  "types": [
+    "agent-loop/config-start-failed",
+    "agent-preset/conflict",
+    "agent-preset/invalid",
+    "agent-preset/locked",
+    "agent-preset/not-found",
+    "agent-preset/selected",
+    "agent/assistant-stream",
+    "agent/created",
+    "agent/disposed",
+    "agent/error",
+    "agent/pre-step",
+    "agent/request",
+    "agent/request-error",
+    "agent/status",
+    "agent/turn-stopping",
+    "api-session/activity",
+    "api-session/added",
+    "api-session/error",
+    "api-session/removed",
+    "api-session/status",
+    "app-boot/config-reload",
+    "approval/asked",
+    "approval/decided",
+    "approval/policy",
+    "approval/request",
+    "assistant/attempt",
+    "assistant/chunk",
+    "assistant/live-chunk",
+    "assistant/message",
+    "authorization/settled",
+    "command/done",
+    "command/executed",
+    "command/run",
+    "commands/change",
+    "compact/end",
+    "compact/prune",
+    "compact/start",
+    "compact/summary",
+    "compaction/end",
+    "compaction/prune",
+    "compaction/start",
+    "compaction/summary",
+    "compaction/summary-error",
+    "connection/request",
+    "connection/reset",
+    "cordis/dynamic-package",
+    "cordis/dynamic-retract",
+    "cordis/inspect-query",
+    "cordis/inspect-query-resolved",
+    "cordis/request-run",
+    "cordis/request-run-resolved",
+    "credential/rejected",
+    "credentials/describe",
+    "credentials/record-updated",
+    "credentials/reference-updated",
+    "credentials/set",
+    "deepseek-account/model-sign-in-required",
+    "deepseek-account/session-expired",
+    "deepseek-account/signed-out",
+    "deliverables/presented",
+    "developer/message",
+    "directory-picker/create-failed",
+    "directory-picker/exists",
+    "directory-picker/unavailable",
+    "directory-picker/unreadable",
+    "document-render/failed",
+    "domain/changed",
+    "dsh-commands/brand",
+    "dsh-llm/brand",
+    "ecdsa/rsa",
+    "eventsource-parser/stream",
+    "f/aqlbg",
+    "f/gfp",
+    "feedback/committed",
+    "feedback/message-delete",
+    "feedback/message-put",
+    "feedback/record",
+    "fmwvqz/sqb",
+    "fmwvqz/sqlefppjlmbopmf",
+    "foo/bar",
+    "fs/edit-intent",
+    "fs/observed",
+    "fs/promises",
+    "fs/write-intent",
+    "gateway/ambiguous-endpoint",
+    "gateway/arguments-invalid",
+    "gateway/bad-request",
+    "gateway/binding-invalid",
+    "gateway/cancelled",
+    "gateway/context-failed",
+    "gateway/context-not-found",
+    "gateway/context-unavailable",
+    "gateway/definition-unavailable",
+    "gateway/input-invalid",
+    "gateway/internal",
+    "gateway/invocation-unavailable",
+    "gateway/lookup-failed",
+    "gateway/lookup-not-found",
+    "gateway/lookup-unavailable",
+    "gateway/method-unavailable",
+    "gateway/protocol",
+    "gateway/provider-mismatch",
+    "gateway/result-invalid",
+    "gateway/service-unavailable",
+    "gateway/signature-invalid",
+    "gateway/uplink-overflow",
+    "goal/activation-changed",
+    "goal/change",
+    "goal/changed",
+    "hmr/change",
+    "hmr/reload",
+    "hook/invoked",
+    "hook/result",
+    "image/offload",
+    "internal/config",
+    "internal/dispatch",
+    "internal/get",
+    "internal/listener",
+    "internal/plugin",
+    "internal/service",
+    "internal/set",
+    "internal/status",
+    "internal/update",
+    "job/not-found",
+    "kb/mqfbgj",
+    "llm/adapters-updated",
+    "llm/model-discovery-rejected",
+    "llm/retry",
+    "llm/retry-started",
+    "llm/stream",
+    "loader/config-update",
+    "loader/entry-init",
+    "loader/partial-dispose",
+    "loader/patch-context",
+    "loader/volatile-update",
+    "locale/change",
+    "m/h",
+    "m/hr",
+    "m/s",
+    "m/sec",
+    "mm/dd",
+    "mode/set",
+    "model/selection",
+    "permission-presets/catalog-changed",
+    "permission/preset",
+    "plan/invalid-address",
+    "plan/mode",
+    "plan/not-found",
+    "plan/read-failed",
+    "plan/unavailable",
+    "plugin-manager/changed",
+    "plugin-manager/install-log",
+    "plugin-manager/install-state",
+    "request/context",
+    "request/header",
+    "request/header-delta",
+    "resources/list",
+    "resources/read",
+    "sandbox/mode",
+    "schedule/change",
+    "schedule/changed",
+    "schedule/list",
+    "session-log-deepseek/delivery-accepted",
+    "session-telemetry/record",
+    "session/agent-busy",
+    "session/attachment-invalid",
+    "session/conflict",
+    "session/created",
+    "session/disposed",
+    "session/end-seed",
+    "session/event",
+    "session/flush",
+    "session/fork-unavailable",
+    "session/invalid-time-zone",
+    "session/model-unavailable",
+    "session/not-found",
+    "session/projections-unavailable",
+    "session/prompt",
+    "session/provider-credentials-unavailable",
+    "session/provider-models-unavailable",
+    "session/queue-item-not-found",
+    "session/steer-unavailable",
+    "session/title",
+    "session/title-invalid",
+    "session/title-llm-request",
+    "session/workspace-attach-failed",
+    "session/writer-held",
+    "settings/conflict",
+    "settings/document-updated",
+    "settings/rejected",
+    "shiki/core",
+    "skills/change",
+    "slash/input-begin-command",
+    "slash/input-consume-token",
+    "slash/input-insert-reference",
+    "slash/input-insert-text",
+    "slots/changed",
+    "speech/invalid-audio",
+    "speech/transcription-failed",
+    "steering/message",
+    "step/end",
+    "step/start",
+    "subagent/attachment-invalid",
+    "subagent/catalog",
+    "subagent/catalog-diagnostic",
+    "subagent/delivery-unavailable",
+    "subagent/descriptor",
+    "subagent/end",
+    "subagent/invalid-time-zone",
+    "subagent/model-selection-policy",
+    "subagent/not-found",
+    "subagent/not-resumable",
+    "subagent/parent-unavailable",
+    "subagent/provider-added",
+    "subagent/provider-removed",
+    "subagent/start",
+    "subagent/unauthorized",
+    "system-prompt/assemble",
+    "system-prompt/change",
+    "system/message",
+    "team/member",
+    "team/task",
+    "terminal/control-unavailable",
+    "terminal/limit-reached",
+    "terminal/unavailable",
+    "terminal/view",
+    "theme/change",
+    "todo/write",
+    "tool-workflow/agent-end",
+    "tool-workflow/agent-start",
+    "tool-workflow/run-end",
+    "tool-workflow/run-start",
+    "tool/call",
+    "tool/code-dispatch",
+    "tool/code-dispatch-start",
+    "tool/ptc-dispatch",
+    "tool/ptc-dispatch-start",
+    "tool/result",
+    "tools/call",
+    "tools/change",
+    "tools/execute",
+    "tools/list",
+    "tools/post-execute",
+    "tools/pre-execute",
+    "tools/ptc-dispatch-log",
+    "tools/result",
+    "tsx/esm",
+    "turn/end",
+    "turn/start",
+    "user-questions/request",
+    "user/message",
+    "v3/opaque-released-event",
+    "web/deepseek-search-llm-request",
+    "webserver/index-inject",
+    "workflow/agent-end",
+    "workflow/agent-start",
+    "workflow/end",
+    "workflow/log",
+    "workflow/phase",
+    "workflow/start",
+    "workspace-file/not-directory",
+    "workspace-file/not-found",
+    "workspace-file/not-regular-file",
+    "workspace-file/not-text",
+    "workspace-file/outside-workspace",
+    "workspace-file/too-large",
+    "workspace-file/unknown-workspace",
+    "workspace-file/unsupported-address",
+    "workspace-file/watch-unsupported",
+    "workspace/changes",
+    "workspace/invalid-path",
+    "workspace/move-invalid",
+    "workspace/name-conflict",
+    "workspace/not-found",
+    "workspace/session-active",
+    "workspace/session-activity",
+    "workspace/session-stop",
+    "x/name",
+    "zustand/middleware",
+    "zustand/shallow",
+    "zustand/vanilla"
+  ]
+}

package/src/index.js

@@ -0,0 +1,76 @@
+import { loadPackage } from './load.js';
+import { RULES, EVENT_TYPES, localeMeta, DOC } from './rules.js';
+
+export { RULES, EVENT_TYPES, DOC };
+export { maskSource } from './mask.js';
+export { loadPackage, filesCover } from './load.js';
+export { formatText, toSarif } from './report.js';
+
+const LEVEL_ORDER = { error: 0, warn: 1, info: 2 };
+
+/** Statements every report carries, so a clean run is never read as an endorsement. */
+const LIMITS = [
+  'Static analysis of files on disk: it reports what it detected and makes no security judgement.',
+  'Line numbers in bundled or minified artifacts point at the bundle, not at the original source.',
+  'A rule cites the upstream document it encodes; the installed Harness remains the authority.',
+];
+
+export function lintPackage(dir, options = {}) {
+  const pkg = loadPackage(dir);
+  const manifestText = pkg.text('package.json') || '';
+  const ctx = Object.assign({}, pkg, {
+    manifestText,
+    byPath: (rel) => pkg.jsFiles.find((f) => f.path === rel),
+    localeFiles: () => (pkg.entries.localeDir ? localeMeta(dir, pkg.entries.localeDir) : []),
+  });
+
+  const findings = [];
+  for (const rule of RULES) {
+    const push = (finding) => {
+      findings.push(Object.assign({ rule: rule.id, level: rule.level, title: rule.title, doc: rule.doc }, finding));
+    };
+    try {
+      rule.check(ctx, options, push);
+    } catch (error) {
+      findings.push({
+        rule: rule.id,
+        level: 'info',
+        title: rule.title,
+        doc: rule.doc,
+        file: 'package.json',
+        line: 1,
+        message: 'rule did not complete: ' + error.message,
+        evidence: '',
+        hint: 'This is a bug in dsh-plugin-lint; please report it.',
+      });
+    }
+  }
+
+  findings.sort((a, b) => LEVEL_ORDER[a.level] - LEVEL_ORDER[b.level]
+    || String(a.file).localeCompare(String(b.file))
+    || (a.line || 0) - (b.line || 0)
+    || a.rule.localeCompare(b.rule));
+
+  const summary = { error: 0, warn: 0, info: 0 };
+  for (const f of findings) summary[f.level] += 1;
+
+  const declared = (pkg.manifest.dsh && pkg.manifest.dsh.compatibility
+    && pkg.manifest.dsh.compatibility.dshReleases) || undefined;
+
+  return {
+    schemaVersion: 1,
+    target: {
+      name: pkg.manifest.name,
+      version: pkg.manifest.version,
+      path: dir,
+    },
+    dsh: {
+      declared: declared ? Object.keys(declared) : [],
+      verified: [],
+    },
+    checks: RULES.length,
+    summary,
+    findings,
+    limits: LIMITS,
+  };
+}

package/src/load.js

@@ -0,0 +1,116 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import { maskSource } from './mask.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) {
+  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.
+  const declaredHost = firstString(manifest.main) || exportTarget(manifest.exports, '.');
+  const entries = {
+    host: norm(declaredHost || 'index.js'),
+    hostDeclared: Boolean(declaredHost || (manifest.dsh && manifest.dsh.bundle)),
+    client: norm(exportTarget(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 = [];
+  collect(dir, dir, jsFiles);
+
+  return {
+    dir,
+    manifest,
+    manifestPath,
+    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; }
+    },
+  };
+}
+
+function collect(root, current, out) {
+  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);
+      continue;
+    }
+    if (!/\.(js|mjs|cjs|jsx)$/.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 string and {default} 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;
+}
+
+/**
+ * npm packing semantics, simplified: an entry covers a path when it is the same
+ * file, a parent directory, or a glob whose pattern matches. \`files\` absent means
+ * everything is published.
+ */
+export function filesCover(files, relPath) {
+  if (files === undefined || files.length === 0) return true;
+  relPath = String(relPath).replace(/^\.\//, '');
+  for (const raw of files) {
+    const pattern = String(raw).replace(/^\.\//, '').replace(/\/+$/, '');
+    if (pattern === '' ) continue;
+    if (pattern === relPath) return true;
+    if (relPath.startsWith(pattern + '/')) return true;
+    if (pattern.includes('*')) {
+      const re = new RegExp('^' + pattern
+        .replace(/[.+^$()|[\]{}\\]/g, '\\$&')
+        .replace(/\*\*\//g, '(?:.*/)?')
+        .replace(/\*\*/g, '.*')
+        .replace(/(?<!\.)\*/g, '[^/]*') + '$');
+      if (re.test(relPath)) return true;
+    }
+  }
+  return false;
+}

package/src/mask.js

@@ -0,0 +1,156 @@
+/**
+ * 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.
+  const regexAllowed = (prev) => prev === '' || '(,=:[!&|?{};+-*%<>~^'.indexOf(prev) >= 0;
+  const lastMeaningful = (idx) => {
+    for (let k = idx - 1; k >= 0; k--) {
+      const c = maskedChars[k];
+      if (c === SP || c === NL || c === '\t') continue;
+      return c;
+    }
+    return '';
+  };
+
+  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(lastMeaningful(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;
+      }
+      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) call sites. */
+export function appendCallSites(masked, strings) {
+  const out = [];
+  const re = /\.append\(\s*/g;
+  let m;
+  while ((m = re.exec(masked)) !== null) {
+    const s = stringAfter(strings, m.index + m[0].length, 32);
+    if (s) out.push({ type: s.value, index: s.start, line: s.line });
+  }
+  return out;
+}
+
+/** 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;
+}