API Host IScriptSourceResolver

IScriptSourceResolver

Host extension point for loading scripts from files, memory, databases, virtual directories, embedded resources, or remote stores.

Namespace: AuroraScript.Source. Kind: interface.

Back to .NET Host API Reference

Overview

Implement IScriptSourceResolver to load scripts from a database, object storage, embedded resources, or virtual directories. Use stable normalized references and retain the importer context when resolving relative imports and includes.

The build pipeline is: parser raw path, then ModuleGraph calls ResolveAsync, then GetSourceAsync.

Note

• A resolver only defines the compiler source universe. It does not decide whether a source is open in an editor.
• A resolver should not hard-code language-server workspace directory filtering; editor and indexing policies belong outside the core resolver.
• Use / internally for virtual paths and normalized file-system paths.

Important

The examples below show interface shape only. A production resolver must normalize paths, honor cancellation, and route GetSourceAsync by reference.BaseDirectory.

Quick Reference

Built-in implementations cover the common cases; implement the interface only for a custom store.

Need	Use
Files on disk	FileSystemScriptSourceResolver
Generated or unsaved sources	MemorySourceResolver
Layered lookup	CompositeScriptSourceResolver

Properties

Root

string Root

Normalized source root represented by this resolver.

Parameters

None.

Returns

Returns string.

Behavior

The root is part of resolver identity. ScriptSourceReference.BaseDirectory must identify the resolver root that can later read the source.

public string Root => "mem://tenant-a/";

Methods

ResolveAsync

ValueTask<ScriptSourceReference?> ResolveAsync(ScriptSourceReference? importer, string requestedPath, ScriptResolveContext context, CancellationToken cancellationToken = default)

Resolves an entry, import, or include path to a stable source reference.

Parameters

Name	Type	Required	Description
importer	ScriptSourceReference?	Yes	Importing source, or null for an entry path.
requestedPath	string	Yes	Raw path written in the script. The parser does not normalize it.
context	ScriptResolveContext	Yes	Resolution context carrying extension and encoding.
cancellationToken	CancellationToken	No	Token that cancels the operation.

Returns

A stable ScriptSourceReference, or null.

Behavior

• When importer is null, resolve requestedPath from Root as an entry path.
• When importer is present, resolve requestedPath from the directory of importer.FullPath.
• Return null when the source does not exist or the resolved target is not owned by this resolver namespace.
• Normalize roots and indexed source keys when the resolver is built, not during every comparison.

public ValueTask<ScriptSourceReference?> ResolveAsync(
    ScriptSourceReference? importer,
    string requestedPath,
    ScriptResolveContext context,
    CancellationToken cancellationToken = default)
{
    var fullPath = Root + requestedPath;
    return ValueTask.FromResult<ScriptSourceReference?>(new ScriptSourceReference(Root, fullPath));
}

GetSourceAsync

ValueTask<ScriptSource> GetSourceAsync(ScriptSourceReference reference, CancellationToken cancellationToken = default)

Returns source text for a resolved reference.

Parameters

Name	Type	Required	Description
reference	ScriptSourceReference	Yes	Reference previously produced for this resolver root.
cancellationToken	CancellationToken	No	Token that cancels the operation.

Returns

The matching ScriptSource.

Behavior

Read only references produced for this resolver root. Composite resolvers route by exact normalized BaseDirectory before calling GetSourceAsync.

public ValueTask<ScriptSource> GetSourceAsync(
    ScriptSourceReference reference,
    CancellationToken cancellationToken = default) =>
    ValueTask.FromResult<ScriptSource>(new MemorySource(Root, reference.FullPath, "@module(MAIN);"));

GetAllSourcesAsync

IAsyncEnumerable<ScriptSource> GetAllSourcesAsync(ScriptSourceQuery query, CancellationToken cancellationToken = default)

Enumerates sources visible to BuildAsync().

Parameters

Name	Type	Required	Description
query	ScriptSourceQuery	Yes	Enumeration filter carrying extension and encoding.
cancellationToken	CancellationToken	No	Token that cancels enumeration.

Returns

An async sequence of ScriptSource values visible to BuildAsync().

Behavior

• Returned sources should use normalized FullPath values so CompositeScriptSourceResolver can de-duplicate overlays by source identity.
• The compiler also uses resolver-visible project sources to discover optional @global() declaration files before module analysis.

public async IAsyncEnumerable<ScriptSource> GetAllSourcesAsync(
    ScriptSourceQuery query,
    [System.Runtime.CompilerServices.EnumeratorCancellation] CancellationToken cancellationToken = default)
{
    yield return new MemorySource(Root, Root + "main.as", "@module(MAIN);");
    await Task.CompletedTask;
}