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

package/node_modules/@hmos-library-adapter/executer/shared/skills/harmonyos-api-upgrade-adapter/scripts/maintenance/regression/compare-golden.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+import { readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parseArgs, requireString } from '../../shared/format/args.mjs';
+import { parseCsv } from '../../shared/format/csv.mjs';
+import { canonicalHarmonyVersion as canonicalVersion } from '../../shared/platform/version.mjs';
+import { comparableCodeLocation } from '../../shared/platform/paths.mjs';
+
+function titleText(value) {
+  const match = String(value).match(/^=HYPERLINK\("(?:[^"]|"")*","((?:[^"]|"")*)"\)$/i);
+  return match ? match[1].replaceAll('""', '"') : String(value);
+}
+
+function normalizeLocation(value, projectRoot) {
+  return comparableCodeLocation(value, projectRoot);
+}
+
+function normalizeVersion(value) {
+  try {
+    return canonicalVersion(String(value));
+  } catch {
+    return String(value).trim();
+  }
+}
+
+function normalizedKey(row, projectRoot) {
+  return [
+    String(row['Api Definition']).replace(/\s+/g, ' ').trim(),
+    row.Language,
+    normalizeVersion(row['Changed in SDK']),
+    titleText(row.Title),
+    normalizeLocation(row['Code Location'], projectRoot),
+    row['Change Type'],
+  ].join('\u0000');
+}
+
+function multiset(rows, projectRoot, keyOf = normalizedKey) {
+  const result = new Map();
+  for (const row of rows) {
+    const key = keyOf(row, projectRoot);
+    const record = result.get(key) ?? { count: 0, row };
+    record.count += 1;
+    result.set(key, record);
+  }
+  return result;
+}
+
+function difference(left, right) {
+  const rows = [];
+  for (const [key, value] of left) {
+    const remaining = value.count - (right.get(key)?.count ?? 0);
+    for (let index = 0; index < Math.max(0, remaining); index += 1) rows.push(value.row);
+  }
+  return rows;
+}
+
+function isDevEcoRule(row) {
+  if (row['Detection Source'] && row['Detection Source'] !== 'DEVECO') return false;
+  if (!('Rule ID' in row)) return true;
+  return !isAdditionalDocumentRule(row);
+}
+
+function isAdditionalDocumentRule(row) {
+  return String(row['Source Reference']).replaceAll('\\', '/').includes('/API变更清单/');
+}
+
+const args = parseArgs(process.argv.slice(2));
+const goldenPath = path.resolve(requireString(args, 'golden'));
+const actualPath = path.resolve(requireString(args, 'actual'));
+const projectRoot = args.project ? path.resolve(args.project) : null;
+const outputPath = args.output ? path.resolve(args.output) : null;
+const scanJsonPath = args['scan-json'] ? path.resolve(args['scan-json']) : null;
+const golden = parseCsv(await readFile(goldenPath, 'utf8')).rows;
+const actualCsv = parseCsv(await readFile(actualPath, 'utf8'));
+const scan = scanJsonPath ? JSON.parse(await readFile(scanJsonPath, 'utf8')) : null;
+if (!scan && actualCsv.headers.includes('Replacement API') && !actualCsv.headers.includes('Rule ID'))
+  throw new Error('Reduced deprecated CSV requires --scan-json for source and symbol identities');
+const fullFindings = scan ? scan.findings : actualCsv.rows;
+const allActual = scan?.mode === 'deprecated' && Array.isArray(scan.actionGroups)
+  ? scan.actionGroups.map(group => ({
+    ...group.occurrences[0],
+    'Action Type': group.actionType, 'Policy ID': group.policyId,
+    'Occurrence Count': group.occurrenceCount, 'Trigger Evidence': group.triggerEvidence,
+  }))
+  : scan ? fullFindings.filter(finding => finding.includedInCsv !== false) : actualCsv.rows;
+if (scan) {
+  const visibleKey = row => JSON.stringify(actualCsv.headers.map(header => {
+    if (header === 'Code Location') return normalizeLocation(row[header], projectRoot);
+    if (header === 'Changed in SDK') return normalizeVersion(row[header] ?? '');
+    return String(row[header] ?? '');
+  }));
+  const csvRows = multiset(actualCsv.rows, projectRoot, visibleKey);
+  const reportedRows = multiset(allActual, projectRoot, visibleKey);
+  if (difference(csvRows, reportedRows).length || difference(reportedRows, csvRows).length)
+    throw new Error('Actual CSV does not match reported scan JSON rows: visible fields or multiplicity differ');
+}
+const actual = allActual.filter(isDevEcoRule);
+const fullActual = fullFindings.filter(isDevEcoRule);
+const deprecated = allActual.filter((row) => row['Change Operation'] === 'API_DEPRECATED' || row['Change Type'] === 'Deprecated API');
+const goldenSet = multiset(golden, projectRoot);
+const actualSet = multiset(actual, projectRoot);
+const fullActualSet = multiset(fullActual, projectRoot);
+const missing = difference(goldenSet, fullActualSet);
+const notReported = difference(goldenSet, actualSet);
+const extra = difference(actualSet, goldenSet);
+const matched = golden.length - missing.length;
+const report = {
+  schemaVersion: scanJsonPath ? 2 : 1,
+  goldenPath,
+  actualPath,
+  scanJsonPath,
+  projectRoot,
+  goldenRows: golden.length,
+  actualDevEcoRows: fullActual.length,
+  reportedDevEcoRows: actual.length,
+  filteredGoldenRows: Math.max(0, notReported.length - missing.length),
+  actualAdditionalDocumentRules: allActual.filter(isAdditionalDocumentRule).length,
+  actualDeprecatedRows: deprecated.length,
+  actualDistinctDeprecatedApis: new Set(deprecated.map((row) => row['API Symbol ID']
+    || [row['Rule ID'] ?? '', row['Api Definition']].join('\u0000'))).size,
+  matchedRows: matched,
+  missingRows: missing.length,
+  extraRows: extra.length,
+  recall: golden.length === 0 ? 1 : matched / golden.length,
+  precision: actual.length === 0 ? (golden.length === 0 ? 1 : 0) : (actual.length - extra.length) / actual.length,
+  missingSample: missing.slice(0, 100),
+  extraSample: extra.slice(0, 100),
+};
+if (outputPath) await writeFile(outputPath, `${JSON.stringify(report, null, 2)}\n`);
+process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);

package/node_modules/@hmos-library-adapter/executer/shared/skills/harmonyos-api-upgrade-adapter/scripts/maintenance/regression/regress-deprecated.mjs

@@ -0,0 +1,120 @@
+import { finished } from 'node:stream/promises';
+import { createWriteStream } from 'node:fs';
+import { cp, mkdir, readFile, mkdtemp } from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { parseArgs, requireString, stringList } from '../../shared/format/args.mjs';
+import { discoverDevEco } from '../../scanner/core/deveco.mjs';
+import { buildSdkCatalog } from '../../scanner/core/sdk-deprecations.mjs';
+import { loadProject } from '../../scanner/core/project.mjs';
+import { atomicWrite, exists, sha256 } from '../../shared/io/fs-utils.mjs';
+import { compareDeprecated } from './compare-deprecated.mjs';
+import { runProcess, prependPath } from '../../shared/platform/process.mjs';
+
+const scannerRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../scanner');
+const args = parseArgs(process.argv.slice(2));
+const projects = stringList(args.project);
+const refs = stringList(args.ref);
+if (!projects.length || refs.length !== projects.length) throw new Error('Pass matching repeated --project and --ref arguments');
+const toolchain = await discoverDevEco(requireString(args, 'sdk'));
+for (const name of ['java', 'ohpm', 'hvigorw']) if (!toolchain[name]) throw new Error(`Build tool is missing: ${name}`);
+const output = path.resolve(args['output-dir'] || await mkdtemp(path.join(os.tmpdir(), 'deprecated-regression-')));
+await mkdir(output, { recursive: true });
+const environment = prependPath({ ...process.env, DEVECO_SDK_HOME: toolchain.sdkRoot, JAVA_HOME: path.dirname(path.dirname(toolchain.java)) },
+  [path.dirname(process.execPath), path.dirname(toolchain.ohpm), path.dirname(toolchain.hvigorw), path.dirname(toolchain.java)]);
+async function run(command, argv, cwd, logPath = null) {
+  const stream = logPath ? createWriteStream(logPath) : null;
+  const complete = stream ? finished(stream) : Promise.resolve();
+  let streamError = null, text = '';
+  complete.catch(error => { streamError = error; });
+  try {
+    const result = await runProcess(command, argv, { cwd, env: environment, detached: true, timeoutMs: 30 * 60_000,
+      onOutput(chunk) { text += chunk; if (streamError) throw streamError; stream?.write(chunk); } });
+    if (result.error) throw new Error(result.error);
+    return { code: result.timedOut ? 124 : result.exitCode ?? 1, text };
+  } finally {
+    stream?.end();
+    await complete;
+  }
+}
+const cases = [];
+for (const [index, original] of projects.entries()) {
+  const name = path.basename(original);
+  const caseRoot = path.join(output, name);
+  const checkout = path.join(caseRoot, 'project');
+  await mkdir(caseRoot, { recursive: true });
+  if (await exists(checkout)) {
+    if (!args['reuse-checkouts']) throw new Error(`Checkout already exists: ${checkout}; choose a new output directory or --reuse-checkouts`);
+    const origin = await run('git', ['remote', 'get-url', 'origin'], checkout);
+    const head = await run('git', ['rev-parse', 'HEAD'], checkout);
+    const desired = await run('git', ['rev-parse', refs[index]], checkout);
+    if (origin.text.trim() !== original || head.text !== desired.text) throw new Error('Refusing to reuse a different checkout');
+  } else {
+    const clone = await run('git', ['clone', '--no-hardlinks', '--no-checkout', original, checkout], output);
+    if (clone.code) throw new Error(clone.text);
+    const checkoutResult = await run('git', ['checkout', '--detach', refs[index]], checkout);
+    if (checkoutResult.code) throw new Error(checkoutResult.text);
+  }
+  if (args['use-project-build-profile']) await cp(path.join(original, 'build-profile.json5'), path.join(checkout, 'build-profile.json5'));
+  const project = await loadProject(checkout, 'default');
+  for (const relative of ['oh_modules', ...project.modules.map(item => `${item.relativeRoot}/oh_modules`),
+    ...project.modules.map(item => `${item.relativeRoot}/src/main/resources/rawfile`)]) {
+    const source = path.join(original, relative);
+    if (await exists(source)) await cp(source, path.join(checkout, relative), { recursive: true, verbatimSymlinks: true, force: false, errorOnExist: false });
+  }
+  for (const [command, argv] of [[toolchain.java, ['-version']], [process.execPath, ['-v']],
+    [toolchain.ohpm, ['-v']], [toolchain.hvigorw, ['-v']]]) {
+    const result = await run(command, argv, checkout);
+    if (result.code) throw new Error(`Environment check failed: ${command}\n${result.text}`);
+  }
+  if (!environment.DEVECO_SDK_HOME) throw new Error('DEVECO_SDK_HOME missing');
+  console.log(`${name}: isolated checkout ready; non-incremental assembleApp`);
+  const logPath = path.join(caseRoot, 'build.log');
+  const before = await loadProject(checkout, 'default');
+  const build = await run(toolchain.hvigorw, ['--mode', 'project', '-p', 'product=default', 'assembleApp', '--analyze=normal', '--parallel', '--no-incremental', '--no-daemon'], checkout, logPath);
+  const after = await loadProject(checkout, 'default');
+  const catalog = await buildSdkCatalog(toolchain);
+  const record = { name, original, revision: refs[index], checkout,
+    buildProfileSource: args['use-project-build-profile'] ? 'CURRENT_PROJECT_CONFIG' : 'GIT_BASELINE_CONFIG', buildProfileHash: after.buildProfileHash,
+    buildExitCode: build.code, buildSourceStable: before.sourceSnapshot === after.sourceSnapshot && before.buildProfileHash === after.buildProfileHash };
+  cases.push(record);
+  await atomicWrite(path.join(output, 'regression.json'), JSON.stringify({ cases }, null, 2));
+  if (build.code || !record.buildSourceStable) { console.log(`${name}: build/input verification failed; see ${logPath}`); continue; }
+  const evidencePath = path.join(caseRoot, 'build-evidence.json');
+  await atomicWrite(evidencePath, JSON.stringify({ schemaVersion: 1, projectRoot: after.root, product: 'default',
+    logHash: sha256(await readFile(logPath)), sourceSnapshot: after.sourceSnapshot, sdkSnapshot: catalog.snapshot,
+    buildProfileHash: after.buildProfileHash,
+    targetSdk: catalog.coverage.targetSdk, nonIncremental: true, status: 'PASSED' }, null, 2));
+  const scanResults = [];
+  for (const round of [1, 2]) {
+    const destination = path.join(caseRoot, `scan-${round}`);
+    console.log(`${name}: scan ${round}/2`);
+    const result = await run(process.execPath, [path.join(scannerRoot, 'bin/harmony-api-scan.mjs'), 'scan', '--mode', 'deprecated', '--project', checkout,
+      '--sdk', toolchain.sdkRoot, '--from', args.from || '5.0.0(12)', '--to', args.to || catalog.coverage.targetSdk,
+      '--product', 'default', '--native-build', 'off', '--output-dir', destination], scannerRoot, path.join(caseRoot, `scan-${round}.log`));
+    const report = result.code === 0 ? JSON.parse(result.text).result : null;
+    scanResults.push({ code: result.code, destination, outputCsv: report?.outputCsv, scanJson: report?.scanJson });
+  }
+  record.scanExitCodes = scanResults.map(item => item.code);
+  if (scanResults.every(item => item.code === 0)) {
+    const comparison = await compareDeprecated({ project: checkout, buildLog: logPath,
+      scanJson: scanResults[0].scanJson, buildProjectRoot: after.root, buildEvidence: evidencePath });
+    await atomicWrite(path.join(caseRoot, 'comparison.json'), JSON.stringify(comparison, null, 2));
+    record.projectGoldCount = comparison.projectGoldCount;
+    record.projectMissingCount = comparison.projectMissingCount;
+    record.scannerOnlyCount = comparison.scannerOnlyCount;
+    record.csvIdentical = sha256(await readFile(scanResults[0].outputCsv)) === sha256(await readFile(scanResults[1].outputCsv));
+    const scans = await Promise.all(scanResults.map(item => readFile(item.scanJson, 'utf8')));
+    const snapshots = scans.map(text => { const { batchId, ...snapshot } = JSON.parse(text); return JSON.stringify(snapshot); });
+    record.scanJsonIdentical = snapshots[0] === snapshots[1];
+    record.deprecatedCount = JSON.parse(scans[0]).findings.filter(item => item['Change Operation'] === 'API_DEPRECATED').length;
+    console.log(`${name}: project gold ${record.projectGoldCount}, missing ${record.projectMissingCount}, deprecated ${record.deprecatedCount}, deterministic ${record.csvIdentical && record.scanJsonIdentical}`);
+  }
+  await atomicWrite(path.join(output, 'regression.json'), JSON.stringify({ cases }, null, 2));
+}
+const passed = cases.length === projects.length && cases.every(item => item.buildExitCode === 0 && item.buildSourceStable
+  && item.scanExitCodes?.every(code => code === 0) && item.projectMissingCount === 0 && item.csvIdentical && item.scanJsonIdentical);
+await atomicWrite(path.join(output, 'regression.json'), JSON.stringify({ status: passed ? 'PASSED' : 'FAILED', cases }, null, 2));
+console.log(`Regression ${passed ? 'PASSED' : 'FAILED'}: ${output}`);
+if (!passed) process.exitCode = 1;

package/node_modules/@hmos-library-adapter/executer/shared/skills/harmonyos-api-upgrade-adapter/scripts/maintenance/test/behavior-catalog-generation.test.mjs

@@ -0,0 +1,59 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import os from 'node:os';
+import { stringifyCsv } from '../../shared/format/csv.mjs';
+import { behaviorSourceHash, loadBehaviorPolicy, validateBehaviorPolicySources } from '../../scanner/behavior/behavior-policy.mjs';
+import { sha256 } from '../../shared/io/fs-utils.mjs';
+
+const run = promisify(execFile);
+
+test('catalog generation keeps official facts and stable identities without full-mode action heuristics', async t => {
+  const root = await mkdtemp(path.join(os.tmpdir(), 'catalog-source-中文 空格-'));
+  t.after(() => rm(root, { recursive: true, force: true }));
+  const refs = path.join(root, 'changelogs');
+  const newPath = path.posix.join('26.0.0', 'beta1-changes.md');
+  await mkdir(path.dirname(path.join(refs, newPath)), { recursive: true });
+  const original = '# 文档\n\n## 字体默认布局变更\n', row = {
+    Title: '字体默认布局变更', 'Source URL': 'https://example.test/change#font',
+    'Changed in SDK': '26.0.0(26) Beta1', 'Affected Versions': 'ALL', 'Affected Device Types': 'phone',
+    Scope: 'UX Style/Effect', 'Requires Adaptation': '是', 'Change Type': 'UX Style/Effect Change',
+    'Adaptation Basis': '官方原因', 'Adaptation Guidance': '官方指导：检查布局。',
+  };
+  await writeFile(path.join(root, 'changelogs-index.json'), JSON.stringify({ schemaVersion: 1,
+    documents: [{ path: newPath }], overview: [] }));
+  const script = fileURLToPath(new URL('../references/generate-behavior-policy.mjs', import.meta.url));
+  for (const [sourcePath, newline] of [[newPath, '\n'], [newPath, '\r\n'], [newPath.replaceAll('/', '\\'), '\n']]) {
+    await writeFile(path.join(refs, newPath), original.replaceAll('\n', newline));
+    const record = { ...row, 'Source Reference': `${sourcePath}:3` };
+    const catalog = path.join(root, '来源.csv'), output = path.join(root, 'catalog.json');
+    const baseline = { ...record, 'Source Reference': '5.0.0(12)/missing.md:1' };
+    await writeFile(catalog, stringifyCsv(Object.keys(record), [baseline, record]));
+    await run(process.execPath, [script, '--catalog', catalog, '--references', refs, '--output', output]);
+    const generated = await loadBehaviorPolicy(output), entry = generated.entries[0];
+    assert.equal(entry.apiLevel, 26);
+    assert.equal(entry.sourceReference, `${newPath}:3`);
+    assert.equal(entry.policyId, `font-${sha256(`${newPath}:3`).slice(0, 8)}`);
+    assert.equal(entry.sourceFileHash, behaviorSourceHash(original));
+    assert.equal(entry.documentConclusion, '是'); assert.equal(entry.rationale, '官方原因');
+    assert.equal(entry.triggerEvidence, row['Adaptation Guidance']);
+    assert.deepEqual(generated.counts, { 'UX Visual Layout Change': 1 });
+    for (const field of ['actionType', 'detectionMode', 'staticChecks', 'validationType', 'validationGuidance'])
+      assert.ok(!Object.hasOwn(entry, field));
+    assert.equal((await validateBehaviorPolicySources(generated, refs)).status, 'COMPLETE');
+    assert.equal(JSON.parse(await readFile(output, 'utf8')).entryCount, 1);
+  }
+  const catalog = path.join(root, '来源.csv'), output = path.join(root, 'catalog.json');
+  const saved = await readFile(output);
+  for (const unknownPath of [path.posix.join('26.0.0', 'unregistered.md'),
+    path.posix.join('26.0.0', 'OS平台能力', '正文.md'), path.posix.join('26.0.0', 'Beta1-正文.md')]) {
+    const record = { ...row, 'Source Reference': `${unknownPath}:3` };
+    await writeFile(catalog, stringifyCsv(Object.keys(record), [record]));
+    await assert.rejects(run(process.execPath, [script, '--catalog', catalog, '--references', refs, '--output', output]), /Unknown changelog source/);
+    assert.deepEqual(await readFile(output), saved);
+  }
+});

package/node_modules/@hmos-library-adapter/executer/shared/skills/harmonyos-api-upgrade-adapter/scripts/maintenance/test/behavior-local-sources.test.mjs

@@ -0,0 +1,44 @@
+// Corpus and documentation contracts only; these do not certify model reading or business applicability.
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseCsv } from '../../shared/format/csv.mjs';
+import { loadChangelogIndex } from '../../shared/platform/changelog-index.mjs';
+import { canonicalHarmonyVersion, compareHarmonyVersions } from '../../shared/platform/version.mjs';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+const references = path.join(root, 'references');
+const changelogs = path.join(references, 'changelogs');
+const expected = [
+  ['CH2026010615012', 966],
+  ['CH2026031846233', 36],
+  ['CH2026032761266', 146],
+  ['CH2026032801249', 87],
+];
+
+test('four-change fixture resolves current local headings and exact versions', async () => {
+  const { rows } = parseCsv(await readFile(new URL('./fixtures/behavior/local-sources.csv', import.meta.url), 'utf8'));
+  const index = await loadChangelogIndex(changelogs);
+  const policy = JSON.parse(await readFile(path.join(root, 'scripts', 'scanner', 'data', 'behavior-change-policy.json'), 'utf8'));
+  assert.deepEqual(rows.map(row => row['Rule ID']), expected.map(([id]) => id));
+  assert.equal(new Set(rows.map(row => row['Source Reference'])).size, 4);
+  for (const [i, row] of rows.entries()) {
+    const [id, line] = expected[i];
+    const source = row['Source Reference'];
+    const relative = source.replace(/:\d+$/, '');
+    assert.ok(source.endsWith(`:${line}`));
+    const document = index.documents.find(entry => entry.path === relative);
+    assert.ok(document, source);
+    const contents = (await readFile(path.join(changelogs, relative), 'utf8')).split(/\r?\n/);
+    assert.equal(contents[line - 1].replace(/^#+\s+/, ''), row.Title);
+    const matches = policy.entries.filter(entry => entry.sourceReference === source
+      && compareHarmonyVersions(entry.changedInSdk, row['Changed in SDK']) === 0);
+    assert.equal(matches.length, 1, `${id}: exact official identity`);
+    assert.equal(new URL(matches[0].sourceUrl).hash, `#${id.toLowerCase()}`);
+    assert.equal(compareHarmonyVersions(matches[0].changedInSdk, '26.0.0(26) Beta2'), -1);
+    assert.equal(compareHarmonyVersions(matches[0].changedInSdk, '26.0.0(26) Release'), -1);
+    assert.equal(canonicalHarmonyVersion(row['Changed in SDK']), '26.0.0(26) Beta1');
+  }
+});

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

@@ -0,0 +1,66 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import os from 'node:os';
+import path from 'node:path';
+import { loadChangelogIndex } from '../../shared/platform/changelog-index.mjs';
+import { referenceDigest } from '../references/references.mjs';
+
+const skillRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+const referenceRoot = path.join(skillRoot, 'references', 'changelogs');
+
+test('bundled corpus has 24 intact ASCII-named source documents under seven API13+ versions', async () => {
+  const index = await loadChangelogIndex(referenceRoot);
+  const versions = (await readdir(referenceRoot, { withFileTypes: true })).filter(entry => entry.name !== '.DS_Store');
+  assert.equal(versions.length, 7);
+  assert.ok(!versions.some(entry => entry.name === '5.0.0(12)'));
+  assert.ok(versions.every(entry => entry.isDirectory()));
+  const actual = [];
+  for (const version of versions) {
+    const files = (await readdir(path.join(referenceRoot, version.name), { withFileTypes: true }))
+      .filter(entry => entry.name !== '.DS_Store');
+    assert.ok(files.length > 0);
+    assert.ok(files.every(entry => entry.isFile() && entry.name.endsWith('.md')));
+    actual.push(...files.map(entry => path.posix.join(version.name, entry.name)));
+  }
+  assert.equal(index.documents.length, 24);
+  assert.deepEqual(actual.sort(), index.documents.map(entry => entry.path).sort());
+  assert.equal(new Set(actual.map(file => file.toLowerCase())).size, 24);
+  assert.ok(actual.every(file => /^[\x20-\x7e]+$/.test(file)));
+  assert.equal(index.overview.length, 195);
+  assert.ok(index.overview.every(entry => entry.version !== '5.0.0(12)'));
+  assert.ok(index.overview.every(entry => !Object.hasOwn(entry, 'originalSourceReference')));
+  for (const document of index.documents) {
+    assert.deepEqual(Object.keys(document).sort(), ['path', 'sha256']);
+    const file = path.join(referenceRoot, document.path);
+    assert.equal(await referenceDigest(file), document.sha256, document.path);
+    const text = await readFile(file, 'utf8');
+    for (const field of ['变更原因', '变更影响', '适配指导']) assert.ok(text.includes(`**${field}**`), document.path);
+  }
+});
+
+test('current document paths handle Windows separators and reject unsafe or duplicate identities', async t => {
+  const root = await mkdtemp(path.join(os.tmpdir(), 'changelog-中文 空格-'));
+  t.after(() => rm(root, { recursive: true, force: true }));
+  const refs = path.join(root, 'changelogs'), file = path.join(root, 'changelogs-index.json');
+  await mkdir(refs);
+  assert.deepEqual(await loadChangelogIndex(refs), { documents: [], overview: [] });
+  const source = { path: path.posix.join('26.0.0', 'beta1-changes.md') };
+  const document = { schemaVersion: 1, documents: [source], overview: [] };
+  await writeFile(file, JSON.stringify(document));
+  assert.deepEqual(await loadChangelogIndex(refs), document);
+  await writeFile(file, JSON.stringify({ ...document, documents: [{ path: source.path.replaceAll('/', '\\') }] }));
+  assert.deepEqual(await loadChangelogIndex(refs), document);
+  for (const value of [path.posix.join('..', 'outside.md'), path.win32.join('C:\\', 'outside.md'),
+    path.posix.join('/', 'outside.md'), '26.0.0/../outside.md', '26.0.0//file.md', '', 7]) {
+    await writeFile(file, JSON.stringify({ ...document, documents: [{ path: value }] }));
+    await assert.rejects(loadChangelogIndex(refs), /Invalid changelog document path/);
+  }
+  for (const duplicate of [source.path, source.path.toUpperCase(), source.path.replaceAll('/', '\\')]) {
+    await writeFile(file, JSON.stringify({ ...document, documents: [source, { path: duplicate }] }));
+    await assert.rejects(loadChangelogIndex(refs), /Duplicate changelog document path/);
+  }
+  await writeFile(file, '{');
+  await assert.rejects(loadChangelogIndex(refs), SyntaxError);
+});

package/node_modules/@hmos-library-adapter/executer/shared/skills/harmonyos-api-upgrade-adapter/scripts/maintenance/test/compare-golden.test.mjs

@@ -0,0 +1,103 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { runProcess } from '../../shared/platform/process.mjs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { DEPRECATED_HEADERS, stringifyCsv, UPGRADE_HEADERS } from '../../shared/format/csv.mjs';
+
+const packageRoot = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+
+async function run(command, args) {
+  const result = await runProcess(command, args, { timeoutMs: 30_000, detached: true });
+  return { ...result, code: result.exitCode };
+}
+
+test('counts documented no-adaptation rows as covered through scan JSON', async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), 'scanner-golden-audit-'));
+  const golden = path.join(root, 'golden.csv');
+  const actual = path.join(root, 'actual.csv');
+  const scanJson = path.join(root, 'apiChange.scan.json');
+  const base = {
+    'Api Definition': 'run(): void', Language: 'ArkTS', 'Changed in SDK': '6.0.0(20) Beta1',
+    'Affected Versions': 'ALL', Fixed: 'Unfixed', 'Change Type': 'API Behavior Change',
+  };
+  const reported = { ...base, Title: '需要适配', 'Code Location': 'entry/A.ets:1', 'Rule ID': 'r1', 'Change Operation': 'API_BEHAVIOR', 'Source Reference': 'behavior.md:1' };
+  const filtered = { ...base, Title: '无需适配', 'Code Location': 'entry/A.ets:2', 'Rule ID': 'r2', 'Change Operation': 'API_BEHAVIOR', 'Source Reference': 'behavior.md:2', includedInCsv: false, disposition: 'FILTERED_COMPATIBLE', filterReason: 'DOCUMENTED_NO_ADAPTATION' };
+  const headers = ['Api Definition', 'Language', 'Changed in SDK', 'Affected Versions', 'Title', 'Code Location', 'Fixed', 'Change Type'];
+  await writeFile(golden, stringifyCsv(headers, [reported, filtered]));
+  await writeFile(actual, stringifyCsv(UPGRADE_HEADERS, [reported]));
+  await writeFile(scanJson, `${JSON.stringify({ findings: [{ ...reported, includedInCsv: true }, filtered] })}\n`);
+
+  const result = await run(process.execPath, [
+    path.join(packageRoot, 'regression', 'compare-golden.mjs'),
+    '--golden', golden,
+    '--actual', actual,
+    '--scan-json', scanJson,
+  ]);
+  assert.equal(result.code, 0, result.stderr);
+  const report = JSON.parse(result.stdout);
+  assert.equal(report.matchedRows, 2);
+  assert.equal(report.missingRows, 0);
+  assert.equal(report.filteredGoldenRows, 1);
+  assert.equal(report.reportedDevEcoRows, 1);
+  assert.equal(report.recall, 1);
+});
+
+for (const mode of ['upgrade', 'deprecated']) {
+  test(`${mode} golden comparison checks reduced CSV multiplicity and uses complete JSON identities`, async t => {
+    const root = await mkdtemp(path.join(os.tmpdir(), 'reduced-golden-中文 '));
+    t.after(() => rm(root, { recursive: true, force: true }));
+    const golden = path.join(root, 'golden.csv'), actual = path.join(root, 'actual.csv'), scanJson = path.join(root, 'scan.json');
+    const headers = mode === 'upgrade' ? UPGRADE_HEADERS : DEPRECATED_HEADERS;
+    const findings = [1, 8].map(Column => ({
+      'Api Definition': 'old(): void', Language: 'ArkTS', 'Changed in SDK': '6.0.0(20) Beta1',
+      'Affected Versions': 'ALL', Title: '变更', 'Code Location': 'entry/A.ets:1', Fixed: 'Unfixed',
+      'Change Type': mode === 'upgrade' ? 'API Behavior Change' : 'Deprecated API',
+      'Rule ID': 'same-rule', 'Source Reference': 'behavior.md:1', 'Replacement API': 'new()',
+      'API Symbol ID': `symbol-${Column}`, 'Detection Source': mode === 'upgrade' ? 'DEVECO' : 'SDK_STATE',
+      Column, includedInCsv: true,
+    }));
+    const rows = [...findings].reverse();
+    const scan = { mode, findings, ...(mode === 'deprecated' ? { actionGroups: rows.map(row => ({ occurrences: [row] })) } : {}) };
+    await writeFile(golden, stringifyCsv(headers, mode === 'upgrade' ? findings : []));
+    await writeFile(actual, stringifyCsv(headers, rows));
+    await writeFile(scanJson, JSON.stringify(scan));
+    const compare = () => run(process.execPath, [path.join(packageRoot, 'regression', 'compare-golden.mjs'),
+      '--golden', golden, '--actual', actual, '--scan-json', scanJson]);
+    const result = await compare();
+    assert.equal(result.code, 0, result.stderr);
+    const report = JSON.parse(result.stdout);
+    assert.equal(report.reportedDevEcoRows, mode === 'upgrade' ? 2 : 0);
+    assert.equal(report.actualDeprecatedRows, mode === 'deprecated' ? 2 : 0);
+    assert.equal(report.actualDistinctDeprecatedApis, mode === 'deprecated' ? 2 : 0);
+    assert.equal(report.actualAdditionalDocumentRules, 0);
+    assert.equal(report.missingRows, 0);
+    if (mode === 'deprecated') {
+      const missingJson = await run(process.execPath, [path.join(packageRoot, 'regression', 'compare-golden.mjs'),
+        '--golden', golden, '--actual', actual]);
+      assert.equal(missingJson.code, 1);
+      assert.match(missingJson.stderr, /requires --scan-json/);
+    }
+    for (const invalid of [[rows[0]], [...rows, rows[0]], [{ ...rows[0], Title: '错误标题' }, rows[1]]]) {
+      await writeFile(actual, stringifyCsv(headers, invalid));
+      const mismatch = await compare();
+      assert.equal(mismatch.code, 1);
+      assert.match(mismatch.stderr, /CSV does not match reported scan JSON/);
+    }
+  });
+}
+
+test('golden comparison strips a native absolute project root and preserves line and column',async()=>{
+  const root=await mkdtemp(path.join(os.tmpdir(),'golden spaces 中文-'));
+  const golden=path.join(root,'golden.csv'),actual=path.join(root,'actual.csv');
+  const row={'Api Definition':'api(): void',Language:'ArkTS','Changed in SDK':'26',Title:'变更','Code Location':'entry/A.ets:12:4','Change Type':'API Behavior Change'};
+  const absolute=path.join(root,'entry/A.ets')+':12:4';
+  await writeFile(golden,stringifyCsv(Object.keys(row),[{...row,'Code Location':process.platform==='win32'?absolute.toUpperCase():absolute}]));
+  await writeFile(actual,stringifyCsv(Object.keys(row),[row]));
+  const result=await run(process.execPath,[path.join(packageRoot,'regression/compare-golden.mjs'),'--golden',golden,'--actual',actual,'--project',root]);
+  assert.equal(result.code,0,result.stderr);
+  const report=JSON.parse(result.stdout);
+  assert.equal(report.missingRows,0);assert.equal(report.extraRows,0);
+});

package/node_modules/@hmos-library-adapter/executer/shared/skills/harmonyos-api-upgrade-adapter/scripts/maintenance/test/fixtures/behavior/local-sources.csv

@@ -0,0 +1,5 @@
+Api Definition,Language,Changed in SDK,Affected Versions,Title,Code Location,Fixed,Change Type,Rule ID,Change Operation,Source Reference
+declare class CommonMethod<T>,ArkTS,7.0.0(26) Beta1,ALL,ArkUI接口新增仅支持Stage模型的约束,entry/src/main/ets/pages/Index.ets:243,Unfixed,API Definition Change,CH2026010615012,API_DEFINITION,26.0.0/beta1-changes-for-all-apps.md:966
+declare const Button: ButtonInterface,ArkTS,7.0.0(26) Beta1,26.0.0(26) - 26.0.0(26),表单类组件触摸热区最小高度变更,entry/src/main/ets/pages/Index.ets:294,Unfixed,UX Visual Layout Change,CH2026031846233,UX_VISUAL,26.0.0/beta1-ux-style-and-effect-changes.md:36
+declare function showToast(options: ShowToastOptions): void,ArkTS,7.0.0(26) Beta1,26.0.0(26) - 26.0.0(26),Dialog、Toast、AlphabetIndexer和文本选择菜单默认开启沉浸式系统材质,entry/src/main/ets/pages/Index.ets:125,Unfixed,UX Visual Layout Change,CH2026032761266,UX_VISUAL,26.0.0/beta1-ux-style-and-effect-changes.md:146
+declare function showToast(options: ShowToastOptions): void,ArkTS,7.0.0(26) Beta1,26.0.0(26) - 26.0.0(26),内置文本的组件文本样式优化,entry/src/main/ets/pages/Index.ets:125,Unfixed,UX Visual Layout Change,CH2026032801249,UX_VISUAL,26.0.0/beta1-ux-style-and-effect-changes.md:87

package/node_modules/@hmos-library-adapter/executer/shared/skills/harmonyos-api-upgrade-adapter/scripts/maintenance/test/references.test.mjs

@@ -0,0 +1,16 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {mkdtemp,writeFile,rm} from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import {referenceDigest} from '../references/references.mjs';
+
+test('reference text hashes are stable across BOM and line endings', async t => {
+  const root = await mkdtemp(path.join(os.tmpdir(), 'adapter-reference-hash-'));
+  t.after(() => rm(root, { recursive: true, force: true }));
+  const lf = path.join(root, 'lf.md');
+  const crlf = path.join(root, 'crlf.md');
+  await writeFile(lf, '标题\n内容\n');
+  await writeFile(crlf, '\ufeff标题\r\n内容\r\n');
+  assert.equal(await referenceDigest(lf), await referenceDigest(crlf));
+});