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

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

@@ -0,0 +1,425 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { buildSdkCatalog, resolveRuleDeclarations } from './sdk-deprecations.mjs';
+import { listFiles, portableRelative, sha256 } from '../../shared/io/fs-utils.mjs';
+import { canonicalHarmonyVersion as canonicalVersion, compareHarmonyVersions as compareVersions, devecoVersionName, parseVersion } from '../../shared/platform/version.mjs';
+import { readZipTextEntries } from '../../shared/format/zip.mjs';
+import { normalizeDocumentUrl, entryUrl } from '../../shared/platform/document-links.mjs';
+import { loadChangelogIndex } from '../../shared/platform/changelog-index.mjs';
+import { requireScanMode } from '../../shared/platform/scan-mode.mjs';
+
+const API_PLATFORM = new Map([
+  [12, '5.0.0'], [13, '5.0.1'], [14, '5.0.2'], [15, '5.0.3'], [16, '5.0.4'], [17, '5.0.5'],
+  [18, '5.1.0'], [19, '5.1.1'], [20, '6.0.0'], [21, '6.0.1'], [22, '6.0.2'], [23, '6.1.0'],
+  [24, '6.1.1'], [26, '26.0.0'],
+]);
+
+const CHANGE_TYPE_MAP = new Map([
+  ['接口行为变更', ['API Behavior Change', 'API_BEHAVIOR']],
+  ['接口行为变更（API变更）', ['API Behavior Change', 'API_BEHAVIOR']],
+  ['UX视觉布局变更', ['UX Visual Layout Change', 'UX_VISUAL']],
+  ['视觉布局变更', ['UX Visual Layout Change', 'UX_VISUAL']],
+  ['UX交互行为变更', ['UX Interaction Behavior Change', 'UX_INTERACTION']],
+  ['接口定义变更', ['API Definition Change', 'API_DEFINITION']],
+  ['接口废弃变更', ['Deprecated API', 'API_DEPRECATED']],
+]);
+
+const BEHAVIOR_BASELINE_API_LEVEL = 12;
+const BEHAVIOR_CHANGE_TYPES = new Set([
+  'API Behavior Change',
+  'UX Visual Layout Change',
+  'UX Interaction Behavior Change',
+]);
+const BEHAVIOR_BASELINE_REASON = 'BEHAVIOR_BASELINE_ALREADY_ADAPTED';
+
+const CHANGE_TITLE_OVERRIDES = new Map([
+  ['CH2026042864213', '通过ohos.permission.READ_IMAGEVIDEO权限可读取的媒体库文件的范围变更'],
+]);
+
+function ruleId(parts) {
+  return `rule-${sha256(parts.join('\u0000')).slice(0, 20)}`;
+}
+
+function normalizeTitle(value) {
+  return String(value).toLowerCase().replaceAll('\\', '').replace(/[^\p{L}\p{N}]+/gu, '');
+}
+
+function markdownField(section, label) {
+  const escaped = label.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return section.match(new RegExp(`\\*\\*${escaped}\\*\\*\\s*\\n+([\\s\\S]*?)(?=\\n\\*\\*[^*]+\\*\\*|\\n#{1,6}\\s|$)`))?.[1]?.trim() ?? '';
+}
+
+function cleanStatement(value) {
+  return String(value)
+    .replace(/!\[[^\]]*\]\([^)]+\)/g, '')
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
+    .replace(/[*_`]/g, '')
+    .replace(/^\s*(?:[-*+]\s+|\d+[.)]\s+)/, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function guidanceNoAdaptationEvidence(guidance) {
+  const normalized = guidance.split(/\r?\n/).map(cleanStatement).filter(Boolean).join('\n');
+  const direct = /^(?:(?:默认(?:行为|效果|UX样式)?变更|(?:此|该|本)变更)[，,：:]?\s*)?(?:开发者|应用)?(?:无需(?:进行|应用)?适配|不涉及应用适配)/;
+  if (!direct.test(normalized)) return null;
+  return {
+    sectionField: '适配指导',
+    statement: normalized.split('\n', 1)[0],
+  };
+}
+
+export function documentedNoAdaptationEvidence(section) {
+  const guidance = markdownField(section, '适配指导');
+  const guidanceEvidence = guidanceNoAdaptationEvidence(guidance);
+  if (guidanceEvidence) return guidanceEvidence;
+  const wholeSectionMatch = section.match(/(?:此|该)变更不涉及应用适配[。.]?/);
+  if (!wholeSectionMatch) return null;
+  if (/(?:无需(?:进行|应用)?适配|不涉及应用适配)/.test(guidance)) return null;
+  const remaining = section.replace(wholeSectionMatch[0], '');
+  if (/(?:此|该)变更涉及应用适配|(?:需要|必须|应当)修改|(?:需要|必须|(?<!无)需)适配/.test(remaining)) return null;
+  return { sectionField: '变更影响', statement: cleanStatement(wholeSectionMatch[0]) };
+}
+
+export function documentedNoAdaptation(section) {
+  return documentedNoAdaptationEvidence(section) !== null;
+}
+
+export function applyBehaviorBaseline(rules, apiLevel = BEHAVIOR_BASELINE_API_LEVEL) {
+  const included = [];
+  const excluded = [];
+  for (const rule of rules) {
+    const level = parseVersion(rule.changedInSdk).apiLevel;
+    if (BEHAVIOR_CHANGE_TYPES.has(rule.changeType) && level <= apiLevel) {
+      excluded.push({
+        ruleId: rule.ruleId,
+        changedInSdk: rule.changedInSdk,
+        changeType: rule.changeType,
+        title: rule.title,
+        sourceReference: rule.sourceReference,
+        reason: BEHAVIOR_BASELINE_REASON,
+      });
+    } else {
+      included.push(rule);
+    }
+  }
+  return {
+    rules: included,
+    excluded,
+    audit: {
+      apiLevel,
+      policy: 'ALREADY_ADAPTED',
+      reason: BEHAVIOR_BASELINE_REASON,
+      excludedRuleCount: excluded.length,
+    },
+  };
+}
+
+async function buildHeadingIndex(referenceRoot) {
+  const changelogIndex = await loadChangelogIndex(referenceRoot);
+  const files = await listFiles(referenceRoot, (file) => file.endsWith('.md'));
+  const byTitle = new Map();
+  const byNormalizedTitle = new Map();
+  const linkedTitlesByChangeId = new Map();
+  const sectionsBySourceReference = new Map();
+  const documentSources = new Map();
+  const links = [];
+  for (const file of files) {
+    const relative = portableRelative(referenceRoot, file);
+    const lines = (await readFile(file, 'utf8')).split(/\r?\n/);
+    documentSources.set(relative, lines.find(line => /^source:\s*https?:\/\//.test(line))?.replace(/^source:\s*/, '').trim());
+    let fenced = false;
+    const headings = [];
+    for (let index = 0; index < lines.length; index += 1) {
+      if (lines[index].trim().startsWith('```')) {
+        fenced = !fenced;
+        continue;
+      }
+      if (fenced) continue;
+      const heading = lines[index].match(/^#{2,6}\s+(.+?)\s*$/);
+      if (!heading) continue;
+      headings.push({ index, level: lines[index].match(/^#+/)?.[0].length ?? 6 });
+      const entries = byTitle.get(heading[1]) ?? [];
+      entries.push(`${relative}:${index + 1}`);
+      byTitle.set(heading[1], entries);
+      const normalized = normalizeTitle(heading[1]);
+      const normalizedEntries = byNormalizedTitle.get(normalized) ?? [];
+      normalizedEntries.push(`${relative}:${index + 1}`);
+      byNormalizedTitle.set(normalized, normalizedEntries);
+    }
+    for (let index = 0; index < headings.length; index += 1) {
+      const heading = headings[index];
+      const next = headings.slice(index + 1).find((candidate) => candidate.level <= heading.level);
+      sectionsBySourceReference.set(
+        `${relative}:${heading.index + 1}`,
+        lines.slice(heading.index, next?.index ?? lines.length).join('\n').trim(),
+      );
+    }
+    for (const line of lines) {
+      for (const match of line.matchAll(/\[([^\]]+)\]\((https?:\/\/[^)#]+#([^)]+))\)/g)) {
+        const id = decodeURIComponent(match[3]).toLowerCase();
+        links.push({ title: match[1], url: match[2], id, version: relative.split('/')[0] });
+        const titles = linkedTitlesByChangeId.get(id) ?? [];
+        titles.push(match[1]);
+        linkedTitlesByChangeId.set(id, titles);
+      }
+    }
+  }
+  for (const record of changelogIndex.overview) {
+    for (const match of record.row.matchAll(/\[([^\]]+)\]\((https?:\/\/[^)#]+#([^)]+))\)/g)) {
+      const id = decodeURIComponent(match[3]).toLowerCase();
+      links.push({ title: match[1], url: match[2], id, version: record.version });
+      const titles = linkedTitlesByChangeId.get(id) ?? [];
+      titles.push(match[1]);
+      linkedTitlesByChangeId.set(id, titles);
+    }
+  }
+  return { byTitle, byNormalizedTitle, linkedTitlesByChangeId, sectionsBySourceReference, documentSources, links };
+}
+
+function documentLink(change, sourceReference, index) {
+  const file = sourceReference.replace(/:\d+$/, ''), versionRoot = file.split('/')[0];
+  const page = normalizeDocumentUrl(index.documentSources.get(file), { fragment: false });
+  const candidates = index.links.filter(link => link.version === versionRoot
+    && normalizeDocumentUrl(link.url, { fragment: false }) === page);
+  const byId = candidates.filter(link => link.id === String(change.id).toLowerCase());
+  const heading = index.sectionsBySourceReference.get(sourceReference)?.split('\n')[0].replace(/^#+\s*/, '');
+  const matched = byId.length ? byId : candidates.filter(link => normalizeTitle(link.title) === normalizeTitle(heading ?? change.changeTitle));
+  const urls = [...new Set(matched.map(link => entryUrl(link.url)).filter(Boolean))];
+  let provided = null;
+  try { provided = entryUrl(new URL(change.url, 'https://developer.huawei.com/consumer/cn/doc/harmonyos-releases/').href); } catch { /* No plugin URL. */ }
+  if (provided && (urls.length === 1 && provided === urls[0] || !urls.length
+    && normalizeDocumentUrl(provided, { fragment: false }) === page
+    && new URL(provided).hash.toLowerCase() === `#${String(change.id).toLowerCase()}`))
+    return { url: provided, source: 'DEVECO_RULE' };
+  return urls.length === 1 ? { url: urls[0], source: 'OFFICIAL_OVERVIEW' }
+    : { url: '', source: null, reason: urls.length ? 'AMBIGUOUS_DOCUMENT_LINK' : 'DOCUMENT_LINK_NOT_FOUND' };
+}
+
+function affectedVersionRange(change, endVersion) {
+  if (['NOT_ISOLATED', 'COULD_NOT_ISOLATED'].includes(change.apiEffectiveVersion)) return 'ALL';
+  const apiText = String(change.apiVersion ?? '');
+  const apiLevel = /^\d+$/.test(apiText) ? Number(apiText) : parseVersion(apiText).apiLevel;
+  const platform = API_PLATFORM.get(apiLevel);
+  const start = platform ? `${platform}(${apiLevel})` : apiText;
+  return `${start} - ${endVersion.platformVersion}(${endVersion.apiLevel})`;
+}
+
+function ruleResourceVersion(name) {
+  return parseVersion(path.basename(name, '.json'));
+}
+
+function ruleResourceKey(name) {
+  try {
+    const version = ruleResourceVersion(name);
+    return ['version', version.platformVersion, version.apiLevel, version.channel, version.channelNumber].join(':');
+  } catch {
+    return `file:${path.basename(name).toLowerCase()}`;
+  }
+}
+
+export async function loadDevEcoRules(toolchain, referenceRoot, range, mode) {
+  requireScanMode(mode);
+  const headingIndex = await buildHeadingIndex(referenceRoot);
+  const resourcesByVersion = new Map();
+  if (toolchain.apiChangeResourceRoot) {
+    const files = await listFiles(toolchain.apiChangeResourceRoot, file => file.endsWith('.json'));
+    const directoryResources = await Promise.all(files.map(async file => ({
+      name: path.basename(file),
+      sourceReference: file,
+      text: await readFile(file, 'utf8'),
+    })));
+    for (const resource of directoryResources) resourcesByVersion.set(ruleResourceKey(resource.name), resource);
+  }
+  if (toolchain.apiChangeResourceArchive) {
+    const archiveResources = (await readZipTextEntries(toolchain.apiChangeResourceArchive,
+      name => /^apiChange\/.+\.json$/i.test(name) && !resourcesByVersion.has(ruleResourceKey(name)))).map(entry => ({
+      name: path.basename(entry.name),
+      sourceReference: `${toolchain.apiChangeResourceArchive}!/${entry.name}`,
+      text: entry.text,
+    }));
+    for (const resource of archiveResources) resourcesByVersion.set(ruleResourceKey(resource.name), resource);
+  }
+  const resources = [...resourcesByVersion.values()];
+  const rules = [];
+  const excluded = [];
+  const errors = [];
+  const versionNames = {};
+  const ruleSource = [toolchain.apiChangeResourceRoot, toolchain.apiChangeResourceArchive].filter(Boolean).join(' | ');
+  if (!resources.some((resource) => {
+    try { return compareVersions(ruleResourceVersion(resource.name), range.end) === 0; }
+    catch { return false; }
+  })) {
+    errors.push({
+      sourceReference: ruleSource,
+      message: `DevEco rule pack does not cover target ${devecoVersionName(range.end)}`,
+    });
+  }
+  for (const resource of resources) {
+    let version;
+    try {
+      version = ruleResourceVersion(resource.name);
+      versionNames[canonicalVersion(version)] = path.basename(resource.name, '.json');
+    } catch (error) {
+      errors.push({ sourceReference: resource.sourceReference, message: error.message });
+      continue;
+    }
+    if (compareVersions(version, range.start) <= 0 || compareVersions(version, range.end) > 0) continue;
+    const entries = JSON.parse(resource.text);
+    for (const entry of entries) {
+      const change = entry.interfaceChanges ?? {};
+      const affectedApis = Array.isArray(entry.affectedApis) ? entry.affectedApis : [];
+      const mapped = CHANGE_TYPE_MAP.get(change.changeType);
+      if (mode === 'upgrade' && mapped?.[0] === 'Deprecated API') {
+        excluded.push({ changeId: change.id, title: change.changeTitle, reason: 'UPGRADE_EXCLUDES_DEPRECATED' });
+        continue;
+      }
+      if (mode === 'deprecated' && mapped?.[0] !== 'Deprecated API') {
+        excluded.push({ changeId: change.id, title: change.changeTitle, reason: 'DEPRECATED_EXCLUDES_NON_DEPRECATED' });
+        continue;
+      }
+      if (mapped && BEHAVIOR_CHANGE_TYPES.has(mapped[0])
+        && parseVersion(change.sdkVersion || canonicalVersion(version)).apiLevel <= BEHAVIOR_BASELINE_API_LEVEL) {
+        excluded.push({ ruleId: change.id ? String(change.id) : null,
+          changedInSdk: change.sdkVersion || canonicalVersion(version), changeType: mapped[0],
+          title: change.changeTitle ?? '', sourceReference: null, reason: BEHAVIOR_BASELINE_REASON });
+        continue;
+      }
+      let sources = headingIndex.byTitle.get(change.changeTitle) ?? [];
+      if (sources.length !== 1) {
+        sources = headingIndex.byNormalizedTitle.get(normalizeTitle(change.changeTitle)) ?? [];
+      }
+      if (sources.length !== 1 && change.id !== undefined && change.id !== null) {
+        const idCandidates = [String(change.id).toLowerCase(), `section${String(change.id).toLowerCase()}`];
+        const linkedTitles = idCandidates.flatMap((id) => headingIndex.linkedTitlesByChangeId.get(id) ?? []);
+        const linkedSources = linkedTitles.flatMap((title) => headingIndex.byTitle.get(title)
+          ?? headingIndex.byNormalizedTitle.get(normalizeTitle(title)) ?? []);
+        if (linkedSources.length === 1) sources = linkedSources;
+      }
+      if (sources.length !== 1) {
+        const overrideTitle = CHANGE_TITLE_OVERRIDES.get(String(change.id));
+        if (overrideTitle) {
+          sources = headingIndex.byTitle.get(overrideTitle)
+            ?? headingIndex.byNormalizedTitle.get(normalizeTitle(overrideTitle)) ?? [];
+        }
+      }
+      if (!mapped || affectedApis.length === 0) {
+        excluded.push({
+          sourceReference: sources.length === 1 ? sources[0] : null,
+          changeId: change.id ?? null,
+          title: change.changeTitle ?? '',
+          reason: affectedApis.length === 0 ? 'NO_AFFECTED_APIS' : `UNSUPPORTED_CHANGE_TYPE:${change.changeType ?? ''}`,
+        });
+        continue;
+      }
+      if (sources.length !== 1) {
+        errors.push({
+          changeId: change.id ?? null,
+          title: change.changeTitle ?? '',
+          message: sources.length === 0 ? 'changelog heading not found' : 'ambiguous changelog heading',
+          candidates: sources,
+        });
+        continue;
+      }
+      const id = String(change.id || ruleId([change.sdkVersion ?? canonicalVersion(version), change.changeTitle, sources[0]]));
+      const noAdaptation = documentedNoAdaptationEvidence(headingIndex.sectionsBySourceReference.get(sources[0]) ?? '');
+      const link = documentLink(change, sources[0], headingIndex);
+      rules.push({
+        provider: 'DEVECO',
+        ruleId: id,
+        changeOperation: mapped[1],
+        changeType: mapped[0],
+        changedInSdk: change.sdkVersion || canonicalVersion(version),
+        affectedVersions: affectedVersionRange(change, range.end),
+        title: change.changeTitle ?? '',
+        url: link.url,
+        documentLink: link,
+        sourceReference: sources[0],
+        affectedApis,
+        reportDisposition: noAdaptation ? 'FILTERED_COMPATIBLE' : 'REQUIRES_REVIEW',
+        filterReason: noAdaptation ? 'DOCUMENTED_NO_ADAPTATION' : null,
+        applicabilityProof: noAdaptation ? {
+          kind: 'DOCUMENTED_NO_ADAPTATION',
+          sourceReference: sources[0],
+          ...noAdaptation,
+        } : null,
+        rawEntry: entry,
+      });
+    }
+  }
+  return { rules, excluded, errors, versionNames };
+}
+
+export async function compileRules({ toolchain, referenceRoot, range, strict = true, mode }) {
+  requireScanMode(mode);
+  const deveco = await loadDevEcoRules(toolchain, referenceRoot, range, mode);
+  const selected = mode === 'upgrade' ? deveco.rules.map(rule => ({
+    ...rule, reportDisposition: 'REQUIRES_REVIEW', filterReason: null, applicabilityProof: null,
+  })) : deveco.rules;
+  const baseline = applyBehaviorBaseline(selected);
+  const rules = baseline.rules;
+  const errors = deveco.errors;
+  const coverage = {
+    status: errors.length === 0 ? 'COMPLETE' : 'INCOMPLETE',
+    includedRuleCount: rules.length,
+    devecoRuleCount: rules.length,
+    excludedRuleCount: deveco.excluded.length + baseline.excluded.length,
+    behaviorBaseline: { ...baseline.audit, excludedRuleCount: baseline.audit.excludedRuleCount
+      + deveco.excluded.filter(entry => entry.reason === BEHAVIOR_BASELINE_REASON).length },
+    devecoVersionNames: deveco.versionNames,
+    errorCount: errors.length,
+    excluded: [...deveco.excluded, ...baseline.excluded],
+    errors,
+  };
+  if (strict && errors.length) {
+    const error = new Error(`Rule coverage is incomplete: ${errors.length} rule errors`);
+    error.code = 'INCOMPLETE_RULE_COVERAGE';
+    error.details = errors.slice(0, 20);
+    throw error;
+  }
+  return { rules, coverage };
+}
+
+export async function auditDeprecationRules(toolchain, rules, catalog = null) {
+  catalog ??= await buildSdkCatalog(toolchain);
+  const sourceFilesByParserName = new Map(
+    [...catalog.sourceFiles.values()].map(sourceFile => [sourceFile.fileName, sourceFile]),
+  );
+  let targetSdkTagged = 0;
+  let replacementCount = 0;
+  let legacyChangelogSignature = 0;
+  const legacySamples = [];
+  for (const rule of rules.filter(item => item.changeOperation === 'API_DEPRECATED')) {
+    const api = rule.affectedApis[0];
+    const matches = api.implementLanguage.toLowerCase() === 'typescript'
+      ? resolveRuleDeclarations(catalog, api).filter(entry => entry.deprecatedSince !== null)
+      : [];
+    rule.sdkSymbolIds = matches.map(entry => entry.symbolId);
+    if (matches.length === 1) {
+      const entry = matches[0];
+      rule.replacementApi = entry.replacementApi;
+      rule.replacementSource = `${entry.file}:${entry.line}`;
+      const sf = catalog.sourceFiles.get(entry.file) ?? sourceFilesByParserName.get(entry.file);
+      if (!sf) {
+        const error = new Error(`SDK declaration source is unavailable: ${entry.file}`);
+        error.code = 'SDK_DECLARATION_SOURCE_MISSING';
+        error.details = { ruleId: rule.ruleId, symbolId: entry.symbolId, file: entry.file };
+        throw error;
+      }
+      const commentStart = sf.text.lastIndexOf('/**', entry.start);
+      rule.replacementDeclaration = `${commentStart >= 0 ? sf.text.slice(commentStart, entry.start) : ''}${entry.declaration}`;
+      targetSdkTagged += 1;
+      if (entry.replacementApi) replacementCount += 1;
+    } else {
+      rule.replacementApi = null;
+      rule.replacementSource = null;
+      legacyChangelogSignature += 1;
+      if (legacySamples.length < 20) legacySamples.push({
+        ruleId: rule.ruleId, sourceReference: rule.sourceReference,
+        apiDefinition: api.methodDefinition,
+        reason: matches.length > 1 ? 'SDK_DECLARATION_AMBIGUOUS' : 'EXACT_SDK_DECLARATION_NOT_FOUND',
+      });
+    }
+  }
+  return { targetSdkTagged, replacementCount, legacyChangelogSignature, legacySamples };
+}

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

@@ -0,0 +1,23 @@
+// Scanner provenance: tool identity only.
+// This records tool identity only; it does not diagnose or run API adaptation.
+import path from 'node:path';
+import {readFile} from 'node:fs/promises';
+import {listFiles,portableRelative,sha256} from '../../shared/io/fs-utils.mjs';
+import {requireScanMode} from '../../shared/platform/scan-mode.mjs';
+
+export async function runtimeIdentity(skillRoot,{mode}={}) {
+  requireScanMode(mode);
+  const root=path.resolve(skillRoot),adapter=JSON.parse(await readFile(path.join(root,'package.json'),'utf8'));
+  const scanner=JSON.parse(await readFile(path.join(root,'scripts','scanner','package.json'),'utf8')),files=[];
+  const selected=[path.join(root,'scripts','shared','platform','scan-version-catalog.json')];
+  for(const directory of [path.join('scripts','shared'),path.join('scripts','scanner')])
+    selected.push(...await listFiles(path.join(root,directory),file=>/\.(mjs|cjs)$/.test(file),directory=>path.basename(directory)!=='test'));
+  for(const file of selected) {
+    const text=(await readFile(file,'utf8')).replace(/^\ufeff/,'').replace(/\r\n?/g,'\n');
+    files.push(`${portableRelative(root,file)}\0${sha256(text)}`);
+  }
+  return {identityVersion:2,featureMode:mode,featureVersion:1,skillRoot:root,adapterVersion:adapter.version,
+    scannerVersion:scanner.version,nodeVersion:process.version,platform:process.platform,
+    implementationFingerprint:sha256(files.sort().join('\n')),
+    capabilities:['independent-scanner','upgrade-plugin-mode','scan-statistics','official-change-links','native-abi-compilation-context']};
+}