Add Roslyn analyzer OCVS001: detect Row().At<T>(col) misuse at compile time

Introduces OpenCvSharp.Analyzers project with OCVS001 that warns at compile
time when At<T>(int) is called on a Mat returned by Row(), catching the
misuse pattern that causes silent out-of-bounds memory access (#1775).

The analyzer detects both forms:
  mat.Row(i).At<Vec3b>(c)         // direct chain
  var row = mat.Row(i); row.At<Vec3b>(c)  // local variable

The analyzer DLL is included in the OpenCvSharp4 NuGet package under
analyzers/dotnet/cs/ via ProjectReference with OutputItemType=Analyzer,
so all NuGet consumers receive compile-time warnings automatically.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: shimat

src/OpenCvSharp.Analyzers/AnalyzerReleases.Shipped.md

@@ -0,0 +1,2 @@
+; Shipped analyzer releases
+; https://github.com/dotnet/roslyn-analyzers/blob/main/src/Microsoft.CodeAnalysis.Analyzers/ReleaseTrackingAnalyzers.Help.md

src/OpenCvSharp.Analyzers/AnalyzerReleases.Unshipped.md

@@ -0,0 +1,7 @@
+; Unshipped analyzer releases
+
+### New Rules
+
+Rule ID | Category | Severity | Notes
+--------|----------|----------|-------
+OCVS001 | Correctness | Warning | At<T>(int) called on a Mat row submatrix

src/OpenCvSharp.Analyzers/OpenCvSharp.Analyzers.csproj

@@ -0,0 +1,29 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>netstandard2.0</TargetFramework>
+    <LangVersion>12</LangVersion>
+    <Nullable>enable</Nullable>
+    <RootNamespace>OpenCvSharp.Analyzers</RootNamespace>
+    <AssemblyName>OpenCvSharp.Analyzers</AssemblyName>
+    <IsRoslynComponent>true</IsRoslynComponent>
+    <!-- EnforceExtendedAnalyzerRules ensures the analyzer follows Roslyn analyzer best practices -->
+    <EnforceExtendedAnalyzerRules>true</EnforceExtendedAnalyzerRules>
+    <!-- Suppress build output from the package; it goes into analyzers/ folder only -->
+    <IncludeBuildOutput>false</IncludeBuildOutput>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+    <!-- DiagnosticId, SupportedDiagnostics, Initialize are required overrides; XML comments not needed -->
+    <NoWarn>CS1591</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="4.8.0" PrivateAssets="all" />
+    <PackageReference Include="Microsoft.CodeAnalysis.Analyzers" Version="3.3.4" PrivateAssets="all" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <AdditionalFiles Include="AnalyzerReleases.Shipped.md" />
+    <AdditionalFiles Include="AnalyzerReleases.Unshipped.md" />
+  </ItemGroup>
+
+</Project>

src/OpenCvSharp.Analyzers/RowAtAnalyzer.cs

@@ -0,0 +1,128 @@
+using System.Collections.Immutable;
+using System.Linq;
+using Microsoft.CodeAnalysis;
+using Microsoft.CodeAnalysis.CSharp;
+using Microsoft.CodeAnalysis.CSharp.Syntax;
+using Microsoft.CodeAnalysis.Diagnostics;
+
+namespace OpenCvSharp.Analyzers;
+
+/// <summary>
+/// Detects the misuse pattern <c>mat.Row(i).At&lt;T&gt;(col)</c> where the column index is
+/// silently interpreted as a row index, causing out-of-bounds memory access.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <c>Mat.Row(i)</c> returns a 1×N submatrix. <c>At&lt;T&gt;(int i0)</c> on a 2D matrix
+/// treats <c>i0</c> as the row index (dimension 0), not a column index. The resulting
+/// address is <c>data + step * col</c> — jumping entire rows past the end of the submatrix.
+/// </para>
+/// <para>
+/// Use <c>mat.At&lt;T&gt;(row, col)</c> or <c>mat.AsRows&lt;T&gt;()</c> instead.
+/// See https://github.com/shimat/opencvsharp/issues/1775
+/// </para>
+/// </remarks>
+[DiagnosticAnalyzer(LanguageNames.CSharp)]
+public sealed class RowAtAnalyzer : DiagnosticAnalyzer
+{
+    public const string DiagnosticId = "OCVS001";
+
+    private static readonly DiagnosticDescriptor Rule = new(
+        id: DiagnosticId,
+        title: "At<T>(int) called on a Mat row submatrix",
+        messageFormat: "At<T>(int) on the 1-row Mat returned by Row() treats the argument as a row index, " +
+                       "not a column index, silently producing wrong results or out-of-bounds access. " +
+                       "Use mat.At<T>(row, col) or mat.AsRows<T>() instead.",
+        category: "Correctness",
+        defaultSeverity: DiagnosticSeverity.Warning,
+        isEnabledByDefault: true,
+        description: "Mat.Row(i) returns a 2D 1×N submatrix. At<T>(int i0) interprets i0 as a row " +
+                     "index (dimension 0), not a column index. Access the parent matrix directly: " +
+                     "mat.At<T>(row, col), or use mat.AsRows<T>() for high-performance loops.",
+        helpLinkUri: "https://github.com/shimat/opencvsharp/issues/1775");
+
+    public override ImmutableArray<DiagnosticDescriptor> SupportedDiagnostics
+        => ImmutableArray.Create(Rule);
+
+    public override void Initialize(AnalysisContext context)
+    {
+        context.ConfigureGeneratedCodeAnalysis(GeneratedCodeAnalysisFlags.None);
+        context.EnableConcurrentExecution();
+        context.RegisterSyntaxNodeAction(AnalyzeInvocation, SyntaxKind.InvocationExpression);
+    }
+
+    private static void AnalyzeInvocation(SyntaxNodeAnalysisContext context)
+    {
+        var atInvocation = (InvocationExpressionSyntax)context.Node;
+
+        if (!IsMatAtIntCall(atInvocation, context.SemanticModel))
+            return;
+
+        if (atInvocation.Expression is not MemberAccessExpressionSyntax memberAccess)
+            return;
+
+        var receiver = memberAccess.Expression;
+
+        // Case 1: direct chain — mat.Row(i).At<T>(c)
+        if (IsMatRowCall(receiver, context.SemanticModel))
+        {
+            context.ReportDiagnostic(Diagnostic.Create(Rule, atInvocation.GetLocation()));
+            return;
+        }
+
+        // Case 2: local variable — var row = mat.Row(i); row.At<T>(c)
+        if (receiver is IdentifierNameSyntax identifier &&
+            context.SemanticModel.GetSymbolInfo(identifier).Symbol is ILocalSymbol local &&
+            IsLocalDeclaredFromRowCall(local, context.SemanticModel))
+        {
+            context.ReportDiagnostic(Diagnostic.Create(Rule, atInvocation.GetLocation()));
+        }
+    }
+
+    /// <summary>
+    /// Returns true when <paramref name="expr"/> is a call to <c>OpenCvSharp.Mat.At&lt;T&gt;(int)</c>.
+    /// </summary>
+    private static bool IsMatAtIntCall(InvocationExpressionSyntax expr, SemanticModel model)
+    {
+        if (expr.Expression is not MemberAccessExpressionSyntax ma)
+            return false;
+        if (ma.Name.Identifier.ValueText != "At")
+            return false;
+        if (expr.ArgumentList.Arguments.Count != 1)
+            return false;
+
+        var sym = model.GetSymbolInfo(expr).Symbol as IMethodSymbol;
+        return sym is { Parameters.Length: 1 } &&
+               sym.ContainingType?.ToDisplayString() == "OpenCvSharp.Mat" &&
+               sym.Parameters[0].Type.SpecialType == SpecialType.System_Int32;
+    }
+
+    /// <summary>
+    /// Returns true when <paramref name="expr"/> is a call to <c>OpenCvSharp.Mat.Row(int)</c>.
+    /// </summary>
+    private static bool IsMatRowCall(ExpressionSyntax expr, SemanticModel model)
+    {
+        if (expr is not InvocationExpressionSyntax inv)
+            return false;
+        if (inv.Expression is not MemberAccessExpressionSyntax ma)
+            return false;
+        if (ma.Name.Identifier.ValueText != "Row")
+            return false;
+
+        var sym = model.GetSymbolInfo(inv).Symbol as IMethodSymbol;
+        return sym?.ContainingType?.ToDisplayString() == "OpenCvSharp.Mat";
+    }
+
+    /// <summary>
+    /// Returns true when the local variable's declaration initializer is a call to <c>Mat.Row(int)</c>.
+    /// Covers: <c>var row = mat.Row(i);</c>
+    /// </summary>
+    private static bool IsLocalDeclaredFromRowCall(ILocalSymbol local, SemanticModel model)
+    {
+        var syntaxRef = local.DeclaringSyntaxReferences.FirstOrDefault();
+        if (syntaxRef?.GetSyntax() is not VariableDeclaratorSyntax { Initializer.Value: { } initializer })
+            return false;
+
+        return IsMatRowCall(initializer, model);
+    }
+}

src/OpenCvSharp/OpenCvSharp.csproj

@@ -44,6 +44,14 @@
   <ItemGroup>
     <PackageReference Include="System.Memory" Version="4.6.3" />
   </ItemGroup>
+
+  <ItemGroup>
+    <!-- Include the analyzer in this package under analyzers/dotnet/cs/ -->
+    <ProjectReference Include="..\OpenCvSharp.Analyzers\OpenCvSharp.Analyzers.csproj"
+                      ReferenceOutputAssembly="false"
+                      OutputItemType="Analyzer"
+                      SetTargetFramework="TargetFramework=netstandard2.0" />
+  </ItemGroup>
   <ItemGroup Condition=" '$(TargetFramework)' == 'netstandard2.1'">
     <PackageReference Include="System.Runtime.CompilerServices.Unsafe" Version="6.1.2" />
   </ItemGroup>

test/OpenCvSharp.Analyzers.Tests/OpenCvSharp.Analyzers.Tests.csproj

@@ -0,0 +1,24 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <LangVersion>12</LangVersion>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <IsPackable>false</IsPackable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.9.0" />
+    <PackageReference Include="xunit" Version="2.7.0" />
+    <PackageReference Include="xunit.runner.visualstudio" Version="2.5.7" PrivateAssets="all" />
+    <PackageReference Include="Microsoft.CodeAnalysis.CSharp.Analyzer.Testing.XUnit" Version="1.1.2" />
+    <!-- Override the old CodeAnalysis pulled in transitively by the testing framework -->
+    <PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="4.8.0" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\OpenCvSharp.Analyzers\OpenCvSharp.Analyzers.csproj" />
+  </ItemGroup>
+
+</Project>

test/OpenCvSharp.Analyzers.Tests/RowAtAnalyzerTests.cs

@@ -0,0 +1,99 @@
+using Microsoft.CodeAnalysis.CSharp.Testing;
+using Microsoft.CodeAnalysis.Testing;
+using Microsoft.CodeAnalysis.Testing.Verifiers;
+using OpenCvSharp.Analyzers;
+using Xunit;
+
+namespace OpenCvSharp.Analyzers.Tests;
+
+public class RowAtAnalyzerTests
+{
+    // Minimal stub of OpenCvSharp.Mat — lets the analyzer resolve types
+    // without requiring the actual OpenCvSharp assembly.
+    private const string MatStub = """
+        namespace OpenCvSharp
+        {
+            public class Mat
+            {
+                public Mat Row(int y) => this;
+                public ref T At<T>(int i0) where T : unmanaged => throw null!;
+                public ref T At<T>(int i0, int i1) where T : unmanaged => throw null!;
+            }
+            public struct Vec3b { }
+        }
+        """;
+
+    private static Task Verify(string source, params DiagnosticResult[] expected)
+    {
+        var test = new CSharpAnalyzerTest<RowAtAnalyzer, XUnitVerifier>
+        {
+            TestCode = MatStub + source,
+        };
+        test.ExpectedDiagnostics.AddRange(expected);
+        return test.RunAsync();
+    }
+
+    [Fact]
+    public Task DirectChain_ReportsWarning() => Verify(
+        """
+        class Test
+        {
+            void M(OpenCvSharp.Mat mat)
+            {
+                var _ = {|#0:mat.Row(1).At<OpenCvSharp.Vec3b>(2)|};
+            }
+        }
+        """,
+        DiagnosticResult.CompilerWarning(RowAtAnalyzer.DiagnosticId).WithLocation(0));
+
+    [Fact]
+    public Task LocalVariable_ReportsWarning() => Verify(
+        """
+        class Test
+        {
+            void M(OpenCvSharp.Mat mat)
+            {
+                var row = mat.Row(1);
+                var _ = {|#0:row.At<OpenCvSharp.Vec3b>(2)|};
+            }
+        }
+        """,
+        DiagnosticResult.CompilerWarning(RowAtAnalyzer.DiagnosticId).WithLocation(0));
+
+    [Fact]
+    public Task TwoArgAt_NoWarning() => Verify(
+        """
+        class Test
+        {
+            void M(OpenCvSharp.Mat mat)
+            {
+                var _ = mat.At<OpenCvSharp.Vec3b>(1, 2);
+            }
+        }
+        """);
+
+    [Fact]
+    public Task AtOnFullMatrix_NoWarning() => Verify(
+        """
+        class Test
+        {
+            void M(OpenCvSharp.Mat mat)
+            {
+                var _ = mat.At<OpenCvSharp.Vec3b>(1);
+            }
+        }
+        """);
+
+    [Fact]
+    public Task LocalAssignedFromNonRowMethod_NoWarning() => Verify(
+        """
+        class Test
+        {
+            void M(OpenCvSharp.Mat mat, OpenCvSharp.Mat other)
+            {
+                var row = other;
+                var _ = row.At<OpenCvSharp.Vec3b>(2);
+            }
+        }
+        """);
+}