Revamp documentation #168
Draft
Revamp documentation #168
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Extract EVM execution and state access utilities into a standalone package: - Executor: wraps @ethereumjs/evm for contract deployment and execution - createMachineState: adapter for @ethdebug/pointers Machine.State interface - Trace utilities: capture execution traces step-by-step Extracted from packages/bugc/test/evm and packages/bugc/test/examples.
Extract React components for program visualization from packages/web/src/theme/ProgramExample and ShikiCodeBlock. New package includes: - ProgramExampleContextProvider and useProgramExampleContext - Opcodes, SourceContents, HighlightedInstruction components - ShikiCodeBlock and useHighlighter for syntax highlighting - Utility functions: computeOffsets, resolveDynamicInstruction Web package now consumes @ethdebug/programs-react, keeping only Docusaurus-specific components (Details, Variables, Viewer) and CSS.
Extract visualization components from playground for BUG compiler output: - AstView, IrView, CfgView, BytecodeView components - Monaco-based Editor with BUG syntax highlighting - EthdebugTooltip for debug context display - Theme-aware CSS using Docusaurus/Infima conventions - Utility functions for debug info extraction
Mock console.error during the test that verifies the hook throws when used outside its provider, preventing React's error logging from cluttering test output.
Add BUG Playground page to docs with interactive compiler visualization. The playground allows editing BUG source code and viewing AST, IR, CFG, and Bytecode output with bidirectional source highlighting. Changes to bugc-react: - Remove CSS imports from components (CSS now managed by consumers) - Fix SourceRange type to use offset/length instead of line/column - Simplify extractSourceRange to return correct format New theme components in web package: - BugcExample wrapper components with Docusaurus theming - Monaco editor decoration CSS for source highlighting
Phase 1 of docs improvement plan: - Create new sections: getting-started, concepts, types, pointers, programs - Move goals.mdx and known-challenges.mdx to reference/ - Move bug-playground.mdx to examples/ - Delete outdated docs/sketches/ - Add _category_.json files for sidebar organization - Add stub index pages for all new sections - Add compiler guides section under implementation-guides
Phase 2 of docs restructure: - Rewrite overview.mdx with clear intro and navigation cards - Add getting-started path chooser with debugger/compiler guides - Add concepts section explaining types, pointers, programs - Add data locations reference for EVM storage areas - Update implementation-guides landing page
Phase 3 of docs restructure: - Types: overview, elementary types, composite types - Pointers: overview, regions guide - Programs: overview, instructions, variables - Fix broken links to /spec and /docs/known-challenges
Add remaining documentation pages for types, pointers, and programs: - types/representation.mdx: How types map to bytes (encoding contexts, packed storage layout, dynamic data representation) - pointers/expressions.mdx: Expression language for dynamic locations ($sum, $keccak256, $read, .offset, .length, etc.) - pointers/resolution.mdx: Stub for future pointer resolution widget - programs/tracing.mdx: Stub for future execution tracing widget Update index pages with navigation cards linking to new content.
- Add @ethdebug/pointers-react package with:
- PointerResolverProvider context and usePointerResolution hook
- ResolutionVisualizer, RegionMap, RegionOutput components
- createMockState utility for mock EVM state
- CSS with light/dark theme support
- Extend @ethdebug/programs-react with tracing:
- TraceContext for execution trace state
- TraceControls navigation component
- VariableInspector component
- mockTrace utilities
- Add web integration:
- PointersExample theme wrapper with BrowserOnly for SSR
- ProgramExample TraceViewer wrapper
- CSS theming for both light and dark modes
- Add documentation:
- reference/glossary.mdx with terminology definitions
- implementation-guides/compiler/case-study-bug.mdx case study
- Update pointers/resolution.mdx with interactive widget
- Update programs/tracing.mdx with expanded documentation
- Fix browser compatibility in @ethdebug/pointers:
- Remove top-level await import("util") that broke SSG
- Use Symbol.for("nodejs.util.inspect.custom") instead
Create a pull-out drawer for exploring pointer resolution: - PointerPlaygroundContext manages state between examples and drawer - PointerDrawer renders at bottom ~40% height, resizable via drag handle - PointerExample component with "Try it" button loads into drawer - Mobile support with full-screen drawer on narrow viewports - Resolve button moved to header row for better layout - Simple scrolling content pane for natural content flow Update resolution.mdx to use new interactive example components. Add showControls prop to ResolutionVisualizer for external control.
Document the six collection types for composing pointers: - group: combine multiple pointers - list: generate indexed sequences - conditional: choose based on runtime values - scope: define variables for nested pointers - reference: invoke reusable templates - templates: define inline templates Include examples for each type and explain nesting patterns.
Replace static JSON code blocks with PointerExample components that load directly into the Pointer Playground drawer. Fix pointer syntax to match schema requirements: - Use region references (strings) for $read expressions - Wrap template invocations in define blocks for variables - Avoid reserved property name "length" in region names
Convert static JSON code blocks to interactive PointerExample components in both regions.mdx and expressions.mdx documentation pages. Each example now includes: - Properly structured pointer definitions - Complete machine state (storage, memory, stack, etc.) - Descriptive titles and explanations Fixed computation descriptions to show correct results: - expressions.mdx: array-start (0x40) + index (2) × 32 = 0x80 - regions.mdx: base (0x80) + index (2) × 32 = 0xc0 Examples added to regions.mdx: - Memory region (slice-based) - Storage slot (slot-based) - Packed storage (sub-slot) - Memory, Storage, Stack, Calldata, Returndata, Code, Transient regions - Named regions - Dynamic memory offset Examples added to expressions.mdx: - Array element access - $sum, $difference, $product, $quotient, $remainder arithmetic - $read from named region - .offset and .length property lookups - $keccak256 for array and mapping slots - Nested mapping slots - $concat, $sized32, $wordsized data manipulation - List variables in expressions - Complete dynamic array element example
Renamed region from 'length' to 'len' to avoid JavaScript conflict with the built-in length property that was causing resolution errors.
- Migrate from eslint 8.x to eslint 9.x - Convert .eslintrc.json to eslint.config.js (flat config format) - Add typescript-eslint unified package - Add eslint-plugin-react-hooks for React rules - Remove old .eslintrc.cjs files from sub-packages - Remove @typescript-eslint dependencies from sub-packages - Update lint scripts to remove deprecated --ext flag
Adds a trace playground drawer that compiles BUG code and steps through EVM execution with source highlighting and variable inspection. Features: - Shared Drawer component for reuse with pointer playground - TracePlayground context for sharing examples between cards and drawer - TraceExample cards with "Try it" buttons to load examples - TraceDrawer with BUG editor, compile, and trace execution - Source highlighting linked to current trace step - Variables in scope display with type information - Stack and storage inspection panels - Horizontal step navigation controls Dependencies added: - @ethdebug/evm for bytecode execution - buffer polyfill for browser compatibility
Documentation updates: - Refine concepts, getting-started, and overview pages - Update pointers documentation (collections, expressions, regions) - Remove resolution.mdx (merged into other pages) - Update programs documentation (index, instructions, variables) - Update types documentation (composite, elementary, representation) - Update implementation guides and reference pages Styling fixes: - Update BugPlayground CSS - Update PointerDrawer and PointerExample CSS for consistency
Contributor
|
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
(This still needs to be seriously de-slopped)