@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/cli.mjs

@@ -0,0 +1,416 @@
+import { readFile, mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { assertBatchDirectory, createScanBatch, ensureBatchDirectory } from '../../shared/platform/artifact-layout.mjs';
+import { fileURLToPath } from 'node:url';
+import { parseArgs, integerArg, requireString, stringList } from '../../shared/format/args.mjs';
+import { discoverDevEco, validateTargetCoverage } from './deveco.mjs';
+import { assertUpgradeRange, canonicalHarmonyVersion as canonicalVersion } from '../../shared/platform/version.mjs';
+import { auditDeprecationRules, compileRules } from './rules.mjs';
+import { loadProject } from './project.mjs';
+import { ensureNativeBuild } from '../native/native.mjs';
+import { runDevEcoScan } from './scan-runner.mjs';
+import { atomicWrite, ensureDir, exists, sha256 } from '../../shared/io/fs-utils.mjs';
+import { buildSdkCatalog } from './sdk-deprecations.mjs';
+import { scanArkTsDeprecations } from '../deprecated/arkts-deprecations.mjs';
+import { importDeprecatedBuildLog } from '../deprecated/build-log.mjs';
+import { loadBehaviorPolicy, validateBehaviorPolicySources } from '../behavior/behavior-policy.mjs';
+import { serializeError } from '../../shared/platform/errors.mjs';
+import { runtimeIdentity } from './runtime-identity.mjs';
+import { upgradeRuleCoverage } from '../behavior/upgrade-coverage.mjs';
+import { findingStatistics } from '../../shared/platform/scan-statistics.mjs';
+import { discoverScanVersions, resolveScanVersion } from '../../shared/platform/scan-versions.mjs';
+import { requireScanMode } from '../../shared/platform/scan-mode.mjs';
+
+const packageRoot = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const defaultReferenceRoot = path.resolve(packageRoot, '..', '..', 'references', 'changelogs');
+const defaultBehaviorPolicy = path.join(packageRoot, 'data', 'behavior-change-policy.json');
+
+export function usage() {
+  return `HarmonyOS API compatibility scanner
+
+Commands:
+  scan --project <path> --sdk <path> --from <version> [--to <version>]
+       [--deveco-home <path>]
+       [--product <name>] [--scan-dir <path>] [--scan-module <name>] [--project-type app|har] [--native-build auto|off]
+       [--batch-size <count>] [--references <path>] [--output-dir <path>]
+       [--build-log <path>] [--build-evidence <path>]
+       --mode upgrade|deprecated
+  inspect-rules --sdk <path> --from <version> [--to <version>]
+       --mode upgrade|deprecated [--deveco-home <path>] [--references <path>] [--allow-incomplete]
+`;
+}
+
+export function runTimestamp(now = new Date()) {
+  const pad = (value) => String(value).padStart(2, '0');
+  return `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}`
+    + `${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+}
+
+export async function createRunOutputDirectory(root) {
+  const base = runTimestamp();
+  let name = base;
+  let suffix = 2;
+  await ensureDir(root);
+  for (;;) {
+    const directory = path.join(root, name);
+    try { await mkdir(directory); return { directory, stamp: name }; }
+    catch (error) { if (error.code !== 'EEXIST') throw error; name = `${base}-${suffix++}`; }
+  }
+}
+
+function scanOptions(args) {
+  const mode = requireScanMode(args.mode);
+  const projectPath = path.resolve(requireString(args, 'project'));
+  return {
+    projectPath,
+    sdkPath: path.resolve(requireString(args, 'sdk')),
+    devecoHome: args['deveco-home'] ? path.resolve(requireString(args, 'deveco-home')) : null,
+    from: requireString(args, 'from'),
+    to: typeof args.to === 'string' ? args.to : null,
+    productName: typeof args.product === 'string' ? args.product : 'default',
+    scanDirs: stringList(args['scan-dir']),
+    scanModules: stringList(args['scan-module']),
+    projectType: args['project-type'] || 'app',
+    nativeBuild: args['native-build'] ?? 'auto',
+    batchSize: integerArg(args['batch-size'], 1000, 'batch-size'),
+    mode,
+    referenceRoot: path.resolve(args.references || defaultReferenceRoot),
+    outputRoot: path.resolve(args['output-dir'] || path.join(projectPath, '.api-change-output')),
+    buildLog: args['build-log'] ? path.resolve(requireString(args, 'build-log')) : null,
+    buildEvidence: args['build-evidence'] ? path.resolve(requireString(args, 'build-evidence')) : null,
+  };
+}
+
+export function resolveScanTargetVersion(to, toolchain, versions = undefined) {
+  const selected = to || toolchain?.sdkVersion;
+  if (!selected) {
+    const error = new Error('Target SDK version is missing and cannot be inferred from the selected toolchain');
+    error.code = 'TARGET_SDK_UNRESOLVED';
+    throw error;
+  }
+  const value = typeof selected === 'object' && !Array.isArray(selected) && !selected.key
+    ? selected.raw : selected;
+  const input = typeof value === 'object' ? canonicalVersion(value) : value;
+  return { version: resolveScanVersion(input,{endpoint:'to',compileSdkVersion:toolchain?.sdkVersion?.raw ?? toolchain?.sdkVersion,versions}), source: to ? 'to' : 'toolchain' };
+}
+
+async function inspectRules(args) {
+  const mode = requireScanMode(args.mode);
+  const sdkPath = path.resolve(requireString(args, 'sdk'));
+  const referenceRoot = path.resolve(args.references || defaultReferenceRoot);
+  const devecoHome = args['deveco-home'] ? path.resolve(requireString(args, 'deveco-home')) : null;
+  const toolchain = await discoverDevEco(sdkPath, devecoHome, { targetVersion: typeof args.to === 'string' ? args.to : null });
+  const versions = await discoverScanVersions(toolchain);
+  const target = resolveScanTargetVersion(typeof args.to === 'string' ? args.to : null, toolchain, versions);
+  const range = assertUpgradeRange(resolveScanVersion(requireString(args,'from'),{endpoint:'from',versions}), target.version);
+  validateTargetCoverage(toolchain, range.end);
+  const compiled = await compileRules({ toolchain, referenceRoot, range, strict: args['allow-incomplete'] !== true, mode });
+  const catalog = await buildSdkCatalog(toolchain, range.end);
+  const deprecationValidation = mode === 'upgrade' ? { status: 'NOT_APPLICABLE' } : await auditDeprecationRules(toolchain, compiled.rules, catalog);
+  const { excluded, errors, ...summary } = compiled.coverage;
+  return {
+    sdk: toolchain.sdkMetadata.data,
+    toolchain: {
+      deveco: toolchain.productInfo,
+      devecoCompatibility: toolchain.devecoCompatibility,
+      backend: toolchain.apiChangeBackend,
+      scanner: toolchain.apiChangeScan,
+      resources: toolchain.apiChangeResourceRoot,
+      resourceArchive: toolchain.apiChangeResourceArchive,
+      parser: toolchain.parserPath,
+      cApiScanJar: toolchain.cApiScanJar,
+    },
+    coverage: { ...summary, deprecationValidation, deprecationCatalog: catalog.coverage },
+    errorSample: errors.slice(0, 20),
+    excludedSample: excluded.slice(0, 20),
+  };
+}
+
+export function selectScanRules(rules, mode) {
+  requireScanMode(mode);
+  if (mode === 'upgrade') return rules.filter(rule => rule.provider === 'DEVECO' && rule.changeType !== 'Deprecated API');
+  const scoped = rules.filter(rule => rule.changeType === 'Deprecated API');
+  return scoped.filter(rule => rule.changeOperation !== 'API_DEPRECATED'
+    || rule.affectedApis[0]?.implementLanguage.toLowerCase() !== 'typescript');
+}
+
+async function scan(args) {
+  const options = scanOptions(args);
+  if (!['auto', 'off'].includes(options.nativeBuild)) throw new Error('--native-build must be auto or off');
+  if (options.batchSize !== 1000) {
+    throw new Error('The DevEco v1 backend supports --batch-size 1000 only');
+  }
+  const { directory: outputDirectory } = await createRunOutputDirectory(options.outputRoot);
+  const outputLayout = await createScanBatch(options.outputRoot, outputDirectory, {mode:options.mode});
+  await ensureBatchDirectory(outputLayout, outputLayout.scannerDirectory);
+  const coverageJson = outputLayout.coverageJson;
+  const diagnosticsJson = outputLayout.diagnosticsJson;
+  const runtime = await runtimeIdentity(path.resolve(packageRoot, '..', '..'), {mode:options.mode});
+  let diagnostics = { schemaVersion: 1, status: 'FAILED', runtime, options: { ...options, projectPath: options.projectPath } };
+  let stage = 'DISCOVER_TOOLCHAIN';
+  try {
+    const toolchain = await discoverDevEco(options.sdkPath, options.devecoHome, { targetVersion: options.to });
+    options.sdkPath = toolchain.sdkRoot;
+    const versions = await discoverScanVersions(toolchain);
+    const rawInputs = {from:options.from,to:options.to};
+    const target = resolveScanTargetVersion(options.to, toolchain, versions);
+    options.from = resolveScanVersion(options.from,{endpoint:'from',versions});
+    options.to = target.version;
+    options.versionResolution = {rawInputs,scanFromSdkVersion:options.from,scanToSdkVersion:options.to,
+      compileSdkVersion:canonicalVersion(toolchain.sdkVersion)};
+    options.targetVersionSource = target.source;
+    const range = assertUpgradeRange(options.from, options.to);
+    stage = 'VALIDATE_TARGET_COVERAGE';
+    validateTargetCoverage(toolchain, range.end);
+    stage = 'LOAD_PROJECT';
+    const project = await loadProject(options.projectPath, options.productName, options.scanDirs, options.scanModules, options.projectType);
+    stage = 'COMPILE_RULES';
+    const compiled = await compileRules({ toolchain, referenceRoot: options.referenceRoot, range, strict: true, mode: options.mode });
+    stage = 'VALIDATE_BEHAVIOR_POLICY';
+    const behaviorPolicy = await loadBehaviorPolicy(defaultBehaviorPolicy);
+    const behaviorPolicyCoverage = await validateBehaviorPolicySources(behaviorPolicy, options.referenceRoot);
+    if (options.mode === 'upgrade') {
+      compiled.coverage.upgrade = upgradeRuleCoverage({ policies: behaviorPolicy.entries, rules: compiled.rules,
+        excluded: compiled.coverage.excluded, range });
+      compiled.coverage.upgrade.rulePack = { version: toolchain.productInfo?.version ?? null,
+        resources: toolchain.apiChangeResourceRoot, archive: toolchain.apiChangeResourceArchive };
+      // Publish the verified plugin results, but never equate plugin coverage with
+      // complete official-document coverage. Do not invent rules outside this mode.
+    }
+    stage = 'BUILD_SDK_CATALOG';
+    const catalog = await buildSdkCatalog(toolchain, range.end);
+    stage = 'AUDIT_DEPRECATION_RULES';
+    const deprecationValidation = options.mode === 'upgrade' ? { status: 'NOT_APPLICABLE' } : await auditDeprecationRules(toolchain, compiled.rules, catalog);
+    if (catalog.coverage.status !== 'COMPLETE') {
+      const error = new Error('Target SDK declaration catalog is incomplete');
+      error.code = 'SDK_CATALOG_INCOMPLETE'; error.details = catalog.coverage.errors; throw error;
+    }
+    stage = 'SCAN_ARKTS_DEPRECATIONS';
+    const deprecations = options.mode === 'upgrade'
+      ? { findings: [], unresolved: [], analyzedFiles: [], coverage: { status: 'NOT_APPLICABLE' } }
+      : await scanArkTsDeprecations({ project, catalog, documentRules: compiled.rules });
+    deprecations.catalogCoverage = catalog.coverage;
+    if (deprecations.unresolved.length) {
+      await atomicWrite(outputLayout.scanJson, `${JSON.stringify({
+        schemaVersion: 3, sourceSnapshot: project.sourceSnapshot, status: 'INCOMPLETE',
+        deprecationCatalog: catalog.coverage, deprecationCoverage: deprecations.coverage,
+        unresolved: deprecations.unresolved, resolutionWarnings: deprecations.resolutionWarnings,
+        findings: deprecations.findings,
+      }, null, 2)}\n`);
+      const error = new Error(`${deprecations.unresolved.length} unresolved SDK/source references prevent a complete scan`);
+      error.code = 'UNRESOLVED_DEPRECATION_REFERENCES'; error.details = deprecations.unresolved.slice(0, 30); throw error;
+    }
+    stage = 'IMPORT_BUILD_LOG';
+    const buildLogImport = options.mode === 'upgrade' ? null : await importDeprecatedBuildLog({ project, catalog, logPath: options.buildLog, evidencePath: options.buildEvidence });
+    const ruleSnapshot = sha256(catalog.snapshot + JSON.stringify(compiled.rules.map((rule) => ({
+      ruleId: rule.ruleId,
+      changedInSdk: rule.changedInSdk,
+      changeOperation: rule.changeOperation,
+      reportDisposition: rule.reportDisposition ?? 'REQUIRES_REVIEW',
+      filterReason: rule.filterReason ?? null,
+      applicabilityProof: rule.applicabilityProof ?? null,
+      replacementApi: rule.replacementApi ?? null,
+      replacementSource: rule.replacementSource ?? null,
+      sourceReference: rule.sourceReference,
+      affectedApis: rule.affectedApis,
+    }))));
+    stage = 'WRITE_INITIAL_COVERAGE';
+    await atomicWrite(coverageJson, `${JSON.stringify({
+      ...compiled.coverage,
+      ruleSnapshot,
+      deprecationValidation,
+      deprecationCatalog: catalog.coverage,
+      behaviorPolicy: behaviorPolicyCoverage,
+    }, null, 2)}\n`);
+    stage = 'NATIVE_BUILD';
+    const nativeBuilds = await ensureNativeBuild({
+      project,
+      toolchain,
+      mode: options.nativeBuild,
+    });
+    stage = 'RUN_DEVECO_SCAN';
+    const result = await runDevEcoScan({
+      toolchain,
+      project,
+      range,
+      rules: selectScanRules(compiled.rules, options.mode),
+      outputDirectory,
+      batchId: outputLayout.batchId,
+      deprecations,
+      buildLogImport,
+      mode: options.mode,
+      devecoVersionNames: compiled.coverage.devecoVersionNames,
+      runtime,
+      verifyInputs: async () => {
+        const afterProject = await loadProject(options.projectPath, options.productName, options.scanDirs, options.scanModules, options.projectType);
+        const afterCatalog = await buildSdkCatalog(toolchain, range.end);
+        const changed = [];
+        if (afterProject.sourceSnapshot !== project.sourceSnapshot) changed.push('project sources');
+        if (afterProject.buildProfileHash !== project.buildProfileHash) changed.push('build-profile.json5');
+        if (afterCatalog.snapshot !== catalog.snapshot) changed.push('SDK declarations/parser');
+        for (const item of deprecations.analyzedFiles) {
+          if (sha256(await readFile(item.file)) !== item.hash) changed.push(item.file);
+        }
+        if (changed.length) {
+          const error = new Error('Scan input changed before report publication');
+          error.code = 'SOURCE_CHANGED_DURING_SCAN'; error.details = changed; throw error;
+        }
+      },
+    });
+    stage = 'VERIFY_SOURCE_SNAPSHOT';
+    const after = await loadProject(options.projectPath, options.productName, options.scanDirs, options.scanModules, options.projectType);
+    if (after.sourceSnapshot !== project.sourceSnapshot) {
+      const error = new Error('Project source changed during the scan');
+      error.code = 'SOURCE_CHANGED_DURING_SCAN';
+      throw error;
+    }
+    const warnings = [...result.diagnostics.warnings];
+    if (compiled.coverage.upgrade) {
+      const hitRules = new Set(result.allFindings.map(finding => finding['Rule ID']));
+      for (const entry of compiled.coverage.upgrade.entries) if (entry.status === 'RULE_AVAILABLE')
+        entry.projectStatus = entry.ruleIds.some(id => hitRules.has(id)) ? 'HIT' : 'NOT_RELATED_TO_PROJECT';
+    }
+    if (compiled.coverage.upgrade?.missingRuleCount) warnings.push(
+      `当前加载的 DevEco ${toolchain.productInfo?.version ?? '未知版本'} 插件规则包未覆盖官方文档中 ${compiled.coverage.upgrade.missingRuleCount} 条变更：`
+      + compiled.coverage.upgrade.missing.map(entry => `${entry.title}（${entry.changedInSdk}；${entry.sourceUrl ?? entry.sourceReference}）`).join('、')
+      + `；官方规则覆盖为 INCOMPLETE，详见 ${coverageJson}`);
+    if (options.mode === 'upgrade') {
+      const missingLinks = [...new Map(result.allFindings.filter(finding => !finding.documentLink?.url)
+        .map(finding => [finding['Rule ID'], finding])).values()];
+      if (missingLinks.length) warnings.push(`以下命中缺少唯一条目链接，Title 保留纯文本：${missingLinks.map(finding => finding['Rule ID']).join('、')}`);
+    }
+    const scanStatistics = { loadedRuleCount: compiled.coverage.devecoRuleCount, raw: findingStatistics(result.findings) };
+    const coverage = {
+      ...compiled.coverage,
+      ruleSnapshot,
+      deprecationValidation,
+      deprecationCatalog: catalog.coverage,
+      behaviorPolicy: behaviorPolicyCoverage,
+      scanCoverage: {
+        arkts: 'COMPLETE',
+        deprecations: deprecations.coverage,
+        cpp: result.diagnostics.cppStatus,
+      },
+      scanStatistics,
+    };
+    stage = 'WRITE_RESULTS';
+    await assertBatchDirectory(outputLayout, outputLayout.scannerDirectory);
+    await atomicWrite(coverageJson, `${JSON.stringify(coverage, null, 2)}\n`);
+    diagnostics = {
+      schemaVersion: 1,
+      runtime,
+      status: warnings.length ? 'COMPLETE_WITH_WARNINGS' : 'COMPLETE',
+      inputs: {
+        project: project.root,
+        sdk: toolchain.sdkRoot,
+        devecoHome: toolchain.contentsRoot,
+        from: options.from,
+        to: options.to,
+        targetSdkVersionSource: options.targetVersionSource,
+        product: project.product.name,
+        scanDirs: project.scanDirs.map((item) => item.relative),
+        scanModules: project.sourceScope.scanModules,
+        projectType: options.projectType,
+        nativeBuild: options.nativeBuild,
+        mode: options.mode,
+        batchSize: options.batchSize,
+        buildLog: options.buildLog,
+        buildEvidence: options.buildEvidence,
+      },
+      sourceSnapshot: project.sourceSnapshot,
+      sourceScope: project.sourceScope,
+      scannedFiles: project.sourceFiles.map(file => path.relative(project.root, file).split(path.sep).join('/')),
+      ruleSnapshot,
+      deprecationCatalog: catalog.coverage,
+      deprecationCoverage: deprecations.coverage,
+      toolchain: {
+        sdk: toolchain.sdkMetadata.data,
+        deveco: toolchain.productInfo,
+        devecoCompatibility: toolchain.devecoCompatibility,
+        backend: toolchain.apiChangeBackend,
+        scanCapabilities:{moduleScope:toolchain.moduleScanSupported,fileScope:toolchain.fileScanSupported,evidence:toolchain.capabilityEvidence},
+        paths: {
+          home: toolchain.contentsRoot,
+          analyzer: toolchain.analyzerRoot,
+          scanner: toolchain.apiChangeScan,
+          resources: toolchain.apiChangeResourceRoot,
+          resourceArchive: toolchain.apiChangeResourceArchive,
+          parser: toolchain.parserPath,
+          cApiScanJar: toolchain.cApiScanJar,
+        },
+        hashes: toolchain.hashes,
+      },
+      nativeBuilds,
+      nativePasses: result.diagnostics.nativePasses,
+      findingCount: result.findings.length,
+      scanStatistics,
+      totalFindingCount: result.allFindings.length,
+      filteredFindingCount: result.filteredFindings.length,
+      actionGroupCount: result.actionGroups.length,
+      validationGroupCount: result.validationGroups.length,
+      filterSummary: result.diagnostics.filterSummary,
+      durationMs: result.diagnostics.durationMs,
+      backend: toolchain.apiChangeBackend,
+      deveco: toolchain.productInfo,
+      devecoCompatibility: toolchain.devecoCompatibility,
+      warnings,
+      scannerOutput: {
+        ...(result.diagnostics.cleanupWarning ? { cleanupWarning: result.diagnostics.cleanupWarning } : {}),
+        stdout: result.diagnostics.stdout,
+        stderr: result.diagnostics.stderr,
+      },
+    };
+    await atomicWrite(diagnosticsJson, `${JSON.stringify(diagnostics, null, 2)}\n`);
+    return {
+      outputCsv: result.outputCsv,
+      outputLayout, batchId: outputLayout.batchId,
+      scanStatistics,
+      ...(compiled.coverage.upgrade ? { officialCoverage: { status: compiled.coverage.upgrade.status,
+        missingRuleCount: compiled.coverage.upgrade.missingRuleCount, missing: compiled.coverage.upgrade.missing,
+        rulePack: compiled.coverage.upgrade.rulePack } } : {}),
+      validationCsv: result.validationCsv,
+      scanJson: result.scanJson,
+      coverageJson,
+      diagnosticsJson,
+      findingCount: result.findings.length,
+      totalFindingCount: result.allFindings.length,
+      filteredFindingCount: result.filteredFindings.length,
+      actionGroupCount: result.actionGroups.length,
+      validationGroupCount: result.validationGroups.length,
+      filterSummary: result.diagnostics.filterSummary,
+      durationMs: result.diagnostics.durationMs,
+      warnings,
+      ruleSnapshot,
+      resolvedTargetSdkVersion: options.to,
+      compileSdkVersion: canonicalVersion(toolchain.sdkVersion),
+      ...(compiled.coverage.upgrade ? { officialCoverageStatus: compiled.coverage.upgrade.status } : {}),
+      targetSdkVersionSource: options.targetVersionSource,
+      runtime,
+    };
+  } catch (error) {
+    if (error && typeof error === 'object') error.stage ??= stage;
+    if (error && typeof error === 'object') error.code ??= 'SCAN_FAILED';
+    if (error && typeof error === 'object') error.artifactPaths ??= [diagnosticsJson];
+    diagnostics = {
+      ...diagnostics,
+      error: serializeError(error, { command: 'scan', stage }),
+    };
+    await assertBatchDirectory(outputLayout, outputLayout.scannerDirectory);
+    await atomicWrite(diagnosticsJson, `${JSON.stringify(diagnostics, null, 2)}\n`);
+    throw error;
+  }
+}
+
+export async function execute(argv) {
+  const [command, ...rest] = argv;
+  const args = parseArgs(rest);
+  switch (command) {
+    case 'scan': return scan(args);
+    case 'inspect-rules': return inspectRules(args);
+    case 'help':
+    case '--help':
+    case '-h':
+    case undefined: return { usage: usage() };
+    default: throw new Error(`Unknown command: ${command}\n\n${usage()}`);
+  }
+}