diff --git a/TruePath.PathIoGenerator.Tests/CancellationTests.cs b/TruePath.PathIoGenerator.Tests/CancellationTests.cs new file mode 100644 index 0000000..50e4eb0 --- /dev/null +++ b/TruePath.PathIoGenerator.Tests/CancellationTests.cs @@ -0,0 +1,80 @@ +// SPDX-FileCopyrightText: 2026 TruePath contributors +// +// SPDX-License-Identifier: MIT + +using System.Collections.Immutable; +using Microsoft.CodeAnalysis; +using Microsoft.CodeAnalysis.CSharp; +using Microsoft.CodeAnalysis.Text; +using Xunit; + +namespace TruePath.PathIoGenerator.Tests; + +public sealed class CancellationTests +{ + [Fact] + public void CancellationDuringDocumentationReadStopsTheRunAndAllowsRetry() + { + using var cancellation = new CancellationTokenSource(); + var reads = 0; + var docs = new CallbackText("System.Runtime.xml", token => + { + if (++reads == 1) + { + Assert.Equal(cancellation.Token, token); + cancellation.Cancel(); + } + }, ""); + var compilation = TestHelper.CreateCompilation(TestHelper.DefaultSources); + GeneratorDriver driver = CSharpGeneratorDriver.Create( + new[] { new PathIoSourceGenerator().AsSourceGenerator() }, new[] { docs }); + + Assert.Throws(() => driver.RunGenerators(compilation, cancellation.Token)); + + driver = driver.RunGenerators(compilation, TestContext.Current.CancellationToken); + Assert.NotEmpty(driver.GetRunResult().GeneratedTrees); + Assert.Empty(driver.GetRunResult().Diagnostics); + } + + [Fact] + public void CancellationDuringExclusionReadStopsTheRun() + { + using var cancellation = new CancellationTokenSource(); + var exclusions = new CallbackText("path-io-exclusions.txt", token => + { + Assert.Equal(cancellation.Token, token); + cancellation.Cancel(); + }); + var compilation = TestHelper.CreateCompilation(TestHelper.DefaultSources); + GeneratorDriver driver = CSharpGeneratorDriver.Create( + new[] { new PathIoSourceGenerator().AsSourceGenerator() }, new[] { exclusions }); + + Assert.Throws(() => driver.RunGenerators(compilation, cancellation.Token)); + } + + [Fact] + public void CoreOperationsHonorAnAlreadyCancelledToken() + { + var token = new CancellationToken(canceled: true); + var compilation = TestHelper.CreateCompilation(TestHelper.DefaultSources); + var markedType = compilation.GetTypeByMetadataName("TruePath.SystemIo.PathIo")!; + + Assert.Throws(() => BclDocIndex.Build(ImmutableArray.Empty, token)); + Assert.Throws(() => Exclusions.Parse(ImmutableArray.Empty, token)); + Assert.Throws(() => PathIoGeneratorCore.CollectUserDefinedMembersInfo(compilation, markedType, token)); + Assert.Throws(() => PathIoGeneratorCore.Generate( + compilation, "TruePath.SystemIo.PathIo", false, UserDefinedMembersInfo.Empty, + ImmutableHashSet.Empty, BclDocIndex.Build(ImmutableArray.Empty, TestContext.Current.CancellationToken), token)); + } + + private sealed class CallbackText(string path, Action callback, string text = "") : AdditionalText + { + public override string Path => path; + + public override SourceText GetText(CancellationToken cancellationToken = default) + { + callback(cancellationToken); + return SourceText.From(text); + } + } +} diff --git a/TruePath.PathIoGenerator.Tests/DocumentationIndexTests.cs b/TruePath.PathIoGenerator.Tests/DocumentationIndexTests.cs new file mode 100644 index 0000000..0a27a1d --- /dev/null +++ b/TruePath.PathIoGenerator.Tests/DocumentationIndexTests.cs @@ -0,0 +1,122 @@ +// SPDX-FileCopyrightText: 2026 TruePath contributors +// +// SPDX-License-Identifier: MIT + +using System.Collections.Immutable; +using System.Xml.Linq; +using Microsoft.CodeAnalysis; +using Xunit; + +namespace TruePath.PathIoGenerator.Tests; + +public sealed class DocumentationIndexTests +{ + private const string Id = "M:System.IO.File.ReadAllText(System.String)"; + + [Theory] + [InlineData("\n")] + [InlineData("\r\n")] + [InlineData("\r")] + [InlineData("\u0085")] + [InlineData("\u2028")] + [InlineData("\u2029")] + public void ReadsRelevantMembersWithAnyLineEndingsAndTrailingWhitespace(string newline) + { + var text = string.Join(newline, new[] + { + "", + " ", + " first", "second", " \t", + "" + }); + var index = Build(new InMemoryAdditionalText("System.Runtime.xml", text)); + + Assert.True(index.TryGetMethodMember(Id, out var member)); + Assert.Equal("first\nsecond", member.Element("summary")!.Value); + Assert.False(index.TryGetMethodMember("M:System.String.Unrelated", out _)); + } + + [Theory] + [InlineData(61)] + [InlineData(128)] + public void ReadsMembersWhoseOpeningTagCrossesOrFollowsThePrefixBuffer(int indentation) + { + var index = Build(new InMemoryAdditionalText("System.Runtime.xml", new string(' ', indentation) + + $"valid")); + + Assert.True(index.TryGetMethodMember(Id, out var member)); + Assert.Equal("valid", member.Element("summary")!.Value); + } + + [Fact] + public void ReadsSingleLineMembersAndSkipsMalformedMembers() + { + // Only netstandard.xml is parsed leniently, so this is the file where a malformed member is skipped. + var index = Build(new InMemoryAdditionalText("netstandard.xml", $""" + + + valid + ignored + directory + + """)); + + Assert.False(index.TryGetMethodMember("M:System.IO.File.Broken", out _)); + Assert.False(index.TryGetMethodMember("M:System.IO.FileStream.Unrelated", out _)); + Assert.True(index.TryGetMethodMember(Id, out _)); + Assert.True(index.TryGetMethodMember("M:System.IO.Directory.Delete(System.String)", out _)); + } + + [Fact] + public void FrameworkDocumentationWinsOverStandardDocumentation() + { + // A malformed framework member is a hard parse error now, so the merge only ever sees valid members; the + // framework-specific file must still take precedence over the standard one. + var index = Build( + new InMemoryAdditionalText("System.Runtime.xml", $"framework"), + new InMemoryAdditionalText("netstandard.xml", $"standard")); + + Assert.True(index.TryGetMethodMember(Id, out var member)); + Assert.Equal("framework", member.Element("summary")!.Value); + } + + [Fact] + public void PublicLookupCannotMutateTheCachedMember() + { + var index = Build(new InMemoryAdditionalText("System.Runtime.xml", + $"original")); + Assert.True(index.TryGetMethodMember(Id, out var first)); + first.ReplaceAll(new XElement("summary", "changed")); + + Assert.True(index.TryGetMethodMember(Id, out var second)); + Assert.Equal("original", second.Element("summary")!.Value); + } + + [Fact] + public void FormattingPreservesIndependentFragmentsEscapingAndNamespaces() + { + var member = XElement.Parse(""" + + A & B + Path <value> + result + details + + """); + + var lines = DocFormatting.ToDocLines(member, ImmutableArray.Create("sourceFile"), TestContext.Current.CancellationToken); + + Assert.Equal(new[] + { + "A & B ", + "Path <value>", + "result", + "details" + }, lines); + Assert.Equal("sourceFileName", member.Element("param")!.Attribute("name")!.Value); + } + + private static BclDocIndex Build(params AdditionalText[] files) => + BclDocIndex.Build(files.ToImmutableArray(), TestContext.Current.CancellationToken); +} diff --git a/TruePath.PathIoGenerator.Tests/IncrementalityTests.cs b/TruePath.PathIoGenerator.Tests/IncrementalityTests.cs new file mode 100644 index 0000000..88361b4 --- /dev/null +++ b/TruePath.PathIoGenerator.Tests/IncrementalityTests.cs @@ -0,0 +1,298 @@ +// SPDX-FileCopyrightText: 2026 TruePath contributors +// +// SPDX-License-Identifier: MIT + +using System.Collections.Immutable; +using System.Globalization; +using Microsoft.CodeAnalysis; +using Microsoft.CodeAnalysis.CSharp; +using Microsoft.CodeAnalysis.Text; +using Xunit; + +namespace TruePath.PathIoGenerator.Tests; + +public sealed class IncrementalityTests +{ + private const string ReadAllTextDeclaration = "public static string ReadAllText(this AbsolutePath path)"; + private const string ReadAllTextId = "M:System.IO.File.ReadAllText(System.String)"; + + [Theory] + [InlineData(false)] + [InlineData(true)] + public void UnrelatedAndMarkedCommentEditsReuseTemplatesAndRenderedSource(bool editMarkedFile) + { + var compilation = TestHelper.CreateCompilation(TestHelper.DefaultSources); + var unrelated = Parse("class Other { int M() => 0; }"); + compilation = compilation.AddSyntaxTrees(unrelated); + var driver = CreateDriver().RunGenerators(compilation, TestContext.Current.CancellationToken); + var original = Source(driver); + var tree = editMarkedFile ? compilation.SyntaxTrees.First() : unrelated; + + for (var i = 0; i < 10; i++) + { + var replacement = tree.WithChangedText(SourceText.From(editMarkedFile + ? TestHelper.DefaultSources + $"\n// {i}" + : $"class Other {{ int M() => {i + 1}; }}")); + compilation = compilation.ReplaceSyntaxTree(tree, replacement); + tree = replacement; + driver = driver.RunGenerators(compilation, TestContext.Current.CancellationToken); + + Assert.Equal(original, Source(driver)); + AssertCached(driver, "MethodTemplates", "RenderedSource"); + } + } + + [Fact] + public void ExclusionCommentsOrderingAndDiagnosticsDoNotInvalidateSource() + { + var compilation = TestHelper.CreateCompilation(TestHelper.DefaultSources); + AdditionalText exclusions = new InMemoryAdditionalText("path-io-exclusions.txt", + "M:System.IO.File.Encrypt(System.String)\nM:System.IO.File.Decrypt(System.String)"); + var driver = CreateDriver(exclusions).RunGenerators(compilation, TestContext.Current.CancellationToken); + var original = Source(driver); + var replacement = new InMemoryAdditionalText(exclusions.Path, + "# comment\nM:System.IO.File.Decrypt(System.String)\nM:System.IO.File.Encrypt(System.String)\ninvalid"); + + driver = driver.ReplaceAdditionalText(exclusions, replacement) + .RunGenerators(compilation, TestContext.Current.CancellationToken); + + Assert.Equal(original, Source(driver)); + AssertCached(driver, "MethodTemplates", "RenderedSource"); + Assert.Contains(driver.GetRunResult().Diagnostics, diagnostic => diagnostic.Id == "TPG003"); + + driver = driver.ReplaceAdditionalText(replacement, new InMemoryAdditionalText(exclusions.Path, "")) + .RunGenerators(compilation, TestContext.Current.CancellationToken); + Assert.Contains("public static void Encrypt(", Source(driver)); + Assert.Empty(driver.GetRunResult().Diagnostics); + AssertCached(driver, "MethodTemplates"); + } + + [Fact] + public void OtherPartialDeclarationsChangeHandWrittenOverrides() + { + var compilation = TestHelper.CreateCompilation(TestHelper.DefaultSources); + var driver = CreateDriver().RunGenerators(compilation, TestContext.Current.CancellationToken); + Assert.Contains(ReadAllTextDeclaration, Source(driver)); + var partial = Parse(""" + namespace TruePath.SystemIo; + public static partial class PathIo + { + public static string ReadAllText(TruePath.AbsolutePath path) => "custom"; + } + """); + + driver = driver.RunGenerators(compilation.AddSyntaxTrees(partial), TestContext.Current.CancellationToken); + Assert.DoesNotContain(ReadAllTextDeclaration, Source(driver)); + AssertCached(driver, "MethodTemplates"); + + driver = driver.RunGenerators(compilation, TestContext.Current.CancellationToken); + Assert.Contains(ReadAllTextDeclaration, Source(driver)); + AssertCached(driver, "MethodTemplates"); + } + + [Fact] + public void GlobalAliasChangesRebindUnchangedForwardingBodies() + { + var compilation = TestHelper.CreateCompilation(TestHelper.SourcesWithUserDefinedMembers( + "public static void Custom(TruePath.AbsolutePath path) => Io.Delete(path.Value);")); + var alias = Parse("global using Io = System.IO.File;"); + compilation = compilation.AddSyntaxTrees(alias); + var driver = CreateDriver().RunGenerators(compilation, TestContext.Current.CancellationToken); + Assert.Contains("public static void Delete(this AbsolutePath path) => Directory.Delete(path.Value);", Source(driver)); + + compilation = compilation.ReplaceSyntaxTree(alias, Parse("global using Io = System.IO.Directory;")); + driver = driver.RunGenerators(compilation, TestContext.Current.CancellationToken); + + Assert.Contains("public static void Delete(this AbsolutePath path) => File.Delete(path.Value);", Source(driver)); + AssertCached(driver, "MethodTemplates"); + } + + [Fact] + public void UnchangedDocumentationMembersStopBeforeFormattingAndOtherFilesAreNotReadAgain() + { + var compilation = TestHelper.CreateCompilation(TestHelper.DefaultSources); + var first = new CountingText("netstandard.xml", Docs("standard")); + var second = new CountingText("System.Runtime.xml", Docs("runtime")); + var driver = CreateDriver(second, first).RunGenerators(compilation, TestContext.Current.CancellationToken); + Assert.Contains("runtime", Source(driver)); + + var replacement = new CountingText(second.Path, Docs("runtime") + "\n"); + driver = driver.ReplaceAdditionalText(second, replacement) + .RunGenerators(compilation, TestContext.Current.CancellationToken); + + Assert.Equal(1, first.Reads); + Assert.Equal(1, replacement.Reads); + AssertCached(driver, "DocumentationIndex", "MethodTemplates", "RenderedSource"); + + driver = driver.ReplaceAdditionalText(replacement, new CountingText(second.Path, Docs("updated"))) + .RunGenerators(compilation, TestContext.Current.CancellationToken); + Assert.Contains("updated", Source(driver)); + Assert.Equal(1, first.Reads); + } + + [Fact] + public void RemovingFrameworkDocumentationRevealsTheStandardDocumentation() + { + var compilation = TestHelper.CreateCompilation(TestHelper.DefaultSources); + var standard = new InMemoryAdditionalText("netstandard.xml", Docs("standard")); + var framework = new InMemoryAdditionalText("System.Runtime.xml", Docs("framework")); + var driver = CreateDriver(framework, standard).RunGenerators(compilation, TestContext.Current.CancellationToken); + + driver = driver.RemoveAdditionalTexts(ImmutableArray.Create(framework)) + .RunGenerators(compilation, TestContext.Current.CancellationToken); + + Assert.Contains("standard", Source(driver)); + Assert.DoesNotContain("framework", Source(driver)); + } + + [Theory] + [InlineData("\u0085")] + [InlineData("\u2028")] + [InlineData("\u2029")] + public void UnicodeDocumentationLineBreaksKeepEveryGeneratedLineCommented(string newline) + { + var compilation = TestHelper.CreateCompilation(TestHelper.DefaultSources); + var docs = new InMemoryAdditionalText("System.Runtime.xml", Docs("first" + newline + "second")); + var driver = CreateDriver(docs).RunGenerators(compilation, TestContext.Current.CancellationToken); + + Assert.Contains("/// first" + Environment.NewLine + " /// second", Source(driver)); + Assert.DoesNotContain(newline, Source(driver)); + var updated = compilation.AddSyntaxTrees(driver.GetRunResult().GeneratedTrees); + Assert.Empty(updated.GetDiagnostics(TestContext.Current.CancellationToken) + .Where(diagnostic => diagnostic.Severity == DiagnosticSeverity.Error)); + } + + [Theory] + [InlineData("", "")] + [InlineData("", "")] + public void CommentsAndProcessingInstructionsInsideDocumentationInvalidateOutput(string before, string after) + { + var compilation = TestHelper.CreateCompilation(TestHelper.DefaultSources); + var original = new InMemoryAdditionalText("System.Runtime.xml", Docs("text " + before)); + var driver = CreateDriver(original).RunGenerators(compilation, TestContext.Current.CancellationToken); + + driver = driver.ReplaceAdditionalText(original, + new InMemoryAdditionalText(original.Path, Docs("text " + after))) + .RunGenerators(compilation, TestContext.Current.CancellationToken); + + Assert.Contains(after, Source(driver)); + Assert.DoesNotContain(before, Source(driver)); + } + + [Fact] + public void SymbolDocumentationChangesInvalidateTemplatesEvenWhenApiSignaturesAreUnchanged() + { + var compilation = TestHelper.CreateCompilation(TestHelper.DefaultSources); + var fileAssembly = compilation.GetTypeByMetadataName("System.IO.File")!.ContainingAssembly; + var originalReference = (PortableExecutableReference)compilation.GetMetadataReference(fileAssembly)!; + using var metadata = (AssemblyMetadata)originalReference.GetMetadata(); + var reference = metadata.GetReference(documentation: new MethodDocumentation("first")); + compilation = compilation.ReplaceReference(originalReference, reference); + var driver = CreateDriver().RunGenerators(compilation, TestContext.Current.CancellationToken); + Assert.Contains("first", Source(driver)); + + compilation = compilation.ReplaceReference(reference, + metadata.GetReference(documentation: new MethodDocumentation("second"))); + driver = driver.RunGenerators(compilation, TestContext.Current.CancellationToken); + + Assert.Contains("second", Source(driver)); + Assert.DoesNotContain("first", Source(driver)); + } + + [Fact] + public void PartialValidationAndDiagnosticLocationsFollowEdits() + { + var text = TestHelper.DefaultSources.Replace("static partial class", "static class"); + var compilation = TestHelper.CreateCompilation(text); + var driver = CreateDriver().RunGenerators(compilation, TestContext.Current.CancellationToken); + var before = Assert.Single(driver.GetRunResult().Diagnostics, diagnostic => diagnostic.Id == "TPG002"); + Assert.Empty(driver.GetRunResult().GeneratedTrees); + + var tree = compilation.SyntaxTrees.Single(); + compilation = compilation.ReplaceSyntaxTree(tree, tree.WithChangedText(SourceText.From("\n\n" + text))); + driver = driver.RunGenerators(compilation, TestContext.Current.CancellationToken); + var after = Assert.Single(driver.GetRunResult().Diagnostics, diagnostic => diagnostic.Id == "TPG002"); + Assert.Equal(before.Location.GetLineSpan().StartLinePosition.Line + 2, + after.Location.GetLineSpan().StartLinePosition.Line); + AssertCached(driver, "RenderedSource"); + + driver = driver.RunGenerators(TestHelper.CreateCompilation(TestHelper.DefaultSources), TestContext.Current.CancellationToken); + Assert.Empty(driver.GetRunResult().Diagnostics); + Assert.NotEmpty(driver.GetRunResult().GeneratedTrees); + } + + [Fact] + public void RemovingTheMarkerRemovesGeneratedSource() + { + var compilation = TestHelper.CreateCompilation(TestHelper.DefaultSources); + var driver = CreateDriver().RunGenerators(compilation, TestContext.Current.CancellationToken); + Assert.NotEmpty(driver.GetRunResult().GeneratedTrees); + + compilation = TestHelper.CreateCompilation(TestHelper.DefaultSources.Replace("[GenerateSystemIoExtensions]", "")); + driver = driver.RunGenerators(compilation, TestContext.Current.CancellationToken); + + Assert.Empty(driver.GetRunResult().GeneratedTrees); + } + + [Fact] + public void RemovingARequiredTypeInvalidatesTheCachedApi() + { + var compilation = TestHelper.CreateCompilation(TestHelper.DefaultSources); + var driver = CreateDriver().RunGenerators(compilation, TestContext.Current.CancellationToken); + + driver = driver.RunGenerators(TestHelper.CreateCompilation( + TestHelper.DefaultSources.Replace("AbsolutePath", "OtherPath")), TestContext.Current.CancellationToken); + + Assert.Empty(driver.GetRunResult().GeneratedTrees); + Assert.Contains(driver.GetRunResult().Diagnostics, diagnostic => diagnostic.Id == "TPG001"); + driver = driver.RunGenerators(compilation, TestContext.Current.CancellationToken); + Assert.NotEmpty(driver.GetRunResult().GeneratedTrees); + Assert.Empty(driver.GetRunResult().Diagnostics); + } + + private static string Docs(string summary) => $""" + + + {summary} + The path. + + + """; + + private static SyntaxTree Parse(string text) => CSharpSyntaxTree.ParseText(text, new CSharpParseOptions(LanguageVersion.Latest)); + + private static GeneratorDriver CreateDriver(params AdditionalText[] texts) => CSharpGeneratorDriver.Create( + new[] { new PathIoSourceGenerator().AsSourceGenerator() }, texts, + driverOptions: new GeneratorDriverOptions(IncrementalGeneratorOutputKind.None, trackIncrementalGeneratorSteps: true)); + + private static string Source(GeneratorDriver driver) => driver.GetRunResult().GeneratedTrees.Single().GetText().ToString(); + + private static void AssertCached(GeneratorDriver driver, params string[] names) + { + var steps = driver.GetRunResult().Results.Single().TrackedSteps; + foreach (var name in names) + Assert.All(steps[name].SelectMany(step => step.Outputs), output => Assert.Equal(IncrementalStepRunReason.Cached, output.Reason)); + } + + private sealed class CountingText(string path, string text) : AdditionalText + { + public int Reads { get; private set; } + public override string Path => path; + public override SourceText GetText(CancellationToken cancellationToken = default) + { + Reads++; + return SourceText.From(text); + } + } + + private sealed class MethodDocumentation(string summary) : DocumentationProvider + { + protected override string GetDocumentationForSymbol(string documentationMemberID, CultureInfo preferredCulture, + CancellationToken cancellationToken = default) => documentationMemberID == ReadAllTextId + ? $"{summary}" : ""; + + public override bool Equals(object? obj) => obj is MethodDocumentation other && summary == other.Summary; + public override int GetHashCode() => summary.GetHashCode(); + private string Summary => summary; + } +} diff --git a/TruePath.PathIoGenerator.Tests/PathIoGeneratorTests.cs b/TruePath.PathIoGenerator.Tests/PathIoGeneratorTests.cs index 9007379..4f9231a 100644 --- a/TruePath.PathIoGenerator.Tests/PathIoGeneratorTests.cs +++ b/TruePath.PathIoGenerator.Tests/PathIoGeneratorTests.cs @@ -119,7 +119,7 @@ public void PureForwardMethodIsGenerated() public void BclDocIndexFindsBclMembers() { var index = BclDocIndex.Build( - [new InMemoryAdditionalText("/ref/System.Runtime.xml", BclDocs)]); + [new InMemoryAdditionalText("/ref/System.Runtime.xml", BclDocs)], TestContext.Current.CancellationToken); Assert.True(index.TryGetMethodMember("M:System.IO.File.ReadAllText(System.String)", out var member)); Assert.Contains("OPENS A TEXT FILE, READS ALL THE TEXT IN THE FILE.", member.ToString()); @@ -142,7 +142,7 @@ public void BclDocIndexFindsBclMembers() public void BclDocIndexToleratesBrokenMembersInNetStandardDoc() { var index = BclDocIndex.Build( - [new InMemoryAdditionalText("/ref/netstandard.xml", BrokenBclDocs)]); + [new InMemoryAdditionalText("/ref/netstandard.xml", BrokenBclDocs)], TestContext.Current.CancellationToken); Assert.True(index.TryGetMethodMember("M:System.IO.File.ReadAllText(System.String)", out _)); Assert.False(index.TryGetMethodMember("M:System.IO.File.Delete(System.String)", out _)); @@ -152,7 +152,7 @@ public void BclDocIndexToleratesBrokenMembersInNetStandardDoc() public void BclDocIndexRejectsInvalidXmlInOtherDocs() { Assert.Throws(() => BclDocIndex.Build( - [new InMemoryAdditionalText("/ref/System.Runtime.xml", BrokenBclDocs)])); + [new InMemoryAdditionalText("/ref/System.Runtime.xml", BrokenBclDocs)], TestContext.Current.CancellationToken)); } [Fact] @@ -160,11 +160,11 @@ public void CoreUsesBclDocIndexDirectly() { var compilation = TestHelper.CreateCompilation(TestHelper.DefaultSources); var index = BclDocIndex.Build( - [new InMemoryAdditionalText("/ref/System.Runtime.xml", BclDocs)]); + [new InMemoryAdditionalText("/ref/System.Runtime.xml", BclDocs)], TestContext.Current.CancellationToken); var result = PathIoGeneratorCore.Generate( compilation, "TruePath.SystemIo.PathIo", markedTypeIsNested: false, UserDefinedMembersInfo.Empty, - ImmutableHashSet.Empty, index); + ImmutableHashSet.Empty, index, TestContext.Current.CancellationToken); Assert.Contains("/// OPENS A TEXT FILE, READS ALL THE TEXT IN THE FILE.", result.Source); } diff --git a/TruePath.PathIoGenerator/BclApiModel.cs b/TruePath.PathIoGenerator/BclApiModel.cs new file mode 100644 index 0000000..c1cea5f --- /dev/null +++ b/TruePath.PathIoGenerator/BclApiModel.cs @@ -0,0 +1,25 @@ +// SPDX-FileCopyrightText: 2026 TruePath contributors +// +// SPDX-License-Identifier: MIT + +using System.Collections.Immutable; + +namespace TruePath.PathIoGenerator; + +// Only values leave the semantic projection: no symbols or compilations survive in the rendering cache. +internal sealed class BclApiModel( + ImmutableArray methods, + ImmutableArray importedNamespaces, + ImmutableArray missingTypes) +{ + public ImmutableArray Methods { get; } = methods; + public ImmutableArray ImportedNamespaces { get; } = importedNamespaces; + public ImmutableArray MissingTypes { get; } = missingTypes; + + public override bool Equals(object? obj) => obj is BclApiModel other + && Methods.SequenceEqual(other.Methods) + && ImportedNamespaces.SequenceEqual(other.ImportedNamespaces) + && MissingTypes.SequenceEqual(other.MissingTypes); + + public override int GetHashCode() => Methods.Length; +} diff --git a/TruePath.PathIoGenerator/BclDocIndex.cs b/TruePath.PathIoGenerator/BclDocIndex.cs index 5b1a209..de978df 100644 --- a/TruePath.PathIoGenerator/BclDocIndex.cs +++ b/TruePath.PathIoGenerator/BclDocIndex.cs @@ -3,6 +3,7 @@ // SPDX-License-Identifier: MIT using System.Collections.Immutable; +using System.Globalization; using System.Text; using System.Text.RegularExpressions; using System.Xml; @@ -20,35 +21,60 @@ namespace TruePath.PathIoGenerator; /// public sealed class BclDocIndex { - private readonly ImmutableArray _files; + private readonly bool _isNetstandard; private readonly ImmutableDictionary _members; private BclDocIndex(ImmutableArray files, ImmutableDictionary members) { - _files = files; + _isNetstandard = files.All(file => Path.GetFileName(file.Path) == "netstandard.xml"); _members = members; } public bool TryGetMethodMember(string docId, out XElement member) { - return _members.TryGetValue(docId, out member!); + if (_members.TryGetValue(docId, out var stored)) + { + member = new XElement(stored); + return true; + } + member = null!; + return false; } - public static BclDocIndex Build(ImmutableArray files) + // Only DocFormatting reads the shared instance, and it clones before normalizing parameters. + internal XElement? GetMethodMember(string docId) => _members.TryGetValue(docId, out var member) ? member : null; + + internal static BclDocIndex Merge(ImmutableArray indexes, CancellationToken cancellationToken) { + cancellationToken.ThrowIfCancellationRequested(); + var members = ImmutableDictionary.CreateBuilder(); + foreach (var index in indexes.OrderBy(index => index._isNetstandard ? 0 : 1)) + foreach (var pair in index._members) + { + cancellationToken.ThrowIfCancellationRequested(); + members[pair.Key] = pair.Value; + } + return new BclDocIndex(ImmutableArray.Empty, members.ToImmutable()); + } + + public static BclDocIndex Build(ImmutableArray files, CancellationToken cancellationToken = default) + { + cancellationToken.ThrowIfCancellationRequested(); // netstandard.xml is processed first, so that the framework-specific System.Runtime.xml wins on conflicts. var orderedFiles = files.OrderBy(file => IsNetStandardDoc(file) ? 0 : 1); var builder = ImmutableDictionary.CreateBuilder(); foreach (var file in orderedFiles) { - var text = file.GetText(); + cancellationToken.ThrowIfCancellationRequested(); + var text = file.GetText(cancellationToken); + cancellationToken.ThrowIfCancellationRequested(); if (text == null) continue; if (IsNetStandardDoc(file)) - ExtractMembersLeniently(text, builder); + ExtractMembersLeniently(text, builder, cancellationToken); else - ExtractMembers(text, builder); + ExtractMembers(text, builder, cancellationToken); } return new BclDocIndex(files, builder.ToImmutable()); @@ -61,81 +87,118 @@ private static bool IsNetStandardDoc(AdditionalText file) return Path.GetFileName(file.Path) == NetStandardDocFileName; } - private static bool IsIndexedMember(string name) + private static void ExtractMembers( + SourceText text, + ImmutableDictionary.Builder builder, + CancellationToken cancellationToken) { - return name.StartsWith("M:System.IO.File.", StringComparison.Ordinal) - || name.StartsWith("M:System.IO.Directory.", StringComparison.Ordinal); + ExtractMembers(text, builder, skipMalformedMembers: false, cancellationToken); } - private static void ExtractMembers(SourceText text, ImmutableDictionary.Builder builder) + private static void ExtractMembersLeniently( + SourceText text, + ImmutableDictionary.Builder builder, + CancellationToken cancellationToken) { - var document = XDocument.Parse(text.ToString()); - foreach (var member in document.Descendants("member")) - { - var name = member.Attribute("name")?.Value; - if (name == null || !IsIndexedMember(name)) continue; - - builder[name] = member; - } + ExtractMembers(text, builder, skipMalformedMembers: true, cancellationToken); } - private static void ExtractMembersLeniently( + /// + /// Scans the documentation line by line and materializes only the member elements the index needs, instead of + /// allocating the whole file through SourceText.ToString() first. + /// + /// + /// netstandard.xml is known to contain invalid XML (see https://github.com/dotnet/standard/issues/1527), so + /// its malformed members are skipped; in every other file a malformed member surfaces the parse error. + /// + private static void ExtractMembers( SourceText text, - ImmutableDictionary.Builder builder) + ImmutableDictionary.Builder builder, + bool skipMalformedMembers, + CancellationToken cancellationToken) { - // netstandard.xml contains invalid XML, so member elements are extracted line by line and parsed one by one: - // a broken member is then skipped instead of failing the whole file. - // - // See https://github.com/dotnet/standard/issues/1527 on the topic of the broken XML doc. - var current = new StringBuilder(); + var prefix = new char[64]; + var memberStart = 0; string? currentName = null; foreach (var textLine in text.Lines) { - var line = textLine.ToString(); - var trimmed = line.TrimStart(); + cancellationToken.ThrowIfCancellationRequested(); + var span = textLine.Span; if (currentName == null) { - if (!trimmed.StartsWith(" span.Start && char.IsWhiteSpace(text[end - 1])) end--; + if (!Matches(text, end - "".Length, end, "")) continue; + try { - current.Append('\n').Append(line); + // Allocate only a relevant member. Roslyn also recognizes Unicode line breaks that XML does not + // normalize; preserve the previous line-by-line reconstruction's LF conversion. + var memberText = text.ToString(TextSpan.FromBounds(memberStart, span.End)) + .Replace('\u0085', '\n').Replace('\u2028', '\n').Replace('\u2029', '\n'); + builder[currentName] = XElement.Parse(memberText); } - - if (trimmed.TrimEnd().EndsWith("", StringComparison.Ordinal)) + catch (XmlException) when (skipMalformedMembers) { - try - { - builder[currentName] = XElement.Parse(current.ToString()); - } - catch (XmlException) - { - // Skip a malformed member. - } - - currentName = null; + // Skip a malformed member without hiding other valid entries. } + + currentName = null; } } + private static bool StartsMember(SourceText text, TextSpan line, char[] prefix, out int start) + { + // Bulk copying avoids virtual SourceText indexer calls for every character of every unrelated line. + var length = Math.Min(prefix.Length, line.Length); + text.CopyTo(line.Start, prefix, 0, length); + var offset = 0; + while (offset < length && char.IsWhiteSpace(prefix[offset])) offset++; + start = line.Start + offset; + const string opening = " other._members.TryGetValue(pair.Key, out var member) && XNode.DeepEquals(pair.Value, member)); } public override int GetHashCode() { - return _files.Length; + return _members.Count; } } @@ -160,16 +223,26 @@ internal static class DocFormatting /// normalized against the actual parameter names of the generated method: the BCL documentation sometimes /// mismatches them (in casing or entirely), which would break XML documentation checks. /// - public static ImmutableArray ToDocLines(XElement member, ImmutableArray parameterNames) + public static ImmutableArray ToDocLines(XElement member, ImmutableArray parameterNames, CancellationToken cancellationToken = default) { + cancellationToken.ThrowIfCancellationRequested(); // Work on a copy: the element may be a cached BclDocIndex entry shared across runs, and this method // renames its param elements in place. member = new XElement(member); var documentedParameters = new HashSet(StringComparer.Ordinal); var elements = new List(); + // A writer allocates a sizable buffer. Reuse it across this member's independent XML fragments. + var buffer = new StringBuilder(); + using var textWriter = new StringWriter(buffer, CultureInfo.InvariantCulture); + using var xmlWriter = XmlWriter.Create(textWriter, new XmlWriterSettings + { + OmitXmlDeclaration = true, + ConformanceLevel = ConformanceLevel.Fragment, + }); foreach (var element in member.Elements()) { + cancellationToken.ThrowIfCancellationRequested(); if (element.Name.LocalName == "param") { var name = element.Attribute("name")?.Value; @@ -182,7 +255,10 @@ public static ImmutableArray ToDocLines(XElement member, ImmutableArray< documentedParameters.Add(actual); } - elements.Add(element.ToString(SaveOptions.DisableFormatting)); + element.WriteTo(xmlWriter); + xmlWriter.Flush(); + elements.Add(buffer.ToString()); + buffer.Clear(); } foreach (var missing in parameterNames.Where(p => !documentedParameters.Contains(p))) @@ -209,7 +285,8 @@ public static ImmutableArray ToDocLines(XElement member, ImmutableArray< } private static string Rewrite(string line, ImmutableArray parameterNames) - { line = ParamRefRegex.Replace(line, match => + { + line = ParamRefRegex.Replace(line, match => { var actual = MatchParameter(match.Groups["name"].Value, parameterNames); var inner = match.Groups["inner"].Success ? match.Groups["inner"].Value : null; diff --git a/TruePath.PathIoGenerator/DocIdSetComparer.cs b/TruePath.PathIoGenerator/DocIdSetComparer.cs new file mode 100644 index 0000000..247763f --- /dev/null +++ b/TruePath.PathIoGenerator/DocIdSetComparer.cs @@ -0,0 +1,17 @@ +// SPDX-FileCopyrightText: 2026 TruePath contributors +// +// SPDX-License-Identifier: MIT + +using System.Collections.Immutable; + +namespace TruePath.PathIoGenerator; + +internal sealed class DocIdSetComparer : IEqualityComparer> +{ + public static DocIdSetComparer Instance { get; } = new(); + + public bool Equals(ImmutableHashSet? x, ImmutableHashSet? y) => + ReferenceEquals(x, y) || x != null && y != null && x.SetEquals(y); + + public int GetHashCode(ImmutableHashSet obj) => obj.Count; +} diff --git a/TruePath.PathIoGenerator/Exclusions.cs b/TruePath.PathIoGenerator/Exclusions.cs index ee9de85..0836831 100644 --- a/TruePath.PathIoGenerator/Exclusions.cs +++ b/TruePath.PathIoGenerator/Exclusions.cs @@ -24,14 +24,16 @@ private Exclusions(ImmutableHashSet docIds, ImmutableArray d Diagnostics = diagnostics; } - public static Exclusions Parse(ImmutableArray fileTexts) + public static Exclusions Parse(ImmutableArray fileTexts, CancellationToken cancellationToken = default) { + cancellationToken.ThrowIfCancellationRequested(); var docIds = ImmutableHashSet.CreateBuilder(); var diagnostics = ImmutableArray.CreateBuilder(); foreach (var text in fileTexts) foreach (var rawLine in text.Replace("\r\n", "\n").Split('\n')) { + cancellationToken.ThrowIfCancellationRequested(); var line = rawLine.Trim(); if (line.Length == 0 || line.StartsWith("#", StringComparison.Ordinal)) continue; diff --git a/TruePath.PathIoGenerator/MarkedType.cs b/TruePath.PathIoGenerator/MarkedType.cs index de52940..be62811 100644 --- a/TruePath.PathIoGenerator/MarkedType.cs +++ b/TruePath.PathIoGenerator/MarkedType.cs @@ -5,26 +5,27 @@ namespace TruePath.PathIoGenerator; /// -/// The equatable payload the pipeline computes for every marked class: its display name, whether it is nested -/// (rejected by with a diagnostic), and the user-defined member -/// analysis. Being equatable lets the incremental pipeline cache it across unrelated edits. +/// The value-equatable facts needed to render one marked class. Semantic analysis may run after any edit; +/// equal facts stop the downstream rendering pipeline, including after edits in another partial declaration. /// -internal sealed class MarkedType(string typeName, bool isNested, UserDefinedMembersInfo userDefinedMembers) +internal sealed class MarkedType( + string typeName, string simpleName, string namespaceName, + bool isNested, bool isPartial, bool resolves, UserDefinedMembersInfo userDefinedMembers) { public string TypeName { get; } = typeName; + public string SimpleName { get; } = simpleName; + public string NamespaceName { get; } = namespaceName; public bool IsNested { get; } = isNested; + public bool IsPartial { get; } = isPartial; + public bool Resolves { get; } = resolves; public UserDefinedMembersInfo UserDefinedMembers { get; } = userDefinedMembers; - public override bool Equals(object? obj) - { - return obj is MarkedType other - && TypeName == other.TypeName - && IsNested == other.IsNested - && UserDefinedMembers.Equals(other.UserDefinedMembers); - } + public bool CanGenerate => !IsNested && IsPartial && Resolves; - public override int GetHashCode() - { - return TypeName.GetHashCode(); - } + public override bool Equals(object? obj) => obj is MarkedType other + && TypeName == other.TypeName && SimpleName == other.SimpleName && NamespaceName == other.NamespaceName + && IsNested == other.IsNested && IsPartial == other.IsPartial && Resolves == other.Resolves + && UserDefinedMembers.Equals(other.UserDefinedMembers); + + public override int GetHashCode() => TypeName.GetHashCode(); } diff --git a/TruePath.PathIoGenerator/MarkedTypeAnalysis.cs b/TruePath.PathIoGenerator/MarkedTypeAnalysis.cs new file mode 100644 index 0000000..3eb24c2 --- /dev/null +++ b/TruePath.PathIoGenerator/MarkedTypeAnalysis.cs @@ -0,0 +1,14 @@ +// SPDX-FileCopyrightText: 2026 TruePath contributors +// +// SPDX-License-Identifier: MIT + +using Microsoft.CodeAnalysis; + +namespace TruePath.PathIoGenerator; + +// Locations follow the current syntax tree in a separate diagnostic branch, never the source rendering branch. +internal sealed class MarkedTypeAnalysis(MarkedType type, Location location) +{ + public MarkedType Type { get; } = type; + public Location Location { get; } = location; +} diff --git a/TruePath.PathIoGenerator/MethodCandidate.cs b/TruePath.PathIoGenerator/MethodCandidate.cs new file mode 100644 index 0000000..9697cf2 --- /dev/null +++ b/TruePath.PathIoGenerator/MethodCandidate.cs @@ -0,0 +1,20 @@ +// SPDX-FileCopyrightText: 2026 TruePath contributors +// +// SPDX-License-Identifier: MIT + +namespace TruePath.PathIoGenerator; + +// A null method records an API without a leading path parameter, for the generated skipped-method list. +internal sealed class MethodCandidate(string docId, string signature, GeneratedMethod? method, string? fallbackXml) +{ + public string DocId { get; } = docId; + public string Signature { get; } = signature; + public GeneratedMethod? Method { get; } = method; + public string? FallbackXml { get; } = fallbackXml; + + public override bool Equals(object? obj) => obj is MethodCandidate other + && DocId == other.DocId && Signature == other.Signature + && Equals(Method, other.Method) && FallbackXml == other.FallbackXml; + + public override int GetHashCode() => DocId.GetHashCode(); +} diff --git a/TruePath.PathIoGenerator/PathIoGeneratorCore.cs b/TruePath.PathIoGenerator/PathIoGeneratorCore.cs index b33e66b..180195e 100644 --- a/TruePath.PathIoGenerator/PathIoGeneratorCore.cs +++ b/TruePath.PathIoGenerator/PathIoGeneratorCore.cs @@ -48,85 +48,129 @@ public static GenerationResult Generate( bool markedTypeIsNested, UserDefinedMembersInfo userDefinedMembers, ImmutableHashSet excludedDocIds, - BclDocIndex docIndex) + BclDocIndex docIndex, + CancellationToken cancellationToken = default) { - var diagnostics = ImmutableArray.CreateBuilder(); + cancellationToken.ThrowIfCancellationRequested(); + var symbol = compilation.GetTypeByMetadataName(markedTypeMetadataName); + var type = new MarkedType(markedTypeMetadataName, symbol?.Name ?? markedTypeMetadataName, + symbol?.ContainingNamespace.ToDisplayString() ?? string.Empty, markedTypeIsNested, + symbol != null && IsDeclaredPartial(symbol, cancellationToken), symbol != null, userDefinedMembers); + var analysis = new MarkedTypeAnalysis(type, symbol?.Locations.FirstOrDefault() ?? Location.None); + var api = ExtractBclApi(compilation, cancellationToken); + var diagnostics = GetTypeDiagnostics(analysis, api); + if (diagnostics.Length > 0) return new GenerationResult(null, diagnostics); + return new GenerationResult(Render(type, AddDocumentation(api, docIndex, cancellationToken), excludedDocIds, cancellationToken), diagnostics); + } - if (markedTypeIsNested) - { - diagnostics.Add(Diagnostic.Create(GeneratorDiagnostics.MarkedClassIsNested, Location.None, markedTypeMetadataName)); - return new GenerationResult(null, diagnostics.ToImmutable()); - } + internal static MarkedTypeAnalysis AnalyzeMarkedType( + Compilation compilation, INamedTypeSymbol symbol, CancellationToken cancellationToken) + { + cancellationToken.ThrowIfCancellationRequested(); + var name = symbol.ToDisplayString(); + var type = new MarkedType(name, symbol.Name, symbol.ContainingNamespace.ToDisplayString(), + symbol.ContainingType != null, IsDeclaredPartial(symbol, cancellationToken), + compilation.GetTypeByMetadataName(name) != null, + CollectUserDefinedMembersInfo(compilation, symbol, cancellationToken)); + return new MarkedTypeAnalysis(type, symbol.Locations.FirstOrDefault() ?? Location.None); + } + + internal static ImmutableArray GetTypeDiagnostics(MarkedTypeAnalysis analysis, BclApiModel api) + { + var type = analysis.Type; + if (type.IsNested) + return [Diagnostic.Create(GeneratorDiagnostics.MarkedClassIsNested, Location.None, type.TypeName)]; + var diagnostics = ImmutableArray.CreateBuilder(); + foreach (var missing in api.MissingTypes) + diagnostics.Add(Diagnostic.Create(GeneratorDiagnostics.RequiredTypeNotFound, Location.None, missing)); + if (!type.Resolves) + diagnostics.Add(Diagnostic.Create(GeneratorDiagnostics.RequiredTypeNotFound, Location.None, type.TypeName)); + if (diagnostics.Count == 0 && !type.IsPartial) + diagnostics.Add(Diagnostic.Create(GeneratorDiagnostics.MarkedClassNotPartial, analysis.Location, type.SimpleName)); + return diagnostics.ToImmutable(); + } + + internal static BclApiModel ExtractBclApi(Compilation compilation, CancellationToken cancellationToken) + { + cancellationToken.ThrowIfCancellationRequested(); var fileType = compilation.GetTypeByMetadataName("System.IO.File"); var directoryType = compilation.GetTypeByMetadataName("System.IO.Directory"); var absolutePathType = compilation.GetTypeByMetadataName(PathIoRules.AbsolutePathTypeName); - var markedType = compilation.GetTypeByMetadataName(markedTypeMetadataName); - - foreach (var (name, symbol) in new[] - { - ("System.IO.File", fileType), - ("System.IO.Directory", directoryType), - (PathIoRules.AbsolutePathTypeName, absolutePathType), - (markedTypeMetadataName, markedType), - }) - if (symbol == null) - diagnostics.Add(Diagnostic.Create(GeneratorDiagnostics.RequiredTypeNotFound, Location.None, name)); - if (diagnostics.Count > 0) - return new GenerationResult(null, diagnostics.ToImmutable()); - - if (!IsDeclaredPartial(markedType!)) - { - diagnostics.Add(Diagnostic.Create( - GeneratorDiagnostics.MarkedClassNotPartial, - markedType!.Locations.FirstOrDefault() ?? Location.None, - markedType.Name)); - return new GenerationResult(null, diagnostics.ToImmutable()); - } + var missing = ImmutableArray.CreateBuilder(); + if (fileType == null) missing.Add("System.IO.File"); + if (directoryType == null) missing.Add("System.IO.Directory"); + if (absolutePathType == null) missing.Add(PathIoRules.AbsolutePathTypeName); + if (missing.Count > 0) + return new BclApiModel([], [], missing.ToImmutable()); var renderer = TypeRenderer.Create(compilation); - var generatedMethods = new List(); - var generatedKeys = new HashSet(); - var skippedWithoutPath = new SortedSet(StringComparer.Ordinal); - + var methods = ImmutableArray.CreateBuilder(); foreach (var owner in new[] { fileType!, directoryType! }) // File first, so File wins on duplicate signatures foreach (var method in owner.GetMembers().OfType()) { - if (method.MethodKind != MethodKind.Ordinary - || !method.IsStatic - || method.DeclaredAccessibility != Accessibility.Public - || method.IsGenericMethod - || method.Parameters.Any(p => p.RefKind != RefKind.None)) - continue; + cancellationToken.ThrowIfCancellationRequested(); + if (method.MethodKind != MethodKind.Ordinary || !method.IsStatic + || method.DeclaredAccessibility != Accessibility.Public || method.IsGenericMethod + || method.Parameters.Any(p => p.RefKind != RefKind.None)) continue; var docId = DocId.ForMethod(method); - if (excludedDocIds.Contains(docId) || userDefinedMembers.ForwardedDocIds.Contains(docId)) continue; - - var pathOrdinals = method.Parameters - .Where(p => p.Type.SpecialType == SpecialType.System_String && PathIoRules.IsPathParameterName(p.Name)) - .Select(p => p.Ordinal) - .ToImmutableHashSet(); - if (pathOrdinals.Count == 0 || !pathOrdinals.Contains(0)) + var pathOrdinals = PathParameterOrdinals(method); + if (!pathOrdinals.Contains(0)) { - skippedWithoutPath.Add(docId); + methods.Add(new MethodCandidate(docId, string.Empty, null, null)); continue; } - var key = SignatureKey(method.Name, method.Parameters.Select(p => SignatureTypeDisplay(p, pathOrdinals, absolutePathType!, renderer))); - if (userDefinedMembers.Signatures.Contains(key)) continue; - if (!generatedKeys.Add(key)) continue; + var template = BuildMethod(owner, method, pathOrdinals, absolutePathType!, renderer); + methods.Add(new MethodCandidate(docId, + SignatureKey(method.Name, method.Parameters.Select(p => SignatureTypeDisplay(p, pathOrdinals, absolutePathType!, renderer))), template, + method.GetDocumentationCommentXml(cancellationToken: cancellationToken))); + } - generatedMethods.Add(BuildMethod(owner, method, pathOrdinals, absolutePathType!, docIndex, renderer)); + return new BclApiModel(methods.ToImmutable(), + renderer.ImportedNamespaces.OrderBy(name => name, StringComparer.Ordinal).ToImmutableArray(), []); + } + + internal static BclApiModel AddDocumentation(BclApiModel api, BclDocIndex docIndex, CancellationToken cancellationToken) + { + cancellationToken.ThrowIfCancellationRequested(); + var methods = ImmutableArray.CreateBuilder(); + foreach (var candidate in api.Methods) + { + cancellationToken.ThrowIfCancellationRequested(); + var method = candidate.Method; + if (method == null) { methods.Add(candidate); continue; } + var names = method.Parameters.Select(p => p.Name).ToImmutableArray(); + var documented = new GeneratedMethod(method.Name, method.ReturnType, method.Parameters, method.BclCall, + method.Attributes, BuildDocLines(candidate, docIndex, names, cancellationToken)); + methods.Add(new MethodCandidate(candidate.DocId, candidate.Signature, documented, candidate.FallbackXml)); } + return new BclApiModel(methods.ToImmutable(), api.ImportedNamespaces, api.MissingTypes); + } - var source = RenderFile(markedType!, generatedMethods, skippedWithoutPath, renderer); - return new GenerationResult(source, diagnostics.ToImmutable()); + internal static string? Render(MarkedType type, BclApiModel api, ImmutableHashSet exclusions, CancellationToken cancellationToken) + { + cancellationToken.ThrowIfCancellationRequested(); + if (!type.CanGenerate || api.MissingTypes.Length > 0) return null; + var generatedMethods = new List(); + var keys = new HashSet(); + var skipped = new SortedSet(); + foreach (var candidate in api.Methods) + { + cancellationToken.ThrowIfCancellationRequested(); + if (exclusions.Contains(candidate.DocId) || type.UserDefinedMembers.ForwardedDocIds.Contains(candidate.DocId)) continue; + if (candidate.Method == null) { skipped.Add(candidate.DocId); continue; } + if (type.UserDefinedMembers.Signatures.Contains(candidate.Signature) || !keys.Add(candidate.Signature)) continue; + generatedMethods.Add(candidate.Method); + } + return RenderFile(type, generatedMethods, skipped, api.ImportedNamespaces, cancellationToken); } - private static bool IsDeclaredPartial(INamedTypeSymbol type) + private static bool IsDeclaredPartial(INamedTypeSymbol type, CancellationToken cancellationToken) { return type.DeclaringSyntaxReferences - .Select(reference => reference.GetSyntax()) + .Select(reference => reference.GetSyntax(cancellationToken)) .OfType() .Any(syntax => syntax.Modifiers.Any(SyntaxKind.PartialKeyword)); } @@ -134,12 +178,14 @@ private static bool IsDeclaredPartial(INamedTypeSymbol type) /// /// Collects the exclusion-relevant facts about the user-defined members of the marked type: their rewritten /// signatures, and the IDs of the BCL overloads they forward to. Called from the syntax-anchored part of - /// the incremental pipeline, so it only re-runs when the marked type's syntax changes. + /// the incremental pipeline; semantic changes in other files can also cause it to re-run. /// public static UserDefinedMembersInfo CollectUserDefinedMembersInfo( Compilation compilation, - INamedTypeSymbol markedType) + INamedTypeSymbol markedType, + CancellationToken cancellationToken = default) { + cancellationToken.ThrowIfCancellationRequested(); var fileType = compilation.GetTypeByMetadataName("System.IO.File"); var directoryType = compilation.GetTypeByMetadataName("System.IO.Directory"); var absolutePathType = compilation.GetTypeByMetadataName(PathIoRules.AbsolutePathTypeName); @@ -152,16 +198,18 @@ public static UserDefinedMembersInfo CollectUserDefinedMembersInfo( foreach (var member in markedType.GetMembers().OfType()) { + cancellationToken.ThrowIfCancellationRequested(); signatures.Add(SignatureKey(member.Name, member.Parameters.Select(p => SignatureTypeDisplay(p, null, absolutePathType, renderer)))); foreach (var reference in member.DeclaringSyntaxReferences) { - var syntax = reference.GetSyntax(); + var syntax = reference.GetSyntax(cancellationToken); var model = compilation.GetSemanticModel(syntax.SyntaxTree); foreach (var invocation in syntax.DescendantNodes().OfType()) { + cancellationToken.ThrowIfCancellationRequested(); if (invocation.ArgumentList.Arguments.Count == 0) continue; - if (model.GetSymbolInfo(invocation).Symbol is not IMethodSymbol target) continue; + if (model.GetSymbolInfo(invocation, cancellationToken).Symbol is not IMethodSymbol target) continue; var owner = target.ContainingType?.OriginalDefinition; if (!comparer.Equals(owner, fileType.OriginalDefinition) @@ -245,7 +293,6 @@ private static GeneratedMethod BuildMethod( IMethodSymbol method, ImmutableHashSet pathOrdinals, INamedTypeSymbol absolutePathType, - BclDocIndex docIndex, TypeRenderer renderer) { var parameterNames = method.Parameters @@ -268,7 +315,7 @@ private static GeneratedMethod BuildMethod( .Where(a => a.AttributeClass != null && ForwardedAttributes.Contains(a.AttributeClass.ToDisplayString())) .Select(attribute => RenderAttribute(attribute, renderer)) .ToImmutableArray(), - BuildDocLines(method, docIndex, parameterNames)); + ImmutableArray.Empty); } private static string? RenderDefaultValue(IParameterSymbol parameter, TypeRenderer renderer) @@ -318,27 +365,29 @@ private static string RenderAttribute(AttributeData attribute, TypeRenderer rend return "[" + name + (arguments.Length == 0 ? "" : "(" + arguments + ")") + "]"; } private static ImmutableArray BuildDocLines( - IMethodSymbol method, + MethodCandidate candidate, BclDocIndex docIndex, - ImmutableArray parameterNames) + ImmutableArray parameterNames, + CancellationToken cancellationToken) { - if (docIndex.TryGetMethodMember(DocId.ForMethod(method), out var cachedMember)) - return DocFormatting.ToDocLines(cachedMember, parameterNames); + cancellationToken.ThrowIfCancellationRequested(); + if (docIndex.GetMethodMember(candidate.DocId) is { } cachedMember) + return DocFormatting.ToDocLines(cachedMember, parameterNames, cancellationToken); - var xml = method.GetDocumentationCommentXml(); + var xml = candidate.FallbackXml; if (!string.IsNullOrWhiteSpace(xml)) try { var root = XElement.Parse("" + xml!.Trim() + ""); if (root.Element("member") is { } member) - return DocFormatting.ToDocLines(member, parameterNames); + return DocFormatting.ToDocLines(member, parameterNames, cancellationToken); } - catch (Exception) + catch (System.Xml.XmlException) { // Malformed documentation falls back to the generated summary below. } - var cref = DocId.ForCref(method); + var cref = candidate.DocId.Substring(2); return [ $"Equivalent to .", @@ -380,11 +429,13 @@ private static string SignatureKey(string name, IEnumerable parameterTyp return name + "(" + string.Join(", ", parameterTypes) + ")"; } - private static string RenderFile(INamedTypeSymbol markedType, + private static string RenderFile(MarkedType markedType, List methods, SortedSet skippedWithoutPath, - TypeRenderer renderer) + ImmutableArray importedNamespaces, + CancellationToken cancellationToken) { + cancellationToken.ThrowIfCancellationRequested(); var orderedMethods = methods .OrderBy(m => m.Name, StringComparer.Ordinal) .ThenBy(m => m.Parameters.Length) @@ -398,17 +449,18 @@ private static string RenderFile(INamedTypeSymbol markedType, sb.AppendLine(); sb.AppendLine("#nullable enable"); sb.AppendLine(); - foreach (var importedNamespace in renderer.ImportedNamespaces.OrderBy(namespaceName => namespaceName, StringComparer.Ordinal)) + foreach (var importedNamespace in importedNamespaces) sb.AppendLine("using " + importedNamespace + ";"); sb.AppendLine(); - sb.AppendLine("namespace " + markedType.ContainingNamespace.ToDisplayString() + ";"); + sb.AppendLine("namespace " + markedType.NamespaceName + ";"); sb.AppendLine(); sb.AppendLine("[global::System.CodeDom.Compiler.GeneratedCodeAttribute(\"" + GeneratorName + "\", \"" + GeneratorVersion + "\")]"); - sb.AppendLine("public static partial class " + markedType.Name); + sb.AppendLine("public static partial class " + markedType.SimpleName); sb.AppendLine("{"); for (var memberIndex = 0; memberIndex < orderedMethods.Count; memberIndex++) { + cancellationToken.ThrowIfCancellationRequested(); var method = orderedMethods[memberIndex]; if (memberIndex > 0) sb.AppendLine(); @@ -474,6 +526,13 @@ internal sealed class GeneratedMethod( public string BclCall { get; } = bclCall; public ImmutableArray Attributes { get; } = attributes; public ImmutableArray DocLines { get; } = docLines; + + public override bool Equals(object? obj) => obj is GeneratedMethod other + && Name == other.Name && ReturnType == other.ReturnType && BclCall == other.BclCall + && Parameters.SequenceEqual(other.Parameters) && Attributes.SequenceEqual(other.Attributes) + && DocLines.SequenceEqual(other.DocLines); + + public override int GetHashCode() => Name.GetHashCode(); } internal sealed class GeneratedParameter(string type, string name, bool isPath, string? defaultValue) @@ -482,4 +541,9 @@ internal sealed class GeneratedParameter(string type, string name, bool isPath, public string Name { get; } = name; public bool IsPath { get; } = isPath; public string? DefaultValue { get; } = defaultValue; + + public override bool Equals(object? obj) => obj is GeneratedParameter other + && Type == other.Type && Name == other.Name && IsPath == other.IsPath && DefaultValue == other.DefaultValue; + + public override int GetHashCode() => Name.GetHashCode(); } diff --git a/TruePath.PathIoGenerator/PathIoSourceGenerator.cs b/TruePath.PathIoGenerator/PathIoSourceGenerator.cs index b491268..bb48621 100644 --- a/TruePath.PathIoGenerator/PathIoSourceGenerator.cs +++ b/TruePath.PathIoGenerator/PathIoSourceGenerator.cs @@ -2,6 +2,7 @@ // // SPDX-License-Identifier: MIT +using System.Collections.Immutable; using System.Text; using Microsoft.CodeAnalysis; using Microsoft.CodeAnalysis.CSharp.Syntax; @@ -10,68 +11,65 @@ namespace TruePath.PathIoGenerator; /// -/// Fills the other partial part of every class marked with TruePath.SystemIo.GenerateSystemIoExtensionsAttribute -/// with the BCL-forwarding extension methods described in . +/// Generates System.IO forwarding extensions for marked partial classes. Semantic projections may rerun on +/// any compilation change; value equality stops unchanged facts before documentation formatting and rendering. /// [Generator] public sealed class PathIoSourceGenerator : IIncrementalGenerator { public void Initialize(IncrementalGeneratorInitializationContext context) { - // The expensive per-type analysis runs in the syntax-anchored transform, so it is cached across edits in - // unrelated files; everything else that is independent of the compilation (exclusion texts, the XML - // documentation index) is also computed in nodes of its own instead of inside the output stage. - var markedTypes = context.SyntaxProvider.ForAttributeWithMetadataName( + var analyses = context.SyntaxProvider.ForAttributeWithMetadataName( PathIoRules.MarkerAttributeName, static (node, _) => node is ClassDeclarationSyntax, - static (attributeContext, _) => new MarkedType( - attributeContext.TargetSymbol.ToDisplayString(), - attributeContext.TargetSymbol.ContainingType != null, - PathIoGeneratorCore.CollectUserDefinedMembersInfo( - attributeContext.SemanticModel.Compilation, - (INamedTypeSymbol)attributeContext.TargetSymbol))); + static (attributeContext, cancellationToken) => PathIoGeneratorCore.AnalyzeMarkedType( + attributeContext.SemanticModel.Compilation, + (INamedTypeSymbol)attributeContext.TargetSymbol, cancellationToken)); + var markedTypes = analyses.Select(static (analysis, _) => analysis.Type).WithTrackingName("MarkedTypes"); - var exclusionTexts = context.AdditionalTextsProvider + var parsedExclusions = context.AdditionalTextsProvider .Where(static file => Path.GetFileName(file.Path) == PathIoRules.ExclusionFileName) - .Select(static (file, _) => file.GetText()?.ToString() ?? string.Empty) - .Collect(); + .Select(static (file, cancellationToken) => file.GetText(cancellationToken)?.ToString() ?? string.Empty) + .Collect() + .Select(static (texts, cancellationToken) => Exclusions.Parse(texts, cancellationToken)); + var exclusions = parsedExclusions.Select(static (parsed, _) => parsed.DocIds) + .WithComparer(DocIdSetComparer.Instance).WithTrackingName("ExclusionIds"); + context.RegisterSourceOutput(parsedExclusions, static (output, parsed) => + { + foreach (var diagnostic in parsed.Diagnostics) output.ReportDiagnostic(diagnostic); + }); var docIndex = context.AdditionalTextsProvider .Where(static file => file.Path.EndsWith(".xml", StringComparison.Ordinal)) + .Select(static (file, cancellationToken) => BclDocIndex.Build(ImmutableArray.Create(file), cancellationToken)) + .WithTrackingName("DocumentFiles") .Collect() - .Select(static (files, _) => BclDocIndex.Build(files)); - - var input = markedTypes.Collect() - .Combine(exclusionTexts) - .Combine(docIndex) - .Combine(context.CompilationProvider); + .Select(static (indexes, cancellationToken) => BclDocIndex.Merge(indexes, cancellationToken)) + .WithTrackingName("DocumentationIndex"); + var api = context.CompilationProvider + .Select(static (compilation, cancellationToken) => PathIoGeneratorCore.ExtractBclApi(compilation, cancellationToken)) + .WithTrackingName("BclApi"); + var templates = api.Combine(docIndex) + .Select(static (pair, cancellationToken) => PathIoGeneratorCore.AddDocumentation(pair.Left, pair.Right, cancellationToken)) + .WithTrackingName("MethodTemplates"); - context.RegisterSourceOutput(input, static (productionContext, tuple) => + // Diagnostics retain current source locations without invalidating the source rendering cache. + context.RegisterSourceOutput(analyses.Combine(api), static (output, pair) => { - var (((typeInfos, exclusionTexts), docIndex), compilation) = tuple; - - var exclusions = Exclusions.Parse(exclusionTexts); - foreach (var diagnostic in exclusions.Diagnostics) productionContext.ReportDiagnostic(diagnostic); - - foreach (var typeInfo in typeInfos.Sort((left, right) => string.CompareOrdinal(left.TypeName, right.TypeName))) - { - var result = PathIoGeneratorCore.Generate( - compilation, - typeInfo.TypeName, - typeInfo.IsNested, - typeInfo.UserDefinedMembers, - exclusions.DocIds, - docIndex); - foreach (var diagnostic in result.Diagnostics) productionContext.ReportDiagnostic(diagnostic); + foreach (var diagnostic in PathIoGeneratorCore.GetTypeDiagnostics(pair.Left, pair.Right)) + output.ReportDiagnostic(diagnostic); + }); - if (result.Source is { } source) - { - // Nested marked types are rejected with TPG004, so the simple type name is unambiguous here. - // Should two same-named top-level types ever be marked, AddSource fails loudly. - var hintName = typeInfo.TypeName.Substring(typeInfo.TypeName.LastIndexOf('.') + 1) + ".Generated.g.cs"; - productionContext.AddSource(hintName, SourceText.From(source, Encoding.UTF8)); - } - } + var sources = markedTypes.Combine(templates).Combine(exclusions) + .Select(static (input, cancellationToken) => ( + HintName: input.Left.Left.SimpleName + ".Generated.g.cs", + Source: PathIoGeneratorCore.Render(input.Left.Left, input.Left.Right, input.Right, cancellationToken))) + .WithTrackingName("RenderedSource"); + context.RegisterSourceOutput(sources, static (output, source) => + { + output.CancellationToken.ThrowIfCancellationRequested(); + if (source.Source != null) + output.AddSource(source.HintName, SourceText.From(source.Source, Encoding.UTF8)); }); } }