@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/test/behavior-policy.test.mjs

@@ -0,0 +1,75 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { classifyDeprecatedFindings, loadBehaviorPolicy, validateBehaviorPolicySources } from '../behavior/behavior-policy.mjs';
+import { sha256 } from '../../shared/io/fs-utils.mjs';
+
+const scannerRoot = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+
+test('bundled policy catalog covers 188 reviewed API13+ changes and validates their actual sources', async () => {
+  const catalog = await loadBehaviorPolicy(path.join(scannerRoot, 'data', 'behavior-change-policy.json'));
+  assert.equal(catalog.entryCount, 188);
+  assert.ok(catalog.entries.every(entry => entry.apiLevel >= 13));
+  for (const entry of catalog.entries)
+    assert.equal(entry.policyId, `${entry.sourceAnchor || 'behavior'}-${sha256(entry.sourceReference).slice(0, 8)}`);
+  assert.equal(catalog.entries.filter(entry => entry.documentConclusion === '否').length, 34);
+  const sources = await validateBehaviorPolicySources(catalog, path.resolve(scannerRoot, '..', '..', 'references', 'changelogs'));
+  assert.equal(sources.entryCount, 188);
+  assert.ok(catalog.entries.every(entry => entry.actionType && entry.rationale !== undefined));
+  for (const title of ['notofonts三方件小语种字体升级变更', '内置文本的组件文本样式优化']) {
+    const entry = catalog.entries.find(item => item.title === title);
+    assert.equal(entry.actionType, 'RUNTIME_VALIDATION');
+    assert.equal(entry.detectionMode, 'PROJECT_WIDE');
+  }
+});
+
+test('behavior policy source hashes are stable across LF and CRLF checkouts', async t => {
+  const root = await mkdtemp(path.join(os.tmpdir(), 'behavior-policy-newlines-'));
+  t.after(() => rm(root, { recursive: true, force: true }));
+  const file = path.join(root, 'source.md');
+  const lf = '# Title\n\nBody\n';
+  const document = {
+    entries: [{ policyId: 'policy', sourceReference: 'source.md:1', sourceFileHash: sha256(lf) }],
+    counts: {},
+  };
+  await writeFile(file, lf.replaceAll('\n', '\r\n'));
+  const result = await validateBehaviorPolicySources(document, root);
+  assert.equal(result.status, 'COMPLETE');
+  assert.equal(result.sourceFileCount, 1);
+});
+
+test('behavior policy validation distinguishes changed and missing source files', async t => {
+  const root = await mkdtemp(path.join(os.tmpdir(), 'behavior-policy-errors-'));
+  t.after(() => rm(root, { recursive: true, force: true }));
+  const file = path.join(root, 'source.md');
+  const document = {
+    entries: [{ policyId: 'policy', sourceReference: 'source.md:1', sourceFileHash: sha256('expected\n') }],
+    counts: {},
+  };
+  await writeFile(file, 'changed\r\n');
+  await assert.rejects(validateBehaviorPolicySources(document, root), error => {
+    assert.equal(error.details[0].reason, 'SOURCE_HASH_CHANGED');
+    return true;
+  });
+  await rm(file);
+  await assert.rejects(validateBehaviorPolicySources(document, root), error => {
+    assert.equal(error.details[0].reason, 'SOURCE_NOT_FOUND');
+    return true;
+  });
+});
+
+test('deprecated occurrences retain separate columns, original annotations and stable grouping', () => {
+  const findings = [1, 8].map(Column => ({
+    'Change Type': 'Deprecated API', 'Rule ID': 'sdk-old', 'Code Location': 'entry/A.ets:1',
+    occurrenceId: 'old-' + Column, Column, includedInCsv: true,
+  }));
+  const result = classifyDeprecatedFindings(findings);
+  assert.equal(result.actionGroups.length, 2);
+  assert.deepEqual(result.actionGroups.flatMap(group => group.occurrences.map(item => item.Column)).sort((a,b)=>a-b), [1,8]);
+  assert.ok(result.actionRows.every(row => row['Occurrence Count'] === 1 && row['Action Type'] === 'CODE_REVIEW_REQUIRED'));
+  assert.deepEqual(result.validationGroups, []); assert.deepEqual(result.validationRows, []);
+  assert.deepEqual(result.findings.map(item => item.occurrenceId), ['old-1','old-8']);
+});

package/node_modules/@hmos-library-adapter/executer/shared/skills/harmonyos-api-upgrade-adapter/scripts/scanner/test/build-log.test.mjs

@@ -0,0 +1,69 @@
+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 { parseDeprecatedBuildLog, importDeprecatedBuildLog } from '../deprecated/build-log.mjs';
+import { sha256 } from '../../shared/io/fs-utils.mjs';
+import { compareDeprecated } from '../../maintenance/regression/compare-deprecated.mjs';
+
+const log = `WARN: ArkTS:WARN File: /baseline/entry/A.ets:2:4
+ 'getContext' has been deprecated.
+WARN: ArkTS:WARN File: /baseline/oh_modules/vendor/A.ets:3:5
+ 'create' has been deprecated.
+WARN: ArkTS:WARN File: /baseline/oh_modules/vendor/A.ets:3:5
+ 'create' has been deprecated.
+`;
+
+test('compiler warning parser preserves columns and deduplicates repeated messages', () => {
+  const parsed = parseDeprecatedBuildLog(log);
+  assert.equal(parsed.length, 2);
+  assert.equal(parsed[1].column, 5);
+  assert.equal(parseDeprecatedBuildLog("'create' has been deprecated.")[0].located, false);
+});
+
+test('Windows logs and historical comparisons match case variants while rejecting other roots and tampering',async t=>{
+  const root=await mkdtemp(path.join(os.tmpdir(),'windows-build-log-'));
+  t.after(()=>rm(root,{recursive:true,force:true}));
+  const logPath=path.join(root,'build.log'),evidencePath=path.join(root,'evidence.json'),scanJson=path.join(root,'scan.json');
+  const text="WARN: ArkTS:WARN File: d:\\harmony\\APP\\oh_modules\\vendor\\A.ets:3:5\n 'create' has been deprecated.\n";
+  const project={sourceSnapshot:'source',buildProfileHash:'profile',product:{name:'default'}};
+  const catalog={platform:'win32',snapshot:'sdk',coverage:{targetSdk:'26'},deprecatedEntries:[]};
+  const evidence={schemaVersion:1,projectRoot:'D:\\Harmony\\App',sourceSnapshot:'source',buildProfileHash:'profile',sdkSnapshot:'sdk',
+    targetSdk:'26',product:'default',logHash:sha256(text),nonIncremental:true,status:'PASSED'};
+  await writeFile(logPath,text);await writeFile(evidencePath,JSON.stringify(evidence));
+  const result=await importDeprecatedBuildLog({project,catalog,logPath,evidencePath});
+  assert.equal(result.findings.length,1);
+  await writeFile(path.join(root,'build-profile.json5'),'{"modules":[{"name":"entry","srcPath":"entry"}]}');
+  await writeFile(scanJson,JSON.stringify({sourceSnapshot:'source',buildProfileHash:'profile',deprecationCoverage:{sdkSnapshot:'sdk'},deprecationCatalog:{targetSdk:'26'},findings:[]}));
+  const comparison=await compareDeprecated({project:root,buildLog:logPath,scanJson,buildProjectRoot:'d:/harmony/app',buildEvidence:evidencePath,platform:'win32'});
+  assert.equal(comparison.evidenceStatus,'MATCHED_BUILD_SNAPSHOT');assert.equal(comparison.unmappedCount,0);
+  for(const wrong of ['E:\\Harmony\\App','D:\\Harmony\\Application']) {
+    await writeFile(evidencePath,JSON.stringify({...evidence,projectRoot:wrong}));
+    assert.equal((await importDeprecatedBuildLog({project,catalog,logPath,evidencePath})).findings.length,0);
+  }
+  await writeFile(evidencePath,JSON.stringify({...evidence,sourceSnapshot:'tampered'}));
+  await assert.rejects(importDeprecatedBuildLog({project,catalog,logPath,evidencePath}),{code:'BUILD_EVIDENCE_MISMATCH'});
+});
+
+test('only verified logs import dependencies; absent or mismatched evidence is not trusted', async (t) => {
+  const root = await mkdtemp(path.join(os.tmpdir(), 'deprecated-build-log-'));
+  t.after(() => rm(root, { recursive: true, force: true }));
+  const logPath = path.join(root, 'build.log'), evidencePath = path.join(root, 'build-evidence.json');
+  await writeFile(logPath, log);
+  const project = { sourceSnapshot: 'source', buildProfileHash: 'config', product: { name: 'default' } };
+  const catalog = { snapshot: 'sdk', coverage: { targetSdk: '26.0.0(26) Release' }, deprecatedEntries: [] };
+  const untrusted = await importDeprecatedBuildLog({ project, catalog, logPath });
+  assert.equal(untrusted.findings.length, 0);
+  assert.equal(untrusted.audit.status, 'UNVERIFIED_LOG');
+  const evidence = { schemaVersion: 1, projectRoot: '/baseline', sourceSnapshot: 'source', buildProfileHash: 'config', sdkSnapshot: 'sdk',
+    targetSdk: '26.0.0(26) Release', product: 'default', logHash: sha256(log), nonIncremental: true, status: 'PASSED' };
+  await writeFile(evidencePath, JSON.stringify(evidence));
+  const trusted = await importDeprecatedBuildLog({ project, catalog, logPath, evidencePath });
+  assert.equal(trusted.findings.length, 1);
+  assert.equal(trusted.findings[0]['Source Scope'], 'DEPENDENCY');
+  assert.equal(trusted.findings[0].evidenceStatus, 'COMPILER_ONLY');
+  assert.equal(trusted.findings[0].autoEditAllowed, false);
+  await writeFile(evidencePath, JSON.stringify({ ...evidence, sourceSnapshot: 'old' }));
+  await assert.rejects(importDeprecatedBuildLog({ project, catalog, logPath, evidencePath }), { code: 'BUILD_EVIDENCE_MISMATCH' });
+});

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

@@ -0,0 +1,102 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, readFile, readdir, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  createRunOutputDirectory,
+  execute,
+  resolveScanTargetVersion,
+  runTimestamp,
+  selectScanRules,
+} from '../core/cli.mjs';
+
+test('uses an explicit scan target before the exact toolchain channel', () => {
+  assert.deepEqual(resolveScanTargetVersion('26.0.0(26) Beta1', { sdkVersion: { raw: '26.0.0(26) Beta2' } }),
+    { version: '26.0.0(26) Beta1', source: 'to' });
+  assert.deepEqual(resolveScanTargetVersion(null, { sdkVersion: { raw: '26.0.0(26) Beta2' } }),
+    { version: '26.0.0(26) Beta2', source: 'toolchain' });
+});
+
+test('rejects unsupported batch sizes instead of pretending they are applied', async () => {
+  await assert.rejects(() => execute([
+    'scan', '--mode', 'upgrade', '--project', '/project', '--sdk', '/sdk', '--from', '5.0.0(12)', '--to', '5.0.1(13)',
+    '--batch-size', '500',
+  ]), /supports --batch-size 1000 only/);
+});
+
+test('rejects unsupported scan modes', async () => {
+  await assert.rejects(() => execute([
+    'scan', '--project', '/project', '--sdk', '/sdk', '--from', '5.0.0(12)', '--to', '5.0.1(13)',
+    '--mode', 'behavior-only',
+  ]), { code: 'SCAN_MODE_INVALID' });
+});
+
+test('deprecated mode keeps only deprecated rules for the DevEco backend', () => {
+  const rules = [
+    { ruleId: 'behavior', changeType: 'API Behavior Change', changeOperation: 'API_BEHAVIOR', affectedApis: [{ implementLanguage: 'typescript' }] },
+    { ruleId: 'definition', changeType: 'API Definition Change', changeOperation: 'API_DEFINITION_CHANGED', affectedApis: [{ implementLanguage: 'typescript' }] },
+    { ruleId: 'deprecated-arkts', changeType: 'Deprecated API', changeOperation: 'API_DEPRECATED', affectedApis: [{ implementLanguage: 'typescript' }] },
+    { ruleId: 'deprecated-cpp', changeType: 'Deprecated API', changeOperation: 'API_DEPRECATED', affectedApis: [{ implementLanguage: 'c' }] },
+  ];
+  assert.deepEqual(selectScanRules(rules, 'deprecated').map(rule => rule.ruleId), ['deprecated-cpp']);
+  assert.throws(() => selectScanRules(rules, 'full'), {code:'SCAN_MODE_INVALID'});
+});
+
+test('run timestamps use local YYYYMMDDHHmmss and increment on collision', async () => {
+  const now = new Date(2026, 6, 29, 8, 23, 50);
+  assert.equal(runTimestamp(now), '20260729082350');
+  const root = await mkdtemp(path.join(os.tmpdir(), 'scanner-run-dir-'));
+  const first = await createRunOutputDirectory(root);
+  const second = await createRunOutputDirectory(root);
+  assert.match(first.stamp, /^\d{14}$/);
+  assert.equal(second.stamp, `${first.stamp}-2`);
+  const nested = await readdir(path.join(root, first.stamp));
+  assert.deepEqual(nested, []);
+});
+
+test('scan failures identify the pipeline stage in the error and diagnostics', async t => {
+  const root = await mkdtemp(path.join(os.tmpdir(), 'scanner-stage-'));
+  t.after(() => rm(root, { recursive: true, force: true }));
+  const output = path.join(root, 'output');
+  await mkdir(output, { recursive: true });
+  await assert.rejects(execute([
+    'scan', '--mode', 'upgrade', '--project', path.join(root, 'project'), '--sdk', path.join(root, 'missing-sdk'),
+    '--from', '5.0.0(12)', '--to', '26.0.0(26) Beta1', '--output-dir', output,
+  ]), error => {
+    assert.equal(error.stage, 'DISCOVER_TOOLCHAIN');
+    return true;
+  });
+  const runDirectories = (await readdir(output)).filter(name => /^\d{14}(?:-\d+)?$/.test(name));
+  assert.equal(runDirectories.length, 1);
+  const diagnostics = JSON.parse(await readFile(path.join(output, runDirectories[0], '.internal', 'scanner', 'diagnostics.json'), 'utf8'));
+  assert.equal(diagnostics.error.stage, 'DISCOVER_TOOLCHAIN');
+  const skillRoot = path.resolve(fileURLToPath(new URL('../../../', import.meta.url)));
+  assert.equal(diagnostics.runtime.skillRoot, skillRoot);
+  assert.equal(diagnostics.options.referenceRoot, path.join(skillRoot, 'references', 'changelogs'));
+});
+
+for(const mode of ['upgrade','deprecated']) test(`${mode} CLI reserves a feature batch before backend discovery`,async t=>{
+  const root=await mkdtemp(path.join(os.tmpdir(),'scanner-batch-'));
+  t.after(()=>rm(root,{recursive:true,force:true}));
+  try {
+    await execute(['scan','--project',path.join(root,'project'),'--sdk',path.join(root,'missing-sdk'),
+      '--from','22','--to','26','--mode',mode,'--output-dir',root]);
+    assert.fail('missing SDK must fail');
+  } catch(error) { assert.equal(error.code,'SDK_ROOT_INVALID'); }
+  const folders=(await readdir(root)).filter(name=>/^\d{14}(?:-\d+)?$/.test(name));
+  assert.equal(folders.length,1);
+  const scan=path.join(root,folders[0]);
+  const metadata=JSON.parse(await readFile(path.join(scan,'.internal','scan-batch.json'),'utf8'));
+  assert.equal(metadata.schemaVersion,4);
+  assert.equal(metadata.mode,mode);
+  if(mode==='deprecated') assert.equal(metadata.scanStamp,folders[0]);
+  assert.ok((await readdir(scan)).includes(mode));
+  assert.match(metadata.batchId,/^[a-f0-9]{12}$/);
+  const diagnostics=JSON.parse(await readFile(path.join(scan,'.internal','scanner','diagnostics.json'),'utf8'));
+  assert.equal(diagnostics.error.code,'SDK_ROOT_INVALID');
+  assert.equal(diagnostics.runtime.featureMode,mode);
+  assert.equal(diagnostics.error.artifactPaths[0],path.join(scan,'.internal','scanner','diagnostics.json'));
+  await assert.rejects(readFile(path.join(scan,'diagnostics.json')),{code:'ENOENT'});
+});

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

@@ -0,0 +1,35 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { DEPRECATED_HEADERS, parseCsv, SCANNER_HEADERS, stringifyCsv, UPGRADE_HEADERS } from '../../shared/format/csv.mjs';
+
+test('mode-specific CSV projections preserve duplicate rows, escaping and hyperlinks', () => {
+  assert.deepEqual(UPGRADE_HEADERS, ['Api Definition', 'Language', 'Changed in SDK', 'Affected Versions',
+    'Title', 'Code Location', 'Fixed', 'Change Type', 'Rule ID']);
+  assert.deepEqual(DEPRECATED_HEADERS, ['Api Definition', 'Language', 'Changed in SDK',
+    'Title', 'Code Location', 'Fixed', 'Change Type', 'Replacement API']);
+  for (const headers of [UPGRADE_HEADERS, DEPRECATED_HEADERS]) {
+    const row = Object.fromEntries(headers.map(header => [header, '']));
+    row['Api Definition'] = 'run("a,b"): void\nnext';
+    row.Title = '=HYPERLINK("https://example.test/a","标题,一")';
+    const text = stringifyCsv(headers, [{ ...row, Column: 1 }, { ...row, Column: 8 }]);
+    assert.ok(text.startsWith('\ufeff'));
+    assert.ok(text.endsWith('\r\n'));
+    assert.deepEqual(parseCsv(text), { headers, rows: [row, row] });
+    assert.deepEqual(parseCsv(stringifyCsv(headers, [])), { headers, rows: [] });
+  }
+});
+
+test('round trips BOM, CRLF, hyperlink formulas and scanner metadata', () => {
+  const row = Object.fromEntries(SCANNER_HEADERS.map((header) => [header, '']));
+  row['Api Definition'] = 'run(value: string, count: number): void';
+  row.Language = 'ArkTS';
+  row.Title = '=HYPERLINK("https://example.test/a","标题,一")';
+  row['Code Location'] = 'entry/src/main/ets/A.ets:3';
+  row.Fixed = 'Unfixed';
+  row['Change Type'] = 'API Behavior Change';
+  row['Rule ID'] = 'rule-1';
+  const encoded = stringifyCsv(SCANNER_HEADERS, [row]);
+  assert.ok(encoded.startsWith('\ufeff'));
+  assert.ok(encoded.includes('\r\n'));
+  assert.deepEqual(parseCsv(encoded), { headers: SCANNER_HEADERS, rows: [row] });
+});

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

@@ -0,0 +1,283 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync } from 'node:fs';
+import { mkdir, mkdtemp, writeFile, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { buildSdkCatalog, catalogEntry, indexSdkFile, resolveRuleDeclarations, sdkLocationKey } from '../core/sdk-deprecations.mjs';
+import { compilerPathIdentity, projectModuleForFile, scanArkTsDeprecations } from '../deprecated/arkts-deprecations.mjs';
+import { loadProject } from '../core/project.mjs';
+import { parseVersion } from '../../shared/platform/version.mjs';
+
+const parserPath = process.env.HARMONYOS_TYPESCRIPT || '/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/ets/build-tools/ets-loader/node_modules/typescript/lib/typescript.js';
+const available = existsSync(parserPath);
+
+test('compiler path identity treats Windows parser and filesystem separators as the same file', () => {
+  assert.equal(
+    compilerPathIdentity('D:\\SDK\\api\\@ohos.promptAction.d.ts', 'win32'),
+    compilerPathIdentity('d:/sdk/api/@ohos.promptAction.d.ts', 'win32'),
+  );
+});
+
+test('catalog lookup normalizes Windows separators for SDK declaration locations', () => {
+  const indexedFile = 'D:/SDK/api/@ohos.promptAction.d.ts';
+  const originalFile = { fileName: 'D:\\SDK\\api\\@ohos.promptAction.d.ts' };
+  const cloneFile = { fileName: originalFile.fileName };
+  const original = { getSourceFile: () => originalFile, getStart: () => 42 };
+  const clone = { getSourceFile: () => cloneFile, getStart: () => 42, end: 50 };
+  const entry = { symbolId: 'api-show-toast' };
+  const catalog = {
+    platform: 'win32',
+    ts: { getOriginalNode: () => original },
+    byLocation: new Map([[`${indexedFile}\0${original.getStart()}`, entry]]),
+    byComparableLocation: new Map([[sdkLocationKey(indexedFile, original.getStart(), 'win32'), entry]]),
+  };
+
+  assert.equal(catalogEntry(catalog, clone), entry);
+});
+
+test('maps parser-normalized Windows source paths back to their project module', () => {
+  const module = projectModuleForFile({ modules: [{
+    name: 'module_transition',
+    root: 'D:\\Work\\News\\components\\module_transition',
+  }] }, 'D:/Work/News/components/module_transition/src/main/ets/Utils.ets', 'win32');
+
+  assert.equal(module?.name, 'module_transition');
+});
+
+test('SDK indexing ignores nameless JSDoc tags without losing known tags', () => {
+  const no = () => false;
+  const sourceFile = {
+    fileName: 'sdk.d.ts',
+    text: 'declare function legacy(): void;',
+    name: { getText: () => 'legacy' },
+    end: 32,
+    getStart: () => 0,
+    getText() { return this.text; },
+    getLineAndCharacterOfPosition: () => ({ line: 0, character: 0 }),
+  };
+  const deprecated = {
+    comment: 'since 26',
+    parent: { tags: [{}, { tagName: { text: 'useinstead' }, comment: 'modern' }] },
+  };
+  const ts = {
+    isClassDeclaration: no,
+    isStructDeclaration: no,
+    isAnnotationDeclaration: no,
+    isInterfaceDeclaration: no,
+    isEnumDeclaration: no,
+    isModuleDeclaration: no,
+    isConstructorDeclaration: no,
+    isFunctionDeclaration: node => node === sourceFile,
+    isMethodDeclaration: no,
+    isMethodSignature: no,
+    isCallSignatureDeclaration: no,
+    isGetAccessor: no,
+    isSetAccessor: no,
+    isEnumMember: no,
+    isPropertyDeclaration: no,
+    isPropertySignature: no,
+    isAnnotationPropertyDeclaration: no,
+    isVariableDeclaration: no,
+    isTypeAliasDeclaration: no,
+    getJSDocTags: () => [{}, { tagName: { text: 'throws' }, getText: () => '@throws Error' }],
+    getJSDocDeprecatedTag: () => deprecated,
+    forEachChild: () => {},
+    SyntaxKind: { StaticKeyword: 126 },
+  };
+
+  const result = indexSdkFile(ts, sourceFile, 'openharmony', 'api/sdk.d.ts');
+
+  assert.equal(result.declarations.length, 1);
+  assert.equal(result.declarations[0].replacementApi, 'modern');
+  assert.deepEqual(result.declarations[0].throws, ['@throws Error']);
+});
+
+async function fixture(t, source) {
+  const root = await mkdtemp(path.join(os.tmpdir(), 'deprecated-semantics-'));
+  t.after(() => rm(root, { recursive: true, force: true }));
+  const sdkRoot = path.join(root, 'sdk');
+  const ets = path.join(sdkRoot, 'default/openharmony/ets');
+  const files = {
+    'build-profile.json5': '{app:{products:[{name:"default"}]},modules:[{name:"entry",srcPath:"./entry"},{name:"shared",srcPath:"./shared"}]}',
+    'entry/src/main/module.json5': '{module:{type:"entry"}}',
+    'shared/src/main/module.json5': '{module:{type:"har"}}',
+    'shared/oh-package.json5': '{name:"shared",main:"Index.ets"}',
+    'shared/Index.ets': 'export { getView } from "./View";',
+    'shared/View.ets': 'import { modern } from "@kit.TestKit"; export function getView(): modern.View { return new modern.View(); }',
+    'entry/oh-package.json5': '{dependencies:{shared:"file:../shared"}}',
+    'entry/src/main/ets/A.ets': source,
+    'oh_modules/unused/A.ets': 'oldGlobal(1);',
+  };
+  for (const [f, text] of Object.entries(files)) {
+    await mkdir(path.dirname(path.join(root, f)), { recursive: true });
+    await writeFile(path.join(root, f), text);
+  }
+  await mkdir(path.join(ets, 'api'), { recursive: true });
+  await mkdir(path.join(ets, 'kits'), { recursive: true });
+  await mkdir(path.join(ets, 'component'), { recursive: true });
+  await writeFile(path.join(ets, 'component/global.d.ts'), '/** @deprecated since 18\n * @useinstead modern.View.convert\n */ declare function oldGlobal(value: number): number;');
+  await writeFile(path.join(ets, 'kits/@kit.TestKit.d.ts'), 'export { legacy, modern, Alert, Animator } from "../api/@ohos.test";');
+  await writeFile(path.join(ets, 'api/@ohos.test.d.ts'), `
+export namespace legacy {
+  /** @deprecated since 20\n   * @useinstead modern.View\n   */ export class Format {
+    /** @deprecated since 20\n     * @useinstead modern.View.convert\n     */ format(value: number): number;
+    formatMatcher: string;
+  }
+  export class Decoder {
+    /** @deprecated since 9\n     * @useinstead decodeToString\n     */ decode(value: string): string;
+    decodeToString(value: string): string;
+  }
+}
+export namespace modern { export class View { convert(value: number): number; } }
+/** @deprecated since 26\n * @useinstead modern.View\n */ export class Alert {
+  /** @deprecated since 18\n   * @useinstead modern.View.convert\n   */ static show(value: number): void;
+}
+export class Animator {
+  /** @deprecated since 18\n   * @useinstead modern.View\n   */ static create(value: number): void;
+  static create(value: string): void;
+  /** @deprecated since 30 */ static future(): void;
+}
+`);
+  const toolchain = { sdkRoot, parserPath, sdkVersion: parseVersion('26.0.0(26) Release'), sdkMetadata: { data: { apiVersion: '26', platformVersion: '26.0.0', releaseType: 'Release' } } };
+  const catalog = await buildSdkCatalog(toolchain, parseVersion('26.0.0(26) Release'));
+  const project = await loadProject(root, 'default');
+  return { root, project, catalog, toolchain, ets };
+}
+
+test('SDK identity is namespace and overload exact; replacement never matches substrings', { skip: !available }, async (t) => {
+  const { catalog } = await fixture(t, '');
+  const declarations = resolveRuleDeclarations(catalog, { completePath: '/interface/sdk-js/api/@ohos.test.d.ts', className: 'Format', interfaceName: 'format', interfaceType: 'method', methodDefinition: 'format(value: number): number;' });
+  assert.equal(declarations.length, 1);
+  assert.equal(declarations[0].qualifiedName, 'legacy.Format.format');
+  assert.equal(declarations[0].replacementApi, 'modern.View.convert');
+  assert.equal(catalog.deprecatedEntries.some(e => e.name === 'future'), false);
+});
+
+test('unrelated missing SDK exports warn, but a project use of that export blocks coverage', { skip: !available }, async t => {
+  const { project, catalog, ets } = await fixture(t, 'oldGlobal(1);');
+  const file = path.join(ets, 'api/@ohos.test.d.ts');
+  const { readFile } = await import('node:fs/promises');
+  await writeFile(file, `${await readFile(file, 'utf8')}\nexport { Missing } from './missing-in-sdk';\n`);
+  const updated = await buildSdkCatalog(catalog.toolchain, catalog.targetVersion);
+  const unrelated = await scanArkTsDeprecations({ project, catalog: updated });
+  assert.equal(unrelated.coverage.status, 'COMPLETE');
+  assert.ok(unrelated.resolutionWarnings.some(item => item.module === './missing-in-sdk'
+    && item.reason === 'UNUSED_SDK_IMPORT_NOT_RESOLVED'));
+  await writeFile(project.sourceFiles.find(file => file.endsWith('/A.ets')),
+    'import { Missing } from "@ohos.test"; let value: Missing; oldGlobal(1);');
+  const used = await scanArkTsDeprecations({ project, catalog: updated });
+  assert.equal(used.coverage.status, 'INCOMPLETE');
+  assert.ok(used.unresolved.some(item => item.module === './missing-in-sdk'));
+});
+
+test('deprecated titles link official references and prefer documented change URLs', { skip: !available }, async (t) => {
+  const { project, catalog } = await fixture(t, `import { legacy } from '@kit.TestKit';
+const f = new legacy.Format(); f.format(1);
+oldGlobal(1);`);
+  const moduleUrl = 'https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-test';
+  const plain = await scanArkTsDeprecations({ project, catalog });
+  const formatRow = plain.findings.find(f => f.sdkEvidence.qualifiedName === 'legacy.Format.format');
+  assert.ok(plain.findings.some(f => f.Title.includes(moduleUrl)));
+  assert.ok(plain.findings.some(f => f.Title.includes('API 废弃')));
+  const globalRows = plain.findings.filter(f => f.sdkEvidence.name === 'oldGlobal');
+  assert.ok(globalRows.length > 0 && globalRows.every(f => !String(f.Title).startsWith('=')));
+  const documented = await scanArkTsDeprecations({
+    project, catalog,
+    documentRules: [{ ruleId: 'r1', sdkSymbolIds: [formatRow['API Symbol ID']], sourceReference: 'changes/a.md:5', url: 'https://example.com/deprecated-format' }],
+  });
+  const documentedRow = documented.findings.find(f => f['API Symbol ID'] === formatRow['API Symbol ID']);
+  assert.equal(documentedRow.Title, '=HYPERLINK("https://example.com/deprecated-format","legacy.Format.format：API 废弃")');
+  assert.deepEqual(documentedRow.documentReferences, [{ ruleId: 'r1', sourceReference: 'changes/a.md:5', url: 'https://example.com/deprecated-format' }]);
+});
+
+test('resolves old APIs, constructors, inheritance, aliases, reexports and exact overloads', { skip: !available }, async (t) => {
+  const { project, catalog } = await fixture(t, `import { legacy as l, Alert, Animator } from '@kit.TestKit';
+import { getView } from 'shared';
+const f = new l.Format(); f.format(1);
+const d = new l.Decoder(); d.decode('x');
+class Derived extends l.Decoder {} new Derived().decode('x');
+Alert.show(1); Animator.create(1); Animator.create('x'); Animator.future();
+getView().convert(1); const fake = { oldGlobal(x: number) { return x; } }; fake.oldGlobal(1);
+oldGlobal(
+  oldGlobal(1)); oldGlobal(2); oldGlobal(3);
+`);
+  const result = await scanArkTsDeprecations({ project, catalog });
+  assert.deepEqual(result.unresolved, []);
+  assert.equal(result.findings.length, 11);
+  assert.equal(result.findings.filter(f => f['Deprecated Since'] === 9).length, 2);
+  assert.equal(result.findings.filter(f => f.sdkEvidence.qualifiedName === 'Animator.create').length, 1);
+  assert.equal(result.findings.filter(f => f.sdkEvidence.qualifiedName === 'Alert').length, 1);
+  assert.equal(result.findings.filter(f => f.sdkEvidence.qualifiedName === 'Alert.show').length, 1);
+  const alert = result.findings.filter(f => f.sdkEvidence.qualifiedName.startsWith('Alert'));
+  assert.deepEqual(alert[0].callRange, alert[1].callRange);
+  assert.equal(result.findings.filter(f => f.sdkEvidence.name === 'oldGlobal').length, 4);
+  assert.equal(new Set(result.findings.map(f => f.occurrenceId)).size, 11);
+  assert.ok(result.findings.every(f => f.Column > 0 && f['Source Scope'] === 'PROJECT'));
+  const again = await scanArkTsDeprecations({ project, catalog });
+  assert.deepEqual(again.findings, result.findings);
+});
+
+test('ArkUI component initializer fields resolve to the SDK struct, not a same-name object', { skip: !available }, async (t) => {
+  const fixtureData = await fixture(t, `import Card from '@ohos.card';
+@Builder function render() { Card({ callback: () => {} }); }
+const own = { callback: () => {} }; own.callback();`);
+  await writeFile(path.join(fixtureData.ets, 'api/@ohos.card.d.ets'), `
+declare struct Card {
+ /** @deprecated since 19\n  * @useinstead Card.onResult\n  */ callback: () => void;
+ onResult: () => void;
+ build(): void;
+}
+export default Card;`);
+  const catalog = await buildSdkCatalog(fixtureData.toolchain);
+  const project = await loadProject(fixtureData.root, 'default');
+  const result = await scanArkTsDeprecations({ project, catalog });
+  assert.deepEqual(result.unresolved, []);
+  assert.equal(result.findings.length, 1);
+  assert.equal(result.findings[0].sdkEvidence.qualifiedName, 'Card.callback');
+});
+
+test('missing SDK imports are explicit unresolved evidence', { skip: !available }, async (t) => {
+  const { project, catalog } = await fixture(t, 'import { unknown } from "@kit.MissingKit"; unknown.run();');
+  const result = await scanArkTsDeprecations({ project, catalog });
+  assert.ok(result.unresolved.some(e => e.reason === 'MODULE_NOT_RESOLVED'));
+});
+
+test('typed SDK receivers with missing methods fail resolution rather than silently completing', { skip: !available }, async (t) => {
+  const { project, catalog } = await fixture(t, 'import { modern } from "@kit.TestKit"; const ui = new modern.View(); ui.missing(1); ui.toString();');
+  const result = await scanArkTsDeprecations({ project, catalog });
+  assert.ok(result.unresolved.some(item => item.api === 'ui.missing' && item.reason === 'SDK_MEMBER_NOT_RESOLVED'));
+  assert.equal(result.unresolved.some(item => item.api === 'ui.toString'), false);
+});
+
+test('computed SDK calls still resolve the selected overload', { skip: !available }, async (t) => {
+  const { project, catalog } = await fixture(t, `import { legacy, Animator } from '@kit.TestKit';
+const decoder = new legacy.Decoder(); decoder['decode']('x');
+Animator['create'](1); Animator['create']('x');`);
+  const result = await scanArkTsDeprecations({ project, catalog });
+  assert.deepEqual(result.unresolved, []);
+  assert.equal(result.findings.length, 2);
+  assert.deepEqual(result.findings.map(item => item.sdkEvidence.qualifiedName), ['legacy.Decoder.decode', 'Animator.create']);
+});
+
+test('case-insensitive imports use the discovered source spelling', { skip: !available }, async (t) => {
+  const f = await fixture(t, 'import { run } from "./utils"; run();');
+  await mkdir(path.join(f.root, 'entry/src/main/ets/utils'));
+  await writeFile(path.join(f.root, 'entry/src/main/ets/utils/index.ets'), 'export function run() { oldGlobal(1); }');
+  const project = await loadProject(f.root, 'default');
+  const result = await scanArkTsDeprecations({ project, catalog: f.catalog });
+  assert.equal(result.findings.length, 1);
+  assert.equal(result.findings[0]['Code Location'], 'entry/src/main/ets/utils/index.ets:1');
+});
+
+test('a newer compile SDK keeps its real snapshot and filters deprecations by requested target', { skip: !available }, async (t) => {
+  const { toolchain } = await fixture(t, '');
+  const full=await buildSdkCatalog(toolchain,parseVersion('26'));
+  const older=await buildSdkCatalog(toolchain,parseVersion('20'));
+  assert.equal(older.snapshot,full.snapshot);
+  assert.equal(older.coverage.compileSdk,'26.0.0(26) Release');
+  assert.equal(older.coverage.targetSdk,'6.0.0(20) Release');
+  assert.ok(older.deprecatedEntries.every(entry=>entry.deprecatedSince<=20));
+  assert.ok(older.declarations.every(entry=>entry.file.startsWith(older.toolchain.sdkRoot)));
+  await assert.rejects(buildSdkCatalog({...toolchain,sdkVersion:parseVersion('19')},parseVersion('20')),{code:'SDK_TARGET_NOT_COVERED'});
+});