@hmos-library-adapter/fast 0.0.17-beta.0 → 0.0.17-beta.1

package/node_modules/@hmos-library-adapter/executer/shared/skills/harmonyos-api-upgrade-adapter/scripts/scanner/core/scan-runner.mjs

@@ -0,0 +1,521 @@
+import { mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { atomicWrite, ensureDir, exists, portableRelative, sha256 } from '../../shared/io/fs-utils.mjs';
+import { DEPRECATED_HEADERS, hyperlink, hyperlinkUrl, parseCsv, SCANNER_HEADERS, stringifyCsv, UPGRADE_HEADERS } from '../../shared/format/csv.mjs';
+import { canonicalHarmonyVersion as canonicalVersion, compareHarmonyVersions as compareVersions, devecoVersionName, parseVersion } from '../../shared/platform/version.mjs';
+import { locationInsideScanDirs, canonicalSourceFile } from './project.mjs';
+import {
+  classifyDeprecatedFindings,
+  VALIDATION_HEADERS,
+} from '../behavior/behavior-policy.mjs';
+import { runProcess } from '../../shared/platform/process.mjs';
+import { ruleDocumentLink } from '../../shared/platform/document-links.mjs';
+import { retryFileOperation } from '../../shared/platform/fs.mjs';
+import { inside } from '../../shared/platform/source-scope.mjs';
+import { batchArtifactPaths, ensureBatchDirectory } from '../../shared/platform/artifact-layout.mjs';
+import { requireScanMode } from '../../shared/platform/scan-mode.mjs';
+
+const TYPE_RANK = new Map([
+  ['API Behavior Change', 0],
+  ['UX Interaction Behavior Change', 1],
+  ['UX Visual Layout Change', 2],
+  ['Deprecated API', 3],
+  ['API Definition Change', 4],
+]);
+
+const devecoWorkerCompat = fileURLToPath(new URL('../bin/deveco-worker-compat.cjs', import.meta.url));
+
+async function execute(command, args, options, timeoutMs = null) {
+  const result = await runProcess(command, args, { ...options, timeoutMs });
+  if (result.error) throw new Error(result.error);
+  return {
+    code: result.exitCode,
+    stdout: result.stdout,
+    stderr: result.stderr,
+    timedOut: result.timedOut,
+    error: result.error,
+  };
+}
+
+export function interpretDevEcoOutput(processResult) {
+  const combined = `${processResult.stdout}\n${processResult.stderr}`;
+  if (processResult.code !== 0) {
+    const error = new Error(`DevEco API scan exited with code ${processResult.code}`);
+    error.code = 'DEVECO_SCAN_FAILED';
+    error.details = { stdout: processResult.stdout.slice(-12000), stderr: processResult.stderr.slice(-12000) };
+    throw error;
+  }
+  if (/falling back to grep|with grep|error\[2000(?:1|2|3|5)\]/i.test(combined)) {
+    const error = new Error('DevEco scanner used or requested an inaccurate fallback');
+    error.code = 'DEVECO_SCAN_DEGRADED';
+    error.details = { stdout: processResult.stdout.slice(-12000), stderr: processResult.stderr.slice(-12000) };
+    throw error;
+  }
+  const cppTimeoutCount = [...combined.matchAll(/error\[20004\]/gi)].length;
+  return {
+    cppStatus: cppTimeoutCount > 0 ? 'TIMED_OUT' : 'COMPLETE',
+    warnings: cppTimeoutCount > 0
+      ? [`C++扫描超时${cppTimeoutCount}次，已继续生成报告；C++结果可能不完整，需人工复核`]
+      : [],
+  };
+}
+
+function normalizeCodeLocation(project, location) {
+  const normalized = String(location).replaceAll('\\', '/');
+  const match = normalized.match(/^(.*?):(\d+)(?::(\d+))?$/);
+  if (!match) return normalized;
+  if (!path.isAbsolute(match[1])) {
+    const segments = match[1].split('/');
+    const module = project.modules?.find(candidate => candidate.name === segments[0] || path.basename(candidate.root) === segments[0]);
+    const absolute = module ? path.join(module.root, ...segments.slice(1)) : path.join(project.root, match[1]);
+    const actual = canonicalSourceFile(project, absolute);
+    if (actual && project.sourceFiles) return normalizeCodeLocation(project, `${actual}:${match[2]}${match[3] ? `:${match[3]}` : ''}`);
+    return normalized;
+  }
+  const actual = canonicalSourceFile(project, match[1]);
+  if (actual) match[1] = actual;
+  const module = project.modules?.find((candidate) => {
+    const relation = path.relative(candidate.root, match[1]);
+    return relation !== '' && !relation.startsWith('..') && !path.isAbsolute(relation);
+  });
+  if (module) {
+    const moduleRelative = portableRelative(module.root, match[1]);
+    return `${module.name}/${moduleRelative}:${match[2]}${match[3] ? `:${match[3]}` : ''}`;
+  }
+  const relative = portableRelative(project.root, match[1]);
+  if (relative.startsWith('../') || relative === '..') return normalized;
+  return `${relative}:${match[2]}${match[3] ? `:${match[3]}` : ''}`;
+}
+
+function normalizeFinding(row, rule, project = null, mode) {
+  requireScanMode(mode);
+  const originalUrl = hyperlinkUrl(row.Title);
+  const link = ruleDocumentLink(rule, originalUrl, { requireEntry: mode === 'upgrade' });
+  const disposition = rule.reportDisposition ?? 'REQUIRES_REVIEW';
+  const filterReason = rule.filterReason ?? null;
+  const applicabilityProof = rule.applicabilityProof ?? null;
+  return {
+    'Api Definition': row['Api Definition'],
+    Language: row.Language === 'C++' ? 'C' : row.Language,
+    'Changed in SDK': rule.changedInSdk || row['Changed in SDK'],
+    'Affected Versions': rule.affectedVersions ?? row['Affected Versions'],
+    Title: hyperlink(link.url, rule.title),
+    documentLink: link,
+    'Code Location': project
+      ? normalizeCodeLocation(project, row['Code Location'])
+      : String(row['Code Location']).replaceAll('\\', '/'),
+    Fixed: 'Unfixed',
+    ...(mode === 'upgrade' && row.Column !== undefined ? { Column: row.Column } : {}),
+    'Change Type': rule.changeType,
+    'Rule ID': String(rule.ruleId),
+    'Change Operation': rule.changeOperation,
+    'Source Reference': rule.sourceReference,
+    'Replacement API': rule.replacementApi ?? '',
+    'Replacement Source': rule.replacementSource ?? '',
+    includedInCsv: disposition !== 'FILTERED_COMPATIBLE',
+    disposition,
+    filterReason,
+    applicabilityProof,
+  };
+}
+
+function normalizeApiDefinition(value) {
+  return String(value).replace(/\s+/g, ' ').replace(/;\s*$/, '').trim();
+}
+
+function compareFindings(left, right) {
+  const level = finding => finding['Deprecated Since'] !== undefined && finding['Deprecated Since'] !== ''
+    ? Number(finding['Deprecated Since']) : finding['Changed in SDK'] ? parseVersion(finding['Changed in SDK']).apiLevel : 0;
+  const leftLevel = level(left);
+  const rightLevel = level(right);
+  const versionRank = !left['Changed in SDK'] || !right['Changed in SDK']
+    ? (leftLevel ?? 0) - (rightLevel ?? 0)
+    : compareVersions(left['Changed in SDK'], right['Changed in SDK']);
+  const values = [
+    versionRank,
+    (TYPE_RANK.get(left['Change Type']) ?? 99) - (TYPE_RANK.get(right['Change Type']) ?? 99),
+    left['Rule ID'].localeCompare(right['Rule ID']),
+    left.Language.localeCompare(right.Language),
+    left['Code Location'].localeCompare(right['Code Location'], undefined, { numeric: true }),
+    Number(left.Column ?? 0) - Number(right.Column ?? 0),
+    left['Api Definition'].localeCompare(right['Api Definition']),
+  ];
+  return values.find((value) => value !== 0) ?? 0;
+}
+
+function deduplicate(rows) {
+  const seen = new Set();
+  return rows.filter((row) => {
+    const key = row.occurrenceId ?? [row['Rule ID'], row['Api Definition'], row.Language, row['Code Location'], row.Column ?? ''].join('\u0000');
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+async function findOfficialCsv(directory) {
+  const files = (await readdir(directory)).filter((name) => name.endsWith('.csv')).sort();
+  if (files.length !== 1) throw new Error(`Expected one DevEco CSV, found ${files.length}`);
+  return path.join(directory, files[0]);
+}
+
+async function readCsvOutputs(directory) {
+  const files = (await readdir(directory)).filter(name => name.endsWith('.csv')).sort();
+  if (files.length === 0) throw new Error('DevEco scanner did not produce a CSV');
+  const parsed = await Promise.all(files.map(async file => parseCsv(await readFile(path.join(directory, file), 'utf8'))));
+  return {
+    headers: [...new Set(parsed.flatMap(item => item.headers))],
+    rows: parsed.flatMap(item => item.rows),
+  };
+}
+
+function normalizeIndexRow(row) {
+  const location = String(row['Invoke Location'] ?? '');
+  const withColumn = location.match(/^(.*?:\d+):(\d+)$/);
+  return {
+    'Api Definition': row.MethodDefinition ?? row['Api Name'] ?? '',
+    Language: 'ArkTS',
+    ChangeId: row.ChangeId,
+    'Code Location': withColumn ? withColumn[1] : location,
+    Column: withColumn ? Number(withColumn[2]) : undefined,
+  };
+}
+
+export function rulesForProject(rules, project) {
+  const hasArkTs = project.sourceFiles.some((file) => /\.(?:ets|ts)$/i.test(file));
+  const hasCpp = project.sourceFiles.some((file) => /\.(?:c|cc|cpp|cxx)$/i.test(file));
+  const groups = { typescript: new Map(), c: new Map() };
+  const scanRuleMap = new Map();
+  for (const rule of rules) {
+    for (const api of rule.rawEntry.affectedApis) {
+      const language = String(api.implementLanguage).toLowerCase();
+      if (language === 'typescript' && !hasArkTs) continue;
+      if (language === 'c' && !hasCpp) continue;
+      if (!(language in groups)) continue;
+      const identity = [
+        rule.provider ?? 'UNKNOWN', language, api.completePath, api.className, api.interfaceType, api.interfaceName,
+        normalizeApiDefinition(api.methodDefinition), api.invokeInstance ?? '',
+      ].join('\u0000');
+      let scanId = groups[language].get(identity);
+      if (!scanId) {
+        scanId = `scan-${sha256(identity).slice(0, 20)}`;
+        groups[language].set(identity, scanId);
+        scanRuleMap.set(scanId, { api, provider: rule.provider ?? 'UNKNOWN', rules: [], bindings: [] });
+      }
+      const record = scanRuleMap.get(scanId);
+      if (!record.rules.some((candidate) => candidate.ruleId === rule.ruleId)) record.rules.push(rule);
+      if (!record.bindings.some((binding) => binding.rule.ruleId === rule.ruleId)) record.bindings.push({ rule, api });
+    }
+  }
+  const toEntries = (language) => [...groups[language].values()].map((scanId) => {
+    const record = scanRuleMap.get(scanId);
+    const source = record.rules[0].rawEntry;
+    return {
+      ...source,
+      __provider: record.provider,
+      affectedApis: [record.api],
+      interfaceChanges: { ...source.interfaceChanges, id: scanId },
+    };
+  });
+  const arkTsEntries = toEntries('typescript');
+  const cppEntries = toEntries('c');
+  return {
+    entries: [...arkTsEntries, ...cppEntries],
+    arkTsEntries,
+    cppEntries,
+    scanRuleMap,
+    hasArkTs,
+    hasCpp,
+  };
+}
+
+export async function cleanupScanDirectory(directory, remove = rm) {
+  try {
+    await retryFileOperation(() => remove(directory, { recursive: true, force: true }));
+    return null;
+  } catch (error) {
+    return { code: 'SCAN_TEMP_CLEANUP_FAILED', path: directory, errorCode: error.code, message: error.message };
+  }
+}
+
+export async function runDevEcoScan({ toolchain, project, range, rules, outputDirectory, batchId, deprecations = null,
+  buildLogImport = null, devecoVersionNames = {}, runtime = null, mode, verifyInputs = async () => {}, cppPassTimeoutMs = 240_000, removeTemporary = rm }) {
+  requireScanMode(mode);
+  const layout = batchArtifactPaths(outputDirectory, batchId, mode);
+  await ensureBatchDirectory(layout, layout.scannerDirectory);
+  await ensureBatchDirectory(layout, layout.deliveryDirectory);
+  const temporary = await mkdtemp(path.join(os.tmpdir(), 'harmony-api-scan-'));
+  const startedAt = Date.now();
+  const projectRules = rulesForProject(rules, project);
+  let result, failure;
+  try {
+    const selectedModules = project.selectedModules ?? project.modules;
+    const cppModules = selectedModules.filter((module) => project.sourceFiles.some((file) => {
+      if (!/\.(?:c|cc|cpp|cxx)$/i.test(file)) return false;
+      const relation = path.relative(module.root, file);
+      return relation !== '' && !relation.startsWith('..') && !path.isAbsolute(relation);
+    }));
+    if (toolchain.apiChangeBackend === 'index' && projectRules.cppEntries.length > 0 && cppModules.length > 0) {
+      const error = new Error('The discovered DevEco index backend cannot scan C/C++ API changes');
+      error.code = 'C_CPP_BACKEND_UNAVAILABLE';
+      error.details = toolchain.layoutDiagnostics;
+      throw error;
+    }
+    const runPass = async (name, entries, modules, files = null) => {
+      if (entries.length === 0 || modules.length === 0 || files?.length === 0) {
+        return { rows: [], processResult: { stdout: '', stderr: '' }, interpretation: { cppStatus: 'NOT_APPLICABLE', warnings: [] } };
+      }
+      const passRoot = path.join(temporary, name);
+      const officialOutput = path.join(passRoot, 'official');
+      const apiChangesPath = path.join(passRoot, 'api-changes.json');
+      await ensureDir(officialOutput);
+      await writeFile(apiChangesPath, `${JSON.stringify(entries)}\n`);
+      if (toolchain.apiChangeBackend === 'index') {
+        const tmpPath = path.join(passRoot, 'tmp');
+        const logPath = path.join(passRoot, 'APIScan.log');
+        const configPath = path.join(passRoot, 'scanner-config.json');
+        await ensureDir(tmpPath);
+        await writeFile(configPath, `${JSON.stringify({
+          projectPath: project.sourceScope ? modules.map(module => module.root) : project.root,
+          sdks: Object.entries(toolchain.sdkFamilies ?? {}).map(([family, etsRoot]) => ({
+            name: family === 'openharmony' ? 'ohos' : family,
+            path: etsRoot,
+          })),
+          outPath: officialOutput,
+        }, null, 2)}\n`);
+        const processResult = await execute(process.execPath, [
+          '--require', devecoWorkerCompat,
+          toolchain.apiChangeScan,
+          '--configPath', configPath,
+          '--apiModifiedPath', apiChangesPath,
+          '--outPath', officialOutput,
+          '--tmpPath', tmpPath,
+          '--logPath', logPath,
+          '--batchSize', '1000',
+          ...(files ? ['--scanFilePaths', files.join(',')] : []),
+        ], {
+          cwd: passRoot,
+          env: { ...process.env, DEVECO_HOME: toolchain.contentsRoot, DEVECO_SDK_HOME: toolchain.sdkRoot },
+        });
+        if (await exists(logPath)) processResult.stderr += `\n${await readFile(logPath, 'utf8')}`;
+        const interpretation = interpretDevEcoOutput(processResult);
+        const csv = await readCsvOutputs(officialOutput);
+        return { rows: csv.rows.map(normalizeIndexRow), headers: ['ChangeId'], processResult, interpretation };
+      }
+      if (name.startsWith('cpp-') && (!toolchain.cApiScanJar || !toolchain.java)) {
+        const error = new Error('DevEco C/C++ scanner components are unavailable');
+        error.code = 'C_CPP_BACKEND_UNAVAILABLE';
+        error.details = toolchain.layoutDiagnostics;
+        throw error;
+      }
+      const args = [
+        toolchain.apiChangeScan,
+        '--startVersion', devecoVersionNames[canonicalVersion(range.start)] ?? devecoVersionName(range.start),
+        '--endVersion', devecoVersionNames[canonicalVersion(range.end)] ?? devecoVersionName(range.end),
+        ...(files ? [name.startsWith('cpp-') ? '--cppFiles' : '--arkTsFiles', files.join(',')]
+          : ['--modulePaths', modules.map(module => module.root).join(',')]),
+        '--sdkPath', toolchain.sdkRoot,
+        '--apiModifiedPath', apiChangesPath,
+        '--outputPath', officialOutput,
+      ];
+      if (toolchain.cApiScanJar) args.push('--cApiScanJarPath', toolchain.cApiScanJar);
+      const processResult = await execute(process.execPath, args, {
+        detached: name.startsWith('cpp-'),
+        cwd: toolchain.analyzerRoot,
+        env: {
+          ...process.env,
+          DEVECO_HOME: toolchain.contentsRoot,
+          DEVECO_SDK_HOME: toolchain.sdkRoot,
+          ...(toolchain.java ? { JAVA_HOME: path.dirname(path.dirname(toolchain.java)) } : {}),
+        },
+      }, name.startsWith('cpp-') ? cppPassTimeoutMs : null);
+      if (processResult.timedOut) {
+        processResult.code = 0;
+        processResult.stderr += `\nerror[20004] C++ semantic pass exceeded ${cppPassTimeoutMs}ms; process group terminated; completed rows only\n`;
+        const interpretation = interpretDevEcoOutput(processResult);
+        const files = (await readdir(officialOutput)).filter(file => file.endsWith('.csv'));
+        let csv = { rows: [], headers: [] };
+        if (files.length === 1) {
+          try { csv = parseCsv(await readFile(path.join(officialOutput, files[0]), 'utf8')); }
+          catch { interpretation.warnings.push('C++超时导致未完成CSV损坏，已跳过该批次；ArkTS结果继续生成'); }
+        }
+        return { rows: csv.rows, headers: csv.headers, processResult, interpretation };
+      }
+      const interpretation = interpretDevEcoOutput(processResult);
+      const csv = parseCsv(await readFile(await findOfficialCsv(officialOutput), 'utf8'));
+      return { rows: csv.rows, headers: csv.headers, processResult, interpretation };
+    };
+    const groupedPasses = async (language, entries, modules) => {
+      const providers = [...new Set(entries.map((entry) => entry.__provider))].sort();
+      const passes = [];
+      const narrowed = Boolean(project.sourceScope?.scanDirs.length) && modules.some(module =>
+        !project.sourceScope.scanDirs.some(directory => inside(directory,module.root)));
+      const fileMode = narrowed || toolchain.apiChangeBackend === 'index' && project.sourceScope?.restricted && toolchain.fileScanSupported !== false;
+      if (fileMode && toolchain.fileScanSupported === false) {
+        const error = new Error('This DevEco backend cannot scan the requested file scope');
+        error.code = 'SCAN_SCOPE_UNSUPPORTED'; throw error;
+      }
+      for (const provider of providers) {
+        const selectedEntries = entries.filter(entry => entry.__provider === provider);
+        if (!fileMode) {
+          // The native backend owns a fixed per-invocation timeout. Keep module
+          // results independent so a slow CDT parse does not erase sibling results.
+          const batches = language === 'cpp' ? modules.map(module => [module]) : [modules];
+          for (const [index, batch] of batches.entries())
+            passes.push({ ...await runPass(`${language}-${String(provider).toLowerCase()}-${index}`, selectedEntries, batch),
+              modules: batch.map(module => module.name) });
+          continue;
+        }
+        for (const module of modules) {
+          const files = project.sourceFiles.filter(file => {
+            const relative = path.relative(module.root, file);
+            return relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative)
+              && (language === 'arkts' ? /\.(ets|ts)$/i : /\.(c|cc|cpp|cxx|h|hpp)$/i).test(file);
+          });
+          let batch = [], bytes = 0, index = 0;
+          const flush = async () => {
+            if (batch.length) passes.push(await runPass(`${language}-${String(provider).toLowerCase()}-${index++}-${modules.indexOf(module)}`, selectedEntries, [module], batch));
+            batch = []; bytes = 0;
+          };
+          for (const file of files) {
+            const size = Buffer.byteLength(file, 'utf8') + 1;
+            if (file.includes(',') || size > 16000) {
+              const error = new Error('DevEco cannot represent this source path in its file scope');
+              error.code = 'SCAN_SCOPE_UNSUPPORTED'; throw error;
+            }
+            if (bytes + size > 16000) await flush();
+            batch.push(file); bytes += size;
+          }
+          await flush();
+        }
+      }
+      return passes;
+    };
+    const arkTsPasses = await groupedPasses('arkts', projectRules.arkTsEntries, selectedModules);
+    const cppPasses = await groupedPasses('cpp', projectRules.cppEntries, cppModules);
+    const allPasses = [...arkTsPasses, ...cppPasses];
+    const officialRows = allPasses.flatMap((pass) => pass.rows);
+    const idHeader = allPasses.flatMap((pass) => pass.headers ?? []).includes('ChangeId')
+      ? 'ChangeId' : 'Rule ID';
+    const unresolved = [];
+    const findings = [...(deprecations?.findings ?? []), ...(buildLogImport?.findings ?? [])];
+    for (const row of officialRows) {
+      const record = projectRules.scanRuleMap?.get(String(row[idHeader] ?? ''));
+      if (!record) {
+        unresolved.push({ changeId: row[idHeader] ?? '', title: row.Title, location: row['Code Location'] });
+        continue;
+      }
+      for (const binding of record.bindings) {
+        const finding = normalizeFinding({ ...row, 'Api Definition': binding.api.methodDefinition }, binding.rule, project, mode);
+        if (locationInsideScanDirs(project, finding['Code Location'])) findings.push(finding);
+      }
+    }
+    if (unresolved.length) {
+      const error = new Error(`DevEco results contain ${unresolved.length} unresolved rule identifiers`);
+      error.code = 'UNRESOLVED_SCAN_RESULTS';
+      error.details = unresolved.slice(0, 20);
+      throw error;
+    }
+    const rawFindings = deduplicate(findings).sort(compareFindings);
+    const classified = mode === 'upgrade'
+      ? { findings: rawFindings.map(finding => ({ ...finding, includedInCsv: true, disposition: 'REQUIRES_REVIEW', filterReason: null })),
+        actionRows: rawFindings, actionGroups: [], validationRows: [], validationGroups: [] }
+      : classifyDeprecatedFindings(rawFindings);
+    const allFindings = classified.findings;
+    const reportedFindings = classified.actionRows;
+    const filteredFindings = allFindings.filter((finding) => !finding.includedInCsv);
+    const filterSummary = Object.fromEntries([...filteredFindings.reduce((counts, finding) => {
+      counts.set(finding.filterReason, (counts.get(finding.filterReason) ?? 0) + 1);
+      return counts;
+    }, new Map())].sort(([left], [right]) => left.localeCompare(right)));
+    const outputCsv = layout.rawCsv;
+    const validationCsv = mode === 'upgrade' ? null : layout.validationCsv;
+    const scanJson = layout.scanJson;
+    await verifyInputs();
+    await ensureBatchDirectory(layout, layout.deliveryDirectory);
+    await ensureBatchDirectory(layout, layout.scannerDirectory);
+    await atomicWrite(outputCsv, stringifyCsv(mode === 'upgrade' ? UPGRADE_HEADERS : DEPRECATED_HEADERS, reportedFindings));
+    if (validationCsv) await atomicWrite(validationCsv, stringifyCsv(VALIDATION_HEADERS, classified.validationRows));
+    await atomicWrite(scanJson, `${JSON.stringify({
+      schemaVersion: 4,
+      batchId,
+      mode,
+      runtime,
+      versionResolution:{scanFromSdkVersion:range.start ? canonicalVersion(range.start) : null,scanToSdkVersion:range.end ? canonicalVersion(range.end) : null,
+        compileSdkVersion:toolchain.sdkVersion ? canonicalVersion(toolchain.sdkVersion) : null},
+      sourceSnapshot: project.sourceSnapshot,
+      sourceScope: project.sourceScope ?? null,
+      scannedFiles: project.sourceFiles.map(file => path.relative(project.root, file).split(path.sep).join('/')),
+      buildProfileHash: project.buildProfileHash,
+      findingCount: allFindings.length,
+      totalFindingCount: allFindings.length,
+      reportedFindingCount: reportedFindings.length,
+      filteredFindingCount: filteredFindings.length,
+      filterSummary,
+      deprecationCoverage: deprecations?.coverage ?? null,
+      deprecationCatalog: deprecations?.catalogCoverage ?? null,
+      unresolved: deprecations?.unresolved ?? [],
+      resolutionWarnings: deprecations?.resolutionWarnings ?? [],
+      buildLogImport: buildLogImport?.audit ?? null,
+      actionGroups: classified.actionGroups,
+      validationGroups: classified.validationGroups,
+      findings: allFindings.map((finding) => ({
+        findingId: `finding-${sha256(SCANNER_HEADERS.map((header) => finding[header]).join('\u0000')).slice(0, 20)}`,
+        ...finding,
+      })),
+    }, null, 2)}\n`);
+    const warnings = [
+      ...allPasses.flatMap((pass) => pass.interpretation.warnings),
+      ...(deprecations?.resolutionWarnings?.some(item => item.reason === 'UNUSED_SDK_IMPORT_NOT_RESOLVED')
+        ? ['SDK 存在未使用的缺失导出，已通过工程符号影响分析；详见扫描 JSON 的 resolutionWarnings'] : []),
+      ...(deprecations?.resolutionWarnings?.some(item => item.reason !== 'UNUSED_SDK_IMPORT_NOT_RESOLVED')
+        ? [`${deprecations.resolutionWarnings.filter(item => item.reason !== 'UNUSED_SDK_IMPORT_NOT_RESOLVED').length}处非系统模块导入未解析；相关类型证据不完整`] : []),
+      ...(buildLogImport?.warnings ?? []),
+    ];
+    const scannerStdout = allPasses.map((pass, index) => pass.processResult.stdout
+      ? `[pass-${index + 1}]\n${pass.processResult.stdout}` : '').filter(Boolean).join('\n');
+    const scannerStderr = allPasses.map((pass, index) => pass.processResult.stderr
+      ? `[pass-${index + 1}]\n${pass.processResult.stderr}` : '').filter(Boolean).join('\n');
+    const cppStatuses = cppPasses.map((pass) => pass.interpretation.cppStatus);
+    const cppStatus = !projectRules.hasCpp ? 'NOT_APPLICABLE'
+      : cppStatuses.includes('TIMED_OUT') ? 'TIMED_OUT' : 'COMPLETE';
+    result = {
+      outputCsv,
+      validationCsv,
+      scanJson,
+      findings: reportedFindings,
+      allFindings,
+      filteredFindings,
+      actionGroups: classified.actionGroups,
+      validationGroups: classified.validationGroups,
+      diagnostics: {
+        durationMs: Date.now() - startedAt,
+        totalFindingCount: allFindings.length,
+        reportedFindingCount: reportedFindings.length,
+        filteredFindingCount: filteredFindings.length,
+        filterSummary,
+        cppStatus,
+        nativePasses: cppPasses.map(pass => ({ modules: pass.modules ?? [], status: pass.interpretation.cppStatus })),
+        languages: { arkts: projectRules.hasArkTs, cpp: projectRules.hasCpp },
+        warnings,
+        backend: toolchain.apiChangeBackend ?? 'integrated',
+        stdout: scannerStdout.slice(-12000),
+        stderr: scannerStderr.slice(-12000),
+      },
+    };
+    return result;
+  } catch (error) {
+    failure = error;
+    throw error;
+  } finally {
+    const warning = await cleanupScanDirectory(temporary, removeTemporary);
+    if (warning && result) {
+      result.diagnostics.cleanupWarning = warning;
+      result.diagnostics.warnings.push(`${warning.code}: ${warning.path}: ${warning.message}`);
+    } else if (warning && failure) failure.cleanupWarning = warning;
+  }
+}
+
+export { compareFindings, normalizeCodeLocation, normalizeFinding };