🌞 [Other]: AST Module – Release Specification (v1.0)

[MariusStorhaug]

Description

Objectives

• AST Representation for Analysis: Provide a comprehensive object model that represents PowerShell Abstract Syntax Tree (AST) elements for static analysis. The module will parse PowerShell script code and produce a hierarchical object graph of the script’s structure without modifying the original AST or code. This allows tools or developers to introspect scripts programmatically in a safe, read-only manner.

• Hierarchical Structure Capture: Focus on capturing the script’s structural elements (the object graph of the code) in a clear hierarchy. Key script components will be represented as objects (e.g. Script, Function, Module, Class, Data), reflecting how they nest within each other. For example, a Script object will contain child objects for any functions, classes, or data sections defined within it. This hierarchical representation should mirror the code’s organization, making it easy to navigate and analyze.

• PowerShell 7.4+ Support: Ensure full compatibility with PowerShell 7.4 and later language features. The parser and object model must recognize and support all syntax introduced up to PowerShell 7.4 (and be forward-compatible with minor updates). This includes modern PowerShell constructs (for example, pipeline chain operators, null-coalescing operators, classes/enums, etc.) so that no language element is left unrepresented. The module will be tested against PowerShell 7.4 to verify that all AST elements can be captured in the object model.

• Read-Only Analysis (No Modification): Emphasize analysis and representation of code without any modification or execution of the AST. The module will not provide capabilities to alter the AST or the script’s content; it is strictly a passive analysis tool. This ensures using the module has no side effects on the scripts being analyzed. All objects produced will be effectively immutable or treated as read-only data structures.

• Structured Error Reporting: Implement robust error handling to detect and report syntax issues in scripts. If the script contains syntax errors, the module will catch these during parsing and present them in a structured way (with details like line numbers and error messages). This allows users to identify and locate syntax problems easily. The error handling mechanism will integrate with the object model (for example, via dedicated error objects or exception messages) without crashing the analysis process.

• Foundation for Future Extensibility: Design the module’s architecture with future enhancements in mind. Although version 1.0 will focus on basic representation, the structure should be flexible enough to extend later (for example, adding more detailed analysis, new AST node types, or integration with external tools in future versions). The goal is to create a maintainable codebase that can evolve as PowerShell introduces new features or as user needs grow. Version 1.0 will establish a clear and clean baseline on which optimizations and additional functionality can be built in subsequent releases.

• Version 1 Scope Limitations: This initial release purposefully does not include performance optimizations or external tool integrations. The emphasis is on correctness and completeness of the AST representation, not on speed or memory tuning. Likewise, features like integration with editors, linters, or visualization tools are outside the scope for now. By limiting scope, we ensure the core analysis features are solid. Future versions can then iterate on performance and integrations once the foundation is proven.

Class Hierarchy and Object Model

The module defines a set of classes that represent the key elements of a PowerShell script in a hierarchical object graph. These classes mirror the structure of the PowerShell AST, focusing on top-level and organizational elements. Each object provides properties to access important details of that code element. The relationships among these objects follow the nesting in the source code (for example, a Script contains Function and Class objects defined within it). Below is an overview of the major classes in the object model and their key properties:

• Script – Represents an entire PowerShell script file or script block. This is the root of the object graph for a given script.

  • Type: A category of the script content, identifying its primary purpose or structure. Possible values include "script" (a standard .ps1 script meant for execution), "module" (a .psm1 module file), "function" (a script file primarily containing function definitions, e.g. for dot-sourcing), "class" (a script primarily defining a PowerShell class or enum), or "data" (a script that contains a Data section). This classification helps consumers understand the context at a glance.
  • Functions: A collection (list) of Function objects for each function or filter defined at the top level of the script. If the script is a module, this would include all functions intended to be part of that module.
  • Classes: A list of Class objects for each PowerShell class defined in the script. PowerShell classes (available in PS 5.0+) are captured here, including any enums defined at the top level (enums may be represented either as Class objects with a special flag or as separate Enum objects; see Enum below).
  • Enums: A list of Enum objects for any standalone enumerations defined at top level. (If enums are treated as a type of Class in the implementation, they may appear in the Classes list instead, but the model will account for them one way or another.) Each Enum object would contain the name of the enum and its members.
  • DataBlocks: A list of Data objects representing any data { } sections in the script. Typically, a script would have at most one data section used for localized data or configuration. If the script’s type is "data", then it might primarily consist of one Data block. This property will be empty if no data sections are present.
  • Variables: A list of Variable definitions at the script’s top level. This captures global or module-scoped variables that are assigned in the script outside of any function or class. For example, in a module file, any module-level constants or configuration variables assigned would be listed here. Each Variable entry could include the variable’s name and possibly its initial value or type (if it’s a simple literal or declared constant). This helps in analyzing what global state a script or module defines.
  • ScriptParameters: If the script file begins with a param() block (as is allowed in PowerShell scripts), this property holds a list of Parameter objects for those script-level parameters. This is analogous to function parameters but for the entire script (commonly used in script files that act like functions taking arguments). If no param block at the top, this list will be empty.
  • ChildNodes: (Optional) A general collection of all child AST node representations within the script. In version 1, this will likely be a composite of the above lists (Functions, Classes, etc.). It provides a unified way to iterate over top-level elements in the order they appear in the script, if needed.

• Function – Represents a function or filter defined in the script. This corresponds to a function defined via the function (or filter) keyword in PowerShell.

  • Name: The name of the function as declared. This is used to identify the function (and would match how it’s invoked).
  • Type: The kind of function. Typically "function" for a standard function, or "filter" if the function was declared with the filter keyword. (Both are represented by this Function class since they are similar structurally; a property or flag could distinguish if needed.) All functions, including advanced functions (with cmdlet binding), are represented with this class.
  • Attributes: Any attributes applied to the function definition. This would include things like [CmdletBinding()] or [OutputType()] or any custom function-level attributes placed before the function keyword. These are stored as a list of attribute descriptors (with information such as attribute name and any arguments). For example, if a function has [CmdletBinding(SupportsShouldProcess)], that attribute would be captured here.
  • Parameters: A collection of Parameter objects defining the parameters of the function. Each parameter object contains details about one parameter (see Parameter below for details). The order of Parameter objects should match the order in the function’s param block. This list is empty if the function has no parameters.
  • CommentBasedHelp: The comment-based help text associated with the function, if present. If the function is preceded immediately by a comment block (<# ... #> with .SYNOPSIS, .DESCRIPTION, etc.), that text is captured here (likely as a raw string or a structured help object). This allows the analysis to include documentation info. If no such help comment exists, this may be null or an empty string.
  • Body: (Optional in v1) A representation of the function’s script block body. In version 1, the module will not deeply analyze the content of the function’s body (no full AST of statements here), but it may store a reference to the underlying AST node or a placeholder (like the number of lines in the function, or a raw AST object) for potential use. The focus in v1 is on the existence of the function and its signature, rather than the details of its implementation. In future versions, this could be expanded to contain a detailed breakdown of the function’s internal AST (commands, expressions, etc.).

• Class – Represents a PowerShell class defined in the script (PowerShell classes were introduced in PS 5.0 and are fully supported in PS 7.4).

  • Name: The name of the class as declared.
  • BaseClass: The name of the base class, if the class extends another class. If the class does not inherit from another (other than the default System.Object), this could be null or a default value. PowerShell allows single inheritance, so there is at most one base class.
  • Attributes: Attributes on the class definition (if any are supported in PS for classes). In PowerShell, class definitions do not commonly have attribute annotations like C# (aside from attributes on members), so this will usually be empty.
  • Members: A collection of members belonging to the class. Members include properties, methods, constructors, and possibly nested enums. Each member could be represented by a simplified object or record:
    • Properties: Their names and types. Possibly also whether they are static or instance properties.
    • Methods: Their names, return types, and parameter signatures. Includes constructors (which could be represented as methods named like the class or in a separate constructor list).
    • Enumerations: If the class contains an enum definition (PowerShell does not support truly nested class definitions, but it can have an enum defined within the same file; typically enums are top-level or within classes? If allowed within class as a static nested type, we would capture it here).
    • For version 1, the module might not fully enumerate all member details beyond names and basic signatures, because internal class analysis could be complex. However, the structure is in place to record these if needed.
  • InheritanceHierarchy: (Optional) Information about the class’s inheritance or interface implementation. For example, a list of interfaces implemented by the class (PowerShell class can implement interfaces), and possibly a reference to the base class (by name or linked to another Class object if that base is also defined in the same script). In v1, this could be a simple list of interface names (if any) and a base class name string.

• Enum – Represents an enumeration defined at top level (or potentially within a class if applicable).

  • Name: The name of the enum.
  • UnderlyingType: The underlying integer type of the enum (e.g. int by default, or something like byte, string if explicitly specified in the enum declaration). PowerShell enums default to int32 if not specified, and can be set to other numeric types.
  • Members: A list of the enum member names (and optionally their values). Each member of an enum typically has an implicit integer value (0,1,2, …) or an explicit value if given. In v1, the module can capture just the names, or name-value pairs if the value is explicitly set in the source.
  • Attributes: (If any attributes are allowed on enums in PowerShell, such as [Flags()] for a flags enum). If present, those would be captured here.
  • Note: Enums in PowerShell are often declared similarly to classes. In the AST, they have their own node type. The module may either treat them as a distinct Enum class (as described here) or include them in the Class list with a flag indicating it’s an enum. The specification accounts for them to ensure they are not missed in the representation.

• Data – Represents a data { } section within a script. A data section is a special construct in PowerShell used to define data that is isolated from code (often for localization or configuration).

  • VariableName: The name of the variable that the data statement assigns, if one is specified. In PowerShell, a data block can optionally assign its contents to a variable (e.g. data $Translations { ... }). If no name is given, this may be null, meaning the data block’s content is just evaluated in place.
  • Content: A representation of the contents of the data section. Since a data block can contain only restricted syntax (essentially hashtables and constants), this content could be captured as a structured object (like a nested dictionary of keys/values) or as a raw AST of the data block body. In v1, the module might not evaluate the data section, but it will store the AST or text of the data block so that the data (which is static by definition) can be examined. For example, if the data block contains a hashtable of translation strings, the Content might be that hashtable in a form that can be inspected.
  • AllowedCommands: (Optional) If relevant, a list of commands that were allowed in this data section (PowerShell data sections can explicitly permit certain commands via the -SupportedCommand option). Capturing this might be beyond the immediate needs of v1, but the structure allows it if needed for completeness.
  • Data sections are relatively infrequent, but the module includes support for them to ensure no part of the script structure is omitted from analysis.

• Parameter – Represents a parameter in a function or script param block. (This is a supporting class used within Function and Script.)

  • Name: The parameter name (without the $ sigil).
  • Type: The static type of the parameter, if declared (for example, [string], [int], or a custom class type). If no type was specified, this could be null or a generic type indicating it’s untyped (which effectively means System.Object in PowerShell).
  • DefaultValue: The default value of the parameter if one is provided (e.g. = "DefaultValue" in the function signature). This could be stored as a constant value (for literals) or as an AST/object if the default is an expression. In v1, we will capture whatever AST or value is present, but we will not evaluate it (so if the default is something like Get-Date, we just note the expression rather than calling it).
  • Attributes: Any parameter-specific attributes applied to this parameter. This includes attributes like [Parameter()] which can indicate if a parameter is Mandatory, Position, etc., as well as validation attributes like [ValidateRange()], [ValidateSet()], etc. These will be captured as a list of attribute descriptors with their arguments. Storing these allows analysis of parameter metadata (for example, identifying if a parameter is mandatory or has certain validations).
  • IsOptional: (Derived property) Indicates if the parameter is optional. This could be derived from whether it has a default value or is marked Mandatory=$false (default). If Mandatory=$true (and no default), then it’s required. This property isn’t explicitly provided by the AST but can be inferred for convenience in analysis.
  • Position: (Derived) The position index if the parameter is positional. This can be inferred from the [Parameter(Position=n)] attribute if present. If not specified, PowerShell will assign position based on order for parameters without mandatory naming; the module might calculate or provide this for completeness. (This is a potential enhancement; v1 can simply capture the attribute data from which this can be deduced.)

• Variable – Represents a top-level variable assignment captured in a Script (especially for modules).

  • Name: The name of the variable (e.g. $Config would have name "Config").
  • Value: The initial value assigned, if it’s a constant or literal. If the value is a complex expression or not a constant, the module may store an AST or a placeholder rather than evaluating it. For example, if the code says $Config = Get-ConfigData, we will note the presence of $Config but not execute Get-ConfigData. If the assignment is a simple constant (like $Timeout = 30), the value 30 could be stored for convenience.
  • Scope: (Optional) Indicates if the variable has any scope modifiers (in PowerShell, a top-level assignment is usually script-scoped or global-scoped depending on context. In a module, top-level is script scope by default. If the script explicitly used global: or script: in the variable name, that could be noted). In most cases, this will just be script-scope for module variables.
  • Constant: (Optional flag) True if the variable is declared as a constant (using the const keyword). Constant variables cannot be changed at runtime. The module will mark such variables, as this is important in understanding module behavior.

Hierarchy and Relationships: These objects will be linked in a parent-child hierarchy reflecting the code structure. For example, each Function object will have a reference to its parent Script. Class and Enum objects defined in the script similarly link back to the Script. Parameter objects link to their parent Function (or Script, if they are script parameters). This parent linkage, along with the child lists in each container (Script, Function with parameters, Class with members, etc.), allows traversal of the entire object graph in both directions. We will ensure that the hierarchy is consistent: e.g., adding a Function to the Script’s Functions list will also set the Function’s parent reference to that Script internally (the module’s builder will handle this). All relationships are read-only once built; users of the module can navigate them but not alter them.

The design of the class hierarchy closely follows PowerShell’s own AST constructs (e.g., function definitions, class definitions, etc.), which means it can be populated in a straightforward way by walking the real AST. However, it presents the information in a more analysis-friendly manner (grouping related info, omitting extraneous AST details like punctuation tokens, etc.). This hierarchy covers the top-level elements in a script. Deeper AST nodes (like individual statements or expressions inside function bodies) are not individually represented in this object model for version 1, both to keep the model simpler and because analysis often focuses on the structural level (functions, parameters, classes, etc.). In future versions, the object model may be extended to include more granular AST nodes if needed.

Design Considerations

The implementation of this module takes into account various design considerations to meet the objectives and ensure maintainability:

• Leverage PowerShell’s Parser: The module will utilize PowerShell’s built-in parsing engine to generate the initial AST from script text. We aren’t writing a new parser from scratch. Instead, we call the existing parser (available via the System.Management.Automation.Language.Parser API in PowerShell 7.4) to get a ScriptBlockAst for the input script. Using the proven built-in parser guarantees that we handle all PowerShell syntax correctly and consistently with how PowerShell itself interprets the code. Once we have the AST, our module will traverse it to build the custom object representation described in the Class Hierarchy.

• One-to-One Mapping of AST Nodes (Where Practical): The design tries to map each relevant AST node type to our object model in a clear way. For example, a FunctionDefinitionAst will be mapped to a Function object; a ClassDefinitionAst to a Class object; a top-level ScriptBlockAst (with its param block) to a Script object, and so on. This direct mapping makes the implementation straightforward and ensures no code element is missed. In some cases, the mapping is augmented to group related information: e.g., function AST contains the parameters and the body as separate AST nodes, but our Function object will gather parameter info from the AST’s ParamBlock and the help comment from preceding comments. The mapping will ignore AST nodes that are purely syntactic or not needed for structural analysis (like statement separators, or literal tokens), focusing only on semantic elements.

• Immutability and No Side-Effects: All objects created to represent the AST are treated as immutable data structures. Once the object graph is built for a given script, it does not provide methods to alter the script’s structure. This immutability is by design, reinforcing the idea that the module is for analysis only. It also simplifies reasoning about the data (no changes will occur during analysis that could invalidate earlier results). If the user wants to modify a script, they would have to do so outside this module (e.g., by editing the script or using a different tool). Our design does not allow round-tripping changes back into the script file or AST.

• Hierarchy Preservation: The design ensures that the natural hierarchy of code elements is preserved. For instance, functions belong to scripts, parameters belong to functions, etc., exactly as they do in the actual code structure. This means when building the model, the module must correctly handle nested scopes. If in the future PowerShell allows nested function definitions or other more complex scoping, the design would account for that by allowing Function objects to possibly contain other functions or by linking them appropriately. (In current PowerShell, nested function declarations are rare and not typically used, but theoretically could be handled by our model by simply treating them as another Function in the parent Script or function’s scope if we ever needed to represent that.)

• Metadata and Comments: An important consideration is capturing metadata that is not strictly part of code execution but is relevant to analysis, such as comment-based help and attributes. The design includes fields for these (like CommentBasedHelp in Function, and attribute lists for functions, parameters, etc.). To implement this, the module will need to gather comments from the token stream or AST. PowerShell’s parser provides comment tokens, and our design will associate those with the nearest function or script where appropriate. This ensures that documentation (help comments) and annotations (attributes) are not lost, as they are often important in understanding the code (for example, attributes can change how functions behave, and help comments are crucial for module documentation).

• PowerShell Version Compatibility: We target PowerShell 7.4 and above. The design takes into account features available in 7.x. For example, pipeline chaining (&&, ||), null-coalescing (??), and other new syntax elements introduced in PowerShell 7 do not directly introduce new top-level AST node types that our model would represent (they affect expression ASTs, which are lower-level than our focus). However, features like classes and enums (introduced in PS 5.0) and any newer keywords are considered. If PowerShell 7.4 includes new AST elements (for instance, hypothetical future keywords or constructs), the design would be evaluated to include those. So far, our class hierarchy covers the main structural constructs. We will validate the module against sample scripts using various PS 7.4 features to ensure nothing is missed. The code will be written to be forward-compatible where possible (e.g., if the parser returns an AST node type we don't explicitly handle, the module could log or ignore it gracefully, to be addressed in future updates).

• No Performance Optimizations (Deliberate): In this first version, the design does not incorporate advanced performance optimizations. For instance, we will parse the entire script and build the full object graph each time analysis is run, rather than caching results between runs. We also won’t invest in memory-saving techniques like lazy-loading parts of the AST. The rationale is to keep the design simple and correct. The typical use case (analyzing a single script or a moderate number of scripts at a time) should not pose performance issues in modern environments. By avoiding premature optimization, the code remains clearer and easier to maintain. We will, however, structure the code in a way that if performance becomes an issue in future (say, analyzing hundreds of large scripts in one go), we can profile and improve it in targeted ways (like caching parse results, or optimizing data structures) without needing to redesign the whole module.

• No External Dependencies: The module is self-contained with respect to analysis logic. It will not call out to external tools or services (such as PSScriptAnalyzer or language servers) in version 1. All analysis is done using the PowerShell engine’s own capabilities. This keeps the module simple to deploy (no additional installations or network calls) and ensures that analysis results are consistent (not dependent on external rule sets or configurations). While future versions might integrate with such tools or allow pluggable analyzers, the v1 design avoids the complexity of integrating third-party components or APIs. This also eliminates issues of tool compatibility and licensing at this stage.

• Error Handling Strategy: The design includes a clear strategy for error handling (detailed in its own section below). From a design perspective, it means that the module’s functions (for example, a function to analyze a given script file) will return results in a way that encapsulates both the constructed object graph and any errors. This could be an object that has both the root Script object (or null if not parsed) and a collection of Error objects. Alternatively, the module might throw a specific exception on parse failure. We considered both approaches; for ease of integration, returning a result with errors included is more structured (it allows the caller to decide how to handle a syntax error). Internally, the design will involve checking the parser’s error output and either populating error structures or halting the object construction based on the severity of errors. The module design ensures that a syntax error in one part of the script does not produce misleading partial data elsewhere – we either provide what could be parsed with clear error indicators, or stop with an error report.

• Maintainability and Clarity: The code structure of the module is planned to mirror this specification closely. Each class in the object model will likely be implemented as a PowerShell class or a PSCustomObject/C# class (depending on if the module is written in PowerShell or as a binary module). Clear naming (as given in this spec) will be used for properties to make the output self-explanatory. The module will be documented alongside this (so users know what each property means). By designing the classes upfront with explicit responsibilities, we ensure that adding new properties or new node types in the future will be straightforward. The internal traversal of the AST will be modular (e.g., a separate function or method to process functions, one for classes, etc.), making the code easy to navigate and update when PowerShell changes or when new features are needed.

In summary, the design choices prioritize correctness, completeness of representation, and ease of use over raw performance or feature breadth. We stick closely to PowerShell’s own understanding of code (via its AST) but reshape it into a form that is more convenient for analysis. The result is a foundational module that can serve various script analysis needs and can be extended over time.

Extensibility Plans

Although version 1.0 is limited in scope, the module is designed with future extensibility in mind. Here we outline how we anticipate growing and enhancing the module in future releases and how the design will accommodate these changes:

• Support for More AST Node Types: Future versions may extend the object model to include finer-grained AST nodes if there is demand for deeper analysis. For example, we might introduce objects for statements, pipelines, or expressions within function bodies. This would allow analysis of not just the high-level structure (functions, classes) but also the content of those functions (e.g. to find all cmdlets used, or analyze complexity). The current design can be extended by adding new classes (e.g., Statement, Command, Expression classes) and linking them into the existing hierarchy (for example, a Function object could get a list of Statement objects for its body). Because we already maintain parent-child relationships, adding another layer of children for statements is feasible without breaking the existing model. Each new AST node type introduced by future PowerShell versions would be evaluated and a corresponding representation added to the module’s class hierarchy as needed.

• Integration with Analysis Tools: In future releases, we plan to integrate this module with external analysis or development tools. For example, we could integrate with PowerShell Script Analyzer (PSScriptAnalyzer) to run rule checks on the AST object graph or allow our module’s results to be fed into PSScriptAnalyzer for custom rules. Similarly, integration with IDEs or editors (like VS Code’s PowerShell extension) could allow the module to provide features like code outline views or semantic navigation. The design’s separation of structure gathering (AST parsing) from presentation means we can expose the object graph in different contexts easily. We may add APIs or cmdlets that output the analysis in standardized formats (JSON, XML) so other tools can consume it. Because version 1.0 avoids external dependencies, adding them later (optionally) won’t conflict with the core functionality – they would be additional layers or plugins on top of the core analysis engine.

• Performance Improvements: While performance tuning is not in scope for v1, future versions will address it if needed. Possible enhancements include caching parsed ASTs for unchanged files to avoid re-parsing, or analyzing differences between script versions (incremental analysis). We could also optimize memory usage by storing only essential information in the object graph or by sharing common sub-structures. If profiling indicates bottlenecks (for example, extremely large scripts with many functions), we might introduce lazy evaluation of certain properties (only computing detailed info like comment help text when requested) or multi-threaded analysis for batches of files. The current design doesn’t preclude these – for instance, our object model could implement something like an interface or lazy property for body analysis later. By keeping the design modular, we ensure we can swap in optimized components (like a faster parsing routine if available, or a different internal representation) without changing the external API of the module.

• Mutable AST or Refactoring Support (Possibility): A potential future direction (if we ever expand beyond pure analysis) is to allow modifications to the AST or provide refactoring tools (e.g., renaming a function, updating parameters programmatically). If this becomes a goal, the object model we have could serve as a foundation – we would need to add methods to modify the structure and then output the changed script. Our current design is read-only by choice, but in terms of extensibility, we could consider either converting our classes to mutable ones or providing a parallel set of builder classes that can create new or modified ASTs. This would be a significant extension and would be carefully designed to not impact the stability of the analysis features. Essentially, we’d ensure that any such features are isolated such that users who only need read-only analysis are unaffected by the additional complexity.

• Enhanced Error and Semantic Analysis: Today’s error handling focuses on syntax errors. In the future, we might extend the module to also perform certain semantic analyses or validations. For example, we could add checks for undefined variables, unused parameters, or potential runtime issues (this veers into the territory of linting). While some of these go beyond just representing the AST, the information our module gathers can be a basis for such rules. Extensibility could be provided via a plugin system where users can write custom analyzers that traverse our object graph and check for conditions (similar to how linters or analyzers work). The module might offer an API to register such analyzers or a set of built-in analysis rules that can be toggled. Designing our object model to be easily traversable (perhaps by implementing visitor patterns or by leveraging PowerShell’s AST visitor on the underlying AST) will facilitate this sort of extension.

• Maintainability with Evolving PowerShell: We will monitor changes in the PowerShell language (for example, if PowerShell 8.0 introduces new syntax or deprecates something). The module’s architecture should allow accommodating these changes with minimal disruption. This might mean writing version-specific logic if needed (e.g., if a new AST type appears, handling it conditionally based on PS version). Because we target 7.4+, we assume a relatively stable language base for now. If we were to later support older versions (like Windows PowerShell 5.1), we could introduce abstraction to handle differences in AST (for instance, some AST types exist only in newer versions). The code could be structured to detect what’s available and adapt accordingly. In any case, extending support either forward or backward in PowerShell versions is a consideration that the design doesn’t lock us out of.

• Documentation and Usability: As the module grows, we intend to maintain clear documentation and possibly generate schema or diagrams for the object model. An idea for future is to auto-generate documentation of the AST structure (maybe even produce a UML-like class diagram or a markdown table of class properties) directly from the code, ensuring docs stay in sync. Also, future versions might include examples or built-in commands to easily visualize the AST object graph (e.g., a ConvertTo-Json of the structure for quick viewing, or a pretty-print tree). These are usability enhancements that don’t change the core but make the module more accessible. The structured design of our classes should make such additions straightforward.

In summary, version 1.0 is just the starting point. The module is built in a way that new features – whether they are deeper AST insights, integrations, performance tweaks, or even moving into code transformation – can be layered on with minimal rework. Each future enhancement will build on the stable foundation provided by v1. By planning for extensibility now, we ensure the module can adapt to the needs of its users and the evolution of PowerShell itself.

Error Handling Approach

A critical aspect of this module is how it handles errors, particularly syntax errors in the PowerShell scripts being analyzed. The goal is to provide structured and clear feedback when a script cannot be fully parsed, without leaving the user guessing what went wrong. Below is the approach to error handling in this release:

• Parsing Phase and Syntax Error Capture: When the module attempts to parse a script (using PowerShell’s parser), any syntax errors encountered will be caught immediately. The PowerShell parser returns a list of parse errors (each typically includes a message, the location in the script, and an error identifier). The module will collect these errors and not proceed to build the object model until the errors are handled. In practice, this means our analysis function will likely call the parser and check if any errors were returned. If so, it will skip or abort the AST-to-object conversion step and instead focus on preparing error output.

• Error Object Structure: Syntax errors will be encapsulated in Error objects (or a similar structured format) before being returned to the caller. Each Error object will include relevant information such as:

  • Message: The human-readable error message (e.g., “Unexpected token '}' in expression or statement”). This comes from the parser’s error message.
  • Extent (Location): Precise location info, typically the line and column number where the error occurred, and possibly the text snippet (extent) of code that triggered the error. For example, an Error object might indicate it’s at line 10, column 5 of the script, making it easy for a user to find.
  • ErrorId/Type: If available, a specific error ID or category (e.g., IncompleteInput or ParserError) to classify the type of syntax error. This can be useful if the calling application wants to handle certain types of errors differently.
  • These error objects provide a structured way to programmatically inspect errors instead of just printing them to console.

• Reporting and Workflow: The module will provide the error information in one of two ways, depending on how the user calls the analysis:

  1. Return Object: The primary design is that the main analysis function returns a result object that contains either the constructed Script object (on success) and an empty error list, or, in case of parse failure, it contains a null/empty Script object and a populated error list. This way, the user can inspect the result and see if errors occurred. For example, the result might be a custom object with properties like .AstRoot and .Errors. If .Errors is non-empty, the user knows the AST was not built fully.
  2. Exceptions: Optionally, we may allow the module to throw a specific exception when a syntax error is encountered, especially if the user calls a function that expects a valid AST. This exception would carry the same error details. However, by default, we lean towards not using exceptions for control flow, and instead use the result object approach, because it allows multiple errors to be reported at once and fits typical analysis scenarios where you might want to gather all issues. Regardless, the exception (if used) would be a custom one indicating it’s a parse error and would include the errors collection in its data, so even if caught, the caller can retrieve all the error info.

• Multiple Errors Handling: PowerShell’s parser can return more than one error (for example, a script with several mistakes might have multiple parse errors). The module will handle all errors in one pass. All detected syntax errors will be included in the output. We will not stop at the first error unless the parsing process itself cannot continue. Typically, the parser attempts to continue after an error to find more issues, so we take advantage of that. The Error list in the result might contain one or several entries. The user of the module can decide whether to fix all and re-run, or address them iteratively. Our approach ensures the user gets as much information as possible in one go.

• Partial AST Consideration: In some cases, the parser might return a partial AST even if there are errors (for example, if the error is at the end of the script, the beginning might still be parsed into AST nodes). Our module’s default behavior in v1 is not to produce a partial object graph if there are syntax errors. We will either provide a full representation (when no syntax errors) or none (when errors exist), to avoid confusion that could be caused by incomplete data. However, we recognize that there is value in partial analysis (for example, you might want to see the functions that were defined before a syntax error occurred later in the file). We have left room in the design for a future mode or option that could return partial results with errors, but by default in this release, we opt for an “all-or-nothing” representation to keep things straightforward. If partial AST data is returned alongside errors, it will be clearly documented and likely off by default.

• Robust Handling of Edge Cases: The module will also handle other error scenarios gracefully:

  • If the input script file is not found or cannot be read, the module will produce an appropriate error (e.g., an Error object with message “File not found” or “Access denied” rather than a parse error). This is part of the error-handling workflow before parsing – we first ensure the input is accessible, then parse.
  • If the script is empty (no content), this is not exactly an error; the module would return a Script object with no child elements (and no errors). We consider that a valid case (AST would be basically an empty script).
  • If there are unsupported scenarios (for example, running on an older PowerShell version that doesn’t support a syntax used in the script), the parser itself would error. We will report those just as syntax errors. We will document that PS 7.4 is required to parse newer constructs.
  • Internal errors within the module (unexpected exceptions during object graph construction, etc.) will be caught and wrapped into either an Error object or thrown as a module-specific exception. We will try to differentiate these from script syntax errors. For example, if a null reference exception occurred in our code (which shouldn’t happen with thorough testing), we would catch it and perhaps include a generic “Analysis internal error” message. This is to ensure the module doesn’t just crash silently; any failure should be communicated clearly.

• Testing Error Handling: As part of the release, error handling will be tested with a variety of broken scripts to ensure the module correctly captures and reports issues. For instance, we will test a script with an unclosed brace, a script with an illegal character, etc., and confirm that the Errors list is populated with the expected messages and locations. The structured error output will be validated against PowerShell’s own error reporting to make sure we’re consistent (where possible, we use the exact parser message and position to avoid any ambiguity).

• User Experience: From the end-user perspective (like a developer using this module), encountering a syntax error in their script analysis will result in a clear outcome: they will see a list of errors and know that the analysis did not proceed to produce the AST model. They can then correct the script and re-run the analysis. The module’s documentation will include examples of handling errors – for example, demonstrating checking the result object’s Errors property or catching the exception, so users know how to use the information. By structuring the error data, we also enable tooling on top of the module to, say, highlight errors in an editor or generate a report of syntax issues across multiple scripts.

In summary, the error handling approach for the PowerShell AST Analysis Module v1.0 is designed to be comprehensive and developer-friendly. We prioritize clear communication of syntax problems, using structured data to represent errors. This approach ensures that the absence of an AST output is always accompanied by an explanation, and that analysis consumers can programmatically react to errors. By handling errors methodically, the module remains robust even when faced with invalid input, thereby improving trust and reliability in its use.

[MariusStorhaug]

Perfect for speckit!