Skip to content

api-reference.md

Latest commit

 

History

History
102 lines (69 loc) · 4.58 KB

api-reference.md

File metadata and controls

102 lines (69 loc) · 4.58 KB
Raw

Extension Points

← Home

Purpose

CompileScope's own analysis and reporting logic is entirely internal. Four public types exist specifically so a separate Pro-tier package can register additional analysis rules and report sections without modifying CompileScope itself. This is the complete public surface — nothing else in the package is part of a supported API.

Registering an Analysis Rule

using ToolsStudio.CompileScope.Editor.Analysis;

public interface IAnalysisRule
{
    string RuleId { get; }
    bool AppliesTo(AssemblyGraph graph);
    IEnumerable<Recommendation> Evaluate(AssemblyGraph graph, CascadeData cascade);
}

RuleRegistry.Register(myRule);

Call RuleRegistry.Register() from your own [InitializeOnLoad] static constructor. RuleId must be unique across every registered rule — a duplicate throws InvalidOperationException. Registered rules run after CompileScope's five built-in rules on every RecommendationEngine.Evaluate() call, and their output is merged into the same ranked list shown on the Recommendations tab.

Registering a Report Section

using ToolsStudio.CompileScope.Editor.Reports;

public interface IReportSection
{
    string SectionId { get; }
    void Populate(ReportData report, AssemblyGraph graph);
}

ReportPipeline.Register(mySection);

Populate runs on the main thread during ReportExporter.Export() and must complete in under 100 ms. Write only to your own section via ReportData.SetSection(sectionId, content) — never clear or overwrite another section's content.

Data Types

Type Purpose
AssemblyGraph Read-only graph: Nodes, Edges, ByName, GetDependencies(), GetDependents()
AssemblyNode Per-assembly data: name, asmdef path/GUID, script count, compile time, cascade score
GraphEdge A single dependency edge, with whether it's an explicit or auto-referenced reference
Recommendation A single finding: rule ID, severity, affected assembly, title, description, estimated impact
CascadeData Immutable cascade-score lookup by assembly name or script asset path
ReportData Write-only from Populate() — SetSection(sectionId, content) adds your section's Markdown
Severity Low, Medium, High

All of the above are constructed internally by CompileScope. External code only ever reads them — there is no public constructor for any type in this table.

How Analysis Works

Useful context for understanding when a registered rule or report section actually runs:

flowchart LR
    A[".asmdef files"] --> B[AssemblyDiscovery]
    B --> C[AssemblyRegistry]
    C --> D[GraphBuilder]
    D --> E[AssemblyGraph]
    E --> F["CascadeCalculator<br/>cascade scores"]
    E --> G["GraphValidator<br/>structural issues"]
    E --> H["RecommendationEngine<br/>five built-in rules, then registered rules"]
Loading

AssemblyDiscovery runs Unity API calls (AssetDatabase, CompilationPipeline) on the main thread and hands off an immutable DiscoveryResult to a background thread, where AssemblyRegistry and GraphBuilder do the actual graph construction — this is why a large project's analysis doesn't block the Editor UI. CascadeCalculator, GraphValidator, and RecommendationEngine all operate on the completed, immutable AssemblyGraph; a registered IAnalysisRule runs in this same pass, after the five built-in rules.

GraphCache holds the current AssemblyGraph as static state, keyed by a hash of the discovered assembly inputs — a repeat analysis with an unchanged hash returns the cached graph rather than rebuilding, which is why re-running Analyse Now with nothing changed is close to instant. HistoryCache persists compilation and reload records to Library/ToolsStudio/compilescope/history.json, written atomically on every append.

Work Thread
Unity API calls (AssetDatabase, CompilationPipeline) Main thread only
Graph construction, cascade scoring, validation, recommendations Background thread
UI drawing Main thread only

What's Not Public

Everything else — assembly discovery, graph construction, cascade calculation, the five built-in rules, caching, history persistence, and every panel — is internal. There is no supported way to replace or hook into these directly. If your use case needs more than a custom rule or report section, it's outside what the current extension surface supports.

Related