@colixsystems/widget-sdk 0.276.0 → 0.277.0

package/dist/linter.cjs

@@ -1,17 +1,19 @@
-// CommonJS-flavoured copy of the linter so backend services (CJS runtime)
-// can `require()` it directly without dynamic-import gymnastics.
-//
-// The ESM `linter.js` is the source-of-truth. This file MUST mirror its
-// rule set byte-for-byte — the contract test in packages/widget-sdk
-// asserts the two are behaviour-equivalent. When you edit one, edit the
-// other in the same PR.
-//
-// The SDK build script copies both into `dist/`.
-
+// GENERATED from linter.js by scripts/generate-cjs.js — DO NOT EDIT.
+// Change linter.js, then run `npm run generate:cjs` in packages/widget-sdk.
 "use strict";
 
 const { CONTRACT, normaliseActionTriggerTypes } = require("./contract.cjs");
 const { LUCIDE_ICON_NAMES, LUCIDE_VERSION } = require("./lucideIconNames.cjs");
+const { stripNonCode: _stripNonCode } = require("./source-mask.cjs");
+
+// Static-analysis linter per docs/architecture/widget-marketplace.md §3.1.
+// Scans widget source for banned patterns. Pure text scanning — no AST parsing
+// dep — which is sufficient to gate v0.1 submissions and gives clear pointers
+// to humans during review.
+//
+// The banned-identifier list is derived from `CONTRACT.bannedApis` so the
+// system prompt, the linter, and the runtime allowlist agree.
+
 
 // Per-identifier match rule, run over the whole masked source. Most banned
 // identifiers compile to a whole-word match.
@@ -164,156 +166,18 @@ const CONTRACT_RULES = CONTRACT.bannedApis.map((b) =>
   _ruleForIdentifier(b.identifier, b.reason),
 );
 
-// Replace the *content* of comments and string / template literals with
-// spaces so the banned-identifier scan only ever sees executable code. A
-// banned host-escape identifier (`window`, `document`, `eval`, `process`, …)
-// is only dangerous as a real identifier reference — never as prose in a
-// `//` comment or as character data inside a string — so matching the bare
-// word there is a false positive that blocks an otherwise-clean widget (a
-// comment that reads "the hour window the grid renders" must not trip
-// `no-window`).
-//
-// Newlines are preserved verbatim so reported line numbers still line up
-// with the original source. Template-literal `${ … }` expression holes are
-// left intact: real code lives there and must still be scanned (`${window}`
-// is a genuine escape). Backslash escapes inside strings/templates are
-// consumed so an escaped quote (`"\""`) doesn't end the literal early.
-function _stripNonCode(source, { keepStrings = false } = {}) {
-  let out = "";
-  const n = source.length;
-  let mode = "code"; // code | line | block | sq | dq | tmpl
-  // Brace depth, plus a stack of the depths at which an enclosing template
-  // literal resumes — lets a `${ … }` hole (which may itself contain `{}`,
-  // strings, or nested templates) be told apart from the literal text.
-  let braceDepth = 0;
-  const tmplStack = [];
-  const keep = (ch) => {
-    out += ch;
-  };
-  const blank = (ch) => {
-    out += ch === "\n" || ch === "\r" ? ch : " ";
-  };
-  // String / template CONTENT: blanked for the banned-identifier scan
-  // (prose must not trip `no-window`), kept for the host-API-URL scan,
-  // whose whole job is to find a URL literal.
-  const str = keepStrings ? keep : blank;
-  let i = 0;
-  while (i < n) {
-    const ch = source[i];
-    const nx = source[i + 1];
-    if (mode === "code") {
-      if (ch === "/" && nx === "/") {
-        mode = "line";
-        blank(ch);
-        blank(nx);
-        i += 2;
-      } else if (ch === "/" && nx === "*") {
-        mode = "block";
-        blank(ch);
-        blank(nx);
-        i += 2;
-      } else if (ch === "'") {
-        mode = "sq";
-        str(ch);
-        i += 1;
-      } else if (ch === '"') {
-        mode = "dq";
-        str(ch);
-        i += 1;
-      } else if (ch === "`") {
-        mode = "tmpl";
-        str(ch);
-        i += 1;
-      } else if (ch === "{") {
-        braceDepth += 1;
-        keep(ch);
-        i += 1;
-      } else if (ch === "}") {
-        braceDepth -= 1;
-        if (
-          tmplStack.length > 0 &&
-          tmplStack[tmplStack.length - 1] === braceDepth
-        ) {
-          tmplStack.pop();
-          mode = "tmpl";
-          str(ch);
-        } else {
-          keep(ch);
-        }
-        i += 1;
-      } else {
-        keep(ch);
-        i += 1;
-      }
-    } else if (mode === "line") {
-      if (ch === "\n") {
-        mode = "code";
-        keep(ch);
-      } else {
-        blank(ch);
-      }
-      i += 1;
-    } else if (mode === "block") {
-      if (ch === "*" && nx === "/") {
-        mode = "code";
-        blank(ch);
-        blank(nx);
-        i += 2;
-      } else {
-        blank(ch);
-        i += 1;
-      }
-    } else if (mode === "sq" || mode === "dq") {
-      const quote = mode === "sq" ? "'" : '"';
-      if (ch === "\\") {
-        str(ch);
-        if (i + 1 < n) str(nx);
-        i += 2;
-      } else if (ch === quote) {
-        mode = "code";
-        str(ch);
-        i += 1;
-      } else if (ch === "\n") {
-        // A bare newline terminates an unterminated string in JS; bail back
-        // to code so malformed input can't blank the rest of the file.
-        mode = "code";
-        keep(ch);
-        i += 1;
-      } else {
-        str(ch);
-        i += 1;
-      }
-    } else {
-      // mode === "tmpl"
-      if (ch === "\\") {
-        str(ch);
-        if (i + 1 < n) str(nx);
-        i += 2;
-      } else if (ch === "`") {
-        mode = "code";
-        str(ch);
-        i += 1;
-      } else if (ch === "$" && nx === "{") {
-        // Enter an expression hole. Remember the brace depth the template
-        // resumes at, then count the `{` so its matching `}` is recognised.
-        tmplStack.push(braceDepth);
-        braceDepth += 1;
-        mode = "code";
-        keep(ch);
-        keep(nx);
-        i += 2;
-      } else {
-        str(ch);
-        i += 1;
-      }
-    }
-  }
-  return out;
-}
+// sc-6086: moved to source-mask.js so the packer's scanner masks source the
+// same way this linter does. Alias kept — the rules below read _stripNonCode.
 
+// Extra rules that don't map 1:1 to a banned identifier in the contract:
+// host-internal imports that widgets must never touch.
+//
 // REQ-WSDK-PLATFORM: `no-axios-import` is GONE. axios is on the vetted
-// import list now (`CONTRACT.vettedImports`). See linter.js for the
-// source-of-truth comment.
+// import list now (`CONTRACT.vettedImports`) — widgets may call third-party
+// APIs directly. Calls to the host's own /api/* surface are not gated at
+// runtime — they simply 401 (widget code never gets the JWT), so the soft
+// `no-host-api-url` rule below is the only thing that catches them, and it
+// flags relative `/api/` literals as well as the real `/api/v1` prefix.
 const EXTRA_RULES = [
   {
     id: "no-auth-store-import",
@@ -331,12 +195,32 @@ const EXTRA_RULES = [
 
 const RULES = [...CONTRACT_RULES, ...EXTRA_RULES];
 
+/**
+ * Returns the contract-derived list of banned identifiers. Exposed so the
+ * SDK contract test (and any host build step that wants to surface the
+ * list to humans) can read the canonical set without re-parsing the
+ * source.
+ */
 function bannedIdentifiers() {
   return CONTRACT.bannedApis.map((b) => b.identifier);
 }
 
-// REQ-WSDK-PLATFORM §3.4, §8: import-specifier validation. See linter.js
-// for the source-of-truth comment.
+// REQ-WSDK-PLATFORM §3.4, §8: scan the source for every bare import
+// specifier and validate it against `CONTRACT.vettedImports`.
+//
+// Recognised forms (string-level, no AST):
+//   import X from "spec"
+//   import { … } from "spec"   (also wrapped over several lines)
+//   import * as X from "spec"
+//   import "spec"
+//   export { … } from "spec" / export * from "spec"
+//   const X = require("spec")  // CJS — for completeness
+//
+// Relative imports within the bundle (`./foo.js`, `./shared/util.js`) are
+// allowed — REQ-WSDK-PLATFORM §4.2 lets a split-impl widget share helpers
+// between `widget.web.jsx` and `widget.native.jsx`. Parent-directory
+// (`../`) and absolute (`/`, `http(s):`) paths are rejected to keep the
+// bundle scope sealed.
 // The import clause follows the grammar (default, `* as ns`, `{ … }`), so
 // prose that merely says "import … from" rarely matches. A brace list stops
 // at the next import/export keyword and no two quantifiers share whitespace,
@@ -379,8 +263,8 @@ function _classifySpecifier(spec) {
 
 // The package root of a bare specifier: `leaflet/dist/leaflet.css` → "leaflet",
 // `@scope/pkg/sub` → "@scope/pkg". A subpath/asset import of a vetted package
-// belongs to that package, so the root carries the vetting + platforms.
-// Mirror of linter.js.
+// (its CSS, a marker PNG, react-dom/client) belongs to that package, so the
+// root carries the vetting + platform metadata.
 function _packageRoot(spec) {
   const parts = spec.split("/");
   // A traversal / empty segment is a non-canonical specifier — never resolve it
@@ -411,9 +295,7 @@ function subpathImportRootsFor(manifest) {
 
 function _importRules(source, manifest) {
   const findings = [];
-  const allowed = new Map(
-    CONTRACT.vettedImports.map((v) => [v.specifier, v]),
-  );
+  const allowed = new Map(CONTRACT.vettedImports.map((v) => [v.specifier, v]));
   // Core-infra specifiers (react-dom, react-dom/client) are host-shimmed on
   // both runtimes but kept off the author-facing vetted list — accept them so
   // a bundle's transitive react-dom import isn't flagged import-not-vetted.
@@ -422,6 +304,9 @@ function _importRules(source, manifest) {
       allowed.set(spec, { specifier: spec, platforms: ["web", "native"] });
     }
   }
+  // Track declared `supportedPlatforms` so a widget that claims "web only"
+  // doesn't import a native-only package (and vice versa) without the
+  // marketplace listing being honest about which platforms ship.
   const declaredPlatforms =
     manifest &&
     Array.isArray(manifest.supportedPlatforms) &&
@@ -615,6 +500,13 @@ function _leafletRules(source) {
   return findings;
 }
 
+// REQ-WSDK-PLATFORM §3.5: soft warning when source contains host-API URL
+// substrings. `severity: "warning"` so a HUMAN-authored submission still
+// publishes and the marketplace review queue flags it for a human pass.
+// sc-3589 — an AI-agent widget has no such review queue, so its publish loop
+// treats every finding (this one included) as a blocking check that drives a
+// repair turn; a lone unrepaired one still publishes with a warning.
+// False positives are possible: the needles are plain substring matches.
 // Explicit opt-out. A widget legitimately calling a THIRD-PARTY API with a
 // relative path against an `axios` baseURL cannot avoid the substring match,
 // and post-sc-3589 an unavoidable finding burns AI repair turns on correct
@@ -664,6 +556,8 @@ function _hostApiUrlRules(source) {
           line: i + 1,
           snippet: line.trim().slice(0, 200),
         });
+        // Only fire once per line — repeated needle hits on the same line
+        // are noise.
         break;
       }
     }
@@ -671,11 +565,26 @@ function _hostApiUrlRules(source) {
   return findings;
 }
 
-// sc-6970 — see linter.js for the rationale comment. The two files must stay
-// in lockstep (the contract test asserts behaviour-equivalence).
+// sc-6970 — no-html-in-content.
+//
+// Widgets draw with React Native primitives, so there is no
+// `dangerouslySetInnerHTML` on either host: an HTML tag inside a STRING stays
+// literal text the reader sees as tag soup. This is the defect a generated
+// "manage content" widget shipped — a hand-rolled B / I / H2 toolbar whose only
+// possible action was splicing `<strong>` and `<br>` into a TextInput, leaving
+// the author reading markup instead of a preview. `severity: "warning"` so a
+// human submission still publishes and the review queue flags it, while the AI
+// publish loop treats it as a blocking check that drives a repair turn.
+//
+// Only STRING content is scanned. JSX is excluded by construction (the masked
+// and unmasked sources agree outside string literals), so a widget's own
+// `<View>` / `<Text>` elements can never trigger it.
 const HTML_IN_CONTENT_RE =
   /<\/\s*[a-z][a-z0-9]*\s*>|<(?:br|hr|img|p|div|span|strong|em|b|i|u|s|h[1-6]|ul|ol|li|a|blockquote|code|pre|table|thead|tbody|tr|td|th)(?:\s[^<>]*)?\/?>/i;
 
+// Everything the masked source hides but the string-keeping source shows is,
+// by definition, string/template text. Column positions are preserved by both
+// maskings, so the result still lines up 1:1 with the original lines.
 function _stringLiteralLines(source) {
   const withStrings = _stripNonCode(source, { keepStrings: true }).split(
     /\r?\n/,
@@ -712,12 +621,28 @@ function _htmlInContentRules(source) {
   return findings;
 }
 
-// sc-5619 — see linter.js for the rationale comment. The two files must stay
-// in lockstep (the contract test asserts behaviour-equivalence).
+// sc-5619 — no-hand-built-page-url.
+//
+// A published app answers on two URL shapes: `/play/<tenantId>/page/<slug>` on
+// the platform host, and `/page/<slug>` at the workspace's own domain. The host
+// owns that choice (`playerPath.js` on web, react-navigation natively), so a
+// widget that builds the path itself — almost always from the `workspace.id` the
+// SDK hands it — hardcodes ONE shape and breaks on the other: on a custom domain
+// it rewrites the customer's clean domain back to the platform form and
+// republishes their workspace id in the address bar.
+//
+// An `error` with no opt-out directive, like `no-external-translation-api`: the
+// SDK covers every legitimate case, so there is no correct code to rescue.
+// Navigate with `useNavigation().goTo(pageId)`, and follow a link whose shape
+// the widget does NOT control (a datastore value, a notification link) with
+// `useNavigation().openLink(link)` — that routes through the shared resolver,
+// which already accepts either shape and rebuilds the one this host uses.
 const PAGE_URL_RE = /["'`][^"'`]*\/play\/|\/play\/\$\{/;
 
 function _handBuiltPageUrlRules(source) {
   const findings = [];
+  // Strings kept, comments blanked: the literal lives IN a string, but a comment
+  // or doc line quoting `/play/<id>` must not block a publish.
   const lines = _stripNonCode(source, { keepStrings: true }).split(/\r?\n/);
   for (let i = 0; i < lines.length; i += 1) {
     if (!PAGE_URL_RE.test(lines[i])) continue;
@@ -739,8 +664,20 @@ function _handBuiltPageUrlRules(source) {
   return findings;
 }
 
-// sc-4085 — see linter.js for the rationale comment. The two files must stay
-// in lockstep (the contract test asserts behaviour-equivalence).
+// sc-4085 — no-external-translation-api.
+//
+// Translation is a platform capability, not a third-party API: `useTranslate()`
+// (sc-3783) routes content through the platform's provider key, a durable
+// tenant-scoped cache and a metered budget. A widget that fetches a vendor
+// endpoint itself gets none of that, and ships an unvetted third-party
+// dependency into every app the widget is installed in — the same reason a
+// widget may never wire its own payment processor.
+//
+// This is an `error`, not a `warning` like `no-host-api-url`, and it carries no
+// opt-out directive: a hostname match is unambiguous (unlike a relative `/api/`
+// path, which a legitimate third-party call cannot always avoid), so there is
+// no correct code for the directive to rescue. A workspace that needs a
+// different provider changes the platform's translation key, not the widget.
 function _translationApiRules(source) {
   const findings = [];
   const hosts = CONTRACT.translationApiHosts || [];
@@ -802,9 +739,23 @@ function _scopeMintRules(source) {
   return findings;
 }
 
-// REQ-USERMGMT / REQ-ACL-SYS M3 — scope-required-for-user-mutation. See
-// linter.js for the rationale comment. The two files must stay in
-// lockstep (the contract test asserts behaviour-equivalence).
+// REQ-USERMGMT / REQ-ACL-SYS M3 — scope-required-for-user-mutation.
+//
+// A widget that calls `useUsers().invite()` / `.deactivate()` /
+// `.reactivate()` / `.sendPasswordReset()` / `.update()` / `.remove()` MUST declare
+// `users.write:*` in its
+// manifest's `requestedScopes`; similarly `useGroups()` mutation methods
+// require `groups.write:*`. The rule is enforced statically so a manifest
+// that drifts from the source (e.g. an author forgot to add the scope
+// after wiring up the mutation) is rejected at submission time.
+//
+// The check is pattern-based: scan the source for `.invite(`, `.deactivate(`
+// etc. and only fire when the source ALSO contains `useUsers(` / `useGroups(`
+// nearby (i.e. the destructured callee likely originated from the hook).
+// False positives are accepted in exchange for keeping the linter
+// AST-free; an author whose code happened to spell `.invite(` for an
+// unrelated reason can opt out with a `// @appstudio-skip-scope-check`
+// trailing comment on the offending line.
 const USER_MUTATION_METHODS = [
   "invite",
   "deactivate",
@@ -819,7 +770,12 @@ const USER_MUTATION_METHODS = [
 // useUsers().remove() must declare `users.delete:*` so the static contract
 // matches the backend gate on DELETE /api/v1/app/users/:userId.
 const USER_DELETE_METHODS = ["remove"];
-const GROUP_MUTATION_METHODS = ["create", "remove", "addMember", "removeMember"];
+const GROUP_MUTATION_METHODS = [
+  "create",
+  "remove",
+  "addMember",
+  "removeMember",
+];
 const SKIP_COMMENT = /\/\/[^\n]*@appstudio-skip-scope-check/;
 
 function _scopeRules(source, manifest) {
@@ -839,8 +795,7 @@ function _scopeRules(source, manifest) {
     if (!reads) {
       findings.push({
         rule: "scope-required-for-useUsers",
-        label:
-          "useUsers() requires `users.read:*` in manifest.requestedScopes",
+        label: "useUsers() requires `users.read:*` in manifest.requestedScopes",
         line: 0,
         snippet: "",
       });
@@ -917,10 +872,7 @@ function _scopeRules(source, manifest) {
       for (const m of USER_MUTATION_METHODS) {
         const re = new RegExp(`\\.${m}\\s*\\(`);
         if (re.test(line)) {
-          if (
-            !declared.has("users.write:*") &&
-            !declared.has("users.write")
-          ) {
+          if (!declared.has("users.write:*") && !declared.has("users.write")) {
             findings.push({
               rule: "scope-required-for-user-mutation",
               label: `useUsers().${m}() requires \`users.write:*\` in manifest.requestedScopes`,
@@ -963,6 +915,10 @@ function _scopeRules(source, manifest) {
         const needsArgs = m === "remove" ? "\\s*[^)\\s]" : "";
         const re = new RegExp(`${lookbehind}\\.${m}\\s*\\(${needsArgs}`);
         if (re.test(line)) {
+          // `.remove(` is also a useUsers method; only blame groups
+          // when the source also uses the groups hook AND the source
+          // doesn't ALSO use the users hook (an ambiguous .remove(
+          // is best left to the user-mutation rule above).
           if (m === "remove" && usesUsersHook) continue;
           if (
             !declared.has("groups.write:*") &&
@@ -984,10 +940,24 @@ function _scopeRules(source, manifest) {
   return findings;
 }
 
+/**
+ * Lint a JavaScript source string.
+ *
+ * REQ-WSDK-PLATFORM update: findings can now carry a `severity` field
+ * (`"error"` | `"warning"`). The `ok` flag is true iff NO `severity:
+ * "error"` finding exists — warnings (currently just `no-host-api-url`)
+ * surface to the reviewer but do not block publish. Findings without an
+ * explicit `severity` are treated as errors for back-compat with existing
+ * rules.
+ *
+ * @param {string} source
+ * @param {{ manifest?: { requestedScopes?: string[], supportedPlatforms?: string[] } }} [options]
+ * @returns {{ ok: boolean, findings: Array<{ rule: string, severity?: "error" | "warning", label: string, line: number, snippet: string }> }}
+ */
 // REQ-WIDGET-ACTION — validate manifest-declared server actions. These run in
 // the isolated-vm action runner, NOT in the rendered component, so they are
 // validated structurally here (shape + caps) rather than scanned as component
-// source. Mirrors the validator in manifest.cjs; emits `error` findings so a
+// source. Mirrors the validator in manifest.js; emits `error` findings so a
 // malformed / oversized / mis-triggered action blocks publish.
 function _manifestActionRules(manifest) {
   const findings = [];
@@ -995,7 +965,13 @@ function _manifestActionRules(manifest) {
   const validTriggers = new Set(CONTRACT.actionTriggerTypes);
   const maxBytes = CONTRACT.actionScriptMaxBytes;
   const push = (label) =>
-    findings.push({ rule: "manifest-action", severity: "error", label, line: 0, snippet: "" });
+    findings.push({
+      rule: "manifest-action",
+      severity: "error",
+      label,
+      line: 0,
+      snippet: "",
+    });
   if (!Array.isArray(manifest.actions)) {
     push("manifest.actions must be an array (omit it or use [] for none)");
     return findings;
@@ -1018,9 +994,16 @@ function _manifestActionRules(manifest) {
     }
     const triggerTypes = normaliseActionTriggerTypes(a);
     if (triggerTypes === null) {
-      push(`manifest.actions[].triggerTypes must be a non-empty array of unique values from ${[...validTriggers].join(", ")}`);
-    } else if (triggerTypes.includes("schedule") && (typeof a.scheduleCron !== "string" || !a.scheduleCron)) {
-      push("manifest.actions[].scheduleCron is required when triggerTypes contains 'schedule'");
+      push(
+        `manifest.actions[].triggerTypes must be a non-empty array of unique values from ${[...validTriggers].join(", ")}`,
+      );
+    } else if (
+      triggerTypes.includes("schedule") &&
+      (typeof a.scheduleCron !== "string" || !a.scheduleCron)
+    ) {
+      push(
+        "manifest.actions[].scheduleCron is required when triggerTypes contains 'schedule'",
+      );
     }
     if (typeof a.scriptSource !== "string" || a.scriptSource.length === 0) {
       push("manifest.actions[].scriptSource must be a non-empty string");
@@ -1034,7 +1017,9 @@ function _manifestActionRules(manifest) {
       }
     }
     if (a.triggerTableId !== undefined || a.apiKeyId !== undefined) {
-      push("manifest.actions[] must not include triggerTableId or apiKeyId — those are tenant-local and bound after install");
+      push(
+        "manifest.actions[] must not include triggerTableId or apiKeyId — those are tenant-local and bound after install",
+      );
     }
   }
   return findings;
@@ -1047,7 +1032,7 @@ function _manifestActionRules(manifest) {
 // cleanly and fails only at runtime load ("does not provide an export named
 // 'House'"), leaving the widget blank. This rule rejects such imports at publish
 // so the agent's repair loop fixes them. The valid set is committed data
-// (lucideIconNames.cjs) because the linter runs where lucide is not installed.
+// (lucideIconNames.js) because the linter runs where lucide is not installed.
 const LUCIDE_NAME_SET = new Set(LUCIDE_ICON_NAMES);
 // `[^}]*` (not `[\s\S]*?`) so the brace capture can never cross a `}` into a
 // neighbouring import — otherwise a preceding `import { View, Pressable } from
@@ -1270,14 +1255,28 @@ function _selfContainedReferenceRules(source) {
   return findings;
 }
 
-// sc-3466 / sc-3493 — percentage height on an <Image> collapses to 0 against a
-// content-sized parent, so the image loads but renders invisible on both hosts.
-// `severity: "warning"`: the same value is correct under a definite-height
-// parent, which this AST-free scan cannot see. Mirror of linter.js.
+// sc-3466 / sc-3493 — percentage height on an <Image> collapses to 0.
+// React Native / Yoga resolves a percentage `height` against the PARENT's
+// height; a content-sized parent has none, so the value resolves to 0 and the
+// image fetches its uri but renders invisible on BOTH the web Player and the
+// native Expo export. sc-3466 taught the rule to the AI widget agent's
+// DEFAULT_SYSTEM_PROMPT, which remains the primary guard — this is the
+// mechanical belt-and-braces catch for a model (or a human author) that
+// ignores it.
+//
+// `severity: "warning"` deliberately: `height: "100%"` IS correct inside a
+// parent with a definite height (a fixed-height hero), which the AST-free scan
+// cannot see, so a blocking rule would reject valid widgets.
+//
+// Scope is the literal inline form only. A height threaded through a variable
+// or a StyleSheet object stays out of reach of a text scan.
 const _IMAGE_TAG_RE = /<(Image|ImageBackground)\b/g;
 const _PERCENT_HEIGHT_RE =
   /(^|[{,;\s])height\s*:\s*(["'])\s*\d+(?:\.\d+)?\s*%\s*\2/g;
 
+// Index of the `>` closing the JSX opening tag that starts at `from`. Braces
+// and string literals are skipped so a `>` inside `onPress={() => …}` or an
+// attribute string can't end the tag early.
 function _jsxOpenTagEnd(source, from) {
   let depth = 0;
   let quote = "";
@@ -1324,8 +1323,22 @@ function _bundledAssetRules(source, assetFiles) {
   return findings;
 }
 
-// sc-4649 / sc-4686 — see linter.js for the rationale comments. The two
-// files must stay in lockstep (a test asserts behaviour-equivalence).
+// sc-4649 / sc-4686 — payment-currency.
+//
+// A widget must not name a currency AT ALL. Each workspace charges its app users
+// in one currency of its own choosing, the owner can change it long after the
+// widget was authored, and the server refuses a charge in anything else — so
+// omitting `currency` is the ONLY always-correct call: the platform applies the
+// workspace's own, and an existing widget follows a switch with no rebuild.
+//
+// That makes this rule workspace-INDEPENDENT (it needs no expected value passed
+// in, unlike its first sc-4649 form) and therefore it also fires in a bare
+// `appstudio-widget lint`, before a third-party developer ever uploads.
+//
+// `error`, not a warning like `payment-error-not-branched`: a literal here either
+// disagrees with the workspace and kills every checkout, or agrees today and
+// silently starts lying the moment the owner switches. Neither is code worth an
+// opt-out directive.
 const REQUEST_PAYMENT_CALL = "requestPayment(";
 // A generous window: the options object is usually inline, occasionally spread
 // over a few lines. Bounded so an unbalanced source can't scan to EOF.
@@ -1690,6 +1703,8 @@ function _mutationHookCalls(code) {
 
 function _imagePercentHeightRules(source) {
   const findings = [];
+  // Comments are blanked (string contents kept) so a commented-out example —
+  // including the one in this rule's own docs — is never flagged.
   const code = _stripNonCode(source, { keepStrings: true });
   const sourceLines = source.split(/\r?\n/);
   const lineAt = _lineCounter(code);
@@ -1722,16 +1737,38 @@ function _imagePercentHeightRules(source) {
   return findings;
 }
 
-// sc-7274 — a percentage `flexBasis` sizes the MAIN axis, which in a column is
-// the HEIGHT: under a definite-height parent (a Grid cell stretches its child
-// on the web Player) the child fills the container and, with `flex-shrink: 0`,
-// overflows over the content below. `width: "100%"` is the direction-agnostic
-// replacement. Mirror of linter.js (see there for the full rationale).
+// sc-7274 — a percentage `flexBasis` sizes the MAIN axis, and in a column that
+// is the HEIGHT.
+//
+// `flexBasis: "100%"` written to mean "full width" is only that in a ROW. In a
+// column parent it asks for the parent's whole HEIGHT, and the moment an
+// ancestor makes that height definite — a Grid cell stretches its child on the
+// web Player — every such sibling becomes as tall as the container. `View`
+// defaults to `flex-shrink: 0`, so they cannot shrink back: they overflow
+// hundreds of pixels down over whatever follows. That shipped a customer form
+// with a blank band mid-layout and three fields painted across the submit row,
+// visible only once published (the builder canvas leaves the height auto,
+// where the percentage degrades to `content` and the form looks right).
+//
+// `width: "100%"` is the direction-agnostic replacement — it fills the row in a
+// column parent AND takes its own line in a wrap row — so a percentage basis is
+// never the only way to say it.
+//
+// `severity: "warning"`, like `image-percent-height`: in a row parent the value
+// IS correct, and an AST-free scan cannot see the parent's `flexDirection`
+// (the style usually lives in a shared field/cell helper). A warning still
+// drives an AI-agent repair turn, which is the point of the rule.
+//
+// Scope is the literal inline form, including the ternary a responsive cell
+// writes (`flexBasis: stacked ? "100%" : CARD`). A basis threaded through a
+// variable stays beyond the scan; the designer skill remains the first guard.
 const _FLEX_BASIS_PERCENT_RE =
   /\bflexBasis\s*:[^,}\n]*?(["'])\s*(\d+(?:\.\d+)?)\s*%\s*\1/g;
 
 function _flexBasisPercentRules(source) {
   const findings = [];
+  // Comments blanked, strings kept: the value under test IS a string literal,
+  // so this rule's own documentation must not flag itself.
   const code = _stripNonCode(source, { keepStrings: true });
   const sourceLines = source.split(/\r?\n/);
   const lineAt = _lineCounter(code);
@@ -1742,6 +1779,8 @@ function _flexBasisPercentRules(source) {
     findings.push({
       rule: "flex-basis-percent",
       severity: "warning",
+      // Kept under FINDING_LABEL_BUDGET: the repair turn truncates the whole
+      // message at 300 chars, which would otherwise eat the fix and the line.
       label:
         `flexBasis "${hit[2]}%" sizes the MAIN axis — in a column that is the ` +
         `HEIGHT, so under a definite-height parent it fills the container and ` +
@@ -2081,14 +2120,28 @@ function _fieldInBorderedRowRules(source) {
   return findings;
 }
 
-// sc-4913 — a measured frame INCLUDES the element's own padding, so cells sized
-// from it overflow the content box and the last one wraps into an empty column.
-// Mirror of linter.js (see there for the full rationale).
+// sc-4913 — a measured frame INCLUDES the element's own padding.
+//
+// `onLayout` reports the frame width, and padding sits inside that frame. A
+// widget that measures its padded root and then sizes fixed-pixel grid columns
+// to fill the measured number overflows its own content box by left+right
+// padding, so the last column wraps: a whole empty column of whitespace beside
+// the cards, on both hosts. Nothing else catches it — the widget renders and
+// every other gate passes.
+//
+// Fires only when the measurement feeds sizing arithmetic. A padded box
+// measured just to branch narrow/wide is off by one padding pair and correct
+// enough; `isNarrowWidth` is the sanctioned reader for that. A widget that DID
+// subtract its own padding matches too — no text scan can verify the
+// subtraction — and that is deliberate: the remediation (measure an unpadded
+// inner View) is correct for it as well, and retires the arithmetic entirely.
 const _JSX_TAG_RE = /<([A-Z][\w.]*)\b/g;
 const _ON_LAYOUT_ATTR_RE = /\bonLayout\s*=/;
 const _OWN_PADDING_RE = /\bpadding(?:Horizontal|Left|Right|Start|End)?\s*:/;
 const _WIDTH_HOLDER_RE =
   /const\s*\[\s*([\w$]+)\s*,\s*([\w$]+)\s*\]\s*=\s*(useState|useContainerWidth)\b/g;
+// A setter fed a layout width within this many chars of the call is measuring:
+// covers `setW(e.nativeEvent.layout.width)` and `setW(Math.round(…))` alike.
 const _LAYOUT_FEED_WINDOW = 80;
 
 function _measuredWidthNames(code) {
@@ -2131,6 +2184,8 @@ function _sizesFromMeasuredWidth(code, names) {
 }
 
 function _measuredPaddingRules(source) {
+  // Comments are blanked so this rule's own documented anti-pattern, and a
+  // commented-out draft, never fire.
   const code = _stripNonCode(source, { keepStrings: true });
   const measured = _measuredWidthNames(code);
   if (!_sizesFromMeasuredWidth(code, measured)) return [];
@@ -2146,6 +2201,8 @@ function _measuredPaddingRules(source) {
     if (!_ON_LAYOUT_ATTR_RE.test(attrs)) continue;
     const padded = _OWN_PADDING_RE.exec(attrs);
     if (!padded) continue;
+    // Report the padding, not the tag: on a multi-line open tag the style line
+    // is the actionable one.
     const line = lineAt(tag.index + padded.index);
     findings.push({
       rule: "measured-width-ignores-padding",
@@ -2161,9 +2218,13 @@ function _measuredPaddingRules(source) {
   return findings;
 }
 
-// Narrow a split-impl widget's manifest to the platform a single bundle file
-// ships to, so `import-platform-mismatch` lints each file against what it
-// actually targets. Mirror of linter.js.
+/**
+ * Narrow a split-impl widget's manifest to the platform a single bundle file
+ * ships to, so `import-platform-mismatch` lints each file against what it
+ * actually targets. `widget.web.jsx` → ["web"], `widget.native.jsx` →
+ * ["native"], cross-platform `widget.jsx` keeps the manifest's union claim.
+ * Returns a shallow clone; the original is untouched.
+ */
 function narrowManifestForFile(manifest, filename) {
   if (!manifest || typeof manifest !== "object") return manifest;
   if (filename === "widget.web.jsx") {
@@ -2761,6 +2822,7 @@ function lintSource(source, options) {
   // Comments and string text are masked, so a banned identifier fires only on
   // code, never on the same word in prose or string data.
   findings.push(..._bannedApiFindings(source, lines));
+  // REQ-WSDK-PLATFORM §3.4: import-specifier validation.
   findings.push(
     ..._importRules(source, options && options.manifest).map((f) => ({
       ...f,
@@ -2768,6 +2830,7 @@ function lintSource(source, options) {
     })),
   );
   findings.push(..._leafletRules(source));
+  // REQ-WSDK-PLATFORM §3.5: soft host-API URL warning (does not block).
   findings.push(..._hostApiUrlRules(source));
   // sc-6970 — soft warning: HTML markup spliced into a content string.
   findings.push(..._htmlInContentRules(source));
@@ -2776,7 +2839,10 @@ function lintSource(source, options) {
   findings.push(..._handBuiltPageUrlRules(source));
   findings.push(..._lucideIconRules(source));
   findings.push(..._bundledAssetRules(source, options && options.assetFiles));
+  // sc-2353 / sc-5897 — widget source must be self-contained: a referenced
+  // `React` global or SDK export with no import throws at render.
   findings.push(..._selfContainedReferenceRules(source));
+  // sc-3493 — soft warning: percentage height on an <Image> collapses to 0.
   findings.push(..._imagePercentHeightRules(source));
   // sc-7274 — soft warning: a percentage flexBasis sizes the main axis, so in a
   // column it claims the parent's whole height and overflows.
@@ -2800,24 +2866,27 @@ function lintSource(source, options) {
   findings.push(..._rawUseMemoIntoDatastoreQueryRules(source));
   findings.push(..._handRolledWriteGateRules(source));
   findings.push(..._rowActionGatingRules(source));
+  // REQ-USERMGMT / REQ-ACL-SYS M3 — scope-aware rules. Run after the
+  // line-by-line scan so banned-identifier findings stay first in the
+  // output.
   findings.push(
     ..._scopeRules(source, options && options.manifest).map((f) => ({
       ...f,
       severity: f.severity || "error",
     })),
   );
+  // REQ-WIDGET-ACTION — structural validation of manifest-declared actions.
   findings.push(..._manifestActionRules(options && options.manifest));
   findings.push(..._badgeCounterRules(source, options && options.manifest));
   const hasErrors = findings.some((f) => f.severity !== "warning");
   return { ok: !hasErrors, findings };
 }
-
 module.exports = {
-  lintSource,
+  bannedIdentifiers,
+  subpathImportRootsFor,
+  narrowManifestForFile,
   lintStyleWiring,
   callsBasicStyle,
   lintEditability,
-  bannedIdentifiers,
-  narrowManifestForFile,
-  subpathImportRootsFor,
+  lintSource,
 };