dsh-d365-kit 0.0.0-stage → 0.34.3

package/lib/tool-refs.js

@@ -0,0 +1,206 @@
+/**
+ * `d365_refs` — the reverse question: who uses this?
+ *
+ * `d365_metadata` answers "does it exist"; `d365_layers` answers "who overrides
+ * it"; this answers "what breaks if I remove or rename it". Every branch reads
+ * stored definitions (formxml, layoutxml/fetchxml, workflow clientdata) and
+ * reports exact matches, so the answer is evidence rather than a guess.
+ */
+import { loadConfig } from './config.js'
+import { makeClient, pickEnvironments, writeArtifact } from './runtime.js'
+import { D365Error } from './errors.js'
+import {
+  findFieldAutomations,
+  findFieldForms,
+  findFieldViews,
+  findPluginUsage,
+  findResourceForms,
+} from './refs.js'
+
+const KINDS = ['field', 'web_resource', 'plugin_assembly']
+
+export const definition = {
+  name: 'd365_refs',
+  description:
+    '反查引用：某个字段被哪些表单/视图/流程使用，某个 Web 资源被哪些表单加载，某个插件程序集有哪些注册类型与步骤。'
+    + '用于判断"改这个/删这个会不会坏"，与 d365_layers（谁覆盖）互补。可一次查多个环境。',
+  parameters: {
+    type: 'object',
+    additionalProperties: false,
+    required: ['kind'],
+    properties: {
+      kind: {
+        type: 'string',
+        enum: KINDS,
+        description: 'field：字段引用；web_resource：表单脚本引用；plugin_assembly：插件注册情况。',
+      },
+      entity: {
+        type: 'string',
+        description: 'kind=field 时必填：字段所属实体逻辑名，例如 account。',
+      },
+      attribute: {
+        type: 'string',
+        description: 'kind=field 时必填：字段逻辑名，例如 contoso_customertier。',
+      },
+      name: {
+        type: 'string',
+        description: 'kind=web_resource 时填 Web 资源名称（如 contoso_/scripts/account_form.js）；kind=plugin_assembly 时填程序集名（如 Contoso.Customizations）。',
+      },
+      environment: {
+        type: 'string',
+        description: '环境 key，例如 dev。省略则用默认环境。',
+      },
+      environments: {
+        type: 'array',
+        items: { type: 'string' },
+        description: '一次查多个环境，例如 ["dev","sit"]。',
+      },
+      allEnvironments: {
+        type: 'boolean',
+        description: '对全部已配置环境执行同一查询。',
+      },
+    },
+  },
+  output: {
+    schema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['text'],
+      properties: {
+        text: { type: 'string' },
+      },
+    },
+    render(_args, value) {
+      return [{ type: 'text', text: value?.text ?? '' }]
+    },
+  },
+}
+
+/** Render a field reference report for one environment. */
+function renderField(env, entity, attribute, result) {
+  const lines = [`字段 ${entity}.${attribute} 的引用（${env.key}）`]
+  const total = result.forms.length + result.views.length + result.automations.length
+
+  lines.push('', `表单：${result.forms.length} 张`)
+  for (const form of result.forms.slice(0, 10)) {
+    lines.push(`- ${form.name}（${form.typeLabel}${form.managed ? '，受管' : ''}${form.visible ? '' : '，字段被隐藏'}）`)
+  }
+  if (result.forms.length > 10) lines.push(`- … 其余 ${result.forms.length - 10} 张见文件`)
+
+  const layout = result.views.filter((view) => view.inLayout).length
+  const filtered = result.views.filter((view) => view.inFilter).length
+  lines.push('', `视图：${result.views.length} 个（列 ${layout} / 筛选条件 ${filtered}）`)
+  for (const view of result.views.slice(0, 10)) {
+    const usage = [view.inLayout ? '显示列' : null, view.inFilter ? '筛选条件' : null].filter(Boolean).join('+')
+    lines.push(`- ${view.name}（${usage}${view.default ? '，默认视图' : ''}）`)
+  }
+  if (result.views.length > 10) lines.push(`- … 其余 ${result.views.length - 10} 个见文件`)
+
+  lines.push('', `流程/业务规则：${result.automations.length} 个`)
+  for (const item of result.automations.slice(0, 10)) {
+    lines.push(`- ${item.name}（${item.category}，${item.state}）`)
+  }
+  if (result.automations.length > 10) lines.push(`- … 其余 ${result.automations.length - 10} 个见文件`)
+
+  lines.push(
+    '',
+    total
+      ? `结论：共 ${total} 处引用；删除或改名会同时影响上述位置。`
+      : '结论：没有找到引用。注意本工具按实体过滤表单，快速查看表单里引用其它实体字段的情况不在范围内。',
+  )
+  return lines.join('\n')
+}
+
+/** Render a web resource report for one environment. */
+function renderResource(env, name, forms) {
+  const lines = [`Web 资源 ${name} 的引用（${env.key}）`]
+  if (!forms.length) {
+    lines.push('', '结论：没有表单引用这个库。若它是 ribbon 命令或独立加载的脚本，这不代表它没在用。')
+    return lines.join('\n')
+  }
+  lines.push('', `表单：${forms.length} 张`)
+  let handlers = 0
+  for (const form of forms.slice(0, 12)) {
+    handlers += form.handlers.length
+    const names = form.handlers.map((h) => `${h.event || '?'}→${h.functionName || '?'}`).join('，')
+    lines.push(`- ${form.name}（${form.typeLabel}，${form.entity}）${names ? `：${names}` : ''}`)
+  }
+  if (forms.length > 12) lines.push(`- … 其余 ${forms.length - 12} 张见文件`)
+  lines.push('', `结论：${forms.length} 张表单加载该库，共 ${handlers} 个事件处理器；改函数名或删文件会让这些处理器失效。`)
+  return lines.join('\n')
+}
+
+/** Render a plugin assembly report for one environment. */
+function renderAssembly(env, name, result) {
+  const { assembly, types } = result
+  const lines = [
+    `插件程序集 ${assembly.name} 的注册情况（${env.key}）`,
+    `版本：${assembly.version ?? '未知'}，隔离模式：${assembly.isolation ?? '?'}`,
+    `类型：${types.length} 个`,
+  ]
+  let stepCount = 0
+  let disabled = 0
+  for (const type of types.slice(0, 12)) {
+    stepCount += type.steps.length
+    disabled += type.steps.filter((step) => !step.enabled).length
+    lines.push('', `- ${type.typename}`)
+    if (!type.steps.length) lines.push('  （没有注册步骤）')
+    for (const step of type.steps.slice(0, 8)) {
+      const filter = step.filteringAttributes ? `，过滤 ${step.filteringAttributes}` : ''
+      lines.push(`  · ${step.name}（stage ${step.stage}，mode ${step.mode}，rank ${step.rank ?? 1}${filter}${step.enabled ? '' : '，已停用'}）`)
+    }
+    if (type.steps.length > 8) lines.push(`  · … 其余 ${type.steps.length - 8} 步见文件`)
+  }
+  if (types.length > 12) lines.push(`… 其余 ${types.length - 12} 个类型见文件`)
+  lines.push('', `结论：共 ${stepCount} 个步骤${disabled ? `，其中 ${disabled} 个已停用` : ''}。`)
+  return lines.join('\n')
+}
+
+export function register(ctx, state) {
+  return ctx.tools.register({
+    ...definition,
+    async execute(args, exec) {
+      const config = await loadConfig(state.rawConfig)
+      const kind = args.kind
+      if (!KINDS.includes(kind)) {
+        throw new D365Error(`不认识的查询类型：${kind}`, { code: 'unknown-kind', hint: `可选：${KINDS.join(' / ')}` })
+      }
+      if (kind === 'field' && (!args.entity || !args.attribute)) {
+        throw new D365Error('kind=field 需要 entity 和 attribute', { code: 'missing-field' })
+      }
+      if (kind !== 'field' && !args.name) {
+        throw new D365Error(`kind=${kind} 需要 name`, { code: 'missing-name' })
+      }
+
+      const envs = pickEnvironments(config, args)
+      const sections = []
+      const artifact = { kind, entity: args.entity, attribute: args.attribute, name: args.name, environments: {} }
+
+      for (const env of envs) {
+        const client = makeClient(env, config)
+        let text
+        if (kind === 'field') {
+          const result = {
+            forms: await findFieldForms(client, args.entity, args.attribute, exec?.signal),
+            views: await findFieldViews(client, args.entity, args.attribute, exec?.signal),
+            automations: await findFieldAutomations(client, args.entity, args.attribute, exec?.signal),
+          }
+          artifact.environments[env.key] = result
+          text = renderField(env, args.entity, args.attribute, result)
+        } else if (kind === 'web_resource') {
+          const forms = await findResourceForms(client, args.name, exec?.signal)
+          artifact.environments[env.key] = { forms }
+          text = renderResource(env, args.name, forms)
+        } else {
+          const result = await findPluginUsage(client, args.name, exec?.signal)
+          artifact.environments[env.key] = result
+          text = renderAssembly(env, args.name, result)
+        }
+        sections.push(text)
+      }
+
+      const file = await writeArtifact(config, `refs-${kind}`, artifact)
+      return { text: `${sections.join('\n\n')}\n\n完整结果：${file}` }
+    },
+  })
+}

package/lib/tool-reports.js

@@ -0,0 +1,299 @@
+/**
+ * `d365_reports` — one place to see what the other tools produced, how much
+ * space `.d365` is using, and to apply the retention policy by hand.
+ *
+ * Cleanup always plans first (`dryRun` defaults to true) and never touches
+ * waivers, pending plans, config or secrets.
+ */
+
+import { readdir, readFile, stat } from 'node:fs/promises'
+import { isAbsolute, join, relative, resolve } from 'node:path'
+import { loadConfig } from './config.js'
+import { D365Error } from './errors.js'
+import { dataRoot } from './snapshot.js'
+import { readHistory } from './contract-history.js'
+import { readWaivers } from './waivers.js'
+import {
+  applyCleanup, compactAllSnapshots, formatBytes, planCleanup, storageSummary,
+} from './retention.js'
+
+const CLASS_IDS = ['snapshots', 'reports', 'diffs', 'query', 'changes', 'all']
+
+async function listFiles(directory, limit) {
+  let names = []
+  try {
+    names = await readdir(directory)
+  } catch {
+    return []
+  }
+  const rows = []
+  for (const name of names) {
+    try {
+      const info = await stat(join(directory, name))
+      if (!info.isFile()) continue
+      rows.push({ name, size: info.size, modifiedAt: info.mtime.toISOString() })
+    } catch {
+      // A file that vanished between readdir and stat is simply not listed.
+    }
+  }
+  rows.sort((a, b) => b.modifiedAt.localeCompare(a.modifiedAt))
+  return rows.slice(0, limit)
+}
+
+const VIEW_DEFAULT_LIMIT = 60
+const VIEW_MAX_LIMIT = 2000
+const VIEW_WRAP_DEFAULT = 400
+
+/** @returns true when `file` stays inside `root` (no `..` escape, no absolute jump). */
+function insideRoot(root, file) {
+  const rel = relative(root, file)
+  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel))
+}
+
+/**
+ * Locate an artifact the model asked to read.
+ *
+ * Only files under `.d365` are reachable: an absolute path that points
+ * elsewhere is refused rather than silently read, because the tool's contract
+ * is "show me what this plugin wrote", not "read any file".
+ * @returns `{ file, size }`
+ */
+async function resolveArtifact(config, name) {
+  const wanted = String(name ?? '').trim()
+  if (!wanted) {
+    throw new D365Error('view 需要 file', {
+      hint: '先用 action=list 看有哪些产物；file 可以是 .d365 下的相对路径（如 query/xxx.json）或文件名。',
+    })
+  }
+  const root = resolve(dataRoot(config))
+  const candidates = isAbsolute(wanted)
+    ? [resolve(wanted)]
+    : [resolve(root, wanted), ...['query', 'reports', 'diffs', 'changes'].map((dir) => resolve(root, dir, wanted))]
+  for (const candidate of candidates) {
+    if (!insideRoot(root, candidate)) continue
+    try {
+      const info = await stat(candidate)
+      if (info.isFile()) return { file: candidate, size: info.size }
+    } catch {
+      // Not here; the next candidate may be.
+    }
+  }
+  throw new D365Error(`找不到产物：${wanted}`, {
+    code: 'artifact-not-found',
+    hint: '只在 .d365 目录里查找。用 action=list 看现有文件；绝对路径也必须落在这个目录内。',
+  })
+}
+
+/**
+ * Render a window of one artifact.
+ *
+ * JSON written by the query tools is one very long line, so it is expanded by
+ * default; `match` narrows to the lines that mention a string, which is the
+ * only practical way to find one GUID in a 500 KB result.
+ */
+async function renderView(config, args) {
+  const { file, size } = await resolveArtifact(config, args.file)
+  const raw = await readFile(file, 'utf8')
+  const isJson = file.toLowerCase().endsWith('.json')
+  const pretty = args.pretty ?? isJson
+  let text = raw
+  if (pretty && isJson) {
+    try {
+      text = JSON.stringify(JSON.parse(raw), null, 2)
+    } catch {
+      // Malformed or truncated JSON: show what is on disk instead of failing.
+    }
+  }
+
+  const allLines = text.split(/\r?\n/)
+  const match = String(args.match ?? '').trim()
+  const numbered = allLines.map((line, index) => ({ line, number: index + 1 }))
+  const filtered = match
+    ? numbered.filter((item) => item.line.toLowerCase().includes(match.toLowerCase()))
+    : numbered
+
+  const offset = Number.isFinite(args.offset) && args.offset > 0 ? Math.floor(args.offset) : 0
+  const limit = Math.min(Math.max(Number.isFinite(args.limit) ? Math.floor(args.limit) : VIEW_DEFAULT_LIMIT, 1), VIEW_MAX_LIMIT)
+  const wrap = args.wrap === 0 ? 0 : Math.min(Math.max(Number.isFinite(args.wrap) ? Math.floor(args.wrap) : VIEW_WRAP_DEFAULT, 40), 4000)
+  const window = filtered.slice(offset, offset + limit)
+
+  const header = [
+    `文件：${file}`,
+    `大小：${formatBytes(size)} · 行数：${allLines.length}${pretty && isJson ? '（JSON 已展开）' : ''}${match ? ` · 匹配 "${match}"：${filtered.length} 行` : ''}`,
+  ]
+  const shownTo = offset + window.length
+  const remaining = filtered.length - shownTo
+  header.push(`第 ${offset + 1}–${shownTo} 行${remaining > 0 ? `（还有 ${remaining} 行，调 offset: ${shownTo} 继续）` : ''}`)
+
+  const body = []
+  for (const item of window) {
+    const pieces = wrap > 0 ? item.line.match(new RegExp(`[\\s\\S]{1,${wrap}}`, 'g')) ?? [''] : [item.line]
+    body.push(`${String(item.number).padStart(6)}│ ${pieces[0]}`)
+    for (const piece of pieces.slice(1)) body.push(`${' '.repeat(6)}│ ${piece}`)
+  }
+  if (!window.length) body.push(match ? '（没有匹配的行）' : '（文件为空）')
+
+  return { text: [...header, '', ...body].join('\n'), file }
+}
+
+function storageLines(summary) {
+  const lines = [`占用合计：${formatBytes(summary.totalBytes)}${summary.overLimit ? `（超过 ${summary.warnMegabytes} MB，建议清理）` : ''}`, '']
+  for (const row of summary.classes) {
+    lines.push(`- ${row.label}（${row.id}）：${row.count} 个 · ${formatBytes(row.bytes)} · 保留 ${row.keep} 个 / ${row.maxAgeDays} 天${row.hint ? ` · ${row.hint}` : ''}`)
+  }
+  return lines
+}
+
+function planLines(plan) {
+  const lines = [`将删除 ${plan.totalFiles} 个文件，释放 ${formatBytes(plan.totalBytes)}`, '']
+  for (const row of plan.classes) {
+    if (!row.remove.length) {
+      lines.push(`- ${row.label}：无需清理（${row.count} 个，保留 ${row.keep} 个 / ${row.maxAgeDays} 天）`)
+      continue
+    }
+    lines.push(`- ${row.label}：删除 ${row.remove.length} 个 · ${formatBytes(row.bytes)}`)
+    for (const item of row.remove.slice(0, 5)) {
+      lines.push(`  · ${item.name}（${item.ageDays} 天前，${formatBytes(item.bytes)}）`)
+    }
+    if (row.remove.length > 5) lines.push(`  · … 其余 ${row.remove.length - 5} 个`)
+  }
+  return lines
+}
+
+export function register(ctx, state) {
+  const dispose = ctx.tools.register({
+    name: 'd365_reports',
+    description:
+      '查看本机数据占用与产物（.d365/reports、query 等），并按保留策略清理或压缩历史产物。cleanup 默认只预演（dryRun），确认后传 dryRun=false 才真正删除。',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['list', 'cleanup', 'compact', 'view'],
+          description: 'list：看占用与产物；view：读回一个产物文件（分页/过滤）；cleanup：按策略清理；compact：把已有快照压成紧凑 JSON。默认 list。',
+        },
+        file: {
+          type: 'string',
+          description: 'view 的文件：.d365 下的相对路径（如 query/2026-11-06T01-36-47-274Z-layers.json）或文件名。',
+        },
+        offset: { type: 'number', description: 'view 从第几行开始（0 基），默认 0。' },
+        match: { type: 'string', description: 'view 只显示包含这个字符串的行（不区分大小写）。在大 JSON 里找一条 GUID 用这个。' },
+        wrap: { type: 'number', description: 'view 每行最多多少字符，超长折行；0 表示不折行。默认 400。' },
+        pretty: { type: 'boolean', description: 'view 是否把 JSON 缩进展开，默认对 .json 为 true。' },
+        target: {
+          type: 'string',
+          enum: CLASS_IDS,
+          description: 'cleanup 的范围：某一类或 all，默认 all。',
+        },
+        dryRun: {
+          type: 'boolean',
+          description: 'cleanup 默认 true，只预演不删除；确认要删时传 false。',
+        },
+        limit: { type: 'number', description: 'list 每类最多列多少条，默认 15。' },
+      },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['schemaVersion', 'action', 'text'],
+        properties: {
+          schemaVersion: { type: 'number' },
+          action: { type: 'string' },
+          text: { type: 'string' },
+        },
+      },
+      render: (args, value) => [{ type: 'text', text: value.text }],
+    },
+    async execute(args) {
+      const config = await loadConfig(state.rawConfig)
+      const action = args.action ?? 'list'
+
+      if (action === 'view') {
+        const view = await renderView(config, args)
+        return { schemaVersion: 1, action, text: view.text }
+      }
+
+      if (action === 'compact') {
+        const result = await compactAllSnapshots(config)
+        const summary = await storageSummary(config)
+        const lines = [
+          `已压缩 ${result.snapshots} 份快照里的 ${result.files} 个文件，释放 ${formatBytes(result.savedBytes)}。`,
+          '',
+          ...storageLines(summary),
+        ]
+        return { schemaVersion: 1, action, text: lines.join('\n') }
+      }
+
+      if (action === 'cleanup') {
+        const target = CLASS_IDS.includes(args.target) ? args.target : 'all'
+        const dryRun = args.dryRun !== false
+        const plan = await planCleanup(config, { target })
+        if (dryRun) {
+          const lines = [`清理预演（${target}）：尚未删除任何文件。`, '', ...planLines(plan)]
+          lines.push('', '确认要删除时，把 dryRun 设为 false 再调用一次。')
+          return { schemaVersion: 1, action, text: lines.join('\n') }
+        }
+        const applied = await applyCleanup(config, plan)
+        const summary = await storageSummary(config)
+        const lines = [
+          `已删除 ${applied.deleted.length} 个文件，释放 ${formatBytes(applied.bytes)}。`,
+          ...(applied.failures.length ? ['', `失败 ${applied.failures.length} 个：`, ...applied.failures.map((item) => `- ${item.name}：${item.reason}`)] : []),
+          '',
+          ...storageLines(summary),
+        ]
+        return { schemaVersion: 1, action, text: lines.join('\n') }
+      }
+
+      const limit = Number.isFinite(args.limit) ? Math.min(Math.max(args.limit, 1), 100) : 15
+      const root = dataRoot(config)
+      const reports = await listFiles(join(root, 'reports'), limit)
+      const queries = await listFiles(join(root, 'query'), limit)
+      const summary = await storageSummary(config)
+
+      let waiverCount = 0
+      try {
+        const document = await readWaivers(config)
+        waiverCount = (document.waivers ?? []).length
+      } catch {
+        waiverCount = 0
+      }
+      let lastContractRun = ''
+      try {
+        const history = await readHistory(config)
+        const last = history.runs?.[history.runs.length - 1]
+        if (last) {
+          lastContractRun = `${last.at}（${last.source} → ${(last.targets ?? []).join(', ')}，阻断 ${last.blocker ?? 0} / 警告 ${last.warning ?? 0}，豁免 ${last.waived ?? 0}）`
+        }
+      } catch {
+        lastContractRun = ''
+      }
+
+      const lines = ['本机数据', '', ...storageLines(summary), '']
+      // Totals come from the storage summary, not from the truncated listing:
+      // "25 个" next to three bullets looked like a bug.
+      const classCount = (id) => summary.classes.find((item) => item.id === id)?.count ?? 0
+      const reportTotal = classCount('reports')
+      lines.push(`报告（.d365/reports）：${reportTotal} 个${reportTotal > reports.length ? `，下面是最近 ${reports.length} 个` : ''}`)
+      for (const row of reports) {
+        lines.push(`- ${row.name} · ${(row.size / 1024).toFixed(1)} KB · ${row.modifiedAt}`)
+      }
+      lines.push('')
+      const queryTotal = classCount('query')
+      const shownQueries = queries.slice(0, 8)
+      lines.push(`查询留证（.d365/query）：${queryTotal} 个${queryTotal > shownQueries.length ? `，下面是最近 ${shownQueries.length} 个` : ''}`)
+      for (const row of shownQueries) {
+        lines.push(`- ${row.name} · ${(row.size / 1024).toFixed(1)} KB`)
+      }
+      lines.push('')
+      lines.push(`已登记豁免：${waiverCount} 条`)
+      lines.push(`最近一次契约检查：${lastContractRun || '还没有跑过'}`)
+      lines.push('')
+      lines.push('要读回某个产物（而不是只看文件名），用 action=view 加 file；大文件配 match 过滤、offset/limit 翻页。')
+      return { schemaVersion: 1, action: 'list', text: lines.join('\n') }
+    },
+  })
+  return dispose
+}