typebulb 0.12.0 → 0.13.0

package/dist/lint/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Lints a bulb's code block for environment-specific issues — patterns that are
+ * valid TypeScript but break in the Typebulb runtime. Shared by typebulb.com and
+ * the CLI (`typebulb check`) so both enforce the same rules with the same
+ * AI-facing messages.
+ *
+ * Target-aware: `code.tsx` runs in the browser under an import map and a sandboxed
+ * iframe, `server.ts` runs in Node. The import-map / browser rules (dynamic
+ * import, URL / version / `.js`-deep-path imports, CSS imports, navigation) apply
+ * only to the client; the Sucrase / ESM core (require, `const enum`, `namespace`,
+ * `export =` / `import =`, `module {}`, redundant `tb`) applies to both.
+ */
+export type LintTarget = 'client' | 'server';
+export type LintIssueType = 'DYNAMIC_IMPORT' | 'COMMONJS_REQUIRE' | 'JS_EXTENSION_IMPORT' | 'URL_IMPORT' | 'VERSION_SPECIFIER_IMPORT' | 'REDUNDANT_TB_DECLARATION' | 'CONST_ENUM' | 'NAMESPACE_DECLARATION' | 'COMMONJS_EXPORT_EQUALS' | 'COMMONJS_IMPORT_EQUALS' | 'MODULE_DECLARATION' | 'CSS_FILE_IMPORT' | 'NAVIGATION';
+export type LintIssue = {
+    type: LintIssueType;
+    severity: 'error';
+    message: string;
+    lineNumber?: number;
+    lineContent?: string;
+};
+/**
+ * Lint a bulb code block. `target` selects the ruleset: `client` (`code.tsx`,
+ * the browser superset) or `server` (`server.ts`, the Sucrase / ESM core only).
+ */
+export declare function lint(source: string, options: {
+    target: LintTarget;
+}): LintIssue[];
+//# sourceMappingURL=index.d.ts.map

package/dist/lint/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../lint/src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAE5C,MAAM,MAAM,aAAa,GACrB,gBAAgB,GAAG,kBAAkB,GAAG,qBAAqB,GAAG,YAAY,GAC5E,0BAA0B,GAAG,0BAA0B,GAAG,YAAY,GACtE,uBAAuB,GAAG,wBAAwB,GAAG,wBAAwB,GAC7E,oBAAoB,GAAG,iBAAiB,GAAG,YAAY,CAAA;AAE3D,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,aAAa,CAAA;IACnB,QAAQ,EAAE,OAAO,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,CAAA;AA4BD;;;GAGG;AACH,wBAAgB,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE;IAAE,MAAM,EAAE,UAAU,CAAA;CAAE,GAAG,SAAS,EAAE,CAuBjF"}

package/dist/lint/index.js

@@ -0,0 +1,257 @@
+/**
+ * Lints a bulb's code block for environment-specific issues — patterns that are
+ * valid TypeScript but break in the Typebulb runtime. Shared by typebulb.com and
+ * the CLI (`typebulb check`) so both enforce the same rules with the same
+ * AI-facing messages.
+ *
+ * Target-aware: `code.tsx` runs in the browser under an import map and a sandboxed
+ * iframe, `server.ts` runs in Node. The import-map / browser rules (dynamic
+ * import, URL / version / `.js`-deep-path imports, CSS imports, navigation) apply
+ * only to the client; the Sucrase / ESM core (require, `const enum`, `namespace`,
+ * `export =` / `import =`, `module {}`, redundant `tb`) applies to both.
+ */
+const CLIENT = ['client'];
+const BOTH = ['client', 'server'];
+const RULES = [
+    { type: 'DYNAMIC_IMPORT', pattern: /\bimport\s*\(\s*['"`]/, targets: CLIENT },
+    { type: 'COMMONJS_REQUIRE', pattern: /\brequire\s*\(\s*['"`]/, targets: BOTH },
+    // Only flag .js extension when it appears in a deep import path (has /).
+    // Package names that ARE ".js" (like "decimal.js") are legitimate npm packages.
+    // Browser-only: a `.js` on a deep path is valid (often required) in Node ESM.
+    { type: 'JS_EXTENSION_IMPORT', pattern: /from\s+['"][^'"]*\/[^'"]*\.js['"]/, targets: CLIENT },
+    { type: 'URL_IMPORT', pattern: /from\s+['"]https?:\/\//, targets: CLIENT },
+    { type: 'VERSION_SPECIFIER_IMPORT', pattern: /from\s+['"][^'"]*@[\d^~]/, targets: CLIENT },
+    { type: 'REDUNDANT_TB_DECLARATION', pattern: /declare\s+(const|var|let)\s+tb\b/, targets: BOTH },
+    { type: 'CONST_ENUM', pattern: /\bconst\s+enum\b/, targets: BOTH },
+    { type: 'NAMESPACE_DECLARATION', pattern: /\bnamespace\s+\w+/, targets: BOTH },
+    { type: 'COMMONJS_EXPORT_EQUALS', pattern: /\bexport\s*=/, targets: BOTH },
+    { type: 'COMMONJS_IMPORT_EQUALS', pattern: /\bimport\s+\w+\s*=/, targets: BOTH },
+    { type: 'MODULE_DECLARATION', pattern: /\bmodule\s+\w+\s*\{/, targets: BOTH },
+    { type: 'CSS_FILE_IMPORT', pattern: /(?:from|import)\s+['"][^'"]*\.css['"]/, targets: CLIENT },
+    // Navigation APIs break the sandboxed iframe.
+    { type: 'NAVIGATION', pattern: /window\.(location\.(reload|assign|replace)\s*\(|open\s*\()/, targets: CLIENT },
+    { type: 'NAVIGATION', pattern: /window\.location(\.href)?\s*=[^=]/, targets: CLIENT },
+];
+/**
+ * Lint a bulb code block. `target` selects the ruleset: `client` (`code.tsx`,
+ * the browser superset) or `server` (`server.ts`, the Sucrase / ESM core only).
+ */
+export function lint(source, options) {
+    if (!source)
+        return [];
+    const { target } = options;
+    const issues = [];
+    const lines = source.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const lineNumber = i + 1;
+        for (const rule of RULES) {
+            if (!rule.targets.includes(target))
+                continue;
+            if (!rule.pattern.test(line))
+                continue;
+            issues.push({
+                type: rule.type,
+                severity: 'error',
+                message: messageFor(rule.type, lineNumber),
+                lineNumber,
+                lineContent: line,
+            });
+        }
+    }
+    return issues;
+}
+function messageFor(type, lineNumber) {
+    if (type === 'URL_IMPORT') {
+        return `Direct URL imports are not supported! Found on line ${lineNumber}.
+
+**CRITICAL**: Import packages by name only. Do NOT use CDN URLs:
+
+✅ CORRECT - Package name only:
+\`\`\`typescript
+import React from "react"
+import _ from "lodash"
+\`\`\`
+
+❌ WRONG - Direct URL imports:
+\`\`\`typescript
+import React from "https://esm.sh/react"
+import _ from "https://cdn.skypack.dev/lodash"
+import x from "https://unpkg.com/some-package"
+\`\`\`
+
+**Fix:** Use the package name only. Package resolution is handled automatically.`;
+    }
+    if (type === 'VERSION_SPECIFIER_IMPORT') {
+        return `Version specifiers in imports are not supported! Found on line ${lineNumber}.
+
+**CRITICAL**: Import packages by name only. Do NOT include version numbers:
+
+✅ CORRECT - Package name only:
+\`\`\`typescript
+import React from "react"
+import _ from "lodash"
+import { something } from "@scope/package"
+\`\`\`
+
+❌ WRONG - Version in import path:
+\`\`\`typescript
+import React from "react@18.2.0"
+import _ from "lodash@^4.17.0"
+import { x } from "@scope/package@1.0.0"
+\`\`\`
+
+**Fix:** Remove the version specifier (everything from @ onwards). Versions are managed separately.`;
+    }
+    if (type === 'JS_EXTENSION_IMPORT') {
+        return `Deep import paths must NOT include \`.js\` extension! Found on line ${lineNumber}.
+
+**CRITICAL**: Remove the \`.js\` extension from deep import paths (paths with \`/\`):
+
+✅ CORRECT - No extension in deep import:
+\`\`\`typescript
+import { OrbitControls } from "three/examples/jsm/controls/OrbitControls"
+\`\`\`
+
+❌ WRONG - Has .js extension in deep import:
+\`\`\`typescript
+import { OrbitControls } from "three/examples/jsm/controls/OrbitControls.js"
+\`\`\`
+
+**Note:** Package names that literally end with ".js" (like \`decimal.js\`) are fine - this rule only applies to file paths within packages.
+
+**Fix:** Remove \`.js\` from the end of the import path.`;
+    }
+    if (type === 'DYNAMIC_IMPORT') {
+        return `Dynamic imports are not supported! You used \`import('...')\` on line ${lineNumber}.
+
+**CRITICAL**: All imports MUST be at the TOP of the file using standard ES6 import syntax:
+
+✅ CORRECT - Static import at top of file:
+\`\`\`typescript
+import { createRoot } from 'react-dom/client'
+
+// Later in code...
+const root = createRoot(rootElement)
+root.render(<App />)
+\`\`\`
+
+❌ WRONG - Dynamic import() in code:
+\`\`\`typescript
+// This is completely invalid!
+import('react-dom/client').then(({ createRoot }) => {
+  const root = createRoot(rootElement)
+  root.render(<App />)
+})
+\`\`\`
+
+**Fix:** Move ALL import statements to the top of the file using standard \`import\` syntax.`;
+    }
+    if (type === 'REDUNDANT_TB_DECLARATION') {
+        return `Redundant \`declare const tb\` found on line ${lineNumber}.
+The \`tb\` global is already provided by the environment. Remove this declaration.`;
+    }
+    if (type === 'CONST_ENUM') {
+        return `\`const enum\` is not supported! Found on line ${lineNumber}.
+
+**Fix:** Use a regular \`enum\` or an object with \`as const\`:
+
+\`\`\`typescript
+// Option 1: Regular enum
+enum Direction { Up, Down, Left, Right }
+
+// Option 2: Object literal (often better)
+const Direction = { Up: 0, Down: 1, Left: 2, Right: 3 } as const
+\`\`\`
+
+\`const enum\` requires the full TypeScript compiler to inline values at compile time. Regular \`enum\` and object literals work identically at runtime.`;
+    }
+    if (type === 'NAMESPACE_DECLARATION') {
+        return `TypeScript \`namespace\` is not supported! Found on line ${lineNumber}.
+
+**Fix:** Use ES modules instead:
+
+\`\`\`typescript
+// Instead of: namespace MyLib { export function foo() {} }
+// Just use top-level exports:
+export function foo() {}
+\`\`\`
+
+Namespaces are a legacy TypeScript pattern. Use standard ES module imports/exports instead.`;
+    }
+    if (type === 'COMMONJS_EXPORT_EQUALS') {
+        return `\`export =\` syntax is not supported! Found on line ${lineNumber}.
+
+**Fix:** Use ES module \`export default\` instead:
+
+\`\`\`typescript
+// Instead of: export = myValue
+export default myValue
+\`\`\``;
+    }
+    if (type === 'COMMONJS_IMPORT_EQUALS') {
+        return `\`import x =\` syntax is not supported! Found on line ${lineNumber}.
+
+**Fix:** Use ES module \`import\` instead:
+
+\`\`\`typescript
+// Instead of: import x = require('module')
+import x from 'module'
+\`\`\``;
+    }
+    if (type === 'MODULE_DECLARATION') {
+        return `TypeScript \`module\` declarations are not supported! Found on line ${lineNumber}.
+
+**Fix:** Use ES modules instead. The \`module Foo {}\` syntax is a legacy TypeScript pattern — use standard imports/exports.`;
+    }
+    if (type === 'CSS_FILE_IMPORT') {
+        return `Importing CSS files is not supported! Found on line ${lineNumber}.
+
+**CRITICAL**: CSS imports don't work here. The styles.css block is already applied to the page automatically.
+
+✅ CORRECT - Just remove the import. CSS from the styles.css block is already applied to the page.
+
+❌ WRONG - Importing CSS as a file:
+\`\`\`typescript
+import "./styles.css"
+import styles from "./styles.css"
+\`\`\`
+
+**Fix:** Delete the CSS import line entirely. Write styles in the styles.css block — they are loaded automatically.`;
+    }
+    if (type === 'NAVIGATION') {
+        return `Navigation is forbidden in this sandboxed environment! Found on line ${lineNumber}.
+
+**CRITICAL**: \`window.location\` changes, \`window.open()\`, and page reloads will break the app.
+
+✅ CORRECT - Reset application state programmatically:
+\`\`\`typescript
+setState(initialState)
+\`\`\`
+
+❌ WRONG - Browser navigation:
+\`\`\`typescript
+window.location.reload()
+window.location.href = "..."
+window.open("...")
+\`\`\`
+
+**Fix:** Remove the navigation call. To "restart", reset your state variables instead.`;
+    }
+    return `CommonJS \`require()\` is not supported! Found on line ${lineNumber}.
+
+**CRITICAL**: Use ES6 \`import\` statements at the TOP of the file:
+
+✅ CORRECT - ES6 import:
+\`\`\`typescript
+import { something } from 'module-name'
+\`\`\`
+
+❌ WRONG - CommonJS require:
+\`\`\`typescript
+const something = require('module-name')  // NOT SUPPORTED!
+\`\`\`
+
+**Fix:** Replace all \`require()\` calls with ES6 \`import\` statements at the top of the file.`;
+}
+//# sourceMappingURL=index.js.map

package/dist/lint/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../lint/src/index.ts"],"names":[],"mappings":"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"}