@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/scan-scope.test.mjs

@@ -0,0 +1,110 @@
+import { runScanInBatch } from './helpers/scan-batch.mjs';
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { loadProject } from '../core/project.mjs';
+import { cleanupScanDirectory } from '../core/scan-runner.mjs';
+import { serializeError } from '../../shared/platform/errors.mjs';
+
+async function setup(backend, directories) {
+  const root=await mkdtemp(path.join(os.tmpdir(),'backend-scope-'));
+  await writeFile(path.join(root,'build-profile.json5'),JSON.stringify({app:{products:[{name:'default'}]},
+    modules:['entry','library'].map(name=>({name,srcPath:name}))}));
+  for(const name of ['entry','library']) {
+    await mkdir(path.join(root,name,'src/main/ets/keep'),{recursive:true});
+    await writeFile(path.join(root,name,'src/main/module.json5'),JSON.stringify({module:{type:name==='library'?'har':'entry'}}));
+    await writeFile(path.join(root,name,'src/main/ets/keep/A.ts'),'api(1);');
+    await writeFile(path.join(root,name,'src/main/ets/Outside.ts'),'api(1);');
+  }
+  const project=await loadProject(root,'default',directories?['library/src/main/ets/keep']:[],['library'],'har');
+  const fake=path.join(root,'scanner.mjs'), captured=path.join(root,'captured.jsonl');
+  await writeFile(fake,`
+import {mkdir,writeFile,readFile,appendFile} from 'node:fs/promises';
+import path from 'node:path';
+const args=process.argv.slice(2),get=flag=>args[args.indexOf(flag)+1];
+await appendFile(${JSON.stringify(captured)},JSON.stringify(args)+'\\n');
+const backend=${JSON.stringify(backend)},files=args.includes('--scanFilePaths')?get('--scanFilePaths'):
+ args.includes('--arkTsFiles')?get('--arkTsFiles'):null;
+if(files && Buffer.byteLength(files)>16000) throw new Error('file arguments exceed safe command-line budget');
+if(${directories} && !files) throw new Error('directory selection requires a file-level backend call');
+if(files && args.includes('--modulePaths')) throw new Error('module paths override precise file selection');
+if(files && files.split(',').some(file=>path.relative(${JSON.stringify(root)},file).split(path.sep)[0]==='entry')) throw new Error('entry entered the scan');
+if(args.includes('--modulePaths') && get('--modulePaths').split(',').some(file=>path.basename(file)!=='library')) throw new Error('unexpected module');
+const out=get(backend==='index'?'--outPath':'--outputPath');
+const changes=JSON.parse(await readFile(get(backend==='index'?'--apiModifiedPath':'--apiModifiedPath'),'utf8'));
+if(backend==='index') {
+ const config=JSON.parse(await readFile(get('--configPath'),'utf8'));
+ if(!Array.isArray(config.projectPath)||config.projectPath.some(file=>path.basename(file)!=='library'))throw new Error('wrong index module context');
+}
+await mkdir(out,{recursive:true});
+const location='library/src/main/ets/keep/A.ts:1';
+if(backend==='index') await writeFile(path.join(out,'report.csv'),'Api Name,Api Type,Api File Path,Api Prefix,Api Params,API Args,Invoke Method,Invoke Location,Api Key,Invoke Instance,ChangeId,MethodDefinition\\n'+
+ 'api,method,a.d.ts,A,,,api,'+location+',key,,"'+changes[0].interfaceChanges.id+'","api(): void"\\n');
+else await writeFile(path.join(out,'report.csv'),'Api Definition,Language,Changed in SDK,Affected Versions,Title,Code Location,Fixed,Change Type,ChangeId\\n'+
+ 'api(): void,ArkTS,6.1.0(23),ALL,scope,'+location+',Unfixed,API Behavior Change,'+changes[0].interfaceChanges.id+'\\n');
+`);
+  const api={implementLanguage:'typeScript',completePath:'/sdk/a.d.ts',className:'A',interfaceType:'method',interfaceName:'api',methodDefinition:'api(): void'};
+  const rule={provider:'DEVECO',ruleId:'scope-rule',changedInSdk:'6.1.0(23)',affectedVersions:'ALL',changeType:'API Behavior Change',
+    changeOperation:'API_BEHAVIOR',sourceReference:'a.md:1',title:'scope',url:'',rawEntry:{id:'scope-rule',affectedApis:[api],interfaceChanges:{id:'scope-id'}}};
+  return {root,project,captured,rule,toolchain:{apiChangeScan:fake,apiChangeBackend:backend,analyzerRoot:root,sdkRoot:'/sdk',
+    sdkFamilies:{openharmony:'/sdk/ohos',hms:'/sdk/hms'},fileScanSupported:true}};
+}
+
+const range={start:{platformVersion:'6.0.2',apiLevel:22,channel:'release',channelNumber:0},
+  end:{platformVersion:'26.0.0',apiLevel:26,channel:'release',channelNumber:0}};
+
+test('an index without file filtering scans only selected whole modules and rejects narrow directories',async()=>{
+  const f=await setup('index',false);f.toolchain.fileScanSupported=false;
+  await runScanInBatch('upgrade', {...f,rules:[f.rule],range,mode:'upgrade',outputDirectory:f.root});
+  const commands=(await readFile(f.captured,'utf8')).trim().split('\n').map(JSON.parse);
+  assert.equal(commands.length,1);assert.ok(!commands[0].includes('--scanFilePaths'));
+  const narrow=await setup('index',true);narrow.toolchain.fileScanSupported=false;
+  await assert.rejects(runScanInBatch('upgrade', {...narrow,rules:[narrow.rule],range,outputDirectory:narrow.root}),{code:'SCAN_SCOPE_UNSUPPORTED'});
+  f.project.sourceScope.scanDirs=[f.project.selectedModules[0].root];
+  await runScanInBatch('upgrade', {...f,rules:[f.rule],range,mode:'upgrade',outputDirectory:f.root});
+});
+
+test('module and directory selections reach both DevEco backends without scanning entry',async()=>{
+  for(const backend of ['integrated','index']) for(const directories of [false,true]) {
+    const f=await setup(backend,directories);
+    const result=await runScanInBatch('upgrade', {...f,rules:[f.rule],range,mode:'upgrade',outputDirectory:f.root});
+    const commands=(await readFile(f.captured,'utf8')).trim().split('\n').map(JSON.parse);
+    assert.equal(commands.length,1);assert.equal(result.findings.length,1);
+    const expected=backend==='index'?'--scanFilePaths':directories?'--arkTsFiles':'--modulePaths';
+    assert.ok(commands[0].includes(expected));
+    assert.equal(result.findings[0]['Code Location'],'library/src/main/ets/keep/A.ts:1');
+  }
+});
+
+test('precise file scopes are batched and unsupported file backends never widen the scope',async()=>{
+  const f=await setup('index',true), module=f.project.selectedModules[0];
+  f.project.sourceFiles.push(...Array.from({length:500},(_,i)=>path.join(module.root,'src/main/ets/keep',`VeryLongFileName${'x'.repeat(60)}${i}.ts`)));
+  await runScanInBatch('upgrade', {...f,rules:[f.rule],range,mode:'upgrade',outputDirectory:f.root});
+  const commands=(await readFile(f.captured,'utf8')).trim().split('\n').map(JSON.parse);
+  assert.ok(commands.length>1);
+  for(const args of commands)assert.ok(Buffer.byteLength(args[args.indexOf('--scanFilePaths')+1])<=16000);
+  const unsupported=await setup('integrated',true);unsupported.toolchain.fileScanSupported=false;
+  await assert.rejects(runScanInBatch('upgrade', {...unsupported,rules:[unsupported.rule],range,outputDirectory:unsupported.root}),{code:'SCAN_SCOPE_UNSUPPORTED'});
+});
+
+test('temporary cleanup retries locks and never replaces a scan result or its original error',async()=>{
+  let calls=0;
+  assert.equal(await cleanupScanDirectory('temporary',async()=>{
+    if(++calls<3)throw Object.assign(new Error('busy'),{code:'EBUSY'});
+  }),null);
+  assert.equal(calls,3);
+  const f=await setup('integrated',false);
+  const removeTemporary=async()=>{throw Object.assign(new Error('locked'),{code:'EPERM'});};
+  const result=await runScanInBatch('upgrade', {...f,rules:[f.rule],range,mode:'upgrade',outputDirectory:f.root,removeTemporary});
+  assert.equal(result.findings.length,1);
+  assert.equal(result.diagnostics.cleanupWarning.code,'SCAN_TEMP_CLEANUP_FAILED');
+  assert.ok(result.diagnostics.warnings.some(value=>value.includes('locked')));
+  await assert.rejects(runScanInBatch('upgrade', {...f,rules:[f.rule],range,outputDirectory:f.root,removeTemporary,
+    verifyInputs:async()=>{throw Object.assign(new Error('original scan error'),{code:'SOURCE_CHANGED'});}}),error=>{
+    assert.equal(error.code,'SOURCE_CHANGED');
+    assert.equal(serializeError(error).cleanupWarning.errorCode,'EPERM');
+    return true;
+  });
+});

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

@@ -0,0 +1,64 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import os from 'node:os';
+import { mkdtemp, mkdir, realpath, writeFile, symlink } from 'node:fs/promises';
+import { gzipSync } from 'node:zlib';
+import ts from 'typescript';
+import { createArkTsProgram } from '../deprecated/arkts-deprecations.mjs';
+
+async function fixture() {
+  const root = await realpath(await mkdtemp(path.join(os.tmpdir(), 'source-inputs-')));
+  const entry = path.join(root, 'application source'), file = path.join(entry, 'Main.ts');
+  await mkdir(entry);
+  const project = { root, sourceFiles: [file], modules: [] };
+  const catalog = { ts, sourceFiles: new Map(), toolchain: { sdkRoot: root }, etsOptions: {} };
+  return { root, entry, file, project, catalog };
+}
+
+test('binary file dependencies never become TS sources or binary text inputs', async () => {
+  const f = await fixture(), extensions = ['.har', '.hap', '.hsp', '.app', '.abc', '.so', '.a', '.o', '.dll', '.exe', '.bin', ''];
+  const dependencies = {}, imports = [];
+  for (const [index, extension] of extensions.entries()) {
+    const name = `binary${index}`, file = path.join(f.root, `artifact${extension}`);
+    await writeFile(file, gzipSync(Buffer.from([0, 255, 254, index])));
+    dependencies[name] = `file:${path.relative(f.entry, file).split(path.sep).join('/')}`;
+    imports.push(`import { value as v${index} } from '${name}';`);
+  }
+  await writeFile(path.join(f.entry, 'oh-package.json5'), JSON.stringify({ dependencies }));
+  await writeFile(f.file, imports.join('\n'));
+  const context = createArkTsProgram(f.project, f.catalog, { compilerOptions: { noLib: true } });
+  assert.deepEqual(context.program.getSourceFiles().map(source => path.normalize(source.fileName)), [path.normalize(f.file)]);
+  assert.equal(context.unresolvedImports.length, extensions.length);
+
+});
+
+test('package main binaries are excluded while existing text declarations remain usable', async () => {
+  const f = await fixture();
+  for (const [name, types] of [['opaque', false], ['typed', true]]) {
+    const root = path.join(f.entry, 'oh_modules', name);
+    await mkdir(root, { recursive: true });
+    await writeFile(path.join(root, 'oh-package.json5'), JSON.stringify({ main: 'payload.hap', ...(types ? { types: 'Index.d.ts' } : {}) }));
+    await writeFile(path.join(root, 'payload.hap'), gzipSync(Buffer.from('not source')));
+    if (types) await writeFile(path.join(root, 'Index.d.ts'), 'export declare const value: number;');
+  }
+  await writeFile(f.file, "import { value } from 'typed'; import { missing } from 'opaque'; const n: number = value;");
+  const context = createArkTsProgram(f.project, f.catalog, { compilerOptions: { noLib: true } });
+  assert.equal(context.program.getSourceFiles().length, 2);
+  assert.ok(context.program.getSourceFiles().every(source => source.fileName.endsWith('.ts')));
+  assert.deepEqual(context.unresolvedImports.map(item => item.module), ['opaque']);
+});
+
+test('binary roots, overlays and directory aliases cannot bypass the source whitelist', async () => {
+  const f = await fixture(), binary = path.join(f.root, 'payload.har'), alias = path.join(f.root, 'source alias');
+  await writeFile(binary, gzipSync(Buffer.from('archive')));
+  await writeFile(path.join(f.entry, 'payload.har'), gzipSync(Buffer.from('archive')));
+  await writeFile(f.file, 'export const value = 1;');
+  await symlink(f.entry, alias, process.platform === 'win32' ? 'junction' : 'dir');
+  f.project.sourceFiles.push(binary);
+  const context = createArkTsProgram(f.project, f.catalog, { overlays: new Map([[binary, 'pretend source']]), compilerOptions: { noLib: true } });
+  assert.equal(context.program.getSourceFile(binary), undefined);
+  assert.equal(context.resolveModule(path.join(alias, 'payload.har'), f.file), null);
+  assert.equal(context.resolveModule(path.join(alias, 'Main.ts'), f.file), f.file);
+  assert.equal(context.program.getSourceFiles().length, 1);
+});

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

@@ -0,0 +1,164 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdir, mkdtemp, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { rm } from 'node:fs/promises';
+import { compileRules } from '../core/rules.mjs';
+import { selectScanRules, createRunOutputDirectory } from '../core/cli.mjs';
+import { assertUpgradeRange } from '../../shared/platform/version.mjs';
+import { upgradeRuleCoverage } from '../behavior/upgrade-coverage.mjs';
+import { normalizeFinding } from '../core/scan-runner.mjs';
+
+test('upgrade only uses plugin rules, keeps no-adaptation hits and never parses additional API diff or deprecated guidance', async () => {
+  const root=await mkdtemp(path.join(os.tmpdir(),'scanner-upgrade-')),resource=path.join(root,'resources'),refs=path.join(root,'references');
+  await mkdir(resource);await mkdir(refs);await mkdir(path.join(refs,'API变更清单'));
+  await writeFile(path.join(refs,'guide.md'),'---\nsource: https://example.test/change\n---\n\n## 测试行为\n\n**适配指导**\n\n无需适配。\n');
+  await writeFile(path.join(refs,'API变更清单','bad.md'),'| 不支持的操作 | 无法解析 | 无法解析 | missing.d.ts |\n');
+  const entry={affectedApis:[{implementLanguage:'typescript',methodDefinition:'api(): void',className:'global',completePath:'api',interfaceType:'method',interfaceName:'api'}],
+    interfaceChanges:{id:'1',changeTitle:'测试行为',changeType:'接口行为变更',apiEffectiveVersion:'NOT_ISOLATED',sdkVersion:'5.0.2(14) Release',apiVersion:'14'}};
+  await writeFile(path.join(resource,'HarmonyOS_5.0.2(14)_Release.json'),JSON.stringify([entry,{...entry,interfaceChanges:{...entry.interfaceChanges,id:'2',changeTitle:'没有文档的废弃项',changeType:'接口废弃变更'}}]));
+  const result=await compileRules({toolchain:{apiChangeResourceRoot:resource},referenceRoot:refs,range:assertUpgradeRange(13,14),mode:'upgrade'});
+  assert.equal(result.rules.length,1);assert.equal(result.rules[0].provider,'DEVECO');
+  assert.equal(result.rules[0].reportDisposition,'REQUIRES_REVIEW');assert.equal(result.rules[0].filterReason,null);
+  assert.deepEqual(selectScanRules([...result.rules,{provider:'UNSUPPORTED',changeType:'API Definition Change'},{provider:'DEVECO',changeType:'Deprecated API'}],'upgrade'),result.rules);
+});
+
+test('official rule gaps stay incomplete; available, excluded, baseline and empty versions remain distinct', () => {
+  const policies=[{apiLevel:14,changedInSdk:'5.0.2(14)',title:'缺规则',sourceReference:'missing.md:1'},
+    {apiLevel:15,changedInSdk:'5.0.3(15)',title:'有规则',sourceReference:'hit.md:1'},
+    {apiLevel:15,changedInSdk:'5.0.3(15)',title:'无 API',sourceReference:'global.md:1'}];
+  const coverage=upgradeRuleCoverage({policies,rules:[{provider:'DEVECO',sourceReference:'hit.md:1',ruleId:'r'}],
+    excluded:[{sourceReference:'global.md:1',reason:'NO_AFFECTED_APIS'}],range:assertUpgradeRange(13,26)});
+  assert.equal(coverage.status,'INCOMPLETE');assert.equal(coverage.missingRuleCount,1);
+  assert.equal(coverage.entries[1].status,'RULE_AVAILABLE');assert.equal(coverage.entries[2].status,'NOT_SCANNABLE_NO_AFFECTED_APIS');
+  assert.equal(coverage.versions[0].status,'START_BASELINE_EXCLUDED');
+  assert.equal(coverage.versions.find(v=>v.apiLevel===16).status,'NO_OFFICIAL_CHANGES');
+  assert.ok(!coverage.versions.some(v=>v.apiLevel===25));
+});
+
+test('API12 baselines need no deleted source and from=12 still includes API13 changes', async t => {
+  const root = await mkdtemp(path.join(os.tmpdir(), 'scanner-api13-中文 '));
+  t.after(() => rm(root, { recursive: true, force: true }));
+  const resource = path.join(root, 'resources'), refs = path.join(root, 'changelogs');
+  await mkdir(resource); await mkdir(path.join(refs, '5.0.1(13)'), { recursive: true });
+  await writeFile(path.join(refs, '5.0.1(13)', 'release-os-api-behavior-changes.md'),
+    '## API13变更\n**适配指导**\n检查真实调用。\n');
+  const entry = (id, version, title) => ({
+    affectedApis: [{ implementLanguage: 'typescript', interfaceType: 'method', interfaceName: 'api' }],
+    interfaceChanges: { id, changeTitle: title, changeType: '接口行为变更',
+      apiEffectiveVersion: 'NOT_ISOLATED', sdkVersion: version },
+  });
+  await writeFile(path.join(resource, 'HarmonyOS_5.0.0(12)_Release.json'),
+    JSON.stringify([entry('baseline', '5.0.0(12) Release', '已删除的API12变更')]));
+  await writeFile(path.join(resource, 'HarmonyOS_5.0.1(13)_Release.json'),
+    JSON.stringify([entry('api13', '5.0.1(13) Release', 'API13变更')]));
+  for (const from of [12, '5.0.0(12) Beta3']) {
+    const range = assertUpgradeRange(from, 13);
+    const result = await compileRules({ toolchain: { apiChangeResourceRoot: resource }, referenceRoot: refs, range, mode: 'upgrade' });
+    assert.equal(result.coverage.status, 'COMPLETE');
+    assert.deepEqual(result.rules.map(rule => rule.ruleId), ['api13']);
+    const baselineCount = typeof from === 'number' ? 0 : 1;
+    assert.equal(result.coverage.behaviorBaseline.excludedRuleCount, baselineCount);
+    const coverage = upgradeRuleCoverage({ policies: [{ apiLevel: 13, changedInSdk: '5.0.1(13) Release',
+      title: 'API13变更', sourceReference: result.rules[0].sourceReference }], rules: result.rules, range });
+    assert.equal(coverage.entries[0].status, 'RULE_AVAILABLE');
+  }
+});
+
+test('concurrent timestamp output allocation never shares a directory',async()=>{
+  const root=await mkdtemp(path.join(os.tmpdir(),'upgrade-output-'));
+  const results=await Promise.all([createRunOutputDirectory(root),createRunOutputDirectory(root)]);
+  assert.notEqual(results[0].directory,results[1].directory);
+});
+
+test('upgrade preserves plugin columns to distinguish same-line occurrences',()=>{
+  const rule={ruleId:'r',title:'调用变更',changedInSdk:'5.0.2(14)',url:'https://example.test/change',changeType:'API Behavior Change',sourceReference:'doc.md:1'};
+  const findings=[1,12].map(Column=>normalizeFinding({'Api Definition':'api()','Code Location':'entry/A.ets:1',Language:'ArkTS',Column},rule,null,'upgrade'));
+  assert.deepEqual(findings.map(finding=>finding.Column),[1,12]);
+});
+
+test('official entry links resolve by identity and unique source; supplied links survive normalization', async () => {
+  const root=await mkdtemp(path.join(os.tmpdir(),'scanner-links-')),resource=path.join(root,'resources'),refs=path.join(root,'references');
+  await mkdir(resource);await mkdir(path.join(refs,'5.0.2(14)'),{recursive:true});
+  const guide=path.join(refs,'5.0.2(14)/guide.md'), overview=path.join(refs,'5.0.2(14)/overview.md');
+  await writeFile(guide,'---\nsource: https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/test\n---\n## 文档标题\n**适配指导**\n需核对调用。\n');
+  const entry={affectedApis:[{implementLanguage:'typescript',methodDefinition:'api(): void',interfaceType:'method',interfaceName:'api'}],
+    interfaceChanges:{id:'CH123',changeTitle:'文档标题',changeType:'接口行为变更',apiEffectiveVersion:'NOT_ISOLATED',sdkVersion:'5.0.2(14) Release',apiVersion:'14'}};
+  await writeFile(path.join(resource,'HarmonyOS_5.0.2(14)_Release.json'),JSON.stringify([entry]));
+  const load=async()=> (await compileRules({toolchain:{apiChangeResourceRoot:resource},referenceRoot:refs,range:assertUpgradeRange(13,14),mode:'upgrade'})).rules[0];
+  await writeFile(overview,'| [另一个标题](https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/test#ch123) |\n');
+  let rule=await load();assert.equal(rule.url,'https://developer.huawei.com/consumer/cn/doc/doccenter-release-notes/test#ch123');
+  assert.equal(rule.documentLink.source,'OFFICIAL_OVERVIEW');
+  const original='https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/test/#scan-fake';
+  const finding=normalizeFinding({Title:`=HYPERLINK("${original}","原始标题")`,'Code Location':'entry/A.ts:1'},rule,null,'upgrade');
+  assert.equal(finding.Title,`=HYPERLINK("${rule.url}","文档标题")`);assert.equal(finding.documentLink.rejectedReason,'SYNTHETIC_SCAN_ANCHOR');
+  entry.interfaceChanges.url='test#ch123';await writeFile(path.join(resource,'HarmonyOS_5.0.2(14)_Release.json'),JSON.stringify([entry]));
+  assert.equal((await load()).documentLink.source,'DEVECO_RULE');delete entry.interfaceChanges.url;
+  await writeFile(path.join(resource,'HarmonyOS_5.0.2(14)_Release.json'),JSON.stringify([entry]));
+  await writeFile(overview,'| [文档标题](https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/test#one) | [文档标题](https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/test#two) |\n');
+  rule=await load();assert.equal(rule.url,'');assert.equal(rule.documentLink.reason,'AMBIGUOUS_DOCUMENT_LINK');
+});
+
+test('flattened documents resolve plugin aliases and official anchors from the sidecar without overview files', async () => {
+  const root=await mkdtemp(path.join(os.tmpdir(),'scanner-flat-中文 ')),resource=path.join(root,'resources'),refs=path.join(root,'changelogs');
+  await mkdir(resource);await mkdir(path.join(refs,'5.0.2(14)'),{recursive:true});
+  const file=path.posix.join('5.0.2(14)','Beta1-正文.md');
+  const page='https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/test';
+  await writeFile(path.join(refs,file),`---\nsource: ${page}\n---\n## 文档标题\n**适配指导**\n需核对调用。\n`);
+  await writeFile(path.join(root,'changelogs-index.json'),JSON.stringify({schemaVersion:1,
+    documents:[{path:file}],
+    overview:[{version:'5.0.2(14)',row:`| [文档标题](${page}#ch123) | phone | 全部生效 |`},
+      {version:'26.0.0',row:`| [文档标题](${page}#other-version) |`}]}));
+  const entry={affectedApis:[{implementLanguage:'typescript',methodDefinition:'api(): void',interfaceType:'method',interfaceName:'api'}],
+    interfaceChanges:{id:'CH123',changeTitle:'插件中的别名',changeType:'接口行为变更',apiEffectiveVersion:'NOT_ISOLATED',sdkVersion:'5.0.2(14) Release',apiVersion:'14'}};
+  await writeFile(path.join(resource,'HarmonyOS_5.0.2(14)_Release.json'),JSON.stringify([entry]));
+  const result=await compileRules({toolchain:{apiChangeResourceRoot:resource},referenceRoot:refs,range:assertUpgradeRange(13,14),mode:'upgrade'});
+  assert.equal(result.rules.length,1);
+  assert.equal(result.rules[0].sourceReference,`${file}:4`);
+  assert.equal(result.rules[0].url,'https://developer.huawei.com/consumer/cn/doc/doccenter-release-notes/test#ch123');
+  assert.equal(result.rules[0].documentLink.source,'OFFICIAL_OVERVIEW');
+});
+
+test('fallback plugin rule identities use the current source path when the plugin supplies no change id', async () => {
+  const root=await mkdtemp(path.join(os.tmpdir(),'scanner-flat-identity-')),resource=path.join(root,'resources');
+  const before=path.join(root,'before'),after=path.join(root,'after');
+  await mkdir(resource);
+  const oldPath=path.posix.join('5.0.2(14)','OS平台能力','正文.md'),newPath=path.posix.join('5.0.2(14)','正文.md');
+  const text='---\nsource: https://example.test/change\n---\n## 测试行为\n**适配指导**\n需核对调用。\n';
+  for(const [refs,file]of [[before,oldPath],[after,newPath]]) {
+    await mkdir(path.dirname(path.join(refs,file)),{recursive:true});await writeFile(path.join(refs,file),text);
+  }
+  await writeFile(path.join(root,'after-index.json'),JSON.stringify({schemaVersion:1,
+    documents:[{path:newPath}],overview:[]}));
+  const entry={affectedApis:[{implementLanguage:'typescript',methodDefinition:'api(): void',interfaceType:'method',interfaceName:'api'}],
+    interfaceChanges:{changeTitle:'测试行为',changeType:'接口行为变更',apiEffectiveVersion:'NOT_ISOLATED',sdkVersion:'5.0.2(14) Release',apiVersion:'14'}};
+  await writeFile(path.join(resource,'HarmonyOS_5.0.2(14)_Release.json'),JSON.stringify([entry]));
+  const load=referenceRoot=>compileRules({toolchain:{apiChangeResourceRoot:resource},referenceRoot,range:assertUpgradeRange(13,14),mode:'upgrade'});
+  const original=(await load(before)).rules[0],moved=(await load(after)).rules[0];
+  assert.notEqual(moved.ruleId,original.ruleId);assert.equal(moved.sourceReference,`${newPath}:4`);
+  assert.equal((await load(after)).rules[0].ruleId,moved.ruleId);
+});
+
+test('each mode loads only its rule types before resolving unrelated document headings', async t => {
+  const root=await mkdtemp(path.join(os.tmpdir(),'scanner-rule-modes-'));
+  t.after(()=>rm(root,{recursive:true,force:true}));
+  const resource=path.join(root,'resources');await mkdir(resource);
+  const types=['接口行为变更','视觉布局变更','UX交互行为变更','接口定义变更','接口废弃变更'];
+  const entries=types.map((changeType,i)=>({affectedApis:[{implementLanguage:i===4?'c':'typescript',
+    methodDefinition:'api(): void',interfaceType:'method',interfaceName:'api'}],
+    interfaceChanges:{id:String(i),changeTitle:`标题${i}`,changeType,apiEffectiveVersion:'NOT_ISOLATED',
+      sdkVersion:'26.0.0(26) Release',apiVersion:'26'}}));
+  await writeFile(path.join(resource,'HarmonyOS_26.0.0(26)_Release.json'),JSON.stringify(entries));
+  for(const mode of ['upgrade','deprecated']) {
+    const referenceRoot=path.join(root,mode);await mkdir(referenceRoot);
+    await writeFile(path.join(referenceRoot,'guide.md'),types.map((_,i)=>i===4?mode==='deprecated':mode==='upgrade')
+      .flatMap((selected,i)=>selected?[`## 标题${i}`,'**适配指导**','需核对调用。']:[]).join('\n'));
+    const result=await compileRules({toolchain:{apiChangeResourceRoot:resource},referenceRoot,range:assertUpgradeRange(24,26),mode});
+    assert.equal(result.rules.length,mode==='upgrade'?4:1);
+    assert.ok(result.rules.every(rule=>mode==='upgrade'?rule.changeType!=='Deprecated API':rule.changeType==='Deprecated API'));
+    assert.equal(result.coverage.errorCount,0);
+    assert.ok(!Object.hasOwn(result.coverage,'apiDiffRuleCount'));assert.ok(!Object.hasOwn(result.coverage,'operations'));
+    if(mode==='deprecated')assert.equal(selectScanRules(result.rules,mode).length,1);
+  }
+});

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

@@ -0,0 +1,66 @@
+export function parseArgs(argv) {
+  const result = { _: [] };
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith('--')) {
+      result._.push(token);
+      continue;
+    }
+    const separator = token.indexOf('=');
+    const key = separator === -1 ? token.slice(2) : token.slice(2, separator);
+    const value = separator === -1 ? argv[index + 1] : token.slice(separator + 1);
+    if (separator === -1 && (value === undefined || value.startsWith('--'))) {
+      addArg(result, key, true);
+      continue;
+    }
+    addArg(result, key, value);
+    if (separator === -1) index += 1;
+  }
+  return result;
+}
+
+function addArg(result, key, value) {
+  if (result[key] === undefined) {
+    result[key] = value;
+  } else if (Array.isArray(result[key])) {
+    result[key].push(value);
+  } else {
+    result[key] = [result[key], value];
+  }
+}
+
+export function requireString(args, name) {
+  const value = args[name];
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`Missing required argument --${name}`);
+  }
+  return value;
+}
+
+export function stringList(value) {
+  if (value === undefined) return [];
+  return (Array.isArray(value) ? value : [value]).flatMap((item) => String(item).split(','))
+    .map((item) => item.trim()).filter(Boolean);
+}
+
+export function integerArg(value, fallback, name) {
+  if (value === undefined) return fallback;
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+    throw new Error(`--${name} must be a positive integer`);
+  }
+  return parsed;
+}
+
+export function booleanArg(value, fallback = false) {
+  if (value === undefined) {
+    return fallback;
+  }
+  if (value === true || value === 'true' || value === '1') {
+    return true;
+  }
+  if (value === false || value === 'false' || value === '0') {
+    return false;
+  }
+  throw new Error(`Expected boolean value, received ${String(value)}`);
+}

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

@@ -0,0 +1,85 @@
+export const BASE_HEADERS = [
+  'Api Definition', 'Language', 'Changed in SDK', 'Affected Versions',
+  'Title', 'Code Location', 'Fixed', 'Change Type',
+];
+
+// Full internal identity fields; independent of the exported CSV projection.
+export const SCANNER_HEADERS = [
+  ...BASE_HEADERS, 'Rule ID', 'Change Operation', 'Source Reference',
+  'Replacement API', 'Replacement Source',
+  'API Symbol ID', 'Column', 'Deprecated Since', 'Detection Source', 'Source Scope',
+];
+
+export const UPGRADE_HEADERS = [...BASE_HEADERS, 'Rule ID'];
+export const DEPRECATED_HEADERS = [
+  ...BASE_HEADERS.filter(header => header !== 'Affected Versions'), 'Replacement API',
+];
+
+export function parseCsv(text) {
+  const source = text.replace(/^\ufeff/, '');
+  const records = [];
+  let record = [];
+  let field = '';
+  let quoted = false;
+  for (let index = 0; index < source.length; index += 1) {
+    const character = source[index];
+    if (quoted) {
+      if (character === '"') {
+        if (source[index + 1] === '"') {
+          field += '"';
+          index += 1;
+        } else quoted = false;
+      } else field += character;
+    } else if (character === '"' && field.length === 0) quoted = true;
+    else if (character === ',') {
+      record.push(field);
+      field = '';
+    } else if (character === '\r' || character === '\n') {
+      if (character === '\r' && source[index + 1] === '\n') index += 1;
+      record.push(field);
+      if (record.some((value) => value !== '')) records.push(record);
+      record = [];
+      field = '';
+    } else field += character;
+  }
+  if (quoted) throw new Error('Malformed CSV: unterminated quoted field');
+  if (field.length > 0 || record.length > 0) {
+    record.push(field);
+    records.push(record);
+  }
+  if (records.length === 0) return { headers: [], rows: [] };
+  const headers = records[0];
+  const rows = records.slice(1).map((values, index) => {
+    if (values.length !== headers.length) {
+      throw new Error(`Malformed CSV row ${index + 2}: expected ${headers.length} fields, received ${values.length}`);
+    }
+    return Object.fromEntries(headers.map((header, column) => [header, values[column]]));
+  });
+  return { headers, rows };
+}
+
+function encode(value) {
+  const text = value === undefined || value === null ? '' : String(value);
+  return /[",\r\n]/.test(text) ? `"${text.replaceAll('"', '""')}"` : text;
+}
+
+export function stringifyCsv(headers, rows, { bom = true, newline = '\r\n' } = {}) {
+  const lines = [headers.map(encode).join(',')];
+  for (const row of rows) lines.push(headers.map((header) => encode(row[header])).join(','));
+  return `${bom ? '\ufeff' : ''}${lines.join(newline)}${newline}`;
+}
+
+export function hyperlink(url, title) {
+  if (!url) return title;
+  const escape = (value) => String(value).replaceAll('"', '""');
+  return `=HYPERLINK("${escape(url)}","${escape(title)}")`;
+}
+
+export function hyperlinkUrl(value) {
+  const match = String(value ?? '').match(/^=HYPERLINK\("((?:[^"]|"")*)","(?:[^"]|"")*"\)$/i);
+  if (!match) return null;
+  try {
+    const url = new URL(match[1].replaceAll('""', '"'));
+    return ['http:', 'https:'].includes(url.protocol) ? url.href : null;
+  } catch { return null; }
+}

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

@@ -0,0 +1,92 @@
+const IDENTIFIER_START = /[A-Za-z_$]/;
+const IDENTIFIER_PART = /[A-Za-z0-9_$-]/;
+
+export function parseJson5(text) {
+  const tokens = [];
+  let index = 0;
+  while (index < text.length) {
+    const character = text[index];
+    if (/\s|\ufeff/.test(character)) {
+      index += 1;
+    } else if (character === '/' && text[index + 1] === '/') {
+      index += 2;
+      while (index < text.length && text[index] !== '\n') index += 1;
+    } else if (character === '/' && text[index + 1] === '*') {
+      const end = text.indexOf('*/', index + 2);
+      if (end === -1) throw new Error(`Unterminated JSON5 comment at offset ${index}`);
+      index = end + 2;
+    } else if (character === '"' || character === "'") {
+      const quote = character;
+      let value = '';
+      index += 1;
+      while (index < text.length && text[index] !== quote) {
+        if (text[index] === '\\') {
+          index += 1;
+          const escaped = text[index];
+          value += ({ n: '\n', r: '\r', t: '\t', b: '\b', f: '\f' })[escaped] ?? escaped;
+        } else value += text[index];
+        index += 1;
+      }
+      if (text[index] !== quote) throw new Error('Unterminated JSON5 string');
+      tokens.push({ type: 'value', value });
+      index += 1;
+    } else if ('{}[]:,'.includes(character)) {
+      tokens.push({ type: 'punctuation', value: character });
+      index += 1;
+    } else if (IDENTIFIER_START.test(character)) {
+      const start = index++;
+      while (index < text.length && IDENTIFIER_PART.test(text[index])) index += 1;
+      tokens.push({ type: 'identifier', value: text.slice(start, index) });
+    } else if (/[+\-.0-9]/.test(character)) {
+      const start = index++;
+      while (index < text.length && /[A-Fa-fxX0-9eE+\-.]/.test(text[index])) index += 1;
+      tokens.push({ type: 'number', value: text.slice(start, index) });
+    } else throw new Error(`Unexpected JSON5 character ${JSON.stringify(character)} at offset ${index}`);
+  }
+  let cursor = 0;
+  const current = () => tokens[cursor];
+  function consume(value) {
+    const token = current();
+    if (!token || (value !== undefined && token.value !== value)) throw new Error(`Expected ${value ?? 'token'} at token ${cursor}`);
+    cursor += 1;
+    return token;
+  }
+  function value() {
+    const token = current();
+    if (!token) throw new Error('Unexpected end of JSON5 input');
+    if (token.value === '{') return object();
+    if (token.value === '[') return array();
+    cursor += 1;
+    if (token.type === 'value') return token.value;
+    if (token.type === 'number') return Number(token.value);
+    if (token.value === 'true') return true;
+    if (token.value === 'false') return false;
+    if (token.value === 'null') return null;
+    throw new Error(`Unexpected JSON5 value: ${token.value}`);
+  }
+  function object() {
+    const result = {};
+    consume('{');
+    while (current()?.value !== '}') {
+      const key = consume().value;
+      consume(':');
+      result[key] = value();
+      if (current()?.value === ',') consume(',');
+    }
+    consume('}');
+    return result;
+  }
+  function array() {
+    const result = [];
+    consume('[');
+    while (current()?.value !== ']') {
+      result.push(value());
+      if (current()?.value === ',') consume(',');
+    }
+    consume(']');
+    return result;
+  }
+  const result = value();
+  if (cursor !== tokens.length) throw new Error(`Unexpected trailing JSON5 token ${cursor}`);
+  return result;
+}

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

@@ -0,0 +1,45 @@
+import { TextDecoder } from 'node:util';
+import { parseCsv, stringifyCsv } from './csv.mjs';
+import { sha256 } from '../io/fs-utils.mjs';
+
+const resultHeaders = ['处理结论', '处理说明', '后续事项'];
+const conclusions = new Set(['无需适配', '已适配', '待决策']);
+
+/**
+ * Format model-assessed results without changing source cells or deciding business outcomes.
+ * @param {Buffer} scanBytes Original UTF-8 scan bytes, including any BOM.
+ * @param {Array<{rowId: string, 处理结论: string, 处理说明: string, 后续事项: string}>} results
+ *   One result per SHA-256:logical-row identity; input order is immaterial.
+ * @returns {string} CSV with exactly three appended columns, UTF-8 BOM and CRLF records.
+ */
+export function formatUpgradeResults(scanBytes, results) {
+  if (!Buffer.isBuffer(scanBytes)) throw new TypeError('scanBytes 必须是原始扫描字节 Buffer');
+  if (!Array.isArray(results)) throw new TypeError('results 必须是逐行结果数组');
+  let text;
+  try { text = new TextDecoder('utf-8', { fatal: true }).decode(scanBytes); }
+  catch (cause) { throw new Error('原始扫描表必须使用 UTF-8 编码', { cause }); }
+  const { headers, rows } = parseCsv(text);
+  if (!headers.length || headers.some(header => !header.trim())) throw new Error('原始扫描表缺少有效表头');
+  if (new Set(headers).size !== headers.length) throw new Error('原始扫描表包含重复表头');
+  if (resultHeaders.some(header => headers.includes(header)))
+    throw new Error('输入已包含处理列，请使用原始扫描表，不要传入 adapted-results');
+
+  const hash = sha256(scanBytes);
+  const rowIds = rows.map((_, index) => `${hash}:${index + 1}`);
+  const expected = new Set(rowIds);
+  const byId = new Map();
+  for (const result of results) {
+    if (!result || !expected.has(result.rowId)) throw new Error(`未知结果 rowId: ${result?.rowId}`);
+    if (byId.has(result.rowId)) throw new Error(`重复结果 rowId: ${result.rowId}`);
+    if (!conclusions.has(result['处理结论'])) throw new Error(`处理结论必须为无需适配、已适配或待决策: ${result.rowId}`);
+    if (typeof result['处理说明'] !== 'string' || !result['处理说明'].trim())
+      throw new Error(`处理说明必须包含具体理由: ${result.rowId}`);
+    if (typeof result['后续事项'] !== 'string') throw new Error(`后续事项必须为字符串，无待办时留空: ${result.rowId}`);
+    byId.set(result.rowId, result);
+  }
+  if (byId.size !== rows.length) throw new Error('缺少扫描行对应的结果 rowId');
+  return stringifyCsv([...headers, ...resultHeaders], rows.map((row, index) => {
+    const result = byId.get(rowIds[index]);
+    return { ...row, ...Object.fromEntries(resultHeaders.map(header => [header, result[header]])) };
+  }));
+}