@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/shared/format/zip.mjs

@@ -0,0 +1,87 @@
+import { readFile } from 'node:fs/promises';
+import { inflateRawSync } from 'node:zlib';
+
+const CENTRAL_SIGNATURE = 0x02014b50;
+const END_SIGNATURE = 0x06054b50;
+const LOCAL_SIGNATURE = 0x04034b50;
+
+function assertRange(buffer, offset, length, label) {
+  if (offset < 0 || length < 0 || offset + length > buffer.length) {
+    throw new Error(`Invalid ZIP ${label} range`);
+  }
+}
+
+function endOfCentralDirectory(buffer) {
+  if (buffer.length < 22) throw new Error('ZIP archive is truncated');
+  const minimum = Math.max(0, buffer.length - 65_557);
+  for (let offset = buffer.length - 22; offset >= minimum; offset -= 1) {
+    if (buffer.readUInt32LE(offset) === END_SIGNATURE) return offset;
+  }
+  throw new Error('ZIP end of central directory not found');
+}
+
+function centralEntries(buffer) {
+  const end = endOfCentralDirectory(buffer);
+  const count = buffer.readUInt16LE(end + 10);
+  const size = buffer.readUInt32LE(end + 12);
+  const start = buffer.readUInt32LE(end + 16);
+  if (count === 0xffff || size === 0xffffffff || start === 0xffffffff) {
+    throw new Error('ZIP64 archives are not supported');
+  }
+  assertRange(buffer, start, size, 'central directory');
+  const entries = [];
+  let offset = start;
+  for (let index = 0; index < count; index += 1) {
+    assertRange(buffer, offset, 46, 'central header');
+    if (buffer.readUInt32LE(offset) !== CENTRAL_SIGNATURE) throw new Error('Invalid ZIP central header');
+    const flags = buffer.readUInt16LE(offset + 8);
+    const method = buffer.readUInt16LE(offset + 10);
+    const compressedSize = buffer.readUInt32LE(offset + 20);
+    const uncompressedSize = buffer.readUInt32LE(offset + 24);
+    const nameLength = buffer.readUInt16LE(offset + 28);
+    const extraLength = buffer.readUInt16LE(offset + 30);
+    const commentLength = buffer.readUInt16LE(offset + 32);
+    const localOffset = buffer.readUInt32LE(offset + 42);
+    assertRange(buffer, offset + 46, nameLength + extraLength + commentLength, 'central entry');
+    const name = buffer.subarray(offset + 46, offset + 46 + nameLength).toString('utf8');
+    entries.push({ name, flags, method, compressedSize, uncompressedSize, localOffset });
+    offset += 46 + nameLength + extraLength + commentLength;
+  }
+  return entries;
+}
+
+function entryContent(buffer, entry, maxEntrySize) {
+  if ((entry.flags & 0x1) !== 0) throw new Error(`Encrypted ZIP entry is not supported: ${entry.name}`);
+  if (entry.uncompressedSize > maxEntrySize) throw new Error(`ZIP entry is too large: ${entry.name}`);
+  assertRange(buffer, entry.localOffset, 30, 'local header');
+  if (buffer.readUInt32LE(entry.localOffset) !== LOCAL_SIGNATURE) throw new Error('Invalid ZIP local header');
+  const nameLength = buffer.readUInt16LE(entry.localOffset + 26);
+  const extraLength = buffer.readUInt16LE(entry.localOffset + 28);
+  const dataOffset = entry.localOffset + 30 + nameLength + extraLength;
+  assertRange(buffer, dataOffset, entry.compressedSize, 'entry data');
+  const compressed = buffer.subarray(dataOffset, dataOffset + entry.compressedSize);
+  const content = entry.method === 0 ? Buffer.from(compressed)
+    : entry.method === 8 ? inflateRawSync(compressed)
+      : null;
+  if (!content) throw new Error(`Unsupported ZIP compression method ${entry.method}: ${entry.name}`);
+  if (content.length !== entry.uncompressedSize) throw new Error(`ZIP entry size mismatch: ${entry.name}`);
+  return content;
+}
+
+export async function listZipEntries(archivePath) {
+  return centralEntries(await readFile(archivePath)).map(entry => entry.name);
+}
+
+export async function readZipTextEntries(archivePath, predicate = () => true, {
+  maxEntrySize = 16 * 1024 * 1024,
+  maxTotalSize = 64 * 1024 * 1024,
+} = {}) {
+  const buffer = await readFile(archivePath);
+  const selected = centralEntries(buffer).filter(entry => predicate(entry.name));
+  const total = selected.reduce((sum, entry) => sum + entry.uncompressedSize, 0);
+  if (total > maxTotalSize) throw new Error('Selected ZIP entries exceed the allowed total size');
+  return selected.map(entry => ({
+    name: entry.name,
+    text: entryContent(buffer, entry, maxEntrySize).toString('utf8'),
+  }));
+}

package/node_modules/@hmos-library-adapter/executer/shared/skills/harmonyos-api-upgrade-adapter/scripts/shared/io/fs-utils.mjs

@@ -0,0 +1,60 @@
+import { createHash } from 'node:crypto';
+import { access, mkdir, readdir, readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { atomicWriteFile } from '../platform/fs.mjs';
+
+export function sha256(value) {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+export async function sha256File(file) {
+  return sha256(await readFile(file));
+}
+
+export async function exists(target) {
+  try {
+    await stat(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function portableRelative(root, target) {
+  return path.relative(root, target).split(path.sep).join('/');
+}
+
+export function resolveInside(root,file) {
+  const base=path.resolve(root),target=path.resolve(base,file),relative=path.relative(base,target);
+  if(relative==='..'||relative.startsWith(`..${path.sep}`)||path.isAbsolute(relative))throw new Error(`Path escapes project root: ${file}`);
+  return target;
+}
+
+export async function listFiles(root, predicate = () => true, visitDirectory = () => true, { allowMissing = false } = {}) {
+  if (allowMissing && !await pathExists(root)) return [];
+  const results = [];
+  async function visit(directory) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    entries.sort((left, right) => left.name.localeCompare(right.name));
+    for (const entry of entries) {
+      const target = path.join(directory, entry.name);
+      if (entry.isDirectory() && visitDirectory(target)) await visit(target);
+      else if (entry.isFile() && predicate(target)) results.push(target);
+    }
+  }
+  await visit(root);
+  return results;
+}
+
+export async function ensureDir(directory) {
+  await mkdir(directory, { recursive: true });
+}
+
+export async function atomicWrite(target, content) {
+  await atomicWriteFile(target, content, { ensureDirectory: ensureDir });
+}
+
+export async function pathExists(file) {
+  try { await access(file); return true; }
+  catch (error) { if (['ENOENT', 'ENOTDIR'].includes(error.code)) return false; throw error; }
+}

package/node_modules/@hmos-library-adapter/executer/shared/skills/harmonyos-api-upgrade-adapter/scripts/shared/platform/artifact-layout.mjs

@@ -0,0 +1,74 @@
+import { randomBytes, createHash } from 'node:crypto';
+import { mkdir, realpath, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { errorWithCode } from './errors.mjs';
+import { relativePathInside } from './paths.mjs';
+
+const digest = bytes => createHash('sha256').update(bytes).digest('hex');
+
+export function batchArtifactPaths(directory, batchId, mode = 'upgrade') {
+  if (!/^[a-f0-9]{12}$/.test(batchId)) throw errorWithCode('扫描批次 ID 必须为 12 位小写十六进制', 'SCAN_BATCH_INVALID');
+  if (!['upgrade', 'deprecated'].includes(mode)) throw errorWithCode('扫描批次模式无效', 'SCAN_BATCH_INVALID');
+  const api = /^[a-z]:[\\/]|^\\\\/i.test(directory) ? path.win32 : path;
+  const scanDirectory = api.resolve(directory);
+  const internalDirectory = api.join(scanDirectory, '.internal');
+  const scannerDirectory = api.join(internalDirectory, 'scanner');
+  const deliveryDirectory = api.join(scanDirectory, mode);
+  const scanStamp = api.basename(scanDirectory);
+  if (mode === 'deprecated' && !/^\d{14}(?:-[2-9]\d*|-1\d+)?$/.test(scanStamp))
+    throw errorWithCode('废弃 API 批次目录必须使用扫描时间戳', 'SCAN_BATCH_INVALID');
+  const stem = mode === 'deprecated' ? `apiChange_${scanStamp}` : `scan-results-${batchId}`;
+  return {
+    schemaVersion: 4, batchId, mode, scanDirectory, internalDirectory, scannerDirectory, deliveryDirectory,
+    ...(mode === 'deprecated' ? { scanStamp } : {}),
+    batchMetadataPath: api.join(internalDirectory, 'scan-batch.json'),
+    rawCsv: api.join(deliveryDirectory, `${stem}.csv`),
+    adaptedCsv: api.join(deliveryDirectory, `adapted-results-${batchId}.csv`),
+    scanJson: api.join(scannerDirectory, `${stem}.scan.json`),
+    validationCsv: mode === 'deprecated' ? api.join(scannerDirectory, `${stem}.validation.csv`) : null,
+    coverageJson: api.join(scannerDirectory, 'coverage.json'),
+    diagnosticsJson: api.join(scannerDirectory, 'diagnostics.json'),
+  };
+}
+
+export async function assertBatchDirectory(layout, directory) {
+  if (relativePathInside(layout.scanDirectory, directory) === null
+    || relativePathInside(await realpath(layout.scanDirectory), await realpath(directory)) === null
+    || !(await stat(directory)).isDirectory())
+    throw errorWithCode('内部目录越过扫描批次边界或不是目录', 'SCAN_BATCH_INVALID', { path: directory });
+}
+
+// Check each existing parent before creating children, including Windows junctions.
+export async function ensureBatchDirectory(layout, directory) {
+  const relative = relativePathInside(layout.scanDirectory, directory);
+  if (relative === null) throw errorWithCode('内部目录越过扫描批次边界', 'SCAN_BATCH_INVALID', { path: directory });
+  let current = layout.scanDirectory;
+  await assertBatchDirectory(layout, current);
+  for (const part of relative.split(/[\\/]/).filter(Boolean)) {
+    current = path.join(current, part);
+    try { await mkdir(current); }
+    catch (error) { if (error.code !== 'EEXIST') throw error; }
+    await assertBatchDirectory(layout, current);
+  }
+}
+
+export async function createScanBatch(outputRoot, directory, { idFactory = () => randomBytes(6).toString('hex'), mode = 'upgrade' } = {}) {
+  if (!['upgrade', 'deprecated'].includes(mode)) throw errorWithCode('扫描批次模式无效', 'SCAN_BATCH_INVALID');
+  const registry = path.join(outputRoot, '.batch-ids');
+  await mkdir(registry, { recursive: true });
+  if (relativePathInside(await realpath(outputRoot), await realpath(registry)) === null
+    || relativePathInside(await realpath(outputRoot), await realpath(directory)) === null)
+    throw errorWithCode('扫描批次目录越过输出边界', 'SCAN_BATCH_INVALID');
+  for (let attempt = 0; attempt < 32; attempt++) {
+    const paths = batchArtifactPaths(directory, idFactory(), mode);
+    await ensureBatchDirectory(paths, paths.internalDirectory);
+    await ensureBatchDirectory(paths, paths.deliveryDirectory);
+    const content = JSON.stringify({ schemaVersion: 4, batchId: paths.batchId, mode,
+      ...(mode === 'deprecated' ? { scanStamp: paths.scanStamp } : {}), createdAt: new Date().toISOString() }, null, 2) + '\n';
+    try { await writeFile(path.join(registry, paths.batchId), content, { flag: 'wx' }); }
+    catch (error) { if (error.code === 'EEXIST') continue; throw error; }
+    await writeFile(paths.batchMetadataPath, content, { flag: 'wx' });
+    return { ...paths, createdAt: JSON.parse(content).createdAt, batchMetadataSha256: digest(content) };
+  }
+  throw errorWithCode('扫描批次 ID 连续冲突，请重试', 'SCAN_BATCH_COLLISION');
+}

package/node_modules/@hmos-library-adapter/executer/shared/skills/harmonyos-api-upgrade-adapter/scripts/shared/platform/changelog-index.mjs

@@ -0,0 +1,29 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+// The index lists only current document paths and official overview entries.
+// Custom reference corpora without a sidecar retain their existing behavior.
+export async function loadChangelogIndex(referenceRoot) {
+  const file = path.join(path.dirname(referenceRoot), `${path.basename(referenceRoot)}-index.json`);
+  let text;
+  try { text = await readFile(file, 'utf8'); }
+  catch (error) {
+    if (error.code === 'ENOENT') return { documents: [], overview: [] };
+    throw error;
+  }
+  const index = JSON.parse(text);
+  if (index.schemaVersion !== 1 || !Array.isArray(index.documents) || !Array.isArray(index.overview))
+    throw new Error(`Invalid changelog index: ${file}`);
+  const paths = new Map();
+  for (const document of index.documents) {
+    const value = document?.path;
+    if (typeof value !== 'string' || !value || path.posix.isAbsolute(value) || path.win32.isAbsolute(value)
+      || value.split(/[\\/]/).some(part => !part || part === '.' || part === '..'))
+      throw new Error(`Invalid changelog document path: ${value}`);
+    const key = value.replaceAll('\\', '/').toLowerCase();
+    if (paths.has(key)) throw new Error('Duplicate changelog document path');
+    paths.set(key, document);
+    document.path = value.replaceAll('\\', '/');
+  }
+  return index;
+}

package/node_modules/@hmos-library-adapter/executer/shared/skills/harmonyos-api-upgrade-adapter/scripts/shared/platform/deveco-version.mjs

@@ -0,0 +1,40 @@
+import { canonicalHarmonyVersion, parseHarmonyVersion } from './version.mjs';
+import { errorWithCode } from './errors.mjs';
+
+export function inspectDevEcoCompatibility(productInfo, targetVersion, contentsRoot = null) {
+  const target = typeof targetVersion === 'object' ? targetVersion : parseHarmonyVersion(targetVersion);
+  const installedVersion = typeof productInfo?.version === 'string' ? productInfo.version : null;
+  const match = installedVersion?.trim().match(/^(\d+)\.(\d+)\.(\d+)(?:\.(\d+))?$/);
+  const numbers = match ? match.slice(1).filter(value => value !== undefined).map(Number) : null;
+  const result = {
+    status: 'UNRESOLVED',
+    installedVersion,
+    requiredVersion: target.platformVersion,
+    targetVersion: canonicalHarmonyVersion(target),
+    contentsRoot,
+    metadataPath: productInfo?.file ?? null,
+  };
+  if (!numbers?.every(Number.isSafeInteger)) return result;
+  const required = target.platformVersion.split('.').map(Number);
+  const different = required.findIndex((value, index) => numbers[index] !== value);
+  result.status = different !== -1 && numbers[different] < required[different] ? 'TOO_OLD' : 'COMPATIBLE';
+  return result;
+}
+
+export function assertDevEcoCompatibility(compatibility) {
+  if (compatibility.status === 'COMPATIBLE') return;
+  const error = compatibility.status === 'TOO_OLD'
+    ? errorWithCode(
+      `本地 DevEco Studio 版本 ${compatibility.installedVersion} 低于目标 ${compatibility.targetVersion} `
+      + `所需的最低版本 ${compatibility.requiredVersion}，该目标不在当前环境扫描范围内。`
+      + '请降低预期目标版本或升级本地 DevEco Studio。',
+      'DEVECO_TARGET_NOT_COVERED', compatibility,
+    )
+    : errorWithCode(
+      '无法准确识别本地 DevEco Studio 版本，已停止扫描。'
+      + '请修复本地环境或通过 --deveco-home 指定具有有效 product-info.json 的 DevEco Studio 安装后重试。',
+      'DEVECO_VERSION_UNRESOLVED', compatibility,
+    );
+  error.stage = 'VALIDATE_DEVECO_VERSION';
+  throw error;
+}

package/node_modules/@hmos-library-adapter/executer/shared/skills/harmonyos-api-upgrade-adapter/scripts/shared/platform/document-links.mjs

@@ -0,0 +1,30 @@
+export function normalizeDocumentUrl(value, { fragment = true } = {}) {
+  try {
+    const url = new URL(value);
+    if (!['http:', 'https:'].includes(url.protocol)) return null;
+    if (url.hostname === 'developer.huawei.com') url.pathname = url.pathname
+      .replace(/\/doc\/(?:harmonyos-releases|doccenter-release-notes)\//, '/doc/doccenter-release-notes/');
+    url.pathname = url.pathname.replace(/\/$/, '');
+    if (!fragment) url.hash = '';
+    return url.href;
+  } catch { return null; }
+}
+
+export function entryUrl(value) {
+  const normalized = normalizeDocumentUrl(value);
+  if (!normalized) return null;
+  const hash = new URL(normalized).hash;
+  return hash.length > 1 && !/^#scan-/i.test(hash) ? normalized : null;
+}
+
+// A syntactically valid backend URL is not evidence of a public change identity.
+export function ruleDocumentLink(rule, providedUrl, { requireEntry = true } = {}) {
+  const expected = requireEntry ? entryUrl(rule.url) : normalizeDocumentUrl(rule.url);
+  const supplied = normalizeDocumentUrl(providedUrl);
+  const rejectedReason = !supplied ? null : /^#scan-/i.test(new URL(supplied).hash)
+    ? 'SYNTHETIC_SCAN_ANCHOR' : supplied !== expected ? 'RULE_LINK_MISMATCH' : null;
+  return { url: expected ?? '', source: expected ? supplied === expected ? 'VERIFIED_DEVECO_REPORT'
+    : rule.documentLink?.source ?? 'VERIFIED_RULE' : null,
+    ...(rejectedReason ? { originalUrl: providedUrl, rejectedReason } : {}),
+    ...(!expected ? { reason: rule.documentLink?.reason ?? 'DOCUMENT_ENTRY_NOT_VERIFIED' } : {}) };
+}

package/node_modules/@hmos-library-adapter/executer/shared/skills/harmonyos-api-upgrade-adapter/scripts/shared/platform/errors.mjs

@@ -0,0 +1,41 @@
+function stackLines(error, limit) {
+  if (typeof error?.stack !== 'string' || !error.stack) return undefined;
+  return error.stack.split(/\r?\n/).slice(0, limit).join('\n');
+}
+
+export function serializeError(error, {
+  command = undefined,
+  stage = undefined,
+  maxStackLines = 50,
+  maxCauseDepth = 4,
+  depth = 0,
+} = {}) {
+  const source = error && typeof error === 'object' ? error : new Error(String(error));
+  const result = {
+    name: source.name ?? 'Error',
+    code: source.code ?? undefined,
+    message: source.message ?? String(source),
+    command: command ?? source.command ?? undefined,
+    stage: source.stage ?? stage ?? undefined,
+    stack: stackLines(source, maxStackLines),
+    details: source.details ?? undefined,
+    validationErrors: source.validationErrors ?? undefined,
+    artifactPaths: source.artifactPaths ?? undefined,
+    cleanupWarning: source.cleanupWarning ?? undefined,
+  };
+  if (source.cause !== undefined && depth < maxCauseDepth) {
+    result.cause = serializeError(source.cause, {
+      maxStackLines,
+      maxCauseDepth,
+      depth: depth + 1,
+    });
+  }
+  return result;
+}
+
+export function errorWithCode(message, code, details = undefined) {
+  const error = new Error(message);
+  error.code = code;
+  if (details !== undefined) error.details = details;
+  return error;
+}

package/node_modules/@hmos-library-adapter/executer/shared/skills/harmonyos-api-upgrade-adapter/scripts/shared/platform/fs.mjs

@@ -0,0 +1,72 @@
+import { randomUUID } from 'node:crypto';
+import { chmod, rename, rm, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+const RETRYABLE_CODES = new Set(['EACCES', 'EBUSY', 'EPERM']);
+
+function wait(durationMs) {
+  return new Promise((resolve) => setTimeout(resolve, durationMs));
+}
+
+export async function retryFileOperation(operation, { maxRetries = 4, retryDelayMs = 25 } = {}) {
+  let lastError;
+  for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
+    try {
+      return await operation();
+    } catch (error) {
+      lastError = error;
+      if (!RETRYABLE_CODES.has(error.code) || attempt === maxRetries) throw error;
+      await wait(retryDelayMs * (attempt + 1));
+    }
+  }
+  throw lastError;
+}
+
+async function existingMode(target) {
+  try { return (await stat(target)).mode; } catch { return null; }
+}
+
+export async function replaceStagedPath(staged, target, { platform = process.platform } = {}) {
+  let replacementError = null;
+  try {
+    await retryFileOperation(() => rename(staged, target));
+    return;
+  } catch (error) {
+    const directoryReplacement = error.code === 'EEXIST' || error.code === 'ENOTEMPTY';
+    const windowsReplacement = platform === 'win32' && RETRYABLE_CODES.has(error.code);
+    if (!directoryReplacement && !windowsReplacement) throw error;
+    replacementError = error;
+  }
+  try { await stat(target); } catch { throw replacementError; }
+  const backup = path.join(path.dirname(target), `.${path.basename(target)}.${randomUUID()}.bak`);
+  let movedOriginal = false;
+  try {
+    await retryFileOperation(() => rename(target, backup));
+    movedOriginal = true;
+    await retryFileOperation(() => rename(staged, target));
+    await rm(backup, { recursive: true, force: true, maxRetries: 4, retryDelay: 25 });
+  } catch (error) {
+    if (movedOriginal) {
+      await rm(target, { recursive: true, force: true, maxRetries: 4, retryDelay: 25 });
+      try { await retryFileOperation(() => rename(backup, target)); } catch { /* Preserve the original error. */ }
+    }
+    throw error;
+  }
+}
+
+export async function atomicWriteFile(target, content, {
+  ensureDirectory,
+  platform = process.platform,
+} = {}) {
+  if (ensureDirectory) await ensureDirectory(path.dirname(target));
+  const temporary = path.join(path.dirname(target), `.${path.basename(target)}.${randomUUID()}.tmp`);
+  const mode = await existingMode(target);
+  try {
+    await writeFile(temporary, content);
+    if (mode !== null) await chmod(temporary, mode);
+    await replaceStagedPath(temporary, target, { platform });
+  } catch (error) {
+    await rm(temporary, { recursive: true, force: true, maxRetries: 4, retryDelay: 25 });
+    throw error;
+  }
+}

package/node_modules/@hmos-library-adapter/executer/shared/skills/harmonyos-api-upgrade-adapter/scripts/shared/platform/paths.mjs

@@ -0,0 +1,34 @@
+import path from 'node:path';
+
+function pathApi(platform) {
+  return platform === 'win32' ? path.win32 : path.posix;
+}
+
+export function normalizeComparablePath(value, platform = process.platform) {
+  const api = pathApi(platform);
+  const normalized = api.normalize(api.resolve(String(value)));
+  return platform === 'win32' ? normalized.toLowerCase() : normalized;
+}
+
+export function samePath(left, right, platform = process.platform) {
+  return normalizeComparablePath(left, platform) === normalizeComparablePath(right, platform);
+}
+
+export function portablePath(value) {
+  return String(value).replaceAll('\\', '/');
+}
+
+export function relativePathInside(root, file, platform = process.platform) {
+  const api = pathApi(platform);
+  const relative = api.relative(api.resolve(root), api.resolve(file));
+  if (relative === '..' || relative.startsWith(`..${api.sep}`) || api.isAbsolute(relative)) return null;
+  return portablePath(relative);
+}
+
+export function comparableCodeLocation(value, root = null, platform = process.platform) {
+  const match = String(value).match(/^(.*?)(:\d+(?::\d+)?)?$/);
+  let file = match[1];
+  if (root && pathApi(platform).isAbsolute(file)) file = relativePathInside(root, file, platform) ?? file;
+  file = portablePath(file);
+  return (platform === 'win32' ? file.toLowerCase() : file) + (match[2] ?? '');
+}

package/node_modules/@hmos-library-adapter/executer/shared/skills/harmonyos-api-upgrade-adapter/scripts/shared/platform/process.mjs

@@ -0,0 +1,154 @@
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+
+const WINDOWS_SHELL_EXTENSIONS = new Set(['.cmd', '.bat']);
+const WINDOWS_META_CHARACTERS = /([()%!^"<>&|;, *?])/g;
+
+export function prependPath(env, directories, platform = process.platform) {
+  const result = { ...env };
+  const keys = Object.keys(env).filter(key => platform === 'win32' ? key.toLowerCase() === 'path' : key === 'PATH');
+  const key = keys[0] ?? 'PATH';
+  const previous = env.PATH ?? env[key] ?? '';
+  for (const name of keys) delete result[name];
+  result[key] = [...directories.filter(Boolean), previous].filter(Boolean).join(platform === 'win32' ? ';' : ':');
+  return result;
+}
+
+function assertCommandValue(value) {
+  const text = String(value);
+  if (/[\0\r\n]/.test(text)) throw new Error('Command arguments cannot contain NUL or newlines');
+  return text;
+}
+
+function escapeWindowsCommand(value) {
+  return assertCommandValue(value).replace(WINDOWS_META_CHARACTERS, '^$1');
+}
+
+function escapeWindowsArgument(value) {
+  let escaped = assertCommandValue(value);
+  escaped = escaped.replace(/(\\*)"/g, '$1$1\\"');
+  escaped = escaped.replace(/(\\*)$/, '$1$1');
+  escaped = `"${escaped}"`;
+  return escaped.replace(WINDOWS_META_CHARACTERS, '^$1');
+}
+
+export function commandInvocation(command, args = [], platform = process.platform, env = process.env) {
+  const extension = path.extname(command).toLowerCase();
+  if (platform === 'win32' && WINDOWS_SHELL_EXTENSIONS.has(extension)) {
+    const executable = env.ComSpec || env.COMSPEC || 'cmd.exe';
+    const commandLine = [escapeWindowsCommand(command), ...args.map(escapeWindowsArgument)].join(' ');
+    return {
+      command: executable,
+      args: ['/d', '/s', '/v:off', '/c', `"${commandLine}"`],
+      windowsVerbatimArguments: true,
+    };
+  }
+  return { command, args, windowsVerbatimArguments: false };
+}
+
+function waitForClose(child, timeoutMs) {
+  return new Promise((resolve) => {
+    if (child.exitCode !== null || child.signalCode !== null) {
+      resolve(true);
+      return;
+    }
+    const timer = setTimeout(() => resolve(false), timeoutMs);
+    child.once('close', () => {
+      clearTimeout(timer);
+      resolve(true);
+    });
+  });
+}
+
+async function taskkill(pid, env) {
+  await new Promise((resolve) => {
+    const executable = env.SystemRoot
+      ? path.win32.join(env.SystemRoot, 'System32', 'taskkill.exe')
+      : 'taskkill.exe';
+    const child = spawn(executable, ['/pid', String(pid), '/t', '/f'], {
+      env,
+      shell: false,
+      windowsHide: true,
+      stdio: 'ignore',
+    });
+    child.once('error', () => resolve());
+    child.once('close', () => resolve());
+  });
+}
+
+export async function terminateProcessTree(child, {
+  platform = process.platform,
+  env = process.env,
+  detached = false,
+  graceMs = 3000,
+} = {}) {
+  if (!child?.pid || child.exitCode !== null || child.signalCode !== null) return;
+  if (platform === 'win32') {
+    await taskkill(child.pid, env);
+    if (child.exitCode === null && child.signalCode === null) child.kill('SIGTERM');
+    return;
+  }
+  const signal = (name) => {
+    try {
+      if (detached) process.kill(-child.pid, name);
+      else child.kill(name);
+    } catch {
+      try { child.kill(name); } catch { /* The process already exited. */ }
+    }
+  };
+  signal('SIGTERM');
+  if (!(await waitForClose(child, graceMs))) signal('SIGKILL');
+}
+
+export function runProcess(command, args = [], options = {}) {
+  const platform = options.platform ?? process.platform;
+  const env = options.env ?? process.env;
+  const invocation = commandInvocation(command, args, platform, env);
+  return new Promise((resolve) => {
+    let settled = false;
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+    let outputError = null;
+    const child = spawn(invocation.command, invocation.args, {
+      cwd: options.cwd,
+      env,
+      shell: false,
+      windowsHide: true,
+      windowsVerbatimArguments: invocation.windowsVerbatimArguments,
+      detached: options.detached === true,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      resolve({ stdout, stderr, timedOut, ...result });
+    };
+    const timer = options.timeoutMs
+      ? setTimeout(() => {
+        timedOut = true;
+        void terminateProcessTree(child, {
+          platform,
+          env,
+          detached: options.detached === true,
+          graceMs: options.terminationGraceMs,
+        });
+      }, options.timeoutMs)
+      : null;
+    child.stdout?.setEncoding('utf8');
+    child.stderr?.setEncoding('utf8');
+    const output = (chunk, stream) => {
+      if (stream === 'stdout') { if (options.captureStdout !== false) stdout += chunk; } else stderr += chunk;
+      if (!outputError) try { options.onOutput?.(chunk, stream); }
+      catch (error) {
+        outputError = error.message;
+        void terminateProcessTree(child, { platform, env, detached: options.detached === true, graceMs: options.terminationGraceMs });
+      }
+    };
+    child.stdout?.on('data', (chunk) => output(chunk, 'stdout'));
+    child.stderr?.on('data', (chunk) => output(chunk, 'stderr'));
+    child.once('error', (error) => finish({ exitCode: null, signal: null, error: error.message }));
+    child.once('close', (exitCode, signal) => finish({ exitCode, signal, error: outputError }));
+  });
+}

package/node_modules/@hmos-library-adapter/executer/shared/skills/harmonyos-api-upgrade-adapter/scripts/shared/platform/scan-mode.mjs

@@ -0,0 +1,7 @@
+import { errorWithCode } from './errors.mjs';
+
+export function requireScanMode(mode) {
+  if (!['upgrade', 'deprecated'].includes(mode))
+    throw errorWithCode('--mode must be explicitly set to upgrade or deprecated', 'SCAN_MODE_INVALID');
+  return mode;
+}

package/node_modules/@hmos-library-adapter/executer/shared/skills/harmonyos-api-upgrade-adapter/scripts/shared/platform/scan-statistics.mjs

@@ -0,0 +1,7 @@
+// Rule identities, CSV records and physical locations are separate units.
+export function findingStatistics(rows) {
+  const identities = rows.map(row => row['Rule ID'] || (row['Source Reference']
+    ? `${row['Source Reference']}\0${row['Changed in SDK']}` : null));
+  return { ruleCount: identities.every(Boolean) ? new Set(identities).size : null,
+    rowCount: rows.length, codeLocationCount: new Set(rows.map(row => row['Code Location'])).size };
+}