[FSSDK-12092] add platform verification for imports

.eslintrc.js

@@ -8,6 +8,8 @@ module.exports = {
     'eslint:recommended',
     'plugin:@typescript-eslint/recommended',
   ],
+  parser: '@typescript-eslint/parser',
+  plugins: ['@typescript-eslint', 'local-rules'],
   globals: {
     Atomics: 'readonly',
     SharedArrayBuffer: 'readonly',
@@ -25,6 +27,23 @@ module.exports = {
       'rules': {
         '@typescript-eslint/explicit-module-boundary-types': ['error']
       }
+    },
+    {
+      'files': ['lib/**/*.ts', 'src/**/*.ts'],
+      'excludedFiles': [
+        '**/platform_support.ts',
+        '**/*.spec.ts',
+        '**/*.test.ts',
+        '**/*.tests.ts',
+        '**/*.test-d.ts',
+        '**/*.gen.ts',
+        '**/*.d.ts',
+        '**/__mocks__/**',
+        '**/tests/**'
+      ],
+      'rules': {
+        'local-rules/require-platform-declaration': 'error',
+      }
     }
   ],
   rules: {

.platform-isolation.config.js

@@ -0,0 +1,39 @@
+/**
+ * Platform Isolation Configuration
+ * 
+ * Configures which files should be validated by the platform isolation validator.
+ */
+
+module.exports = {
+  // Base directories to scan for source files
+  include: [
+    'lib/**/*.ts',
+    'lib/**/*.js'
+  ],
+
+  // Files and patterns to exclude from validation
+  exclude: [
+    // Platform definition file (this file defines Platform type, doesn't need __platforms)
+    '**/platform_support.ts',
+
+    // Test files
+    '**/*.spec.ts',
+    '**/*.test.ts',
+    '**/*.tests.ts',
+    '**/*.test.js',
+    '**/*.spec.js',
+    '**/*.tests.js',
+    '**/*.umdtests.js',
+    '**/*.test-d.ts',
+
+    // Generated files
+    '**/*.gen.ts',
+
+    // Type declaration files
+    '**/*.d.ts',
+
+    // Test directories and mocks
+    '**/__mocks__/**',
+    '**/tests/**'
+  ]
+};

ESLINT_TROUBLESHOOTING.md

@@ -0,0 +1,84 @@
+# ESLint Rule Troubleshooting
+
+## The Rule is Working!
+
+The `require-platform-declaration` rule **is** working correctly from the command line:
+
+```bash
+$ npx eslint lib/core/custom_attribute_condition_evaluator/index.ts
+
+lib/core/custom_attribute_condition_evaluator/index.ts
+  16:1  error  File must export __platforms to declare which platforms 
+                it supports. Example: export const __platforms = ['__universal__'] as const;
+```
+
+## VSCode Not Showing Errors?
+
+If VSCode isn't showing the ESLint errors, try these steps:
+
+### 1. Restart ESLint Server
+- Open Command Palette: `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux)
+- Type: `ESLint: Restart ESLint Server`
+- Press Enter
+
+### 2. Check ESLint Extension is Installed
+- Open Extensions panel: `Cmd+Shift+X` (Mac) or `Ctrl+Shift+X` (Windows/Linux)
+- Search for "ESLint" by Microsoft
+- Make sure it's installed and enabled
+
+### 3. Check ESLint Output
+- Open Output panel: `Cmd+Shift+U` (Mac) or `Ctrl+Shift+U` (Windows/Linux)  
+- Select "ESLint" from the dropdown
+- Look for any error messages
+
+### 4. Reload VSCode Window
+- Open Command Palette: `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux)
+- Type: `Developer: Reload Window`
+- Press Enter
+
+### 5. Check File is Being Linted
+The rule only applies to:
+- ✅ Files in `lib/` or `src/` directory
+- ✅ TypeScript files (`.ts`)
+- ❌ Test files (`.spec.ts`, `.test.ts`, etc.)
+- ❌ Declaration files (`.d.ts`)
+
+### 6. Verify ESLint Configuration
+Check that `.eslintrc.js` has the parser set:
+```javascript
+parser: '@typescript-eslint/parser',
+```
+
+And that the rule is in the overrides:
+```javascript
+overrides: [{
+  files: ['*.ts', '!*.spec.ts', '!*.test.ts', '!*.tests.ts', '!*.test-d.ts'],
+  rules: {
+    'local-rules/require-platform-declaration': 'error',
+  }
+}]
+```
+
+## Manual Verification
+
+You can always verify the rule works by running:
+
+```bash
+# Check a specific file
+npx eslint lib/service.ts
+
+# Check all lib files (shows only errors)
+npx eslint lib/**/*.ts --quiet
+```
+
+## Adding __platforms
+
+To fix the error, add this export to your file (after imports):
+
+```typescript
+// Universal file (all platforms)
+export const __platforms = ['__universal__'] as const;
+
+// OR platform-specific file
+export const __platforms = ['browser', 'node'] as const;
+```

README.md

@@ -207,6 +207,18 @@ If you're updating your SDK version, please check the appropriate migration guid
 
 ## SDK Development
 
+### Platform Isolation
+
+The SDK supports multiple JavaScript platforms (Browser, Node.js, React Native) with a unified codebase. To prevent runtime errors from platform-specific code being bundled incorrectly, we enforce **platform isolation** constraints:
+
+- Every source file must declare which platforms it supports using `export const __platforms: Platform[] = [...]`
+- Files can only import from other files that support all their declared platforms
+- Universal files (`__platforms = ['__universal__']`) work everywhere but can only import from other universal files
+
+This system is enforced at build time through ESLint rules and validation scripts, ensuring platform-specific code (like browser DOM APIs or Node.js `fs` module) never leaks into incompatible builds.
+
+**For detailed documentation**, see [docs/PLATFORM_ISOLATION.md](docs/PLATFORM_ISOLATION.md).
+
 ### Unit Tests
 
 There is a mix of testing paradigms used within the JavaScript SDK which include Mocha, Chai, Karma, and Vitest, indicated by their respective `*.tests.js` and `*.spec.ts` filenames.