FractalDataWorks.Roslyn.Commands.Abstractions 0.4.0-preview.6

FractalDataWorks.Roslyn.Commands.Abstractions

Abstractions for Roslyn-based code analysis and refactoring commands. Provides interfaces, base classes, and TypeCollections for defining commands that operate on Roslyn solutions and workspaces.

Installation

<PackageReference Include="FractalDataWorks.Roslyn.Commands.Abstractions" Version="1.0.0" />

Overview

This package defines the command pattern infrastructure for Roslyn operations:

• Commands - Stateless data objects describing operations to perform on a solution
• Command Categories - TypeCollection-based categorization (Analysis, Navigation, Refactoring, etc.)
• Command Translators - Execute commands against Roslyn solutions
• Command Results - Query results (read-only) and mutation results (solution changes)

Target Framework

• net10.0

Dependencies

• FractalDataWorks.Commands.Development.Abstractions - Base development command infrastructure
• FractalDataWorks.Collections.SourceGenerators - TypeCollection source generation
• Microsoft.CodeAnalysis.Workspaces.Common - Roslyn workspace APIs

Core Types

Commands

From IRoslynCommand.cs:5-14:

/// <summary>
/// Represents a command that operates on a Roslyn solution.
/// </summary>
public interface IRoslynCommand : ITypeOption<int, RoslynCommandBase>
{
    /// <summary>
    /// Gets the command category. May be null for Empty sentinel.
    /// </summary>
    IRoslynCommandCategory? CommandCategory { get; }
}

From RoslynCommandBase.cs:6-37:

/// <summary>
/// Base class for Roslyn commands.
/// Commands are stateless data objects that describe an operation to perform.
/// </summary>
public abstract class RoslynCommandBase : TypeOptionBase<int, RoslynCommandBase>, IRoslynCommand
{
    /// <summary>
    /// Gets the command category.
    /// </summary>
    public IRoslynCommandCategory? CommandCategory { get; }

    /// <summary>
    /// Initializes a new instance of the <see cref="RoslynCommandBase"/> class.
    /// </summary>
    /// <param name="name">The name of the command.</param>
    /// <param name="commandCategory">The category of the command.</param>
    /// <param name="description">The description of the command.</param>
    protected RoslynCommandBase(string name, IRoslynCommandCategory commandCategory, string description)
        : base(GenerateIdFromName(name), name, name, name, description, "RoslynCommand")
    {
        CommandCategory = commandCategory ?? throw new ArgumentNullException(nameof(commandCategory));
    }
}

Command Handler

From IRoslynCommandHandler.cs:8-35:

/// <summary>
/// Handles execution of Roslyn commands, orchestrating between workspace and translators.
/// </summary>
public interface IRoslynCommandHandler
{
    /// <summary>
    /// Executes a command and returns the result.
    /// </summary>
    /// <typeparam name="TCommand">The type of command to execute.</typeparam>
    /// <typeparam name="TResult">The type of result expected.</typeparam>
    /// <param name="command">The command to execute.</param>
    /// <param name="cancellationToken">The cancellation token.</param>
    /// <returns>A result containing the command output or an error.</returns>
    Task<IGenericResult<TResult>> Execute<TCommand, TResult>(
        TCommand command,
        CancellationToken cancellationToken = default)
        where TCommand : IRoslynCommand
        where TResult : IRoslynCommandResult;

    /// <summary>
    /// Executes a command with dynamic result type.
    /// </summary>
    /// <param name="command">The command to execute.</param>
    /// <param name="cancellationToken">The cancellation token.</param>
    /// <returns>A result containing the command output or an error.</returns>
    Task<IGenericResult<IRoslynCommandResult>> Execute(
        IRoslynCommand command,
        CancellationToken cancellationToken = default);
}

Command Translators

From IRoslynCommandTranslator.cs:9-48:

/// <summary>
/// Translates a Roslyn command into an operation on a Solution.
/// Extends <see cref="IDevelopmentCommandTranslator"/> for Roslyn-specific translation.
/// </summary>
public interface IRoslynCommandTranslator : IDevelopmentCommandTranslator
{
    /// <summary>
    /// Executes the command against the solution.
    /// </summary>
    /// <param name="command">The command to execute.</param>
    /// <param name="solution">The Roslyn solution.</param>
    /// <param name="cancellationToken">The cancellation token.</param>
    /// <returns>The result of the command execution.</returns>
    Task<IGenericResult<IRoslynCommandResult>> Execute(
        IRoslynCommand command,
        Solution solution,
        CancellationToken cancellationToken = default);
}

/// <summary>
/// Strongly-typed translator for a specific Roslyn command type.
/// </summary>
/// <typeparam name="TCommand">The type of command.</typeparam>
/// <typeparam name="TResult">The type of result.</typeparam>
public interface IRoslynCommandTranslator<in TCommand, TResult> : IRoslynCommandTranslator
    where TCommand : IRoslynCommand
    where TResult : IRoslynCommandResult
{
    /// <summary>
    /// Translates and executes the command against the solution.
    /// </summary>
    Task<IGenericResult<TResult>> Translate(
        TCommand command,
        Solution solution,
        CancellationToken cancellationToken = default);
}

Command Results

From IRoslynCommandResult.cs:5-24:

/// <summary>
/// Marker interface for Roslyn command results.
/// </summary>
public interface IRoslynCommandResult
{
    /// <summary>
    /// Gets a summary of the result.
    /// </summary>
    string Summary { get; }

    /// <summary>
    /// Gets a value indicating whether this result represents a mutation.
    /// </summary>
    bool IsMutation { get; }

    /// <summary>
    /// Gets the new solution if this is a mutation result, otherwise null.
    /// </summary>
    Solution? NewSolution { get; }
}

From Results/QueryResult.cs:9-36:

/// <summary>
/// Represents a query result that does not modify the solution.
/// </summary>
/// <typeparam name="T">The type of data returned by the query.</typeparam>
public sealed class QueryResult<T> : IRoslynCommandResult
{
    public QueryResult(string summary, T data)
    {
        Summary = summary ?? throw new ArgumentNullException(nameof(summary));
        Data = data;
    }

    public string Summary { get; }
    public bool IsMutation => false;
    public Solution? NewSolution => null;
    public T Data { get; }
}

From Results/MutationResult.cs:9-52:

/// <summary>
/// Represents a mutation result that modifies the solution.
/// </summary>
public class MutationResult : IRoslynCommandResult
{
    public MutationResult(string summary, Solution newSolution)
    {
        Summary = summary ?? throw new ArgumentNullException(nameof(summary));
        NewSolution = newSolution ?? throw new ArgumentNullException(nameof(newSolution));
        ChangedFiles = Array.Empty<FileChange>();
    }

    public MutationResult(string summary, Solution newSolution, IReadOnlyList<FileChange> changedFiles)
    {
        Summary = summary ?? throw new ArgumentNullException(nameof(summary));
        NewSolution = newSolution ?? throw new ArgumentNullException(nameof(newSolution));
        ChangedFiles = changedFiles ?? throw new ArgumentNullException(nameof(changedFiles));
    }

    public string Summary { get; }
    public bool IsMutation => true;
    public Solution NewSolution { get; }
    public IReadOnlyList<FileChange> ChangedFiles { get; }
}

TypeCollections

RoslynCommands

From RoslynCommands.cs:6-15:

/// <summary>
/// Type collection for Roslyn commands.
/// Child collection of <see cref="DevelopmentCommands"/> for C# specific commands.
/// Discovers all commands marked with [TypeOption(typeof(RoslynCommands), "CommandName")].
/// </summary>
[TypeCollection(typeof(RoslynCommandBase), typeof(IRoslynCommand), typeof(RoslynCommands),
    TypeOption = typeof(DevelopmentCommands), TypeOptionName = "Roslyn")]
public static partial class RoslynCommands
{
}

RoslynCommandCategories

From RoslynCommandCategories.cs:6-12:

/// <summary>
/// Type collection for Roslyn command categories.
/// </summary>
[TypeCollection(typeof(RoslynCommandCategoryBase), typeof(IRoslynCommandCategory), typeof(RoslynCommandCategories))]
public static partial class RoslynCommandCategories
{
}

RoslynCommandTranslators

From RoslynCommandTranslators.cs:6-15:

/// <summary>
/// Type collection for Roslyn command translators.
/// Child collection of <see cref="DevelopmentCommandTranslators"/> for C# specific translators.
/// Discovers all translators marked with [TypeOption(typeof(RoslynCommandTranslators), "TranslatorName")].
/// </summary>
[TypeCollection(typeof(RoslynCommandTranslatorBase), typeof(IRoslynCommandTranslator), typeof(RoslynCommandTranslators),
    TypeOption = typeof(DevelopmentCommandTranslators), TypeOptionName = "Roslyn")]
public static partial class RoslynCommandTranslators
{
}

Built-in Command Categories

The package includes the following command categories:

Example category definition from Categories/NavigationCommandCategory.cs:6-17:

/// <summary>
/// Command category for code navigation operations.
/// </summary>
[TypeOption(typeof(RoslynCommandCategories), "Navigation")]
public sealed class NavigationCommandCategory : RoslynCommandCategoryBase
{
    public NavigationCommandCategory() : base(6, "Navigation", "Code navigation operations")
    {
    }
}

Implementing a Command

To implement a custom Roslyn command:

1. Define the command class extending RoslynCommandBase
2. Mark with [TypeOption(typeof(RoslynCommands), "CommandName")]
3. Implement a translator extending RoslynCommandTranslatorBase<TCommand, TResult>
4. Mark the translator with [TypeOption(typeof(RoslynCommandTranslators), "TranslatorName")]

See FractalDataWorks.Roslyn.Commands for concrete command implementations.

Translator Registry

From ITranslatorRegistry.cs:8-43:

/// <summary>
/// Registry for looking up command translators.
/// </summary>
public interface ITranslatorRegistry
{
    /// <summary>
    /// Gets a translator for the specified command and result types.
    /// </summary>
    IGenericResult<IRoslynCommandTranslator<TCommand, TResult>> GetTranslator<TCommand, TResult>()
        where TCommand : IRoslynCommand
        where TResult : IRoslynCommandResult;

    /// <summary>
    /// Gets a translator for the specified command type.
    /// </summary>
    IGenericResult<IRoslynCommandTranslator> GetTranslator(Type commandType);

    /// <summary>
    /// Registers a translator.
    /// </summary>
    void Register(IRoslynCommandTranslator translator);

    /// <summary>
    /// Registers a strongly-typed translator.
    /// </summary>
    void Register<TCommand, TResult>(IRoslynCommandTranslator<TCommand, TResult> translator)
        where TCommand : IRoslynCommand
        where TResult : IRoslynCommandResult;
}

Related Packages

• FractalDataWorks.Commands.Development.Abstractions - Base development command infrastructure
• FractalDataWorks.Roslyn.Commands - Concrete Roslyn command implementations
• FractalDataWorks.Collections - TypeCollection base types