references/grounding.md
You are an expert code reviewer specializing in Lightning Web Components (LWC) that must run in the **Salesforce Mobile App Plus** and **Field Service Mobile App** in offline mode. The Komaci static-analysis engine pre-primes the data graph for offline use; certain LWC patterns prevent priming and must be flagged with actionable remediations.
Your reviews focus on three categories:
1. **Conditional rendering compatibility** — modern `lwc:if` / `lwc:elseif` / `lwc:else` directives are incompatible with Komaci priming and must be rewritten as legacy `if:true` / `if:false` branches.
2. **GraphQL wire configuration** — inline GraphQL queries in `@wire` configurations prevent Komaci from understanding the data graph; queries must be extracted to a getter on the component class.
3. **Komaci ESLint rule violations** — the `@salesforce/eslint-plugin-lwc-graph-analyzer` plugin exposes a recommended rule set that catches additional priming-blockers (private wire properties, non-local reactive references, getter side-effects, etc.).
references/inline-graphql.md
# Inline GraphQL Wire Configuration
## Framework for the analysis
The Komaci offline static analysis engine requires GraphQL queries to be **extracted from `@wire` adapter configurations into separate getter methods** for proper offline data priming. Inline GraphQL query strings within `@wire` adapter calls prevent the static analysis engine from understanding and optimizing data dependencies for offline scenarios.
**FOCUS:** Only report improper usage of GraphQL queries and variables accessed outside of a component getter function. Do not provide feedback on any other adapter use.
Key points to consider:
- GraphQL queries and variables MUST be accessed from a getter function within the component class.
- GraphQL queries MUST NOT be inlined in the wire adapter configuration object.
- GraphQL variables MUST NOT be inlined in the wire adapter configuration object.
- GraphQL queries MUST NOT be defined as top-level constants.
- GraphQL variables MUST NOT be defined as top-level constants.
- If the query is already in a getter function, do not provide feedback.
- If the component does not use GraphQL, does not import GraphQL, does not use `@wire`, or does not contain a query in a `gql` template literal, do not provide feedback or analyze further.
## Request
Review the JavaScript files for `@wire` decorators with inline GraphQL queries:
1. Identify `@wire` decorators that use GraphQL wire adapters.
2. Look for literal GraphQL query strings within the wire configuration objects.
3. Check for template literals or string literals containing GraphQL syntax.
4. Analyze the complexity and reusability of the inline queries.
5. Determine appropriate getter method names for extracted queries.
6. Validate that extraction will not break existing functionality.
7. Report each violation with specific refactoring guidance.
For each violation, provide a strong suggested action that names a concrete getter — e.g. _"The query MUST be extracted into a getter function called `fooQuery` and accessed by the config `@wire(graphql, { query: '$fooQuery' })`."_
Rules to follow:
- If no action is required, return an empty list. Do not return null or any other value — return an empty array.
- Keep issues concise; avoid duplicated issues or unnecessary analysis for things that are not real violations.
- Stick to the instructions for the specific reviewer in scope. Issues outside that scope will be analyzed by other reviewers.
- For each violation, provide:
- The exact violation type as defined by the reviewer in scope.
- A description of why it is a problem in the context of mobile offline priming.
- An intent analysis explaining what the developer likely intended.
- A suggested action with concrete code-level remediation.
- Do not make assumptions about other components that may be referenced.
references/komaci-eslint.md
# Komaci ESLint Static Analysis (`@salesforce/eslint-plugin-lwc-graph-analyzer`)
## Framework for the analysis
The Komaci offline analyzer is exposed as the ESLint plugin `@salesforce/eslint-plugin-lwc-graph-analyzer`. Its **recommended** ruleset catches LWC patterns that prevent offline data priming. This reviewer runs the plugin against the component's JS file and translates each lint message into an actionable remediation.
Use the documented per-rule remediations below — do not invent new ones — and only emit findings for rules that actually fired against the file in scope.
The recommended preset enables ~36 rules; only the 7 rules documented in **Per-rule remediation** below are surfaced as findings. Other recommended-preset rules (e.g. `no-eval-usage`, `no-functions-declared-within-getter-method`) may fire but are intentionally not mapped to remediations and must be dropped from the report.
## How to run the analyzer
Use the bundled script. It applies the plugin's recommended ruleset with the `bundleAnalyzer` processor enabled, and on first run installs the pinned versions of `@salesforce/eslint-plugin-lwc-graph-analyzer` and `eslint` into `scripts/node_modules` so the runner is isolated from whatever versions the host project happens to ship.
```bash
scripts/run-komaci.sh path/to/component/component.js
```
Prerequisites:
- The component's sibling HTML templates must live in the same directory as the JS file. The plugin's `bundleAnalyzer` processor discovers them automatically (via `readdirSync` on the bundle directory) and uses them to resolve the offline data graph across the bundle.
- A working `npm` and Node ≥ 18 on `PATH` for the first-run install.
The script emits ESLint's `--format json` output on stdout. Each `messages[*]` entry has `ruleId`, `severity`, `message`, `line`, `column`, `endLine`, `endColumn`, and `fix` (optional). Group messages by `ruleId`, then apply the per-rule remediation guidance below.
To run ESLint manually outside the script — using the same pinned versions, so the recommended config resolves to the flat-config-shaped form — install once and invoke the local binary:
```bash
cd scripts
npm install # only on first run
node_modules/.bin/eslint \
--no-config-lookup \
--config komaci.config.mjs \
--format json \
path/to/component/component.js
```
`scripts/komaci.config.mjs` and `scripts/package.json` ship together; the package pin (`@salesforce/eslint-plugin-lwc-graph-analyzer ^1.1.0-beta.2`, `eslint ^9.35.0`) ensures the plugin's `recommended` config is flat-config-shaped (no legacy `extends:` key).
## Per-rule remediation
For each rule below, the `Type`, `Description`, `Intent analysis`, and `Suggested action` strings are canonical and must be emitted unchanged in the finding. Do not paraphrase or augment them.
### `@salesforce/lwc-graph-analyzer/no-private-wire-config-property`
- **Type:** Private Wire Configuration Property
- **Description:** Properties used in wire configurations must be decorated with `@api` to be public and resolvable by the wire service.
- **Intent analysis:** The developer used properties in wire configurations without making them public using the `@api` decorator.
- **Suggested action:**
Make the properties public by using the `@api` decorator:
- Add `@api` decorator to properties used in wire configurations.
### `@salesforce/lwc-graph-analyzer/no-wire-config-references-non-local-property-reactive-value`
- **Type:** Wire Configuration References Non-Local Property
- **Description:** Wire configurations with reactive values (`$prop`) must reference only component properties, not imported values or values defined outside the component class.
- **Intent analysis:** The developer is trying to use a non-local value (imported or module-level) as a reactive parameter in a wire configuration.
- **Suggested action:** Wrap the non-local value in a getter:
- Introduce a getter which returns the imported value or the value of a module-level constant.
- Update the wire configuration to use the getter name as the reactive parameter.
```js
// Instead of:
@wire(getData, { param: '$importedValue' })
// Use:
get localValue() {
return importedValue;
}
@wire(getData, { param: '$localValue' })
```
### Getter-related violations
The five rules below all share the **Violations in Getter** classification and emit the same `description`, `intentAnalysis`, and `suggestedAction`. When any of them fires, emit one finding per (rule, line) pair with the strings reproduced below.
Rules:
- `@salesforce/lwc-graph-analyzer/no-assignment-expression-assigns-value-to-member-variable`
- `@salesforce/lwc-graph-analyzer/no-reference-to-class-functions`
- `@salesforce/lwc-graph-analyzer/no-reference-to-module-functions`
- `@salesforce/lwc-graph-analyzer/no-getter-contains-more-than-return-statement`
- `@salesforce/lwc-graph-analyzer/no-unsupported-member-variable-in-member-expression`
Canonical fields:
- **Type:** Violations in Getter
- **Description:** A getter method does more than just returning a value
- **Intent analysis:** The developer attempted to modify component state, prepare data for consumption, or reference functions within a getter function.
- **Suggested action:**
**Compliant getter implementations**
Getters that:
- Directly access and return property values
- Return a literal value
- Compute and return values derived from existing properties
**Non-compliant getter implementations**
- **Violation: getters that call functions.** Getters that call functions cannot be primed for offline use cases.
*Remediation:* Reorganize any getter implementation code that calls a function, to move such calls out of the getter. Avoid invoking any function calls within getters.
- **Violation: getters with side effects.** Getters that assign values to member variables or modify state create unpredictable side effects and are not suitable for offline scenarios.
*Remediation:* Never assign values to member variables within a getter. LWC getters should only retrieve data without modifying any state. If you need to compute and cache a value, perform the computation and assignment in a lifecycle hook or method, then have the getter simply return the cached value.
- **Violation: getters that do more than just return a value.** Getters that perform complex operations beyond returning a value cannot be primed for offline use cases.
*Remediation:* Review the getters and make sure that they're composed to only return a value. Move any complex logic, data processing, or multiple operations into separate methods or lifecycle hooks, and have the getter simply return the result.
## Rules to follow
- If no action is required, return an empty list. Do not return null or any other value — return an empty array.
- Keep issues concise; avoid duplicated issues or unnecessary analysis for things that are not real violations.
- Stick to the instructions for the specific reviewer in scope. Issues outside that scope will be analyzed by other reviewers.
- For each violation, provide:
- `type` — verbatim from the rule entry above.
- `description` — verbatim from the rule entry above.
- `intentAnalysis` — verbatim from the rule entry above.
- `suggestedAction` — verbatim from the rule entry above.
- `filePath` — the path passed to ESLint.
- `location` — `{ startLine, startColumn, endLine, endColumn }` taken from the ESLint message's `line`, `column`, `endLine`, `endColumn`.
- `code` — *optional* — the source snippet from `startLine` through `endLine`, useful when the violation spans multiple lines.
- Drop messages whose `ruleId` is not in the seven rules above.
- Do not make assumptions about other components that may be referenced.
references/lwc-if.md
# Conditional Rendering Compatibility (`lwc:if` → `if:true`/`if:false`)
## Framework for the analysis
The Komaci offline static analysis engine used by Salesforce Mobile App Plus and Field Service Mobile App does not support modern conditional rendering directives (`lwc:if={property}`, `lwc:elseif={property}`, `lwc:else`). These directives must be replaced with `if:true={property}` and `if:false={property}` to ensure compatibility with offline data priming.
Your task:
1. Inspect HTML.
2. Identify any usage of `lwc:if={property}`, `lwc:elseif={property}`, or `lwc:else`.
3. Recommend exactly how to replace them with `if:true` / `if:false` directives, preserving the original branching logic.
**FOCUS:**
- Only analyze and provide feedback on occurrences of `lwc:if={property}`, `lwc:elseif={property}`, and `lwc:else`.
- Ignore any other directives or potential issues unrelated to those three.
## Conversion rules
- **`lwc:if={property}`** → replace with `if:true={property}`.
- **`lwc:elseif={property}`** → typically requires a nested `if:false={previousCondition}` that wraps an `if:true={property}`.
- **`lwc:else`** → has no condition of its own, so it must be wrapped by `if:false={previousCondition}` (the inverse of the relevant condition chain).
- **Standalone `lwc:if`** (not followed by `lwc:elseif`/`lwc:else`) → still must be replaced with `if:true={property}`.
- **Multiple condition chains** → review every template; do not stop at the first occurrence.
## Conversion example
`before.html`:
```html
<template>
<template lwc:if="{conditionOne}">
<div>show condition one</div>
</template>
<template lwc:elseif="{conditionTwo}">
<div>show condition two</div>
</template>
<template lwc:else>
<div>show default condition</div>
</template>
</template>
```
`after.html`:
```html
<template>
<template if:true="{conditionOne}">
<div>show condition one</div>
</template>
<template if:false="{conditionOne}">
<template if:true="{conditionTwo}">
<div>show condition two</div>
</template>
<template if:false="{conditionTwo}">
<div>show default condition</div>
</template>
</template>
</template>
```
The proper review feedback for the example above:
- replace `lwc:if={conditionOne}` with `if:true={conditionOne}`
- replace `lwc:elseif={conditionTwo}` with `if:false={conditionOne}`, then create a nested template with `if:true={conditionTwo}` wrapping the remainder of the component
- replace `lwc:else` with `if:false={conditionTwo}`
Rules to follow:
- If no action is required, return an empty list. Do not return null or any other value — return an empty array.
- Keep issues concise; avoid duplicated issues or unnecessary analysis for things that are not real violations.
- Stick to the instructions for the specific reviewer in scope. Issues outside that scope will be analyzed by other reviewers.
- For each violation, provide:
- The exact violation type as defined by the reviewer in scope.
- A description of why it is a problem in the context of mobile offline priming.
- An intent analysis explaining what the developer likely intended.
- A suggested action with concrete code-level remediation.
- Do not make assumptions about other components that may be referenced.
scripts/komaci.config.mjs
// ESLint flat config for the Komaci offline static analyzer.
// Applies the recommended ruleset from
// @salesforce/eslint-plugin-lwc-graph-analyzer with the bundleAnalyzer
// processor wired in via the recommended config.
import lwcGraphAnalyzerPlugin from '@salesforce/eslint-plugin-lwc-graph-analyzer';
const PLUGIN_NAME = '@salesforce/lwc-graph-analyzer';
const RECOMMENDED = lwcGraphAnalyzerPlugin.configs.recommended;
export default [
{
name: `config: ${PLUGIN_NAME}`,
plugins: {
[PLUGIN_NAME]: lwcGraphAnalyzerPlugin,
},
...RECOMMENDED,
},
];
scripts/package.json
{
"name": "mobile-platform-offline-validate-runner",
"private": true,
"description": "Pinned ESLint + Komaci plugin used by run-komaci.sh.",
"type": "module",
"dependencies": {
"@salesforce/eslint-plugin-lwc-graph-analyzer": "^1.1.0-beta.2",
"eslint": "^9.35.0"
}
}
scripts/run-komaci.sh
#!/usr/bin/env bash
#
# Komaci offline static analysis runner
#
# Runs @salesforce/eslint-plugin-lwc-graph-analyzer against an LWC bundle
# with the plugin's recommended ruleset and emits ESLint's JSON
# formatter output on stdout.
#
# The plugin's `bundleAnalyzer` processor expects the JS file to live
# next to its sibling HTML templates so the offline data graph can be
# resolved across the bundle.
#
# Plugin + ESLint versions are pinned in scripts/package.json and
# installed into scripts/node_modules on first run so the runner is
# isolated from whatever versions the host project happens to ship.
#
# Usage:
# run-komaci.sh path/to/component.js
#
# Arguments:
# $1 Path to the LWC component's JS file (required). The component's
# sibling HTML templates must live in the same directory; the
# plugin discovers them automatically via the bundle processor.
#
# Environment:
# KOMACI_ESLINT_BIN Override the eslint binary (default: scripts/node_modules/.bin/eslint)
#
# Output:
# ESLint --format json on stdout. Non-zero exit if eslint reports
# errors; the JSON is still emitted on stdout in either case.
set -euo pipefail
if [ $# -lt 1 ]; then
echo "Usage: $0 path/to/component.js" >&2
exit 2
fi
JS_PATH="$1"
if [ ! -f "$JS_PATH" ]; then
echo "Error: $JS_PATH does not exist" >&2
exit 2
fi
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
CONFIG_PATH="$SCRIPT_DIR/komaci.config.mjs"
PLUGIN_DIR="$SCRIPT_DIR/node_modules/@salesforce/eslint-plugin-lwc-graph-analyzer"
# Install the pinned ESLint + plugin versions on first run. We resolve
# them from SCRIPT_DIR so Node ESM picks up the right copy regardless
# of the caller's cwd or the host project's node_modules.
if [ ! -d "$PLUGIN_DIR" ]; then
echo "Installing pinned Komaci runner deps in $SCRIPT_DIR ..." >&2
(cd "$SCRIPT_DIR" && npm install --no-fund --no-save --silent) >&2
fi
ESLINT="${KOMACI_ESLINT_BIN:-$SCRIPT_DIR/node_modules/.bin/eslint}"
# Run eslint with the plugin's recommended config and emit JSON.
# `--no-config-lookup` ignores any host-project ESLint config so only
# the Komaci recommended ruleset applies; `--no-error-on-unmatched-pattern`
# avoids hard failure if the component path is empty.
$ESLINT \
--no-config-lookup \
--no-error-on-unmatched-pattern \
--config "$CONFIG_PATH" \
--format json \
"$JS_PATH"
SKILL.md
---
name: mobile-platform-offline-validate
description: "Review a Lightning Web Component for **mobile offline** compatibility — the Komaci offline static analyzer that pre-primes the data graph for Salesforce Mobile App Plus and Field Service Mobile App. Produces a finding list with code-level fixes covering inline GraphQL queries in `@wire` configurations, modern `lwc:if` / `lwc:elseif` / `lwc:else` directives, and Komaci ESLint rule violations (private wire properties, non-local reactive references, getter side-effects). Use when the user asks for a \"mobile offline review\", \"Komaci check\", \"offline priming audit\", \"offline priming failure\", or \"offline data graph error\", or to validate an LWC against the `@salesforce/eslint-plugin-lwc-graph-analyzer` recommended ruleset. Do not use for generic LWC code review (use an appropriate domain review skill) or for building LWCs with native mobile capabilities (use `mobile-platform-native-capabilities-integrate`)."
metadata:
version: "1.0"
domains: ["Mobile"]
relatedSkills:
- "mobile-platform-native-capabilities-integrate"
cliTools:
- tool: ["eslint"]
semver: ">=8.0.0"
- tool: ["npm"]
semver: ">=9.0.0"
- tool: ["npx"]
semver: ">=9.0.0"
---
# Reviewing LWC Mobile Offline
Run a structured offline-priming compliance pass over a Lightning Web
Component, producing a report of issues found and code-level fixes to bring
the component into compliance with Komaci's static analysis requirements
for the Salesforce Mobile App Plus and Field Service Mobile App.
## When to Use
- The user asks for a "mobile offline review", "Komaci check", or "offline
priming audit" on a specific LWC.
- Preparing a component to ship in Salesforce Mobile App Plus or Field
Service Mobile App offline mode.
- Investigating priming failures reported by the offline analyzer.
Do NOT use this skill for:
- Building an LWC that uses native mobile capabilities (barcode scanner,
biometrics, location, etc.) — use `mobile-platform-native-capabilities-integrate`.
- Generic LWC code review — use the appropriate domain skill
(`reviewing-lws-security`, `reviewing-lwc-rtl`, `accessibility-code-review`).
## Prerequisites
- Component path (LWC bundle under `modules/…`).
- Access to the component's JS/TS and HTML templates.
- Local Node + npm; ability to run `npx eslint` with the
`@salesforce/eslint-plugin-lwc-graph-analyzer` plugin.
## Knowledge Base
[Mobile Offline Grounding](references/grounding.md) explains the three
violation categories and why each blocks offline priming. Read it before
judging. The per-reviewer references below are the source of truth for the
rules and remediations:
- Inline GraphQL wire configuration: [Inline GraphQL Reviewer](references/inline-graphql.md)
- `lwc:if` conditional rendering compatibility: [lwc:if Reviewer](references/lwc-if.md)
- Komaci ESLint static analysis: [Komaci ESLint Reviewer](references/komaci-eslint.md)
## Workflow
### Step 1 — Scope the review
Identify the component bundle: `.html`, `.js`/`.ts`. CSS and meta files are
not in scope for offline priming. If the bundle has multiple HTML
templates, all are reviewed.
### Step 2 — Read the grounding and per-reviewer references
Read [Mobile Offline Grounding](references/grounding.md) and the three
per-reviewer references end-to-end before judging. Cite the specific
reviewer when emitting each finding so the report is auditable.
### Step 3 — `lwc:if` / `lwc:elseif` / `lwc:else` (HTML)
Walk every `.html` file in the bundle and apply the rules in
[lwc:if Reviewer](references/lwc-if.md). For each occurrence of
`lwc:if={…}`, `lwc:elseif={…}`, or `lwc:else`, emit a finding with the
exact `if:true` / `if:false` rewrite — including the nesting required to
preserve `lwc:elseif` and `lwc:else` semantics.
### Step 4 — Inline GraphQL in `@wire` (JS)
Walk every `.js`/`.ts` file in the bundle and apply the rules in
[Inline GraphQL Reviewer](references/inline-graphql.md). For each `@wire`
that references a `gql` template literal directly (or via a top-level
constant), emit a finding that names a concrete getter and shows the
rewritten `@wire` configuration.
### Step 5 — Komaci ESLint pass (JS)
Run the Komaci ESLint analyzer over the bundle's JS file using the
bundled script. It applies the
`@salesforce/eslint-plugin-lwc-graph-analyzer` recommended ruleset with
the `bundleAnalyzer` processor enabled.
```bash
scripts/run-komaci.sh path/to/component.js
```
The script requires `@salesforce/eslint-plugin-lwc-graph-analyzer` to
be resolvable from the working directory, and the component's sibling
HTML templates must live next to the JS file (the plugin's
`bundleAnalyzer` processor uses them to resolve the offline data
graph). Output is ESLint `--format json` on stdout.
For each `messages[*]` entry in the output, group by `ruleId` and look
up the per-rule remediation in
[Komaci ESLint Reviewer](references/komaci-eslint.md). Emit a finding
per (rule, line) pair with the exact remediation text from the
reference; do not invent new advice. See the reference for the manual
`npx eslint ...` invocation if the script is unavailable in the runtime
environment.
### Step 6 — Produce the report
Emit a report in this shape:
```text
## Mobile Offline (Komaci priming)
- <reviewer> — <file>:<startLine>:<startColumn>-<endLine>:<endColumn> — <type>
Description: <verbatim from the reviewer reference>
Intent analysis: <verbatim from the reviewer reference>
Suggested action: <verbatim from the reviewer reference>
Code: |
<source snippet from startLine through endLine, optional but
recommended when the violation spans multiple lines>
Applied: yes/no
## Summary
- <n> issues found; <m> fixed; <k> deferred (with reason)
```
For Komaci ESLint findings, take `startLine`/`startColumn`/`endLine`/
`endColumn` from the ESLint message's `line`/`column`/`endLine`/`endColumn`.
For Inline GraphQL and `lwc:if` findings, supply the line/column range you
observed in the source. If `endLine`/`endColumn` are not available for a
finding, fall back to `<file>:<startLine>` and omit the trailing range.
Cite the reviewer (Inline GraphQL / lwc:if / Komaci ESLint rule id) on every
finding.
### Step 7 — Apply fixes
Apply the remediations directly when the user asked for fixes. If a
remediation conflicts with the component's behavior outside offline (e.g.
the developer relies on `lwc:elseif` for readability and the user is not
yet shipping to mobile offline), surface the conflict in the deferred list
rather than silently rewriting.
## Verification Checklist
- [ ] Every `lwc:if` / `lwc:elseif` / `lwc:else` flagged or absent.
- [ ] Every `@wire` referencing `gql` checked; inline queries extracted to
a getter.
- [ ] Komaci ESLint analyzer was actually run; findings cite real rule
ids, not invented ones.
- [ ] Each finding cites the originating reviewer or rule id.
- [ ] No remediation outside the three categories above (other concerns
belong to other skills).
## Troubleshooting
- **`npx eslint` cannot find the plugin** — install
`@salesforce/eslint-plugin-lwc-graph-analyzer` in the workspace, or use a
pinned local install path. The plugin is the canonical source of Komaci
rules.
- **`bundleAnalyzer` related errors** — the recommended config drives the
bundle processor; do not strip it. The processor expects sibling HTML
files to be discoverable. If running on a stripped-down JS file, supply
the matching HTML in the temp directory.
- **No findings for a component you expect to fail** — confirm the
recommended ruleset is applied (not just `bundleAnalyzer` with empty
rules). Some rules require the HTML to be present alongside the JS.
- **Findings duplicate `lwc:if` from the dedicated reviewer** — the Komaci
plugin does not check templates; the `lwc:if` check is HTML-only and
comes from Step 3. Findings from Step 5 are JS-only.