@colixsystems/widget-sdk 0.188.0 → 0.190.0

package/dist/linter.cjs

@@ -221,8 +221,25 @@ function bannedIdentifiers() {
 
 // REQ-WSDK-PLATFORM §3.4, §8: import-specifier validation. See linter.js
 // for the source-of-truth comment.
-const IMPORT_SPECIFIER_RE =
-  /(?:^|[\s;])(?:import(?:\s+[^"';]+from)?|require)\s*\(?\s*['"]([^'"]+)['"]/g;
+// 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,
+// keeping the whole-source scan linear on hostile input.
+const _ID_CHAR = "[\\p{ID_Continue}$\\\\]";
+const _NAMED = `\\{(?:(?!\\b(?:import|export)\\b)(?:[^}"';]|"[^"\\n]*"|'[^'\\n]*'))*\\}`;
+const _NAMESPACE = `\\*\\s*as\\s+${_ID_CHAR}+`;
+const _IMPORT_CLAUSE =
+  `(?:${_ID_CHAR}+(?:\\s*,\\s*(?:${_NAMESPACE}|${_NAMED}))?` +
+  `|${_NAMESPACE}|${_NAMED})`;
+const IMPORT_SPECIFIER_RE = new RegExp(
+  // Not part of an identifier, a member access, CSS `@import` or JSX text.
+  `(?<![\\p{ID_Continue}$.@#'"\`>])` +
+    `(?:import(?!${_ID_CHAR})\\s*(?:${_IMPORT_CLAUSE}\\s*from\\s*)?(?:\\(\\s*)?` +
+    `|export(?!${_ID_CHAR})\\s*(?:\\*(?:\\s*as\\s+${_ID_CHAR}+)?|${_NAMED})\\s*from\\s*` +
+    `|require(?!${_ID_CHAR})\\s*\\(\\s*)` +
+    `['"]([^'"\\s]+)['"]`,
+  "gu",
+);
 
 function _classifySpecifier(spec) {
   if (
@@ -258,6 +275,24 @@ function _packageRoot(spec) {
   return spec.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0];
 }
 
+/**
+ * The package roots whose SUBPATH imports load in a file whose manifest is
+ * narrowed to it (`narrowManifestForFile`). The web loader shims the packages
+ * the host provides by exact name, so a file that ships to web may import a
+ * subpath only of a bundled vetted package; Metro, on native, resolves any
+ * real subpath of a vetted package. Shared with the agent render sandbox.
+ */
+function subpathImportRootsFor(manifest) {
+  const platforms =
+    manifest && Array.isArray(manifest.supportedPlatforms)
+      ? manifest.supportedPlatforms
+      : [];
+  const nativeOnly = platforms.length > 0 && !platforms.includes("web");
+  return nativeOnly
+    ? [...CONTRACT.allowedBareImports]
+    : [...CONTRACT.subpathImportRoots];
+}
+
 function _importRules(source, manifest) {
   const findings = [];
   const allowed = new Map(
@@ -277,60 +312,86 @@ function _importRules(source, manifest) {
     manifest.supportedPlatforms.length > 0
       ? new Set(manifest.supportedPlatforms)
       : null;
+  const subpathRoots = new Set(subpathImportRootsFor(manifest));
 
-  const lines = source.split(/\r?\n/);
-  for (let i = 0; i < lines.length; i += 1) {
-    const line = lines[i];
+  // Whole-source scan: a Prettier-wrapped import spans several lines. Both
+  // the raw and the comment-masked text are read, because the masker cannot
+  // see regex literals and a `/"/` would blank a real import out of it.
+  const specifiersByEnd = new Map();
+  for (const text of [source, _stripNonCode(source, { keepStrings: true })]) {
     IMPORT_SPECIFIER_RE.lastIndex = 0;
     let m;
-    while ((m = IMPORT_SPECIFIER_RE.exec(line))) {
-      const spec = m[1];
-      const kind = _classifySpecifier(spec);
-      if (kind === "relative-ok") continue;
-      if (kind === "relative-escape") {
-        findings.push({
-          rule: "no-parent-relative-import",
-          label: `relative import "${spec}" escapes the bundle (\`../\`) — only sibling-file imports (\`./foo.js\`) are allowed`,
-          line: i + 1,
-          snippet: line.trim().slice(0, 200),
-        });
-        continue;
-      }
-      if (kind === "absolute") {
-        findings.push({
-          rule: "no-absolute-import",
-          label: `absolute import "${spec}" is not allowed — use a vetted bare specifier or a sibling-file (\`./foo.js\`) import`,
-          line: i + 1,
-          snippet: line.trim().slice(0, 200),
-        });
-        continue;
-      }
-      const entry = allowed.get(spec) || allowed.get(_packageRoot(spec));
-      if (!entry) {
-        findings.push({
-          rule: "import-not-vetted",
-          label:
-            `import "${spec}" is not on the vetted package list — see ` +
-            `CONTRACT.vettedImports for the current set or open a request to add it`,
-          line: i + 1,
-          snippet: line.trim().slice(0, 200),
-        });
-        continue;
-      }
-      if (declaredPlatforms) {
-        for (const wanted of declaredPlatforms) {
-          if (!entry.platforms.includes(wanted)) {
-            findings.push({
-              rule: "import-platform-mismatch",
-              label:
-                `"${spec}" supports [${entry.platforms.join(", ")}] but the ` +
-                `manifest claims supportedPlatforms includes "${wanted}". ` +
-                `Move this import into widget.${wanted === "web" ? "native" : "web"}.jsx, ` +
-                `or drop "${wanted}" from manifest.supportedPlatforms.`,
-              line: i + 1,
-              snippet: line.trim().slice(0, 200),
-            });
-          }
+    while ((m = IMPORT_SPECIFIER_RE.exec(text))) {
+      specifiersByEnd.set(m.index + m[0].length, m[1]);
+    }
+  }
+  IMPORT_SPECIFIER_RE.lastIndex = 0;
+  const sourceLines = source.split(/\r?\n/);
+  const lineAt = _lineCounter(source);
+  const ordered = [...specifiersByEnd].sort((a, b) => a[0] - b[0]);
+  for (const [end, spec] of ordered) {
+    const line = lineAt(end);
+    const snippet = (sourceLines[line - 1] || "").trim().slice(0, 200);
+    const kind = _classifySpecifier(spec);
+    if (kind === "relative-ok") continue;
+    if (kind === "relative-escape") {
+      findings.push({
+        rule: "no-parent-relative-import",
+        label: `relative import "${spec}" escapes the bundle (\`../\`) — only sibling-file imports (\`./foo.js\`) are allowed`,
+        line,
+        snippet,
+      });
+      continue;
+    }
+    if (kind === "absolute") {
+      findings.push({
+        rule: "no-absolute-import",
+        label: `absolute import "${spec}" is not allowed — use a vetted bare specifier or a sibling-file (\`./foo.js\`) import`,
+        line,
+        snippet,
+      });
+      continue;
+    }
+    // Bare specifier — validate against the vetted list. A subpath/asset
+    // import (leaflet/dist/leaflet.css) resolves to its vetted package root.
+    let entry = allowed.get(spec);
+    const root = entry ? null : _packageRoot(spec);
+    if (root && subpathRoots.has(root)) entry = allowed.get(root);
+    if (!entry) {
+      findings.push({
+        rule: "import-not-vetted",
+        label:
+          root && allowed.has(root)
+            ? `import "${spec}" is a subpath of "${root}", which the web ` +
+              `host provides by its exact name only, so it cannot load in ` +
+              `the web Player — import from "${root}" itself (a file that ` +
+              `ships only to native may keep the subpath)`
+            : `import "${spec}" is not on the vetted package list — see ` +
+              `CONTRACT.vettedImports for the current set or open a request to add it`,
+        line,
+        snippet,
+      });
+      continue;
+    }
+    // If the manifest declares supportedPlatforms, every imported
+    // specifier must support every declared platform. A widget that
+    // imports react-native-maps (native-only) cannot honestly claim
+    // supportedPlatforms: ["web", "native"] from a single source file —
+    // it must either drop "web" from the manifest, OR move that import
+    // into widget.native.jsx so the web bundle doesn't see it.
+    if (declaredPlatforms) {
+      for (const wanted of declaredPlatforms) {
+        if (!entry.platforms.includes(wanted)) {
+          findings.push({
+            rule: "import-platform-mismatch",
+            label:
+              `"${spec}" supports [${entry.platforms.join(", ")}] but the ` +
+              `manifest claims supportedPlatforms includes "${wanted}". ` +
+              `Move this import into widget.${wanted === "web" ? "native" : "web"}.jsx, ` +
+              `or drop "${wanted}" from manifest.supportedPlatforms.`,
+            line,
+            snippet,
+          });
         }
       }
     }
@@ -351,8 +412,16 @@ const _ASSET_SPECIFIER_RE = /\.(css|png|jpe?g|gif)$/i;
 const _ICON_DEFAULT_CONFIGURED_RE =
   /\bIcon\s*\.\s*Default\s*(\.\s*mergeOptions\s*\(|\.\s*imagePath\s*=)/;
 
-function _lineAt(code, index) {
-  return code.slice(0, index).split(/\r?\n/).length;
+// Line of an index in `code`, counted forward: indexes must not decrease.
+function _lineCounter(code) {
+  let line = 1;
+  let at = 0;
+  return (index) => {
+    for (; at < index; at += 1) {
+      if (code.charCodeAt(at) === 10) line += 1;
+    }
+    return line;
+  };
 }
 
 function _leafletRules(source) {
@@ -361,6 +430,7 @@ function _leafletRules(source) {
   let firstLeafletLine = 0;
   let importsCss = false;
   let importsReactLeaflet = false;
+  const importLineAt = _lineCounter(code);
   // Whole-source scan: a Prettier-wrapped import spans several lines.
   IMPORT_SPECIFIER_RE.lastIndex = 0;
   let m;
@@ -370,7 +440,7 @@ function _leafletRules(source) {
     const root = _packageRoot(spec);
     if (!_LEAFLET_ROOTS.has(root) || _ASSET_SPECIFIER_RE.test(spec)) continue;
     if (root === "react-leaflet") importsReactLeaflet = true;
-    if (!firstLeafletLine) firstLeafletLine = _lineAt(code, m.index + m[0].length);
+    if (!firstLeafletLine) firstLeafletLine = importLineAt(m.index + m[0].length);
   }
   IMPORT_SPECIFIER_RE.lastIndex = 0;
   if (!firstLeafletLine) return [];
@@ -393,12 +463,13 @@ function _leafletRules(source) {
   ) {
     return findings;
   }
+  const markerLineAt = _lineCounter(code);
   _MARKER_TAG_RE.lastIndex = 0;
   let tag;
   while ((tag = _MARKER_TAG_RE.exec(code))) {
     const end = _jsxOpenTagEnd(code, tag.index + tag[0].length);
     if (/(^|\s)icon\s*=/.test(code.slice(tag.index, end))) continue;
-    const line = _lineAt(code, tag.index);
+    const line = markerLineAt(tag.index);
     findings.push({
       rule: "leaflet-default-marker-icon",
       severity: "warning",
@@ -1980,4 +2051,5 @@ module.exports = {
   lintEditability,
   bannedIdentifiers,
   narrowManifestForFile,
+  subpathImportRootsFor,
 };

package/dist/linter.js

@@ -94,9 +94,10 @@ export function bannedIdentifiers() {
 //
 // Recognised forms (string-level, no AST):
 //   import X from "spec"
-//   import { … } 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
@@ -104,8 +105,25 @@ export function bannedIdentifiers() {
 // between `widget.web.jsx` and `widget.native.jsx`. Parent-directory
 // (`../`) and absolute (`/`, `http(s):`) paths are rejected to keep the
 // bundle scope sealed.
-const IMPORT_SPECIFIER_RE =
-  /(?:^|[\s;])(?:import(?:\s+[^"';]+from)?|require)\s*\(?\s*['"]([^'"]+)['"]/g;
+// 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,
+// keeping the whole-source scan linear on hostile input.
+const _ID_CHAR = "[\\p{ID_Continue}$\\\\]";
+const _NAMED = `\\{(?:(?!\\b(?:import|export)\\b)(?:[^}"';]|"[^"\\n]*"|'[^'\\n]*'))*\\}`;
+const _NAMESPACE = `\\*\\s*as\\s+${_ID_CHAR}+`;
+const _IMPORT_CLAUSE =
+  `(?:${_ID_CHAR}+(?:\\s*,\\s*(?:${_NAMESPACE}|${_NAMED}))?` +
+  `|${_NAMESPACE}|${_NAMED})`;
+const IMPORT_SPECIFIER_RE = new RegExp(
+  // Not part of an identifier, a member access, CSS `@import` or JSX text.
+  `(?<![\\p{ID_Continue}$.@#'"\`>])` +
+    `(?:import(?!${_ID_CHAR})\\s*(?:${_IMPORT_CLAUSE}\\s*from\\s*)?(?:\\(\\s*)?` +
+    `|export(?!${_ID_CHAR})\\s*(?:\\*(?:\\s*as\\s+${_ID_CHAR}+)?|${_NAMED})\\s*from\\s*` +
+    `|require(?!${_ID_CHAR})\\s*\\(\\s*)` +
+    `['"]([^'"\\s]+)['"]`,
+  "gu",
+);
 
 function _classifySpecifier(spec) {
   if (
@@ -141,6 +159,24 @@ function _packageRoot(spec) {
   return spec.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0];
 }
 
+/**
+ * The package roots whose SUBPATH imports load in a file whose manifest is
+ * narrowed to it (`narrowManifestForFile`). The web loader shims the packages
+ * the host provides by exact name, so a file that ships to web may import a
+ * subpath only of a bundled vetted package; Metro, on native, resolves any
+ * real subpath of a vetted package. Shared with the agent render sandbox.
+ */
+export function subpathImportRootsFor(manifest) {
+  const platforms =
+    manifest && Array.isArray(manifest.supportedPlatforms)
+      ? manifest.supportedPlatforms
+      : [];
+  const nativeOnly = platforms.length > 0 && !platforms.includes("web");
+  return nativeOnly
+    ? [...CONTRACT.allowedBareImports]
+    : [...CONTRACT.subpathImportRoots];
+}
+
 function _importRules(source, manifest) {
   const findings = [];
   const allowed = new Map(CONTRACT.vettedImports.map((v) => [v.specifier, v]));
@@ -161,69 +197,86 @@ function _importRules(source, manifest) {
     manifest.supportedPlatforms.length > 0
       ? new Set(manifest.supportedPlatforms)
       : null;
+  const subpathRoots = new Set(subpathImportRootsFor(manifest));
 
-  const lines = source.split(/\r?\n/);
-  for (let i = 0; i < lines.length; i += 1) {
-    const line = lines[i];
-    // Reset lastIndex — the regex is /g and shared across lines.
+  // Whole-source scan: a Prettier-wrapped import spans several lines. Both
+  // the raw and the comment-masked text are read, because the masker cannot
+  // see regex literals and a `/"/` would blank a real import out of it.
+  const specifiersByEnd = new Map();
+  for (const text of [source, _stripNonCode(source, { keepStrings: true })]) {
     IMPORT_SPECIFIER_RE.lastIndex = 0;
     let m;
-    while ((m = IMPORT_SPECIFIER_RE.exec(line))) {
-      const spec = m[1];
-      const kind = _classifySpecifier(spec);
-      if (kind === "relative-ok") continue;
-      if (kind === "relative-escape") {
-        findings.push({
-          rule: "no-parent-relative-import",
-          label: `relative import "${spec}" escapes the bundle (\`../\`) — only sibling-file imports (\`./foo.js\`) are allowed`,
-          line: i + 1,
-          snippet: line.trim().slice(0, 200),
-        });
-        continue;
-      }
-      if (kind === "absolute") {
-        findings.push({
-          rule: "no-absolute-import",
-          label: `absolute import "${spec}" is not allowed — use a vetted bare specifier or a sibling-file (\`./foo.js\`) import`,
-          line: i + 1,
-          snippet: line.trim().slice(0, 200),
-        });
-        continue;
-      }
-      // Bare specifier — validate against the vetted list. A subpath/asset
-      // import (leaflet/dist/leaflet.css) resolves to its vetted package root.
-      const entry = allowed.get(spec) || allowed.get(_packageRoot(spec));
-      if (!entry) {
-        findings.push({
-          rule: "import-not-vetted",
-          label:
-            `import "${spec}" is not on the vetted package list — see ` +
-            `CONTRACT.vettedImports for the current set or open a request to add it`,
-          line: i + 1,
-          snippet: line.trim().slice(0, 200),
-        });
-        continue;
-      }
-      // If the manifest declares supportedPlatforms, every imported
-      // specifier must support every declared platform. A widget that
-      // imports react-native-maps (native-only) cannot honestly claim
-      // supportedPlatforms: ["web", "native"] from a single source file —
-      // it must either drop "web" from the manifest, OR move that import
-      // into widget.native.jsx so the web bundle doesn't see it.
-      if (declaredPlatforms) {
-        for (const wanted of declaredPlatforms) {
-          if (!entry.platforms.includes(wanted)) {
-            findings.push({
-              rule: "import-platform-mismatch",
-              label:
-                `"${spec}" supports [${entry.platforms.join(", ")}] but the ` +
-                `manifest claims supportedPlatforms includes "${wanted}". ` +
-                `Move this import into widget.${wanted === "web" ? "native" : "web"}.jsx, ` +
-                `or drop "${wanted}" from manifest.supportedPlatforms.`,
-              line: i + 1,
-              snippet: line.trim().slice(0, 200),
-            });
-          }
+    while ((m = IMPORT_SPECIFIER_RE.exec(text))) {
+      specifiersByEnd.set(m.index + m[0].length, m[1]);
+    }
+  }
+  IMPORT_SPECIFIER_RE.lastIndex = 0;
+  const sourceLines = source.split(/\r?\n/);
+  const lineAt = _lineCounter(source);
+  const ordered = [...specifiersByEnd].sort((a, b) => a[0] - b[0]);
+  for (const [end, spec] of ordered) {
+    const line = lineAt(end);
+    const snippet = (sourceLines[line - 1] || "").trim().slice(0, 200);
+    const kind = _classifySpecifier(spec);
+    if (kind === "relative-ok") continue;
+    if (kind === "relative-escape") {
+      findings.push({
+        rule: "no-parent-relative-import",
+        label: `relative import "${spec}" escapes the bundle (\`../\`) — only sibling-file imports (\`./foo.js\`) are allowed`,
+        line,
+        snippet,
+      });
+      continue;
+    }
+    if (kind === "absolute") {
+      findings.push({
+        rule: "no-absolute-import",
+        label: `absolute import "${spec}" is not allowed — use a vetted bare specifier or a sibling-file (\`./foo.js\`) import`,
+        line,
+        snippet,
+      });
+      continue;
+    }
+    // Bare specifier — validate against the vetted list. A subpath/asset
+    // import (leaflet/dist/leaflet.css) resolves to its vetted package root.
+    let entry = allowed.get(spec);
+    const root = entry ? null : _packageRoot(spec);
+    if (root && subpathRoots.has(root)) entry = allowed.get(root);
+    if (!entry) {
+      findings.push({
+        rule: "import-not-vetted",
+        label:
+          root && allowed.has(root)
+            ? `import "${spec}" is a subpath of "${root}", which the web ` +
+              `host provides by its exact name only, so it cannot load in ` +
+              `the web Player — import from "${root}" itself (a file that ` +
+              `ships only to native may keep the subpath)`
+            : `import "${spec}" is not on the vetted package list — see ` +
+              `CONTRACT.vettedImports for the current set or open a request to add it`,
+        line,
+        snippet,
+      });
+      continue;
+    }
+    // If the manifest declares supportedPlatforms, every imported
+    // specifier must support every declared platform. A widget that
+    // imports react-native-maps (native-only) cannot honestly claim
+    // supportedPlatforms: ["web", "native"] from a single source file —
+    // it must either drop "web" from the manifest, OR move that import
+    // into widget.native.jsx so the web bundle doesn't see it.
+    if (declaredPlatforms) {
+      for (const wanted of declaredPlatforms) {
+        if (!entry.platforms.includes(wanted)) {
+          findings.push({
+            rule: "import-platform-mismatch",
+            label:
+              `"${spec}" supports [${entry.platforms.join(", ")}] but the ` +
+              `manifest claims supportedPlatforms includes "${wanted}". ` +
+              `Move this import into widget.${wanted === "web" ? "native" : "web"}.jsx, ` +
+              `or drop "${wanted}" from manifest.supportedPlatforms.`,
+            line,
+            snippet,
+          });
         }
       }
     }
@@ -244,8 +297,16 @@ const _ASSET_SPECIFIER_RE = /\.(css|png|jpe?g|gif)$/i;
 const _ICON_DEFAULT_CONFIGURED_RE =
   /\bIcon\s*\.\s*Default\s*(\.\s*mergeOptions\s*\(|\.\s*imagePath\s*=)/;
 
-function _lineAt(code, index) {
-  return code.slice(0, index).split(/\r?\n/).length;
+// Line of an index in `code`, counted forward: indexes must not decrease.
+function _lineCounter(code) {
+  let line = 1;
+  let at = 0;
+  return (index) => {
+    for (; at < index; at += 1) {
+      if (code.charCodeAt(at) === 10) line += 1;
+    }
+    return line;
+  };
 }
 
 function _leafletRules(source) {
@@ -254,6 +315,7 @@ function _leafletRules(source) {
   let firstLeafletLine = 0;
   let importsCss = false;
   let importsReactLeaflet = false;
+  const importLineAt = _lineCounter(code);
   // Whole-source scan: a Prettier-wrapped import spans several lines.
   IMPORT_SPECIFIER_RE.lastIndex = 0;
   let m;
@@ -263,7 +325,7 @@ function _leafletRules(source) {
     const root = _packageRoot(spec);
     if (!_LEAFLET_ROOTS.has(root) || _ASSET_SPECIFIER_RE.test(spec)) continue;
     if (root === "react-leaflet") importsReactLeaflet = true;
-    if (!firstLeafletLine) firstLeafletLine = _lineAt(code, m.index + m[0].length);
+    if (!firstLeafletLine) firstLeafletLine = importLineAt(m.index + m[0].length);
   }
   IMPORT_SPECIFIER_RE.lastIndex = 0;
   if (!firstLeafletLine) return [];
@@ -286,12 +348,13 @@ function _leafletRules(source) {
   ) {
     return findings;
   }
+  const markerLineAt = _lineCounter(code);
   _MARKER_TAG_RE.lastIndex = 0;
   let tag;
   while ((tag = _MARKER_TAG_RE.exec(code))) {
     const end = _jsxOpenTagEnd(code, tag.index + tag[0].length);
     if (/(^|\s)icon\s*=/.test(code.slice(tag.index, end))) continue;
-    const line = _lineAt(code, tag.index);
+    const line = markerLineAt(tag.index);
     findings.push({
       rule: "leaflet-default-marker-icon",
       severity: "warning",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.188.0",
+  "version": "0.190.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",
@@ -45,7 +45,8 @@
     "README.md",
     "LICENSE",
     "src/webbundle.js",
-    "src/dev-shims.js"
+    "src/dev-shims.js",
+    "src/contract.js"
   ],
   "scripts": {
     "build": "node scripts/build.js",