Merge pull request #168 from ethdebug/docs

Revamp documentation

Author: gnidan

.eslintignore

@@ -10,10 +10,12 @@ else
 fi
 
 # Run the commands with concurrently
-concurrently --names=format,pointers,bugc,playground,web,tests \
+concurrently --names=format,pointers,evm,bugc,programs-react,playground,web,tests \
   "cd ./packages/format && yarn watch" \
   "cd ./packages/pointers && yarn watch" \
+  "cd ./packages/evm && yarn watch" \
   "cd ./packages/bugc && yarn watch" \
+  "cd ./packages/programs-react && yarn watch" \
   "cd ./packages/playground && yarn watch" \
   "cd ./packages/web && yarn start $DOCUSAURUS_NO_OPEN" \
   "sleep 5 && yarn test --ui --watch --coverage $VITEST_NO_OPEN"

.eslintrc.json

@@ -0,0 +1,79 @@
+import eslint from "@eslint/js";
+import tseslint from "typescript-eslint";
+import globals from "globals";
+import reactHooks from "eslint-plugin-react-hooks";
+
+export default tseslint.config(
+  eslint.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    files: ["**/*.ts", "**/*.tsx"],
+    plugins: {
+      "react-hooks": reactHooks,
+    },
+    languageOptions: {
+      globals: {
+        ...globals.node,
+        ...globals.es2022,
+      },
+      parserOptions: {
+        projectService: true,
+      },
+    },
+    rules: {
+      "@typescript-eslint/no-explicit-any": "warn",
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        { varsIgnorePattern: "^_", argsIgnorePattern: "^_" },
+      ],
+      "@typescript-eslint/no-namespace": "off",
+      "@typescript-eslint/no-empty-object-type": "off",
+      "no-console": "warn",
+      "require-yield": "off",
+      "react-hooks/rules-of-hooks": "error",
+      "react-hooks/exhaustive-deps": "warn",
+      "no-restricted-imports": [
+        "error",
+        {
+          patterns: [
+            {
+              group: ["../types/*/index*", "../types/*/index"],
+              message: "Use #types/* alias instead of relative imports",
+            },
+            {
+              group: [
+                "../materials/*",
+                "../data/*",
+                "../pointer/*",
+                "../program/*",
+                "../type/*",
+              ],
+              message: "Use #types/* alias instead of relative imports",
+            },
+            {
+              group: ["../../test/*", "../../../test/*"],
+              message: "Use #test/* alias instead of relative imports",
+            },
+            {
+              group: ["../describe*"],
+              message: "Use #describe alias instead of relative imports",
+            },
+          ],
+        },
+      ],
+    },
+  },
+  {
+    ignores: [
+      "node_modules/",
+      "**/dist/",
+      "coverage/",
+      "**/*.d.ts",
+      "**/*.config.js",
+      "**/*.config.ts",
+      "packages/format/src/schemas/yamls.ts",
+      "packages/web/.docusaurus/",
+      "packages/web/build/",
+    ],
+  },
+);

bin/start

@@ -5,7 +5,7 @@
     "packages/*"
   ],
   "scripts": {
-    "build": "tsc --build packages/format packages/pointers packages/bugc",
+    "build": "tsc --build packages/format packages/pointers packages/evm packages/bugc packages/programs-react packages/pointers-react",
     "bundle": "tsx ./bin/bundle-schema.ts",
     "test": "vitest",
     "test:coverage": "vitest run --coverage",
@@ -15,21 +15,25 @@
     "prepare": "husky",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
-    "lint": "eslint . --ext .ts,.tsx",
-    "lint:fix": "eslint . --ext .ts,.tsx --fix"
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
   },
   "devDependencies": {
+    "@eslint/js": "^9.39.2",
     "@typescript-eslint/eslint-plugin": "^8.21.0",
     "@typescript-eslint/parser": "^8.21.0",
     "@vitest/coverage-v8": "^3.2.4",
     "@vitest/ui": "^3.2.4",
     "concurrently": "^8.2.2",
-    "eslint": "^8.57.1",
+    "eslint": "^9.0.0",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "globals": "^17.0.0",
     "husky": "^9.1.7",
     "lerna": "^8.2.4",
     "lint-staged": "^15.4.1",
     "prettier": "^3.4.2",
     "tsx": "^4.21.0",
+    "typescript-eslint": "^8.53.0",
     "vitest": "^3.2.4"
   },
   "lint-staged": {

eslint.config.js

@@ -0,0 +1,59 @@
+{
+  "name": "@ethdebug/bugc-react",
+  "version": "0.1.0-0",
+  "description": "React components for visualizing BUG compiler output",
+  "type": "module",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "license": "MIT",
+  "imports": {
+    "#components/*": {
+      "types": "./src/components/*.tsx",
+      "default": "./dist/src/components/*.js"
+    },
+    "#hooks/*": {
+      "types": "./src/hooks/*.ts",
+      "default": "./dist/src/hooks/*.js"
+    },
+    "#utils/*": {
+      "types": "./src/utils/*.ts",
+      "default": "./dist/src/utils/*.js"
+    },
+    "#types": {
+      "types": "./src/types.ts",
+      "default": "./dist/src/types.js"
+    }
+  },
+  "scripts": {
+    "prepare": "tsc",
+    "build": "tsc",
+    "watch": "tsc --watch --preserveWatchOutput",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@ethdebug/bugc": "^0.1.0-0"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10.0.0",
+    "@testing-library/react": "^16.0.0",
+    "@types/react": "^18.2.43",
+    "@types/react-dom": "^18.2.17",
+    "jsdom": "^26.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.2.4"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  },
+  "optionalDependencies": {
+    "@monaco-editor/react": "^4.7.0",
+    "dagre": "^0.8.5",
+    "react-flow-renderer": "^10.3.17"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package.json

@@ -0,0 +1,21 @@
+/**
+ * Styles for AstView component.
+ */
+
+@import "./variables.css";
+
+.ast-view {
+  height: 100%;
+  overflow: auto;
+}
+
+.ast-json {
+  margin: 0;
+  padding: 1rem;
+  font-family: "Consolas", "Monaco", "Courier New", monospace;
+  font-size: 0.875rem;
+  line-height: 1.5;
+  color: var(--bugc-text-code);
+  white-space: pre;
+  overflow: auto;
+}

packages/bugc-react/package.json

@@ -0,0 +1,45 @@
+/**
+ * AstView component for displaying the AST of a BUG program.
+ */
+
+import React from "react";
+import type { Ast } from "@ethdebug/bugc";
+
+/**
+ * Props for AstView component.
+ */
+export interface AstViewProps {
+  /** The AST to display */
+  ast: Ast.Program;
+}
+
+/**
+ * Displays a BUG program's Abstract Syntax Tree as formatted JSON.
+ *
+ * Automatically excludes parent references to avoid circular structures.
+ *
+ * @param props - AST to display
+ * @returns AstView element
+ *
+ * @example
+ * ```tsx
+ * <AstView ast={compileResult.ast} />
+ * ```
+ */
+export function AstView({ ast }: AstViewProps): JSX.Element {
+  // Format AST as JSON, excluding parent references to avoid circular structure
+  const astJson = JSON.stringify(
+    ast,
+    (key, value) => {
+      if (key === "parent") return undefined;
+      return value;
+    },
+    2,
+  );
+
+  return (
+    <div className="ast-view">
+      <pre className="ast-json">{astJson}</pre>
+    </div>
+  );
+}