@colixsystems/widget-sdk 0.65.0 → 0.66.0

package/README.md

@@ -53,7 +53,16 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.65.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.66.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+
+### What's new in 0.66.0
+
+**New linter rule `image-percent-height`, and `appstudio-widget lint` finally prints warnings (sc-3493).**
+
+- **`image-percent-height` (severity `warning`, non-blocking).** An `<Image>` / `<ImageBackground>` sized with a literal percentage `height` — `style={{ width: "100%", height: "47%" }}` — is flagged. React Native / Yoga resolves a percentage height against the **parent's** height, so under a content-sized parent it collapses to 0: the `uri` still fetches, but the image is invisible on both the web Player and the native Expo export, with nothing in the console to trace. Author fix: size it with `aspectRatio` (`{ width: "100%", aspectRatio: 1 }`) or a numeric pixel height. It is a **warning**, not an error, precisely because `height: "100%"` *is* correct inside a parent with a definite height (a fixed-height hero) and a text scan cannot tell the two apart — so the rule informs without rejecting a valid widget. Scope is the literal inline form only; a height threaded through a variable or a `StyleSheet` object is beyond an AST-free scan, and the guidance in the `useFilestoreFile` note below remains the primary guard. Comments are not scanned, so documenting the anti-pattern is safe.
+- **The CLI no longer swallows warnings.** `runLint` reported `clean` and dropped every `severity: "warning"` finding whenever there were no errors, which made the existing `no-host-api-url` warning (and this new one) invisible to anyone using `appstudio-widget lint`. It now prints an `N error(s), M warning(s)` header and one line per finding tagged `error` / `warning`. **Exit codes are unchanged:** `0` when there are no error-severity findings (warnings included), `1` otherwise — so a warning still never blocks a build. `clean` is printed only when there are genuinely zero findings.
+
+`CONTRACT` is unchanged (no new field), and no export changed signature.
 
 ### What's new in 0.65.0
 

package/dist/cli.js

@@ -60,15 +60,25 @@ function runLint(rest) {
     exit(1);
   }
   const { ok, findings } = lintSource(source);
-  if (ok) {
+  if (findings.length === 0) {
     stdout.write(`${filePath}: clean\n`);
     exit(0);
   }
-  stderr.write(`${filePath}: ${findings.length} finding(s)\n`);
+  // sc-3493 — a warning-severity finding used to be swallowed: `ok` stays true
+  // for warnings, so the CLI printed "clean" and dropped them. A warning nobody
+  // sees is pointless. Report every finding; only errors change the exit code.
+  const errors = findings.filter((f) => f.severity !== "warning").length;
+  const stream = ok ? stdout : stderr;
+  stream.write(
+    `${filePath}: ${errors} error(s), ${findings.length - errors} warning(s)\n`,
+  );
   for (const f of findings) {
-    stderr.write(`  [${f.rule}] line ${f.line}: ${f.label}\n    ${f.snippet}\n`);
+    const severity = f.severity === "warning" ? "warning" : "error";
+    stream.write(
+      `  ${severity} [${f.rule}] line ${f.line}: ${f.label}\n    ${f.snippet}\n`,
+    );
   }
-  exit(1);
+  exit(ok ? 0 : 1);
 }
 
 async function runDev(rest) {

package/dist/linter.cjs

@@ -669,6 +669,64 @@ function _reactInScopeRules(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.
+const _IMAGE_TAG_RE = /<(Image|ImageBackground)\b/g;
+const _PERCENT_HEIGHT_RE =
+  /(^|[{,;\s])height\s*:\s*(["'])\s*\d+(?:\.\d+)?\s*%\s*\2/g;
+
+function _jsxOpenTagEnd(source, from) {
+  let depth = 0;
+  let quote = "";
+  for (let i = from; i < source.length; i += 1) {
+    const ch = source[i];
+    if (quote) {
+      if (ch === "\\") i += 1;
+      else if (ch === quote) quote = "";
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") quote = ch;
+    else if (ch === "{") depth += 1;
+    else if (ch === "}") depth -= 1;
+    else if (ch === ">" && depth <= 0) return i;
+  }
+  return source.length;
+}
+
+function _imagePercentHeightRules(source) {
+  const findings = [];
+  const code = _stripNonCode(source, { keepStrings: true });
+  const sourceLines = source.split(/\r?\n/);
+  _IMAGE_TAG_RE.lastIndex = 0;
+  let tag;
+  while ((tag = _IMAGE_TAG_RE.exec(code))) {
+    const end = _jsxOpenTagEnd(code, tag.index + tag[0].length);
+    const attrs = code.slice(tag.index, end);
+    _PERCENT_HEIGHT_RE.lastIndex = 0;
+    const hit = _PERCENT_HEIGHT_RE.exec(attrs);
+    if (!hit) continue;
+    const line = code.slice(0, tag.index + hit.index).split(/\r?\n/).length;
+    findings.push({
+      rule: "image-percent-height",
+      severity: "warning",
+      label:
+        `<${tag[1]}> sizes its height with a percentage — React Native ` +
+        `resolves that against the PARENT's height, and a content-sized ` +
+        `parent has none, so it collapses to 0: the image loads but is ` +
+        `invisible on BOTH the web Player and the native Expo export. Size ` +
+        `it with aspectRatio (e.g. { width: "100%", aspectRatio: 1 }) or a ` +
+        `numeric pixel height. Warning only — a percentage height is correct ` +
+        `when the parent has a definite height (e.g. a fixed-height hero).`,
+      line,
+      snippet: (sourceLines[line - 1] || "").trim().slice(0, 200),
+    });
+    _IMAGE_TAG_RE.lastIndex = end;
+  }
+  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.
@@ -729,6 +787,7 @@ function lintSource(source, options) {
   findings.push(..._hostApiUrlRules(source));
   findings.push(..._lucideIconRules(source));
   findings.push(..._reactInScopeRules(source));
+  findings.push(..._imagePercentHeightRules(source));
   findings.push(
     ..._scopeRules(source, options && options.manifest).map((f) => ({
       ...f,

package/dist/linter.js

@@ -761,6 +761,82 @@ function _reactInScopeRules(source) {
   return findings;
 }
 
+// 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 = "";
+  for (let i = from; i < source.length; i += 1) {
+    const ch = source[i];
+    if (quote) {
+      if (ch === "\\") i += 1;
+      else if (ch === quote) quote = "";
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") quote = ch;
+    else if (ch === "{") depth += 1;
+    else if (ch === "}") depth -= 1;
+    else if (ch === ">" && depth <= 0) return i;
+  }
+  return source.length;
+}
+
+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/);
+  _IMAGE_TAG_RE.lastIndex = 0;
+  let tag;
+  while ((tag = _IMAGE_TAG_RE.exec(code))) {
+    const end = _jsxOpenTagEnd(code, tag.index + tag[0].length);
+    const attrs = code.slice(tag.index, end);
+    _PERCENT_HEIGHT_RE.lastIndex = 0;
+    const hit = _PERCENT_HEIGHT_RE.exec(attrs);
+    if (!hit) continue;
+    const line = code.slice(0, tag.index + hit.index).split(/\r?\n/).length;
+    findings.push({
+      rule: "image-percent-height",
+      severity: "warning",
+      label:
+        `<${tag[1]}> sizes its height with a percentage — React Native ` +
+        `resolves that against the PARENT's height, and a content-sized ` +
+        `parent has none, so it collapses to 0: the image loads but is ` +
+        `invisible on BOTH the web Player and the native Expo export. Size ` +
+        `it with aspectRatio (e.g. { width: "100%", aspectRatio: 1 }) or a ` +
+        `numeric pixel height. Warning only — a percentage height is correct ` +
+        `when the parent has a definite height (e.g. a fixed-height hero).`,
+      line,
+      snippet: (sourceLines[line - 1] || "").trim().slice(0, 200),
+    });
+    // One finding per <Image>; a second percentage height on the same tag is
+    // the same defect.
+    _IMAGE_TAG_RE.lastIndex = end;
+  }
+  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
@@ -828,6 +904,8 @@ export function lintSource(source, options) {
   findings.push(..._lucideIconRules(source));
   // sc-2353 — widget source must be self-contained (reference React ⇒ import it).
   findings.push(..._reactInScopeRules(source));
+  // sc-3493 — soft warning: percentage height on an <Image> collapses to 0.
+  findings.push(..._imagePercentHeightRules(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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.65.0",
+  "version": "0.66.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -48,7 +48,7 @@
   ],
   "scripts": {
     "build": "node scripts/build.js",
-    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-subscription.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js"
+    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-subscription.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js"
   },
   "engines": {
     "node": ">=18"