@salesforce/afv-skills 1.34.0 → 1.35.0

package/skills/experience-lwc-rtl-validate/scripts/scan-rtl-css.sh

@@ -0,0 +1,206 @@
+#!/usr/bin/env bash
+# Deterministic RTL CSS scanner.
+#
+# Emits one line per physical-CSS declaration in the given files, in the form:
+#   <file>:<line>: <property>: <value> -> <logical-property>: <logical-value>
+#
+# Each output line is a raw finding the caller translates into a
+# Step 6 report bullet (see SKILL.md).
+#
+# Usage:
+#   scripts/scan-rtl-css.sh <file1> [<file2> ...]
+#
+# Recognised patterns (CSS declarations only — HTML `class="…"` is NEVER scanned):
+#   left / right                          -> inset-inline-start / inset-inline-end
+#   margin-left / margin-right            -> margin-inline-start / margin-inline-end
+#   padding-left / padding-right          -> padding-inline-start / padding-inline-end
+#   text-align: left / right              -> text-align: start / end
+#   border-left-* / border-right-*        -> border-inline-start-* / border-inline-end-*
+#   float: left / float: right            -> float: inline-start / float: inline-end
+#   transform: translateX(...)            -> flag; needs sign-flip or logical alternative
+#
+# The scanner tokenizes declarations (split on `;` within braces) so a single
+# minified line with multiple declarations produces one finding per physical
+# declaration. It never rewrites selectors — only the `property: value` half
+# of each declaration is transformed.
+#
+# Exit codes:
+#   0 — scan completed (findings on stdout may be empty; that IS a valid result)
+#   2 — usage error
+
+set -euo pipefail
+
+if [ "$#" -lt 1 ]; then
+  echo "usage: $0 <file1> [<file2> ...]" >&2
+  exit 2
+fi
+
+python3 - "$@" <<'PY'
+import re
+import sys
+
+# Direct property renames (physical -> logical). Value is preserved verbatim.
+PROP_RENAMES = {
+    "margin-left": "margin-inline-start",
+    "margin-right": "margin-inline-end",
+    "padding-left": "padding-inline-start",
+    "padding-right": "padding-inline-end",
+    "left": "inset-inline-start",
+    "right": "inset-inline-end",
+}
+
+# `border-left*` / `border-right*` prefix rewrites (keeps the suffix).
+BORDER_PREFIXES = {
+    "border-left": "border-inline-start",
+    "border-right": "border-inline-end",
+}
+
+# Property/value pairs where the value is the physical keyword to swap.
+VALUE_KEYWORDS = {
+    "text-align": {"left": "start", "right": "end"},
+    "float": {"left": "inline-start", "right": "inline-end"},
+}
+
+DECL_RE = re.compile(r"^\s*([a-zA-Z-]+)\s*:\s*(.*?)\s*$")
+
+def emit(path, lineno, msg):
+    print(f"{path}:{lineno}: {msg}")
+
+def scan_declaration(path, lineno, decl):
+    """Analyse a single `property: value` declaration."""
+    m = DECL_RE.match(decl)
+    if not m:
+        return
+    prop = m.group(1).lower()
+    value = m.group(2)
+    if not value:
+        return
+
+    # Direct property renames (value preserved verbatim).
+    if prop in PROP_RENAMES:
+        emit(path, lineno, f"{prop}: {value} -> {PROP_RENAMES[prop]}: {value}")
+        return
+
+    # border-left* / border-right* (with optional -color / -width / -style / etc).
+    for prefix, replacement in BORDER_PREFIXES.items():
+        if prop == prefix or prop.startswith(prefix + "-"):
+            new_prop = replacement + prop[len(prefix):]
+            emit(path, lineno, f"{prop}: {value} -> {new_prop}: {value}")
+            return
+
+    # text-align / float — swap the physical keyword in the value.
+    if prop in VALUE_KEYWORDS:
+        for phys, logical in VALUE_KEYWORDS[prop].items():
+            # Match the keyword as a whole token, case-insensitive.
+            if re.search(rf"\b{phys}\b", value, re.IGNORECASE):
+                new_value = re.sub(
+                    rf"\b{phys}\b", logical, value, count=1, flags=re.IGNORECASE
+                )
+                emit(path, lineno, f"{prop}: {value} -> {prop}: {new_value}")
+                return
+
+    # transform: translateX(...) — flag for review.
+    if prop == "transform" and re.search(r"\btranslateX\s*\(", value):
+        emit(
+            path,
+            lineno,
+            f"{prop}: {value}  # translateX flagged: sign-flip or use a logical alternative",
+        )
+
+def strip_css_comments(source):
+    """Replace `/* ... */` runs with spaces (preserving \n so line numbers are
+    unchanged). Respects `"..."` / `'...'` strings so a `/*` inside a CSS
+    string is not treated as a comment opener."""
+    out = []
+    i = 0
+    n = len(source)
+    quote = None
+    while i < n:
+        ch = source[i]
+        if quote is not None:
+            out.append(ch)
+            if ch == "\\" and i + 1 < n:
+                out.append(source[i + 1])
+                i += 2
+                continue
+            if ch == quote:
+                quote = None
+            i += 1
+            continue
+        if ch == "/" and i + 1 < n and source[i + 1] == "*":
+            j = source.find("*/", i + 2)
+            if j == -1:
+                j = n
+            else:
+                j += 2
+            # Replace the comment with spaces, but keep newlines to preserve
+            # line numbers for the tokenizer below.
+            for k in range(i, j):
+                out.append("\n" if source[k] == "\n" else " ")
+            i = j
+            continue
+        if ch == '"' or ch == "'":
+            quote = ch
+        out.append(ch)
+        i += 1
+    return "".join(out)
+
+def scan_file(path):
+    try:
+        with open(path, "r", encoding="utf-8", errors="replace") as fh:
+            source = fh.read()
+    except OSError as exc:
+        print(f"scan-rtl-css.sh: {exc}", file=sys.stderr)
+        return
+
+    lines = strip_css_comments(source).splitlines(keepends=True)
+
+    # Split by declaration boundaries (`;`) while tracking source line numbers.
+    # Each declaration starts on the line where its property begins.
+    in_selector = True  # before the first `{`
+    depth = 0
+    buf = []
+    buf_lineno = 0
+
+    for lineno, raw in enumerate(lines, start=1):
+        i = 0
+        while i < len(raw):
+            ch = raw[i]
+            if ch == "{":
+                # We are entering a rule block — the buffer so far was a selector.
+                depth += 1
+                buf = []
+                buf_lineno = 0
+                in_selector = False
+                i += 1
+                continue
+            if ch == "}":
+                if buf and not in_selector:
+                    scan_declaration(path, buf_lineno or lineno, "".join(buf))
+                buf = []
+                buf_lineno = 0
+                depth -= 1
+                if depth == 0:
+                    in_selector = True
+                i += 1
+                continue
+            if ch == ";":
+                if not in_selector and buf:
+                    scan_declaration(path, buf_lineno or lineno, "".join(buf))
+                buf = []
+                buf_lineno = 0
+                i += 1
+                continue
+            if not in_selector:
+                if not buf and not ch.isspace():
+                    buf_lineno = lineno
+                buf.append(ch)
+            i += 1
+
+    # Trailing declaration without a terminating `;` (allowed in CSS).
+    if buf and not in_selector:
+        scan_declaration(path, buf_lineno or len(lines), "".join(buf))
+
+for arg in sys.argv[1:]:
+    scan_file(arg)
+PY

package/skills/experience-lwc-typescript-migrate/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: experience-lwc-typescript-migrate
+description: "Use when converting an existing JavaScript Lightning Web Component (.js, .html, .css) to TypeScript with full type annotations and a matching `.d.ts` file that exposes only the component's `@api` surface. TRIGGER when the user says \"convert LWC to TypeScript\", \"migrate LWC to TS\", \"rename .js to .ts for this component\", \"add types to my LWC\", \"generate .d.ts for this LWC\", \"type-annotate @api properties\", or \"produce declare module 'c/componentName' definitions\". DO NOT TRIGGER when the user is authoring a brand-new LWC from scratch (use experience-lwc-generate), generating Jest tests for an existing LWC (use experience-lwc-generate), or migrating an Aura component to LWC."
+metadata:
+  version: "1.0"
+  relatedSkills:
+    - "experience-lwc-generate"
+  cliTools:
+    - tool: ["git"]
+      semver: ">=2.0.0"
+    - tool: ["jq"]
+      semver: ">=1.6"
+    - tool: ["tsc"]
+      semver: ">=4.0.0"
+---
+<!-- adk-managed-skill -->
+# Converting LWC to TypeScript
+
+Convert a Lightning Web Component bundle from JavaScript to TypeScript. The
+deliverable is a fully-typed `.ts` implementation **plus** a `.d.ts` file
+that only exposes `@api` members (the public surface other LWCs consume).
+
+## When to Use This Skill
+
+- User wants to migrate a single component or a folder of components from
+  `.js` to `.ts`.
+- User needs a `.d.ts` for an existing LWC so other components (or an
+  external TypeScript host) can import it safely.
+- User is adding type annotations to an already-renamed `.ts` LWC that
+  hasn't been properly typed yet.
+- User wants JSDoc-style type hints upgraded to real TypeScript types.
+
+## Prerequisites
+
+- The component builds and runs correctly in JavaScript today.
+- `git` is available (the rename must preserve history via `git mv`).
+- A TypeScript compiler is wired into the build (either the SFDX TS
+  pipeline or a standalone `tsc` step).
+
+---
+
+## Workflow
+
+### Step 1 — Read the component
+
+Open every file in the bundle:
+
+```text
+componentName/
+├── componentName.js
+├── componentName.html
+├── componentName.css
+└── (possibly) __tests__/, __utam__/, existing .d.ts
+```
+
+Understand:
+
+- What extends `LightningElement`? What is the class name?
+- Which fields and methods carry the `@api` decorator?
+- Which properties/methods have existing JSDoc (use as a type hint
+  starting point, but validate against actual usage — JSDoc lies).
+- Which parameters / return types can you infer from how the code is
+  called internally?
+
+### Step 2 — Rename `.js` → `.ts` using `git mv`
+
+```bash
+git mv componentName/componentName.js componentName/componentName.ts
+```
+
+Repeat for any helper `.js` files in the bundle (unless they're already
+`.ts`). **Never** plain `mv` — that loses the history link TypeScript
+reviewers rely on.
+
+### Step 3 — Add type annotations in the `.ts`
+
+Apply types in this priority order so you stop as soon as the public
+contract is solid:
+
+1. **`@api` properties and methods first.** Generate JSDoc if it's
+   missing, then translate JSDoc types to TS syntax (`string`, `number`,
+   `boolean`, `Promise<T>`). Validate each JSDoc claim against the code
+   before trusting it.
+2. **Complex shapes become `interface` or `type` aliases** — not inline
+   shapes repeated everywhere.
+3. **Optional members use `?`** only when the value is genuinely allowed
+   to be `undefined`. Do not sprinkle `?` defensively.
+4. **Private/internal state** — still type it, but don't export the
+   types. Use `private` for members that must never be touched by
+   consumers.
+5. **Event handlers** — prefer precise DOM event types:
+   - `MouseEvent` for `onclick` (and other click-like handlers). `click`
+     is dispatched as a `MouseEvent` — including keyboard-activated
+     clicks — so typing it as `PointerEvent` would let handlers rely on
+     pointer-only fields (`pointerType`, `pressure`, etc.) that are
+     undefined in those cases.
+   - `PointerEvent` for `onpointerdown` / `onpointerup` / `onpointermove`
+     and other `pointer*` handlers where pointer-specific fields are
+     actually meaningful.
+   - `CustomEvent<{ detail: ... }>` for LWC custom events.
+   - `Event` is the last resort; document why when using it.
+6. **Async methods** always return `Promise<T>` — never bare `T`.
+7. **Avoid `any`.** If you genuinely can't type something, use `unknown`
+   and narrow with a type guard.
+
+#### Reference patterns
+
+Load [[assets/type-patterns.ts|assets/type-patterns.ts]] as an inline example
+covering property types, method types, and event handler types.
+
+### Step 4 — Generate the `.d.ts`
+
+Create `componentName.d.ts` next to the `.ts`. It must:
+
+- Contain **only `@api` members** — no private state, no internal
+  methods, no lifecycle hooks unless they are themselves `@api`.
+- Preserve `@api` JSDoc verbatim (including `@type`, `@required`,
+  `@default`, `@param`, `@returns` tags) directly above each declaration.
+- Declare the LWC module namespace `c/componentName` (or the org's
+  namespace if different).
+
+Template: load [[assets/dts-template.ts|assets/dts-template.ts]] as the
+starting `.d.ts` shape.
+
+If the component has **no** `@api` members, still produce the module
+declaration with a comment explaining there's no public surface — don't
+skip the file.
+
+### Step 5 — Compile and test
+
+- Run the TypeScript compiler (`tsc --noEmit` or the build's equivalent).
+  Resolve every error before calling it done; no `@ts-ignore` patches.
+- Run the component's existing Jest tests. The behavior should be
+  identical.
+- Run the bundled consumer-finder unconditionally — empty output is a
+  valid result, not a reason to skip. The script resolves the search
+  paths from `sfdx-project.json`'s `packageDirectories` (or falls back
+  to `<project-root>`), rejects any entry that escapes the project root,
+  and performs the LWC-import search internally so the invocation is
+  fully deterministic:
+
+```bash
+"<skill_dir>/scripts/find-consumers.sh" "<project-root>" "<componentName>"
+```
+
+  For each match, confirm the consumer's expected types still align with
+  the new `.d.ts` public surface.
+
+### Step 6 — Expected final bundle shape
+
+```text
+componentName/
+├── componentName.ts          # Main TypeScript implementation
+├── componentName.html        # Template (unchanged)
+├── componentName.css         # Styles (unchanged)
+└── componentName.d.ts        # Type definitions (new)
+```
+
+---
+
+## Verification Checklist
+
+**Before conversion:**
+
+- [ ] Component is valid JS and all tests pass.
+- [ ] You've identified every `@api` member and its intended type.
+
+**After conversion:**
+
+- [ ] `git mv` was used so history is preserved.
+- [ ] Every variable and parameter in the `.ts` has a concrete type
+      (no implicit `any`).
+- [ ] Complex object shapes live in `interface` / `type` aliases, not
+      inline repeats.
+- [ ] Optional `?` is only on genuinely optional fields.
+- [ ] `.d.ts` exists, declares `c/componentName`, extends
+      `LightningElement`, includes **only** `@api` members.
+- [ ] Every `@api` JSDoc is preserved verbatim in the `.d.ts`.
+- [ ] `tsc` passes with zero errors; no `@ts-ignore` or `any` used as a
+      workaround.
+- [ ] Jest tests still pass.
+
+---
+
+## Common Pitfalls
+
+- **Using `any` to silence errors.** Solve the actual type instead.
+  If the value is truly unknown, use `unknown` + a type guard.
+- **Including private members in the `.d.ts`.** The `.d.ts` is the
+  public contract. Internal lifecycle and helpers must not leak.
+- **Losing JSDoc during the rename.** Scan before and after — JSDoc
+  comments on `@api` members must appear in both the `.ts` and `.d.ts`.
+- **Skipping `git mv`.** Makes review miserable and confuses blame.
+- **Forgetting async return types.** `foo()` with an `async` keyword
+  always returns a `Promise`. Declare it.
+- **Typing `onclick` as `PointerEvent`.** `click` is a `MouseEvent`
+  (keyboard-triggered clicks included), so `PointerEvent` fields like
+  `pointerType` are undefined for those events. Type `onclick` as
+  `MouseEvent`; reserve `PointerEvent` for `onpointer*` handlers. Use
+  `MouseEvent | TouchEvent` only when the code branches on `TouchEvent`
+  distinctly.
+
+## Support Resources
+
+- [LWC TypeScript docs](https://developer.salesforce.com/docs/platform/lwc/guide/ts.html)
+- [TypeScript Handbook](https://www.typescriptlang.org/docs/)
+- [LWC Developer Guide](https://developer.salesforce.com/docs/component-library/documentation/en/lwc)

package/skills/experience-lwc-typescript-migrate/assets/dts-template.ts

@@ -0,0 +1,15 @@
+declare module 'c/componentName' {
+  import { LightningElement } from 'lwc';
+
+  export default class ComponentName extends LightningElement {
+    /**
+     * [Preserved JSDoc comment here]
+     */
+    propertyName: type;
+
+    /**
+     * [Preserved JSDoc comment here]
+     */
+    methodName(param: type): returnType;
+  }
+}

package/skills/experience-lwc-typescript-migrate/assets/type-patterns.ts

@@ -0,0 +1,44 @@
+// Reference patterns for typing an LWC. Members are illustrative — copy the
+// shapes you need into your own class.
+
+import { LightningElement, api } from 'lwc';
+
+interface DataItem {
+  id: string;
+  name: string;
+}
+
+export default class TypePatternsExample extends LightningElement {
+  // Property types
+  @api title: string = '';
+  @api count: number = 0;
+  @api isVisible: boolean = false;
+  @api items: string[] = [];
+  @api config: { enabled: boolean; name: string } = { enabled: false, name: '' };
+  @api optionalProp?: string;
+
+  // Method types
+  @api
+  handleClick(): void {
+    /* ... */
+  }
+
+  @api
+  updateItem(id: string, data: { name: string; value: number }): Promise<void> {
+    return Promise.resolve();
+  }
+
+  @api
+  async loadData(): Promise<DataItem[]> {
+    return [];
+  }
+
+  // Event handlers
+  handleButtonClick(event: MouseEvent): void {
+    /* ... */
+  }
+
+  handleCustomEvent(event: CustomEvent<{ detail: string }>): void {
+    /* ... */
+  }
+}

package/skills/experience-lwc-typescript-migrate/scripts/find-consumers.sh

@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+# find-consumers.sh — deterministically find LWC consumers of a component.
+#
+# Usage: find-consumers.sh <project-root> <componentName>
+#
+# Behavior:
+#   1. Canonicalize <project-root>. Fail if it is not a directory.
+#   2. If <project-root>/sfdx-project.json exists, read every
+#      packageDirectories[].path and canonicalize each one relative to the
+#      project root. Reject absolute paths and any path that escapes the
+#      canonical project root (S2 safety). Skip paths that do not resolve
+#      to a real directory. If no usable paths remain, fail.
+#      Otherwise the search list is just [project-root].
+#   3. Grep every resolved directory for LWC import statements matching
+#      "import ... from 'c/<componentName>'" (single OR double quotes),
+#      limited to .js and .ts files.
+#   4. Print matches (grep -H format: <path>:<match>) to stdout, one per
+#      line. Empty output is a valid result — the caller should treat it
+#      as "no consumers".
+#   5. Exits 0 on success (matches or no matches). Nonzero only on invalid
+#      arguments, unreadable project, or a malformed sfdx-project.json.
+#
+# The consumer-import search algorithm and directory-safety canonicalization
+# both live here so SKILL.md contains no algorithmic logic (A9), and the
+# search list is built into an array so paths with whitespace survive (no
+# xargs word-splitting).
+set -euo pipefail
+
+if [ "$#" -lt 2 ] || [ -z "${1:-}" ] || [ -z "${2:-}" ]; then
+  echo "find-consumers: missing arguments" >&2
+  echo "usage: find-consumers.sh <project-root> <componentName>" >&2
+  exit 64
+fi
+
+root_in="$1"
+component="$2"
+
+if [ ! -d "$root_in" ]; then
+  echo "find-consumers: <project-root> is not a directory: $root_in" >&2
+  exit 66
+fi
+
+# Canonicalize the project root so subsequent containment checks are exact.
+root="$(cd "$root_in" && pwd -P)"
+
+# Validate componentName — camelCase-ish alphanumeric, no separators that
+# could inject shell/regex metacharacters into the grep pattern below.
+if ! printf '%s' "$component" | grep -Eq '^[A-Za-z][A-Za-z0-9]*$'; then
+  echo "find-consumers: componentName must match [A-Za-z][A-Za-z0-9]*: $component" >&2
+  exit 64
+fi
+
+cfg="$root/sfdx-project.json"
+search_dirs=()
+
+if [ -f "$cfg" ]; then
+  # jq -r prints one path per line; empty and null entries are elided.
+  raw_paths="$(jq -r '.packageDirectories[]?.path // empty' "$cfg" 2>/dev/null)" || {
+    echo "find-consumers: $cfg is not valid JSON" >&2
+    exit 65
+  }
+
+  while IFS= read -r p; do
+    [ -z "$p" ] && continue
+
+    # S2: reject absolute paths outright — a project cfg has no business
+    # pointing at anything outside its own root.
+    case "$p" in
+      /*)
+        echo "find-consumers: rejecting absolute packageDirectory path: $p" >&2
+        continue
+        ;;
+    esac
+
+    # Resolve relative to the (canonical) project root.
+    candidate="$root/${p%/}"
+
+    if [ ! -d "$candidate" ]; then
+      echo "find-consumers: packageDirectory not found on disk: $candidate" >&2
+      continue
+    fi
+
+    # Canonicalize the candidate and ensure it stays inside the project
+    # root. This catches `..` escapes and symlinks that point outward.
+    canon="$(cd "$candidate" && pwd -P)"
+    case "$canon" in
+      "$root"|"$root"/*) ;;
+      *)
+        echo "find-consumers: rejecting packageDirectory that escapes project root: $canon" >&2
+        continue
+        ;;
+    esac
+
+    search_dirs+=("$canon")
+  done <<< "$raw_paths"
+
+  if [ "${#search_dirs[@]}" -eq 0 ]; then
+    echo "find-consumers: no usable packageDirectory paths in $cfg" >&2
+    exit 65
+  fi
+else
+  search_dirs=("$root")
+fi
+
+# Build the grep pattern. We anchor on the module-specifier clause —
+# `from <ws> ['"]c/<component>['"]` — which uniquely identifies a consumer
+# import regardless of whether the binding is single-line, multi-line
+# destructured, a `type` import, or a re-export. The `import ... from`
+# prefix is intentionally dropped because in a multi-line import the
+# closing `} from 'c/x'` line does not contain the word `import`; a
+# per-line grep that requires both tokens on the same line would miss
+# it. `[[:space:]]+` handles tabs and repeated spaces. Component name
+# was already validated so it is safe to interpolate into the regex.
+pattern="from[[:space:]]+['\"]c/${component}['\"]"
+
+# Array-quoted expansion preserves paths that contain whitespace. grep
+# returns 1 when there are no matches — treat that as a successful empty
+# result, not an error.
+grep -rHE "$pattern" \
+  --include='*.js' --include='*.ts' \
+  "${search_dirs[@]}" || rc=$?
+
+# grep exit codes: 0=matched, 1=no matches, 2+=error. Only surface real errors.
+rc="${rc:-0}"
+if [ "$rc" -ge 2 ]; then
+  exit "$rc"
+fi
+exit 0