stewbeet.plugins.auto.headers

The auto.headers plugin automatically generates documentation headers for mcfunction files.
It analyzes function calls, function tags, advancement rewards, and macro function arguments
to create @within documentation that shows which functions, tags, or advancements
call each function, providing clear dependency tracking and usage documentation.

Context Analysis: The plugin extracts and preserves execution contexts
from execute commands (such as as @e, positioned, at, rotated, facing, etc.)
and automatically determines the execution context for functions based on their callers.

Macro Analysis: For macro functions (using $(variable) syntax), the plugin automatically
detects macro variables, infers their types from function calls and storage NBT data, and generates
@args documentation with type information. It supports both direct NBT calls and storage-based calls,
with type inheritance from calling functions.

Source Code: stewbeet/plugins/auto/headers/__init__.py

Source Code: stewbeet/plugins/auto/headers/object.py

Source Code: stewbeet/plugins/auto/headers/context_analyzer.py

Source Code: stewbeet/plugins/auto/headers/execution_parser.py

Source Code: stewbeet/plugins/auto/headers/function_analyzer.py

Source Code: stewbeet/plugins/auto/headers/macro_analyzer.py

Source Code: stewbeet/plugins/auto/headers/macro_parser.py

Source Code: stewbeet/plugins/auto/headers/type_inference.py

What it does

  • Automatically generates function documentation headers
  • Tracks function call relationships and dependencies
  • Analyzes function tag memberships and usage
  • Monitors advancement reward function calls
  • Detects macro variables and infers their types automatically
  • Generates @args documentation for macro functions with type information
  • Type inference from NBT data, direct calls, and storage operations
  • Type inheritance from calling functions via $(variable) references
  • Preserves manual descriptions in @args while auto-filling missing types
  • Extracts execution contexts from execute commands (as, at, positioned, rotated, facing, in, anchored, align)
  • Determines function execution contexts automatically based on caller analysis
  • Creates @within and @args documentation

Dependencies

  • โœ… Required: Beet context with functions, function tags, and advancements
  • ๐Ÿ“ Position: Should run after all content generation but before finalization
  • ๐Ÿ”ง Optional: Existing function headers (will be parsed and updated)

Some Features Showcase

Example of a function being called by multiple functions with macro arguments:

Example of a function being called by multiple functions with different contexts:

Example of a function being called by multiple macro arguments (with arguments types):

Configuration

Basic Example Configuration

yaml
pipeline:
  - ...
  - stewbeet.plugins.auto.headers
  - ... # Some finalization plugins

# No configuration required - plugin runs automatically
# Processes all functions, function tags, and advancements by default

Configuration Options

OptionTypeDefaultDescription
Header GenerationautomaticEnabledCreates headers for all mcfunction files
Dependency TrackingautomaticEnabledAnalyzes function calls and references
Tag AnalysisautomaticEnabledProcesses function tag memberships
Advancement RewardsautomaticEnabledTracks advancement reward functions

Features

Macro Argument Analysis (NEW!)

Automatically detects and types macro function arguments:

  • ๐Ÿ” Auto-detection - Scans function content for $(variable) patterns
  • ๐Ÿ“Š Type inference from NBT - Analyzes direct calls like function test {x:10,y:20.5f,id:"hello"}
  • ๐Ÿ’พ Storage-based inference - Parses data modify storage commands to extract types
  • ๐Ÿ”„ Type inheritance - When $(var) references another function's argument, inherits the type
  • ๐Ÿงฌ Recursive analysis - Follows function call chains to ensure all types are resolved
  • ๐Ÿ“ Description preservation - Keeps manually written descriptions while filling missing types
  • ๐ŸŽฏ NBT type mapping - Correctly identifies byte(b), short(s), int, long(l), float(f), double(d), string, compound, list
  • ๐Ÿ“‹ Order preservation - Arguments listed in order of first appearance in the file
  • ๐Ÿ”— Merge logic - Combines inferred types with manual annotations (manual takes precedence)

Supported Type Inference Patterns:

mcfunction
# Direct NBT call
function namespace:target {x:10,y:20.5f,name:"Player"}
# -> Infers: x (int), y (float), name (string)

# Storage-based call
data modify storage temp:data macro set value {dimension:"minecraft:overworld",x:0,y:64,z:0}
function namespace:teleport with storage temp:data macro
# -> Infers: dimension (string), x (int), y (int), z (int)

# Type inheritance
function caller {result:$(value)}
# If caller has @args with value (int), target inherits: result (int)

Execution Context Analysis

Analyses and determines execution contexts:

  • ๐Ÿ” Parses execute commands to extract contexts like as @e[type=zombie], positioned ~ ~1 ~, at @s, rotated 45 0
  • ๐Ÿง  Smart selector simplification for complex selectors with NBT data and multiple attributes
  • ๐Ÿ”„ Context inheritance - functions inherit execution contexts from their callers when appropriate
  • ๐Ÿ“‹ Automatic context determination for advancement reward functions (as the player & at current position)
  • โšก Special handling for tick/load tags and other built-in contexts
  • ๐Ÿ“ Context preservation in @executed header sections

Function Header Parsing

Parses existing function headers:

  • ๐Ÿ” Detects #> function_name header format
  • ๐Ÿ“‹ Extracts existing @within information
  • ๐Ÿ“ Preserves custom documentation comments
  • ๐Ÿ”„ Separates header content from actual function code

Function Tag Analysis

Analyzes function tag memberships for documentation:

  • ๐Ÿ“Š Processes all function tags in the datapack
  • ๐Ÿ”— Creates #namespace:tag_name references for tagged functions
  • ๐Ÿ“ Handles both string and object-based tag entries
  • โœ… Supports conditional tag entries with IDs

Advancement Reward Tracking

Monitors advancement reward function calls:

  • ๐ŸŽฏ Scans advancement reward sections for function calls
  • ๐Ÿ“‹ Creates advancement namespace:advancement_name references
  • ๐Ÿ”— Links reward functions to their triggering advancements
  • โœ… Ensures proper advancement-to-function relationship tracking

Function Call Analysis

Analyzes direct function calls within mcfunction files:

  • ๐Ÿ” Scans each line for function commands
  • ๐ŸŽฏ Extracts called function names with quote handling
  • ๐Ÿ”ง Captures macro parameters and scheduling information
  • ๐Ÿงฉ Resolves macro placeholders in the called path ($function ns:types/$(type)) against every function
  • ๐Ÿท๏ธ Lists a quoted function id given as data ({give_function:"ns:give/weapon"}) as a string in reference
  • ๐ŸŽฎ Analyzes execution contexts from execute commands (as @e, positioned, at, rotated, facing, in, anchored, align)
  • ๐Ÿ“‹ Parses complex selectors with NBT data and multiple attributes
  • ๐Ÿ”„ Inherits execution contexts from calling functions when appropriate
  • ๐Ÿ“Š Prevents duplicate entries in the @within list

Dialog and Enchantment Analysis

Reads functions named in dialogs (run_command actions) and enchantments (run_function effects):

  • ๐Ÿ“‹ Creates dialog namespace:path and enchantment namespace:path references

Header Generation System

Generates documentation headers:

  • ๐Ÿ“ Creates standardized #> function_name headers
  • ๐Ÿ“‹ Generates @within sections listing all callers
  • ๐Ÿ”“ Writes (public) instead of ??? on an uncalled function of the project outside its ns:v<version>/ folder
  • ๐Ÿ”ง Preserves existing custom documentation
  • โœ… Uses proper formatting with tabs and spacing

File Writing and Updates

Updates all mcfunction files with generated headers:

  • ๐Ÿ“ Writes updated headers to all processed functions
  • ๐Ÿ”„ Overwrites existing files with new documentation
  • ๐Ÿ“Š Maintains clean formatting and structure
  • โœ… Ensures all functions have complete documentation headers

Next steps