@cloudcare/hvigor-ohos-plugin 0.1.2-alpha.1 → 0.1.2-alpha.2

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [0.1.2-alpha.2] - 2026-10-30
+
+- Added build warnings with feature names, source paths, skip reasons and source locations for Console/HiLog, cold-launch lifecycle hooks, Session Replay root registration and ArkWeb binding.
+- Fixed automatic Session Replay page registration being skipped on pages that use UI enum values or `ForEach`/`LazyForEach`/`Repeat` child blocks, which could leave native View/Action events without `session_has_replay`.
+
 ## [0.1.2-alpha.1] - 2026-10-19
 
 - Added automatic Session Replay integration for supported ArkUI `@Entry` pages, ArkWeb components and touch events, without manual page registration or event forwarding. Requires `@guancecloud/ft_session_replay` in the HAP and Replay initialization; touch coordinates require `TouchPrivacy.SHOW`.

package/README.md

@@ -46,6 +46,28 @@ The plugin automatically captures page touch events without changing existing `o
 
 Router page changes and explicit `PageTransitionEnter/Exit` slide and opacity animations are captured automatically. Existing transition callbacks are preserved; playback of default system transitions may be approximate.
 
+## Build diagnostics
+
+Search for `[GuanceBuild]` in DevEco Studio's Build output or `.hvigor/outputs/build-logs/build.log` to find instrumentation warnings. Each warning includes a feature name, source path, one-based line and column, skip reason, and explanation. These build-time warnings do not depend on `FTSDKConfig.setDebug(...)`.
+
+| Filter | Feature | Feature-specific skip reasons |
+| --- | --- | --- |
+| `[GuanceLog]` | Console/HiLog collection | `unsupported-log-call`: optional calls, missing HiLog arguments, or an unusable compiler source range |
+| `[GuanceColdLaunch]` | AbilityStage/UIAbility/InsightIntent lifecycle and first-frame hooks | `unresolved-ability-base`: a declared module entry's platform base cannot be resolved; `unsupported-lifecycle`: no instrumentable method/function body; `unsupported-lifecycle-parameters`: unsupported launch or WindowStage parameters |
+| `[GuanceReplay]` | Session Replay `@Entry` page root registration | `unsupported-parser`, `missing-build`, `unsupported-root` |
+| `[GuanceWebReplay]` | ArkWeb controller binding | `unsupported-web-call`: a `Web` call is optional, has a spread argument, or does not have exactly one options argument |
+
+All four features report `parse-error` when a relevant source file cannot be parsed, including the first compiler diagnostic and the number of additional parse errors. Unexpected transform exceptions report `transform-exception` and retain the original build failure. When an exception has no source position, its location is the file's `1:1`.
+
+```text
+[GuanceBuild][GuanceReplay] /project/entry/src/main/ets/pages/Example.ets:12:19: feature=session-replay-root; reason=parse-error; TS1109: Expression expected.
+[GuanceBuild][GuanceColdLaunch] /project/entry/src/main/ets/entryability/EntryAbility.ets:18:3: feature=cold-launch; reason=unsupported-lifecycle-parameters; onWindowStageCreate requires a named WindowStage parameter for automatic first-frame observation.
+```
+
+Warnings do not fail the build by themselves. Unsupported calls/hooks are left unchanged while other supported hooks can still be applied; a parse failure skips that feature's transformation for the file. Application files are never modified on disk. Locations refer to the original source when available; a warning explicitly identifies any location that refers to transformed source instead. Identical warnings are deduplicated per feature and source location within the active compilation.
+
+Modules without the required runtime dependencies, files with no matching calls/classes/pages, and locally shadowed names are skipped without warnings. The plugin does not infer that an arbitrary unresolved business class is an Ability. After updating the plugin, rebuild the application so the source transforms execute again. Existing `ArkTS:WARN` compiler diagnostics remain independent of these plugin warnings.
+
 ## Compatibility
 
 The plugin is verified with Node.js 18 or newer, Hvigor and `@ohos/hvigor-ohos-plugin` 6.23.5, and HarmonyOS SDK 6.0.2 (API 22). Console/HiLog and cold-launch instrumentation require `@guancecloud/ft_sdk` `0.1.17` or later. Automatic Session Replay additionally requires `@guancecloud/ft_sdk` `0.1.18` or later and `@guancecloud/ft_session_replay` `0.1.0` or later.
@@ -59,4 +81,4 @@ Each module that needs automatic collection must declare these SDK packages unde
 
 The plugin checks SDK dependencies in the `oh-package.json5` of the module that contains each source file (HAP, HAR or HSP). Declaring an SDK only in the project-root `oh-package.json5`, another module, or `devDependencies` does not enable automatic collection for that source file.
 
-Optional logging calls such as `console?.info(...)` and `hilog.info?.(...)` are not automatically collected.
+Optional logging calls such as `console?.info(...)` and `hilog.info?.(...)` are not automatically collected and produce `unsupported-log-call` warnings.

package/hvigorCompile/ft-cold-launch-transform.ts

@@ -5,7 +5,8 @@
  * the compiler's in-memory source. Application files are never modified.
  */
 
-import { hasRuntimeDependency } from './ft-transform-context';
+import { hasRuntimeDependency, objectProperty, SourceDiagnosticReporter, SourceTransformDiagnostic,
+  parseApplicationSource, reportSourceDiagnostic, reportSourceParseError } from './ft-transform-context';
 import { createLexicalResolver } from './ft-lexical-scope';
 import { allocateName as selectIdentifierName, collectIdentifierNames } from './ft-generated-names';
 
@@ -42,6 +43,7 @@ interface ColdLaunchInjection {
 interface ColdLaunchInjections {
   injections: ColdLaunchInjection[];
   hasUIAbility: boolean;
+  hasAbility: boolean;
 }
 
 const COLD_LAUNCH_BRIDGE_IMPORT = '@guancecloud/ft_sdk/Index';
@@ -129,6 +131,37 @@ function needsUIAbilityModuleFallback(ts: TypeScriptApi, id: string, readSource?
   }
 }
 
+/** An unresolved business class is not necessarily an Ability; trust explicit module entries. */
+function isDeclaredAbilityEntry(ts: TypeScriptApi, id: string, readSource?: SourceReader): boolean {
+  const normalized = id.replace(/\\/g, '/');
+  const sourceIndex = normalized.lastIndexOf('/src/main/ets/');
+  if (sourceIndex < 0) return false;
+  const nodeRequire = require.main && typeof require.main.require === 'function'
+    ? require.main.require.bind(require.main) : require;
+  const path = nodeRequire('path');
+  const directory = normalized.slice(0, sourceIndex) + '/src/main';
+  try {
+    const manifest = directory + '/module.json5';
+    const code = readSource ? readSource(manifest) : nodeRequire('fs').readFileSync(manifest, 'utf8');
+    if (typeof code !== 'string') return false;
+    const source = ts.createSourceFile(manifest, `const __manifest = ${code}`, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    if (source.parseDiagnostics.length > 0 || source.statements.length !== 1 ||
+      !ts.isVariableStatement(source.statements[0])) return false;
+    const root = source.statements[0].declarationList.declarations[0].initializer;
+    const module = objectProperty(ts, root, 'module');
+    const entries = [objectProperty(ts, module, 'srcEntry')];
+    for (const key of ['abilities', 'extensionAbilities']) {
+      const list = objectProperty(ts, module, key);
+      if (list && ts.isArrayLiteralExpression(list)) {
+        list.elements.forEach((item: any) => entries.push(objectProperty(ts, item, 'srcEntry')));
+      }
+    }
+    return entries.some(entry => entry && ts.isStringLiteral(entry) && path.resolve(directory, entry.text) === path.resolve(id));
+  } catch (_) {
+    return false;
+  }
+}
+
 function classifyAbilityBaseName(name: string): AbilityClassKind | null {
   if (name === 'InsightIntentEntryExecutor') {
     return 'intent';
@@ -504,9 +537,11 @@ function createFirstFrameRetryInjections(ts: TypeScriptApi, sourceFile: any, cod
 
 function createColdLaunchInjections(ts: TypeScriptApi, sourceFile: any, code: string,
   bridgeName: string, pluginVersion: string, identifiers: Set<string>,
-  launchTypes: LaunchParameterTypes, readSource?: SourceReader): ColdLaunchInjections {
+  launchTypes: LaunchParameterTypes, readSource?: SourceReader, reportDiagnostic?: SourceDiagnosticReporter): ColdLaunchInjections {
   const injections: ColdLaunchInjection[] = [];
   let hasUIAbility = false;
+  let hasAbility = false;
+  const declaredEntry = isDeclaredAbilityEntry(ts, sourceFile.fileName, readSource);
   const resolve = createLexicalResolver(ts, sourceFile);
   const resolveClass = createAbilityClassResolver(ts, sourceFile, readSource);
   const pluginVersionArgument = pluginVersion.length > 0 ? `, ${JSON.stringify(pluginVersion)}` : '';
@@ -555,8 +590,14 @@ function createColdLaunchInjections(ts: TypeScriptApi, sourceFile: any, code: st
     const classification = resolveClass(node);
     const kind = classification.kind;
     if (!kind) {
+      if (declaredEntry && (node.modifiers || []).some((modifier: any) => modifier.kind === ts.SyntaxKind.DefaultKeyword)) {
+        reportSourceDiagnostic(sourceFile, node.getStart(sourceFile), 'unresolved-ability-base',
+          'This module entry has no resolvable platform Ability/AbilityStage/InsightIntent base; automatic lifecycle instrumentation was skipped.',
+          reportDiagnostic);
+      }
       return;
     }
+    hasAbility = true;
     if (kind === 'ui') {
       hasUIAbility = true;
     }
@@ -572,7 +613,30 @@ function createColdLaunchInjections(ts: TypeScriptApi, sourceFile: any, code: st
       if (name === 'onBackground') hasOnBackground = true;
       if (name === 'onNewWant') hasOnNewWant = true;
       const member = callableMember(ts, declaration);
-      if (!member || !name) return;
+      if (!name) return;
+      const expected = kind === 'intent' ? name === 'onExecute' : kind === 'legacyIntent'
+        ? ['onExecuteInUIAbilityForegroundMode', 'onExecuteInUIAbilityBackgroundMode'].includes(name)
+        : name === 'onCreate' || (kind === 'ui' &&
+          ['onForeground', 'onBackground', 'onNewWant', 'onWindowStageCreate'].includes(name));
+      if (!member) {
+        if (expected && !node.members.some((other: any) => memberName(ts, other) === name && callableMember(ts, other))) {
+          reportSourceDiagnostic(sourceFile, declaration.getStart(sourceFile), 'unsupported-lifecycle',
+            `${name} is not a method or function property with an instrumentable body; its automatic hook was skipped.`, reportDiagnostic);
+        }
+        return;
+      }
+      if (kind === 'ui' && name === 'onCreate' && member.parameters.slice(0, 2).some((parameter: any) =>
+        !ts.isIdentifier(parameter.name) || parameter.dotDotDotToken)) {
+        reportSourceDiagnostic(sourceFile, declaration.getStart(sourceFile), 'unsupported-lifecycle-parameters',
+          'onCreate uses destructured or rest parameters; automatic launch-reason capture was skipped.', reportDiagnostic);
+        return;
+      }
+      if (kind === 'ui' && name === 'onWindowStageCreate' && (member.parameters.length === 0 ||
+        !ts.isIdentifier(member.parameters[0].name) || member.parameters[0].dotDotDotToken)) {
+        reportSourceDiagnostic(sourceFile, declaration.getStart(sourceFile), 'unsupported-lifecycle-parameters',
+          'onWindowStageCreate requires a named WindowStage parameter for automatic first-frame observation.', reportDiagnostic);
+        return;
+      }
       const indentation = methodIndentation(code, declaration);
       const block = ts.isBlock(member.body);
       const position = member.body.getStart(sourceFile) + (block ? 1 : 0);
@@ -721,7 +785,7 @@ function createColdLaunchInjections(ts: TypeScriptApi, sourceFile: any, code: st
       }
     }
   });
-  return { injections, hasUIAbility };
+  return { injections, hasUIAbility, hasAbility };
 }
 
 function applyColdLaunchInjections(code: string, injections: ColdLaunchInjection[]): string {
@@ -743,7 +807,7 @@ function applyColdLaunchInjections(code: string, injections: ColdLaunchInjection
 }
 
 export function transformColdLaunchSource(ts: TypeScriptApi, id: string, code: string,
-  readSource?: SourceReader): string {
+  readSource?: SourceReader, reportDiagnostic?: SourceDiagnosticReporter): string {
   if (!isApplicationArkTsSource(id) || code.includes(COLD_LAUNCH_TRANSFORM_MARKER) ||
     !hasRuntimeDependency(ts, id, '@guancecloud/ft_sdk', readSource)) {
     return code;
@@ -757,8 +821,13 @@ export function transformColdLaunchSource(ts: TypeScriptApi, id: string, code: s
     needed: false
   };
   const version = getPluginVersion();
+  const diagnostics: SourceTransformDiagnostic[] = [];
   const result = createColdLaunchInjections(ts, sourceFile, code, bridgeName, version, identifiers,
-    launchTypes, readSource);
+    launchTypes, readSource, diagnostic => diagnostics.push(diagnostic));
+  if (result.hasAbility || diagnostics.length > 0) {
+    if (reportSourceParseError(ts, parseApplicationSource(ts, id, code), reportDiagnostic)) return code;
+    diagnostics.forEach(diagnostic => reportDiagnostic?.(diagnostic));
+  }
   const injections = result.injections;
   const moduleFallback = result.hasUIAbility && needsUIAbilityModuleFallback(ts, id, readSource);
   if (injections.length === 0 && !moduleFallback) {

package/hvigorCompile/ft-console-log-transform.ts

@@ -7,7 +7,8 @@
  * never changed.
  */
 
-import { hasRuntimeDependency, SourceReader } from './ft-transform-context';
+import { hasRuntimeDependency, SourceReader, SourceDiagnosticReporter, parseApplicationSource,
+  reportSourceDiagnostic, reportSourceParseError } from './ft-transform-context';
 import { createLexicalResolver } from './ft-lexical-scope';
 import { allocateName, collectIdentifierNames } from './ft-generated-names';
 
@@ -94,16 +95,14 @@ function needsStatementSeparator(ts: TypeScriptApi, node: any): boolean {
     ts.isCaseClause(container) || ts.isDefaultClause(container);
 }
 
-function collectCandidates(ts: TypeScriptApi, sourceFile: any, code: string): TransformCandidate[] {
+function collectCandidates(ts: TypeScriptApi, sourceFile: any, code: string,
+  unsupported: (node: any, message: string) => void): TransformCandidate[] {
   const candidates: TransformCandidate[] = [];
   const hiLogBindings = collectHiLogBindings(ts, sourceFile);
   const resolve = createLexicalResolver(ts, sourceFile);
 
   visit(ts, sourceFile, (node: any) => {
-    // Retain optional calls verbatim so their receiver/method short-circuit also
-    // controls argument evaluation. Nested ordinary calls remain eligible.
-    if (!ts.isCallExpression(node) || !ts.isPropertyAccessExpression(node.expression) ||
-      (ts.isOptionalChain && ts.isOptionalChain(node))) {
+    if (!ts.isCallExpression(node) || !ts.isPropertyAccessExpression(node.expression)) {
       return;
     }
     const delegate = node.expression.expression;
@@ -112,10 +111,20 @@ function collectCandidates(ts: TypeScriptApi, sourceFile: any, code: string): Tr
     }
     const delegateName = delegate.text;
     const level = node.expression.name.text;
+    const isConsole = delegateName === 'console' && !resolve(delegate, delegateName) && CONSOLE_LEVELS.includes(level);
+    const isHiLog = hiLogBindings.has(delegateName) &&
+      resolve(delegate, delegateName) === hiLogBindings.get(delegateName) && HILOG_LEVELS.includes(level);
+    if (!isConsole && !isHiLog) return;
+    // Preserve short-circuit semantics instead of transforming optional calls.
+    if (ts.isOptionalChain && ts.isOptionalChain(node)) {
+      unsupported(node, 'Optional Console/HiLog calls are left unchanged and are not automatically collected.');
+      return;
+    }
     const start = node.getStart(sourceFile);
     const end = node.end;
     const calleeEnd = node.expression.end;
     if (start < 0 || end > code.length || calleeEnd < start || calleeEnd > end) {
+      unsupported(node, 'The compiler returned an invalid source range for this logging call.');
       return;
     }
 
@@ -125,15 +134,16 @@ function collectCandidates(ts: TypeScriptApi, sourceFile: any, code: string): Tr
       spread: ts.isSpreadElement(argument)
     }));
     const statementSeparator = needsStatementSeparator(ts, node);
-    if (delegateName === 'console' && !resolve(delegate, delegateName) && CONSOLE_LEVELS.includes(level)) {
+    if (isConsole) {
       candidates.push({ start, end, calleeEnd, delegate: delegateName, level, source: 'console', callArguments,
         needsStatementSeparator: statementSeparator });
       return;
     }
-    if (hiLogBindings.has(delegateName) && resolve(delegate, delegateName) === hiLogBindings.get(delegateName) &&
-      HILOG_LEVELS.includes(level) && (callArguments.length >= 3 || callArguments.some(argument => argument.spread))) {
+    if (callArguments.length >= 3 || callArguments.some(argument => argument.spread)) {
       candidates.push({ start, end, calleeEnd, delegate: delegateName, level, source: 'hilog', callArguments,
         needsStatementSeparator: statementSeparator });
+    } else {
+      unsupported(node, 'HiLog collection requires domain, tag and format arguments, or a spread argument supplying them.');
     }
   });
   return candidates;
@@ -210,13 +220,19 @@ function findImportInsertionOffset(ts: TypeScriptApi, sourceFile: any): number {
   return offset;
 }
 
-export function transformConsoleLogSource(ts: TypeScriptApi, id: string, code: string, readSource?: SourceReader): string {
+export function transformConsoleLogSource(ts: TypeScriptApi, id: string, code: string, readSource?: SourceReader,
+  reportDiagnostic?: SourceDiagnosticReporter): string {
   if (!isApplicationArkTsSource(id) || code.includes(TRANSFORM_MARKER) ||
     !hasRuntimeDependency(ts, id, '@guancecloud/ft_sdk', readSource)) {
     return code;
   }
   const sourceFile = ts.createSourceFile(id, code, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
-  const candidates = collectCandidates(ts, sourceFile, code);
+  const unsupported: Array<{ node: any; message: string }> = [];
+  const candidates = collectCandidates(ts, sourceFile, code, (node, message) => unsupported.push({ node, message }));
+  if (candidates.length === 0 && unsupported.length === 0) return code;
+  if (reportSourceParseError(ts, parseApplicationSource(ts, id, code), reportDiagnostic)) return code;
+  unsupported.forEach(item => reportSourceDiagnostic(sourceFile, item.node.getStart(sourceFile),
+    'unsupported-log-call', item.message, reportDiagnostic));
   if (candidates.length === 0) {
     return code;
   }

package/hvigorCompile/ft-session-replay-transform.ts

@@ -8,7 +8,8 @@
  */
 
 import { isApplicationArkTsSource } from './ft-console-log-transform';
-import { hasRuntimeDependency, SourceReader } from './ft-transform-context';
+import { hasRuntimeDependency, SourceReader, SourceDiagnosticReporter, parseApplicationSource,
+  reportSourceDiagnostic, reportSourceParseError } from './ft-transform-context';
 import { allocateName as selectUniqueName } from './ft-generated-names';
 
 type TypeScriptApi = any;
@@ -35,6 +36,7 @@ interface RootExpression {
 }
 
 interface EntryStruct {
+  node: any;
   bodyEnd: number;
   methods: Map<string, MethodRange>;
 }
@@ -86,6 +88,19 @@ function findImportInsertionOffset(ts: TypeScriptApi, id: string, code: string):
   return offset;
 }
 
+function findEntryDecorator(ts: TypeScriptApi, source: any): any {
+  let entry: any;
+  const visit = (node: any): void => {
+    if (ts.isDecorator(node)) {
+      const expression = ts.isCallExpression(node.expression) ? node.expression.expression : node.expression;
+      if (ts.isIdentifier(expression) && expression.text === 'Entry') entry ??= node;
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  return entry;
+}
+
 /** Structs, decorators and members must come from the ArkTS parser, never text matches. */
 function collectEntryStructs(ts: TypeScriptApi, source: any): EntryStruct[] {
   const entries: EntryStruct[] = [];
@@ -106,7 +121,7 @@ function collectEntryStructs(ts: TypeScriptApi, source: any): EntryStruct[] {
           bodyStart: member.body.getStart(source), bodyEnd: member.body.end - 1 });
       }
     });
-    entries.push({ bodyEnd: node.end - 1, methods });
+    entries.push({ node, bodyEnd: node.end - 1, methods });
   });
   return entries;
 }
@@ -250,33 +265,31 @@ function addLifecycleInjection(
  * Adds an opaque root ID and page lifecycle registration to every @Entry page.
  * ArkTS nodes locate real decorators, struct members and component expressions.
  */
-export function transformSessionReplaySource(ts: TypeScriptApi, id: string, code: string, readSource?: SourceReader): string {
+export function transformSessionReplaySource(ts: TypeScriptApi, id: string, code: string, readSource?: SourceReader,
+  reportDiagnostic?: SourceDiagnosticReporter): string {
   if (!isApplicationArkTsSource(id) || code.includes(REPLAY_ROOT_TRANSFORM_MARKER) ||
     !hasRuntimeDependency(ts, id, '@guancecloud/ft_sdk', readSource) ||
     !hasRuntimeDependency(ts, id, REPLAY_BRIDGE_IMPORT, readSource)) {
     return code;
   }
 
-  if (typeof ts.isStructDeclaration !== 'function' || typeof ts.isEtsComponentExpression !== 'function') return code;
-  // The parser needs component names to recognize declarative child blocks.
-  // This superset configures parsing only; eligibility is decided by AST nodes.
-  const components = Array.from(collectIdentifiers(code));
-  const source = ts.createSourceFile(id, code, ts.ScriptTarget.Latest, true, ts.ScriptKind.ETS,
-    { ets: {
-      components,
-      render: { method: ['build', 'pageTransition'], decorator: ['Builder', 'LocalBuilder'] },
-      extend: { decorator: ['Extend', 'AnimatableExtend'], components: components.map(name =>
-        ({ name, type: `${name}Attribute`, instance: `${name}Instance` })) },
-      styles: { decorator: 'Styles', component: { name: 'Common', type: 'T', instance: 'CommonInstance' }, property: 'stateStyles' },
-      concurrent: { decorator: 'Concurrent' },
-      customComponent: 'CustomComponent',
-      syntaxComponents: { paramsUICallback: ['ForEach', 'LazyForEach'], attrUICallback: [{ name: 'Repeat', attributes: ['each', 'template'] }] }
-    } });
-  if (source.parseDiagnostics.length > 0) return code;
-  const entries = collectEntryStructs(ts, source);
-  if (entries.length === 0) {
+  const preliminarySource = ts.createSourceFile(id, code, ts.ScriptTarget.Latest, true,
+    ts.ScriptKind.ETS ?? ts.ScriptKind.TS);
+  const report = (source: any, position: number, reason: string, message: string): void => {
+    reportSourceDiagnostic(source, position, reason, message, reportDiagnostic);
+  };
+  if (typeof ts.isStructDeclaration !== 'function' || typeof ts.isEtsComponentExpression !== 'function') {
+    // Even a standard TypeScript parser retains real decorator nodes. Do not
+    // mistake @Entry text inside comments or strings for a page needing Replay.
+    const entryDecorator = findEntryDecorator(ts, preliminarySource);
+    if (entryDecorator) report(preliminarySource, entryDecorator.getStart(preliminarySource), 'unsupported-parser',
+      'The installed compiler does not expose the ArkTS struct/component parser required for automatic Replay roots.');
     return code;
   }
+  const source = parseApplicationSource(ts, id, code, preliminarySource);
+  const entries = collectEntryStructs(ts, source);
+  if (entries.length === 0 && !findEntryDecorator(ts, source)) return code;
+  if (reportSourceParseError(ts, source, reportDiagnostic)) return code;
 
   const identifiers = collectIdentifiers(code);
   const bridgeName = selectUniqueName(identifiers, '__ftSessionReplayAutoRootBridge');
@@ -287,10 +300,15 @@ export function transformSessionReplaySource(ts: TypeScriptApi, id: string, code
   entries.forEach((entry: EntryStruct): void => {
     const buildMethod = entry.methods.get('build');
     if (!buildMethod) {
+      report(source, entry.node.name.getStart(source), 'missing-build',
+        'The @Entry page has no build() method with a body to instrument.');
       return;
     }
     const root = findRootExpression(ts, source, code, buildMethod);
     if (root === null) {
+      const first = buildMethod.node.body.statements[0];
+      report(source, first ? first.getStart(source) : buildMethod.bodyStart + 1, 'unsupported-root',
+        'build() must start with a supported ArkUI root component with a child block for automatic Replay registration.');
       return;
     }
     const indentation = lineIndentation(code, buildMethod.nameStart);

package/hvigorCompile/ft-source-transform-host.ts

@@ -14,6 +14,7 @@ import {
 import { transformColdLaunchSource } from './ft-cold-launch-transform';
 import { transformSessionReplaySource } from './ft-session-replay-transform';
 import { transformWebReplaySource } from './ft-web-replay-transform';
+import { SourceDiagnosticReporter, SourceTransformDiagnostic } from './ft-transform-context';
 
 declare const require: {
   main: {
@@ -23,7 +24,8 @@ declare const require: {
 
 type TypeScriptApi = any;
 type SourceReader = (fileName: string) => string | undefined;
-type SourceTransform = (ts: TypeScriptApi, fileName: string, code: string, readSource?: SourceReader) => string;
+type SourceTransform = (ts: TypeScriptApi, fileName: string, code: string, readSource?: SourceReader,
+  reportDiagnostic?: SourceDiagnosticReporter) => string;
 
 interface CompilePluginContext {
   share: {
@@ -35,6 +37,8 @@ interface CompilePluginContext {
 
 interface SourceTransformDefinition {
   id: string;
+  prefix: string;
+  feature: string;
   transform: SourceTransform;
 }
 
@@ -43,14 +47,15 @@ interface SharedSourceTransformRegistry {
   buffer: any;
   transforms: Map<string, (fileName: string, code: string) => string>;
   owners: Map<object, Map<string, (fileName: string, code: string) => string>>;
+  reportedDiagnostics: Set<string>;
 }
 
 const SOURCE_TRANSFORM_REGISTRY_KEY = '__guanceHvigorSourceTransformRegistry';
 const SOURCE_TRANSFORMS: SourceTransformDefinition[] = [
-  { id: 'guance-console-log-transform', transform: transformConsoleLogSource },
-  { id: 'guance-cold-launch-transform', transform: transformColdLaunchSource },
-  { id: 'guance-session-replay-root-transform', transform: transformSessionReplaySource },
-  { id: 'guance-web-replay-transform', transform: transformWebReplaySource }
+  { id: 'guance-console-log-transform', prefix: 'GuanceLog', feature: 'console-log', transform: transformConsoleLogSource },
+  { id: 'guance-cold-launch-transform', prefix: 'GuanceColdLaunch', feature: 'cold-launch', transform: transformColdLaunchSource },
+  { id: 'guance-session-replay-root-transform', prefix: 'GuanceReplay', feature: 'session-replay-root', transform: transformSessionReplaySource },
+  { id: 'guance-web-replay-transform', prefix: 'GuanceWebReplay', feature: 'web-replay', transform: transformWebReplaySource }
 ];
 
 const registrations: Array<{ fileSystem: any; owner: object; context: CompilePluginContext }> = [];
@@ -60,6 +65,44 @@ function refreshTransforms(registry: SharedSourceTransformRegistry): void {
   registry.owners.forEach(transforms => transforms.forEach((transform, id) => registry.transforms.set(id, transform)));
 }
 
+function createDiagnosticReporter(registry: SharedSourceTransformRegistry, ts: TypeScriptApi,
+  readSource: SourceReader, definition: SourceTransformDefinition):
+  (diagnostic: SourceTransformDiagnostic, inputFile: string, inputCode: string, occurrence?: number) => void {
+  let logger: { warn(message: string): void } | undefined;
+  return (diagnostic: SourceTransformDiagnostic, inputFile: string, inputCode: string, occurrence = 0): void => {
+    // Earlier transforms can insert imports or wrappers. Recheck only failed
+    // pages against the on-disk source so clickable locations refer to app code.
+    const originalCode = readSource(diagnostic.fileName);
+    if (diagnostic.reason !== 'transform-exception' && diagnostic.fileName === inputFile &&
+      originalCode !== undefined && originalCode !== inputCode) {
+      const originalDiagnostics: SourceTransformDiagnostic[] = [];
+      try {
+        definition.transform(ts, diagnostic.fileName, originalCode, readSource, candidate => {
+          if (candidate.reason === diagnostic.reason &&
+            (candidate.message === diagnostic.message || candidate.reason === 'parse-error')) originalDiagnostics.push(candidate);
+        });
+      } catch (_) {
+        // Location mapping is diagnostic-only and must not change build behavior.
+      }
+      diagnostic = originalDiagnostics[occurrence] ?? { ...diagnostic,
+        message: `${diagnostic.message} (Location refers to in-memory transformed source.)` };
+    }
+    const key = `${definition.id}:${JSON.stringify(diagnostic)}`;
+    if (registry.reportedDiagnostics.has(key)) return;
+    registry.reportedDiagnostics.add(key);
+    const message = `[GuanceBuild][${definition.prefix}] ${diagnostic.fileName}:${diagnostic.line}:${diagnostic.column}: ` +
+      `feature=${definition.feature}; reason=${diagnostic.reason}; ${diagnostic.message}`;
+    if (!logger) {
+      try {
+        logger = require.main.require('@ohos/hvigor').HvigorLogger.getLogger(definition.prefix);
+      } catch (_) {
+        logger = { warn: (value: string): void => console.warn(value) };
+      }
+    }
+    logger!.warn(message);
+  };
+}
+
 function installSourceReader(context: CompilePluginContext): void {
   const typeScriptPath = `${context.share.projectConfig.etsLoaderPath}/node_modules/typescript`;
   const ts = require.main.require(typeScriptPath);
@@ -70,7 +113,8 @@ function installSourceReader(context: CompilePluginContext): void {
       originalReadFile: fileSystem.readFileSync as (fileName: string, options?: any) => any,
       buffer: require.main.require('buffer'),
       transforms: new Map<string, (fileName: string, code: string) => string>(),
-      owners: new Map()
+      owners: new Map(),
+      reportedDiagnostics: new Set()
     };
     fileSystem[SOURCE_TRANSFORM_REGISTRY_KEY] = registry;
     fileSystem.readFileSync = (fileName: string, options?: any): any => {
@@ -93,11 +137,33 @@ function installSourceReader(context: CompilePluginContext): void {
       return undefined;
     }
   };
+  // A daemon may retain a registry installed by an earlier plugin version.
+  registry.reportedDiagnostics ??= new Set();
   const owner = {};
   const transforms = new Map<string, (fileName: string, code: string) => string>();
   SOURCE_TRANSFORMS.forEach((definition: SourceTransformDefinition) => {
-    transforms.set(definition.id, (fileName: string, code: string) =>
-      definition.transform(ts, fileName, code, readSource));
+    const reportDiagnostic = createDiagnosticReporter(registry!, ts, readSource, definition);
+    transforms.set(definition.id, (fileName: string, code: string) => {
+      const occurrences = new Map<string, number>();
+      try {
+        return definition.transform(ts, fileName, code, readSource,
+          diagnostic => {
+            const key = `${diagnostic.reason}:${diagnostic.message}`;
+            const occurrence = occurrences.get(key) ?? 0;
+            occurrences.set(key, occurrence + 1);
+            reportDiagnostic(diagnostic, fileName, code, occurrence);
+          });
+      } catch (error) {
+        try {
+          reportDiagnostic({ fileName, line: 1, column: 1, reason: 'transform-exception',
+            message: `Source transform failed: ${error instanceof Error ? error.message : String(error)}` }, fileName, code);
+        } finally {
+          // Preserve the original failure: diagnostics must never turn a broken
+          // transform into a successful build or replace its exception.
+          throw error;
+        }
+      }
+    });
   });
   registry.owners.set(owner, transforms);
   refreshTransforms(registry);

package/hvigorCompile/ft-transform-context.ts

@@ -3,6 +3,61 @@ declare const require: any;
 
 export type SourceReader = (fileName: string) => string | undefined;
 
+export interface SourceTransformDiagnostic {
+  fileName: string;
+  line: number;
+  column: number;
+  reason: string;
+  message: string;
+}
+
+export type SourceDiagnosticReporter = (diagnostic: SourceTransformDiagnostic) => void;
+
+export function reportSourceDiagnostic(source: any, position: number, reason: string, message: string,
+  reporter?: SourceDiagnosticReporter): void {
+  if (!reporter) return;
+  const location = source.getLineAndCharacterOfPosition(position);
+  reporter({ fileName: source.fileName, line: location.line + 1, column: location.character + 1, reason, message });
+}
+
+/** Parse declarative child blocks without treating enum members as components. */
+export function parseApplicationSource(ts: any, id: string, code: string, preliminary?: any): any {
+  const source = preliminary ?? ts.createSourceFile(id, code, ts.ScriptTarget.Latest, true,
+    ts.ScriptKind.ETS ?? ts.ScriptKind.TS);
+  if (!id.endsWith('.ets') || typeof ts.isStructDeclaration !== 'function' ||
+    typeof ts.isEtsComponentExpression !== 'function') return source;
+  const names = new Set<string>();
+  const visit = (node: any): void => {
+    if ((ts.isCallExpression(node) || ts.isEtsComponentExpression(node)) && ts.isIdentifier(node.expression)) {
+      names.add(node.expression.text);
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  const components = Array.from(names).filter(name => !['ForEach', 'LazyForEach', 'Repeat'].includes(name));
+  return ts.createSourceFile(id, code, ts.ScriptTarget.Latest, true, ts.ScriptKind.ETS, { ets: {
+    components,
+    render: { method: ['build', 'pageTransition'], decorator: ['Builder', 'LocalBuilder'] },
+    extend: { decorator: ['Extend', 'AnimatableExtend'], components: components.map(name =>
+      ({ name, type: `${name}Attribute`, instance: `${name}Instance` })) },
+    styles: { decorator: 'Styles', component: { name: 'Common', type: 'T', instance: 'CommonInstance' }, property: 'stateStyles' },
+    concurrent: { decorator: 'Concurrent' },
+    customComponent: 'CustomComponent',
+    syntaxComponents: { paramsUICallback: ['ForEach', 'LazyForEach'],
+      attrUICallback: [{ name: 'Repeat', attributes: ['each', 'template'] }] }
+  } });
+}
+
+export function reportSourceParseError(ts: any, source: any, reporter?: SourceDiagnosticReporter): boolean {
+  if (source.parseDiagnostics.length === 0) return false;
+  const diagnostic = source.parseDiagnostics[0];
+  const remaining = source.parseDiagnostics.length - 1;
+  reportSourceDiagnostic(source, diagnostic.start ?? 0, 'parse-error',
+    `TS${diagnostic.code}: ${ts.flattenDiagnosticMessageText(diagnostic.messageText, ' ')}${
+      remaining > 0 ? ` (${remaining} additional parse errors)` : ''}`, reporter);
+  return true;
+}
+
 export function objectProperty(ts: any, object: any, name: string): any | undefined {
   if (!object || !ts.isObjectLiteralExpression(object)) return undefined;
   const matches = object.properties.filter((item: any) => ts.isPropertyAssignment(item) &&

package/hvigorCompile/ft-web-replay-transform.ts

@@ -1,6 +1,7 @@
 /** Associate every native Web with its controller without replacing application IDs or callbacks. */
 import { isApplicationArkTsSource } from './ft-console-log-transform';
-import { hasRuntimeDependency, SourceReader } from './ft-transform-context';
+import { hasRuntimeDependency, SourceReader, SourceDiagnosticReporter, parseApplicationSource,
+  reportSourceDiagnostic, reportSourceParseError } from './ft-transform-context';
 import { createLexicalResolver } from './ft-lexical-scope';
 import { allocateName, collectIdentifierNames } from './ft-generated-names';
 
@@ -10,7 +11,8 @@ interface Injection { position: number; content: string; }
 const MARKER = '/* guance-web-replay-transform:instrumented */';
 const SDK_IMPORT = '@guancecloud/ft_sdk/Index';
 
-export function transformWebReplaySource(ts: TypeScriptApi, id: string, code: string, readSource?: SourceReader): string {
+export function transformWebReplaySource(ts: TypeScriptApi, id: string, code: string, readSource?: SourceReader,
+  reportDiagnostic?: SourceDiagnosticReporter): string {
   if (!isApplicationArkTsSource(id) || code.includes(MARKER) ||
     !hasRuntimeDependency(ts, id, '@guancecloud/ft_sdk', readSource) ||
     !hasRuntimeDependency(ts, id, '@guancecloud/ft_session_replay', readSource)) return code;
@@ -18,16 +20,24 @@ export function transformWebReplaySource(ts: TypeScriptApi, id: string, code: st
   const source = ts.createSourceFile(id, code, ts.ScriptTarget.Latest, true, ts.ScriptKind.ETS ?? ts.ScriptKind.TS);
   const identifiers = collectIdentifierNames(ts, source);
   const constructors: any[] = [];
+  const unsupported: any[] = [];
   const resolve = createLexicalResolver(ts, source);
   let importEnd = 0;
   const visit = (node: any): void => {
     if (ts.isImportDeclaration(node)) importEnd = Math.max(importEnd, node.end);
     if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === 'Web' &&
-      node.arguments.length === 1 && !ts.isSpreadElement(node.arguments[0]) &&
-      !resolve(node.expression, 'Web')) constructors.push(node);
+      !resolve(node.expression, 'Web')) {
+      if (node.arguments.length === 1 && !ts.isSpreadElement(node.arguments[0]) &&
+        !(ts.isOptionalChain && ts.isOptionalChain(node))) constructors.push(node);
+      else unsupported.push(node);
+    }
     ts.forEachChild(node, visit);
   };
   visit(source);
+  if (constructors.length === 0 && unsupported.length === 0) return code;
+  if (reportSourceParseError(ts, parseApplicationSource(ts, id, code), reportDiagnostic)) return code;
+  unsupported.forEach(node => reportSourceDiagnostic(source, node.getStart(source), 'unsupported-web-call',
+    'Automatic ArkWeb binding requires a non-optional Web(options) call with exactly one non-spread argument.', reportDiagnostic));
   if (constructors.length === 0) return code;
 
   const bridge = allocateName(identifiers, '__ftWebReplayBridge');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudcare/hvigor-ohos-plugin",
-  "version": "0.1.2-alpha.1",
+  "version": "0.1.2-alpha.2",
   "description": "Guance HarmonyOS Hvigor plugin for console, cold-launch, Session Replay page roots, and Web controller binding.",
   "main": "index.js",
   "files": [