CyberdyneDevelopment.Mc3Po.Tools.Abstractions 0.1.0-preview.6

Mc3Po.Tools.Abstractions

Base abstractions for the FractalDataWorks development tools framework.

Overview

This package provides the foundational interfaces and base classes for building development tools that work with Roslyn-based code analysis. Tools are discoverable via the TypeCollection pattern and organized into categories.

Key Types

Core Interfaces

• ITool - Base interface for all development tools, extends ITypeOption<Guid, ToolBase>
• ToolBase - Abstract base class implementing common tool functionality
• ToolInput - Input parameters container for tool execution
• ToolOutput - Result container with message and data dictionary
• ToolParameter - Parameter definition with name, description, type, and validation

TypeCollections

• ToolTypes - TypeCollection for discovering all registered tools
• ToolCategories - TypeCollection for tool categories (Analysis, Compilation, etc.)
• ToolParameterTypes - TypeCollection for parameter types (String, Integer, Boolean, etc.)

Tool Categories

• AnalysisToolCategory - Code analysis tools
• CompilationToolCategory - Build and compilation tools
• FormattingToolCategory - Code formatting tools
• GenerationToolCategory - Code generation tools
• NavigationToolCategory - Code navigation tools
• ProjectToolCategory - Project/solution management tools
• RefactoringToolCategory - Code refactoring tools
• SearchToolCategory - Code search tools
• WorkspaceToolCategory - Workspace management tools
• ConventionsToolCategory - FractalDataWorks-specific tools

Usage

Creating a Custom Tool

using Mc3Po.Tools.Abstractions;
using Mc3Po.Tools.Abstractions.Categories;
using FractalDataWorks.Collections.Attributes;

[TypeOption(typeof(ToolTypes), "MyCustomTool")]
public sealed class MyCustomTool : ToolBase
{
    private readonly IRoslynWorkspace _workspace;

    public MyCustomTool(IRoslynWorkspace workspace)
        : base("MyCustomTool", ToolCategories.Analysis, "Performs custom analysis")
    {
        _workspace = workspace;
    }

    public override IReadOnlyList<ToolParameter> Parameters { get; } =
    [
        new ToolParameter("filePath", "Source file path", ToolParameterTypes.String, isRequired: true),
        new ToolParameter("verbose", "Enable verbose output", ToolParameterTypes.Boolean, isRequired: false, defaultValue: false)
    ];

    public override async Task<IGenericResult<ToolOutput>> Execute(
        ToolInput input,
        CancellationToken cancellationToken = default)
    {
        var filePathResult = input.GetRequired<string>("filePath");
        if (!filePathResult.IsSuccess)
            return GenericResult<ToolOutput>.Failure("File path is required");

        var verbose = input.GetOptional("verbose", false);

        // Perform analysis using _workspace.CurrentSolution...

        return GenericResult<ToolOutput>.Success(
            new ToolOutput("Analysis complete", new Dictionary<string, object>
            {
                ["results"] = new[] { /* ... */ }
            }));
    }
}

Executing a Tool

// Get tool by name from TypeCollection
var tool = ToolTypes.ByName("AnalyzeComplexity");

// Create input with parameters
var input = new ToolInput(new Dictionary<string, object>
{
    ["filePath"] = "/path/to/file.cs",
    ["threshold"] = 15
});

// Execute
var result = await tool.Execute(input, cancellationToken);
if (result.IsSuccess)
{
    Console.WriteLine(result.Value!.Message);
    var methods = result.Value.Data["methods"];
}

Listing Available Tools by Category

// Get all tools
var allTools = ToolTypes.All();

// Filter by category
var analysisTools = allTools.Where(t => t.ToolCategory == ToolCategories.Analysis);

foreach (var tool in analysisTools)
{
    Console.WriteLine($"{tool.Name}: {tool.ToolDescription}");
    foreach (var param in tool.Parameters)
    {
        var required = param.IsRequired ? "(required)" : "(optional)";
        Console.WriteLine($"  --{param.Name}: {param.Description} {required}");
    }
}

Dependencies

• FractalDataWorks.Collections - TypeCollection infrastructure
• FractalDataWorks.Results - Railway-oriented result types
• FractalDataWorks.Messages - Logging infrastructure