diff --git a/Directory.Build.targets b/Directory.Build.targets index 5e6ef0f2764..1bcf12b9c5a 100644 --- a/Directory.Build.targets +++ b/Directory.Build.targets @@ -26,7 +26,7 @@ $(NoWarn);AD0001 - $(NoWarn);EXTEXP0001;EXTEXP0002;EXTEXP0003;EXTEXP0004;EXTEXP0005;EXTEXP0006;EXTEXP0007;EXTEXP0008;EXTEXP0009;EXTEXP0010;EXTEXP0011;EXTEXP0012;EXTEXP0013;EXTEXP0014;EXTEXP0015;EXTEXP0016;EXTEXP0017;EXTEXP0018;MEVD9001 + $(NoWarn);EXTEXP0001;EXTEXP0002;EXTEXP0003;EXTEXP0004;EXTEXP0005;EXTEXP0006;EXTEXP0007;EXTEXP0008;EXTEXP0009;EXTEXP0010;EXTEXP0011;EXTEXP0012;EXTEXP0013;EXTEXP0014;EXTEXP0015;EXTEXP0016;EXTEXP0017;EXTEXP0018;EXTEXP0019;MEVD9001 $(NoWarn);EXTOBS0001; diff --git a/docs/list-of-diagnostics.md b/docs/list-of-diagnostics.md index 4254cf9b25d..cc0888faf1b 100644 --- a/docs/list-of-diagnostics.md +++ b/docs/list-of-diagnostics.md @@ -41,6 +41,7 @@ if desired. | `EXTEXP0016` | Hosting integration testing experiments | | `EXTEXP0017` | Contextual options experiments | | `EXTEXP0018` | HybridCache experiments | +| `EXTEXP0019` | Documents experiments | | `MEAI001` | AI experiments | | `MEVD9001` | Vector Data experiments | diff --git a/src/Libraries/Microsoft.Extensions.Documents.Abstractions/ExtractionDocument.cs b/src/Libraries/Microsoft.Extensions.Documents.Abstractions/ExtractionDocument.cs new file mode 100644 index 00000000000..b76fdddf766 --- /dev/null +++ b/src/Libraries/Microsoft.Extensions.Documents.Abstractions/ExtractionDocument.cs @@ -0,0 +1,107 @@ +// Licensed to the .NET Foundation under one or more agreements. +// The .NET Foundation licenses this file to you under the MIT license. + +using System; +using System.Collections.Generic; +using System.Text.Json.Serialization; +using Microsoft.Extensions.AI; +using Microsoft.Shared.Diagnostics; + +namespace Microsoft.Extensions.Documents; + +/// +/// Represents an ordered, provider-neutral structured document. +/// +public sealed class ExtractionDocument +{ + /// + /// Initializes a new instance of the class. + /// + /// The local identifier of the document. + /// The local payload, or for a structural document. + public ExtractionDocument(string identifier, AIContent? content = null) + { + Identifier = Throw.IfNullOrEmpty(identifier); + Content = content; + } + + /// Gets the document identifier. + public string Identifier { get; } + + /// Gets or sets the local payload of the document, excluding its sections. + /// Payloads are borrowed and mutable; their interpretation is determined by the producer. + public AIContent? Content { get; set; } + + /// Gets the ordered root sections of the document. + public List Sections { get; } = []; + + /// Gets the metadata associated with the document. + public Dictionary Metadata { get; } = new(StringComparer.Ordinal); + + /// Gets source frames, independently of assembled section order. + /// Producers explicitly add frames, including blank frames with no content elements. + public List SourcePages { get; } = []; + + /// Gets or sets the optional borrowed native document result. + /// + /// Native data is not implicitly disposed, deep-cloned, logged or serialized. + /// This does not guarantee original response bytes or durable serialization. + /// + [JsonIgnore] + public object? RawRepresentation { get; set; } + + /// Enumerates non-section content in depth-first document order. + /// + /// This structural traversal does not flatten table cells or return document/section-local payloads. + /// Use the hierarchy to inspect those local payloads and table cells directly. + /// Cyclic section relationships and null entries are rejected when traversed. + /// + /// The content elements in document order. + public IEnumerable EnumerateContent() + { + HashSet path = []; + foreach (ExtractionDocumentSection section in Sections) + { + foreach (ExtractionDocumentElement element in EnumerateSection(section, path)) + { + yield return element; + } + } + } + + private static IEnumerable EnumerateSection( + ExtractionDocumentSection section, HashSet path) + { + if (section is null || !path.Add(section)) + { + throw new InvalidOperationException("A document cannot traverse a null section or a cyclic section relationship."); + } + + try + { + foreach (ExtractionDocumentElement element in section.Elements) + { + if (element is null) + { + throw new InvalidOperationException("A document cannot traverse a null element."); + } + + if (element is ExtractionDocumentSection nestedSection) + { + foreach (ExtractionDocumentElement nestedElement in EnumerateSection(nestedSection, path)) + { + yield return nestedElement; + } + } + else + { + yield return element; + } + } + } + finally + { + _ = path.Remove(section); + } + } +} diff --git a/src/Libraries/Microsoft.Extensions.Documents.Abstractions/ExtractionDocumentElement.cs b/src/Libraries/Microsoft.Extensions.Documents.Abstractions/ExtractionDocumentElement.cs new file mode 100644 index 00000000000..c6771a4b625 --- /dev/null +++ b/src/Libraries/Microsoft.Extensions.Documents.Abstractions/ExtractionDocumentElement.cs @@ -0,0 +1,121 @@ +// Licensed to the .NET Foundation under one or more agreements. +// The .NET Foundation licenses this file to you under the MIT license. + +using System; +using System.Collections.Generic; +using Microsoft.Extensions.AI; +using Microsoft.Shared.Diagnostics; + +namespace Microsoft.Extensions.Documents; + +/// Represents an element in a structured document. +public abstract class ExtractionDocumentElement +{ + /// Initializes a new instance of the class. + /// The local payload, or for a structural element. + protected ExtractionDocumentElement(AIContent? content) => Content = content; + + /// Gets or sets the local payload of this element. + /// + /// TextContent can contain plain text or producer-supplied formatted text. Structural elements can have no payload. + /// Content is local: do not store an aggregate copy of descendant content here. + /// Payloads and their metadata are borrowed and mutable. + /// Text elements require nonnull , including assignments through a base reference. + /// + public AIContent? Content + { + get; + set + { + if (this is ExtractionDocumentTextElement) + { + _ = Throw.IfNull(value); + if (value is not TextContent) + { + Throw.ArgumentException(nameof(value), "A text element requires TextContent."); + } + } + + field = value; + } + } + + /// Gets optional page and region associations. + /// Adding a reference does not add its page to a document. Producers explicitly populate the source-page list. + public List Sources { get; } = []; +} + +/// Represents a section in a document. Sections can be nested in the ordered element collection. +public sealed class ExtractionDocumentSection : ExtractionDocumentElement +{ + /// Initializes a new instance of the class. + /// The local payload, or for a structural section. + public ExtractionDocumentSection(AIContent? content = null) + : base(content) + { + } + + /// Gets the ordered elements in this section, including nested sections. + public List Elements { get; } = []; +} + +/// Represents text in a document, with an optional semantic role. +public sealed class ExtractionDocumentTextElement : ExtractionDocumentElement +{ + /// Initializes a new instance of the class. + /// The text payload, without a required formatting convention. + /// The optional semantic role, or when unspecified. + public ExtractionDocumentTextElement(TextContent content, string? role = null) + : base(Throw.IfNull(content)) + { + Role = role is null ? null : Throw.IfNullOrWhitespace(role); + } + + /// Gets the optional semantic role of this text element. + /// + /// Common roles are heading for a document heading, pageHeader for repeated page headers, + /// and pageFooter for repeated page footers. Custom roles are preserved without normalization. + /// Consumers should treat unspecified or unrecognized roles as ordinary text. + /// + public string? Role { get; } + + /// Gets or sets the positive heading level, or when unspecified. + /// This property is meaningful for the heading role. An unspecified level does not imply a hierarchy level. + public int? HeadingLevel + { + get; + set + { + if (value is not null) + { + _ = Throw.IfLessThanOrEqual(value.Value, 0, nameof(value)); + } + + field = value; + } + } +} + +/// Represents an image in a document. +public sealed class ExtractionDocumentImageElement : ExtractionDocumentElement +{ + /// Initializes a new instance of the class. + /// The local image payload, such as image bytes, a reference, or producer-supplied text. + /// The optional OCR or transcription text, independently of any caption or description. + public ExtractionDocumentImageElement(AIContent? content = null, string? text = null) + : base(content) + { + Text = text; + } + + /// Gets or sets the original asset reference, independently of any payload URI. + /// No URI is fetched or fabricated by the model. + public Uri? Source { get; set; } + + /// Gets or sets OCR or transcription text associated with the image. + /// Captions and descriptions belong in instead. + public string? Text { get; set; } + + /// Gets or sets the alternative text for the image. + public string? AlternativeText { get; set; } +} diff --git a/src/Libraries/Microsoft.Extensions.Documents.Abstractions/ExtractionDocumentSources.cs b/src/Libraries/Microsoft.Extensions.Documents.Abstractions/ExtractionDocumentSources.cs new file mode 100644 index 00000000000..7c45d964fe5 --- /dev/null +++ b/src/Libraries/Microsoft.Extensions.Documents.Abstractions/ExtractionDocumentSources.cs @@ -0,0 +1,225 @@ +// Licensed to the .NET Foundation under one or more agreements. +// The .NET Foundation licenses this file to you under the MIT license. + +using System; +using System.Collections.Generic; +using System.Collections.ObjectModel; +using System.Diagnostics.CodeAnalysis; +using System.Linq; +using Microsoft.Shared.Diagnostics; + +namespace Microsoft.Extensions.Documents; + +/// Identifies the unit of a source page's coordinates. +public enum ExtractionDocumentCoordinateUnit +{ + /// Pixels in the source raster. + Pixel, + + /// Points, each equal to 1/72 inch. + Point, + + /// Inches. + Inch, + + /// Coordinates relative to the page, in the range zero to one. + Normalized +} + +/// Identifies the origin and vertical axis of source coordinates. +public enum ExtractionDocumentCoordinateOrigin +{ + /// Top-left origin, with the vertical axis increasing downwards. + TopLeft, + + /// Bottom-left origin, with the vertical axis increasing upwards. + BottomLeft +} + +/// Represents a vertex in its source page's coordinate frame. +public readonly struct ExtractionDocumentPoint : IEquatable +{ + /// Initializes a new instance of the struct. + public ExtractionDocumentPoint(double x, double y) + { + DocumentSourceValidation.Finite(x, nameof(x)); + DocumentSourceValidation.Finite(y, nameof(y)); + X = x; + Y = y; + } + + /// Gets the horizontal coordinate. + public double X { get; } + + /// Gets the vertical coordinate. + public double Y { get; } + + /// + public bool Equals(ExtractionDocumentPoint other) => X.Equals(other.X) && Y.Equals(other.Y); + + /// + public override bool Equals(object? obj) => obj is ExtractionDocumentPoint other && Equals(other); + + /// + public override int GetHashCode() => unchecked((X.GetHashCode() * 397) ^ Y.GetHashCode()); + + /// Determines whether two points have equal coordinates. + public static bool operator ==(ExtractionDocumentPoint left, ExtractionDocumentPoint right) + { + return left.Equals(right); + } + + /// Determines whether two points have different coordinates. + public static bool operator !=(ExtractionDocumentPoint left, ExtractionDocumentPoint right) + { + return !left.Equals(right); + } +} + +/// Represents source page dimensions in the page's coordinate unit, or an empty (0, 0) value. +/// Empty dimensions cannot be assigned to a source page. Use for unknown page dimensions. +public readonly struct ExtractionDocumentPageDimensions : IEquatable +{ + /// Initializes a new instance of the struct. + public ExtractionDocumentPageDimensions(double width, double height) + { + DocumentSourceValidation.Finite(width, nameof(width)); + DocumentSourceValidation.Finite(height, nameof(height)); + if (!width.Equals(0.0) || !height.Equals(0.0)) + { + _ = Throw.IfLessThanOrEqual(width, 0); + _ = Throw.IfLessThanOrEqual(height, 0); + } + + Width = width; + Height = height; + } + + /// Gets the width. + public double Width { get; } + + /// Gets the height. + public double Height { get; } + + /// + public bool Equals(ExtractionDocumentPageDimensions other) => Width.Equals(other.Width) && Height.Equals(other.Height); + + /// + public override bool Equals(object? obj) => obj is ExtractionDocumentPageDimensions other && Equals(other); + + /// + public override int GetHashCode() => unchecked((Width.GetHashCode() * 397) ^ Height.GetHashCode()); + + /// Determines whether two dimensions have equal width and height. + public static bool operator ==(ExtractionDocumentPageDimensions left, ExtractionDocumentPageDimensions right) + { + return left.Equals(right); + } + + /// Determines whether two dimensions have different width or height. + public static bool operator !=(ExtractionDocumentPageDimensions left, ExtractionDocumentPageDimensions right) + { + return !left.Equals(right); + } +} + +/// Describes a producer-supplied source page, independently of document assembly order. +public sealed class ExtractionDocumentSourcePage +{ + /// Initializes a new instance of the class. + public ExtractionDocumentSourcePage( + string identifier, + int? pageNumber, + ExtractionDocumentPageDimensions? dimensions = null, + ExtractionDocumentCoordinateUnit? coordinateUnit = null, + ExtractionDocumentCoordinateOrigin? coordinateOrigin = null) + { + Identifier = Throw.IfNullOrEmpty(identifier); + PageNumber = pageNumber is { } number ? Throw.IfLessThanOrEqual(number, 0, nameof(pageNumber)) : null; + if (dimensions is { } size && (size.Width <= 0 || size.Height <= 0)) + { + Throw.ArgumentOutOfRangeException(nameof(dimensions)); + } + + if (coordinateUnit is { } unit && !Enum.IsDefined(typeof(ExtractionDocumentCoordinateUnit), unit)) + { + Throw.ArgumentOutOfRangeException(nameof(coordinateUnit)); + } + + if (coordinateOrigin is { } origin && !Enum.IsDefined(typeof(ExtractionDocumentCoordinateOrigin), origin)) + { + Throw.ArgumentOutOfRangeException(nameof(coordinateOrigin)); + } + + Dimensions = dimensions; + CoordinateUnit = coordinateUnit; + CoordinateOrigin = coordinateOrigin; + } + + /// Gets the producer's frame identifier. + public string Identifier { get; } + + /// Gets the one-based originating page number, or for an unnumbered source frame. + /// The source identifier remains meaningful without a number. This value is never an assembly index. + public int? PageNumber { get; } + + /// Gets reported dimensions, or when unknown. + public ExtractionDocumentPageDimensions? Dimensions { get; } + + /// Gets the reported unit, or when unknown. + public ExtractionDocumentCoordinateUnit? CoordinateUnit { get; } + + /// Gets the reported origin, or when unknown. + public ExtractionDocumentCoordinateOrigin? CoordinateOrigin { get; } +} + +/// Associates content with an originating page and an optional source polygon. +/// +/// A reference without a polygon identifies a page, not a precise location. Native observations are +/// borrowed and excluded from semantic projection. A source association does not verify content. +/// +public sealed class ExtractionDocumentSourceReference +{ + private readonly object? _rawRepresentation; + + /// Initializes a new instance of the class. + /// The originating page and coordinate frame. + /// Ordered polygon vertices, or no vertices for a page-only reference. + /// An optional borrowed native observation. + public ExtractionDocumentSourceReference( + ExtractionDocumentSourcePage page, + IEnumerable? polygon = null, + object? rawRepresentation = null) + { + Page = Throw.IfNull(page); + Polygon = new ReadOnlyCollection((polygon ?? Array.Empty()).ToArray()); + if (Polygon.Count is 1 or 2) + { + Throw.ArgumentException(nameof(polygon), "A source polygon must contain at least three vertices."); + } + + _rawRepresentation = rawRepresentation; + } + + /// Gets the originating page and coordinate frame. + public ExtractionDocumentSourcePage Page { get; } + + /// Gets every supplied polygon vertex in order, or an empty list for a page-only reference. + public IReadOnlyList Polygon { get; } + + /// Gets the borrowed native observation for explicit inspection, when supplied. + /// The borrowed native observation, or . + [SuppressMessage("Design", "CA1024:Use properties where appropriate", Justification = "Raw inspection is explicit and excluded from automatic property serialization.")] + public object? GetRawRepresentation() => _rawRepresentation; +} + +internal static class DocumentSourceValidation +{ + internal static void Finite(double value, string name) + { + if (double.IsNaN(value) || double.IsInfinity(value)) + { + Throw.ArgumentOutOfRangeException(name, "A coordinate must be finite."); + } + } +} diff --git a/src/Libraries/Microsoft.Extensions.Documents.Abstractions/ExtractionDocumentTable.cs b/src/Libraries/Microsoft.Extensions.Documents.Abstractions/ExtractionDocumentTable.cs new file mode 100644 index 00000000000..f4a9b361850 --- /dev/null +++ b/src/Libraries/Microsoft.Extensions.Documents.Abstractions/ExtractionDocumentTable.cs @@ -0,0 +1,277 @@ +// Licensed to the .NET Foundation under one or more agreements. +// The .NET Foundation licenses this file to you under the MIT license. + +using System; +using System.Collections; +using System.Collections.Generic; +using Microsoft.Extensions.AI; +using Microsoft.Shared.Diagnostics; + +namespace Microsoft.Extensions.Documents; + +/// +/// Represents a table in a document. +/// +public sealed class ExtractionDocumentTableElement : ExtractionDocumentElement +{ + /// + /// Initializes a new instance of the class. + /// + /// The local payload, or for a structural table. + /// The number of rows. + /// The number of columns. + public ExtractionDocumentTableElement(AIContent? content, int rowCount, int columnCount) + : base(content) + { + _ = Throw.IfLessThan(rowCount, 0); + _ = Throw.IfLessThan(columnCount, 0); + + Cells = new ExtractionDocumentTableCellCollection(this, rowCount, columnCount); + } + + /// + /// Gets the addressable nullable cells in this table. + /// + public ExtractionDocumentTableCellCollection Cells { get; } + +} + +/// +/// Represents one addressable table cell. +/// +public sealed class ExtractionDocumentTableCell +{ + private ExtractionDocumentTableElement? _table; + + /// + /// Initializes a new instance of the class. + /// + /// The element in the cell. Use a section for ordered mixed content. + /// The positive number of rows covered by the cell. + /// The positive number of columns covered by the cell. + /// The optional producer-supplied cell role. + public ExtractionDocumentTableCell(ExtractionDocumentElement content, int rowSpan = 1, int columnSpan = 1, string? role = null) + { + Content = Throw.IfNull(content); + RowSpan = Throw.IfLessThan(rowSpan, 1); + ColumnSpan = Throw.IfLessThan(columnSpan, 1); + Role = role is null ? null : Throw.IfNullOrWhitespace(role); + } + + /// Initializes a new instance of the class without content. + public ExtractionDocumentTableCell(int rowSpan = 1, int columnSpan = 1, string? role = null) + { + RowSpan = Throw.IfLessThan(rowSpan, 1); + ColumnSpan = Throw.IfLessThan(columnSpan, 1); + Role = role is null ? null : Throw.IfNullOrWhitespace(role); + } + + /// + /// Gets the element in the cell. + /// + /// A section can contain multiple paragraphs, images and other elements in order. Its payload remains local, not an aggregate of its children. + public ExtractionDocumentElement? Content { get; } + + /// Gets the number of rows occupied by this anchor cell. + public int RowSpan { get; } + + /// Gets the number of columns occupied by this anchor cell. + public int ColumnSpan { get; } + + /// Gets the optional producer-supplied cell role. + public string? Role { get; } + + /// Gets page and region associations independent of the presence of cell content. + public List Sources { get; } = []; + + /// + /// Gets the row index of the cell. + /// + public int RowIndex { get; internal set; } + + /// + /// Gets the column index of the cell. + /// + public int ColumnIndex { get; internal set; } + + internal ExtractionDocumentTableElement? Table => _table; + + internal void Attach(ExtractionDocumentTableElement table, int row, int column) + { + if (_table is not null) + { + throw new InvalidOperationException("The table cell is already owned by a table."); + } + + _table = table; + RowIndex = row; + ColumnIndex = column; + } + + internal void Detach(ExtractionDocumentTableElement table) + { + if (!ReferenceEquals(_table, table)) + { + throw new InvalidOperationException("The table cell is not owned by the specified table."); + } + + _table = null; + } +} + +/// +/// Provides explicit row and column addressing for nullable table cells. +/// +public sealed class ExtractionDocumentTableCellCollection : IEnumerable +{ + private readonly ExtractionDocumentTableElement _owner; + private readonly ExtractionDocumentTableCell?[,] _cells; + private readonly ExtractionDocumentTableCell?[,] _coveringCells; + + internal ExtractionDocumentTableCellCollection(ExtractionDocumentTableElement owner, int rowCount, int columnCount) + { + _owner = owner; + _cells = new ExtractionDocumentTableCell?[rowCount, columnCount]; + _coveringCells = new ExtractionDocumentTableCell?[rowCount, columnCount]; + } + + /// + /// Gets the number of rows. + /// + public int RowCount => _cells.GetLength(0); + + /// + /// Gets the number of columns. + /// + public int ColumnCount => _cells.GetLength(1); + + /// + /// Gets or sets the anchor cell at a row and column address. + /// + /// + /// The getter returns for an empty position or a position covered by another anchor's span. + /// A covered position must be edited through its anchor cell. + /// + /// The zero-based row index. + /// The zero-based column index. + public ExtractionDocumentTableCell? this[int row, int column] + { + get + { + ValidateAddress(row, column); + return _cells[row, column]; + } + set + { + ValidateAddress(row, column); + + if (IsCovered(row, column)) + { + throw new InvalidOperationException("A covered position must be edited through its anchor cell."); + } + + ExtractionDocumentTableCell? oldCell = _cells[row, column]; + if (ReferenceEquals(oldCell, value)) + { + return; + } + + if (value is not null) + { + ValidateSpan(row, column, value, oldCell); + ValidateCanAdd(value); + value.Attach(_owner, row, column); + } + + if (oldCell is not null) + { + SetCoverage(oldCell, null); + oldCell.Detach(_owner); + } + + _cells[row, column] = value; + if (value is not null) + { + SetCoverage(value, value); + } + } + } + + /// Gets the anchor cell covering a position, or for an empty position. + /// The covering anchor, or . + internal ExtractionDocumentTableCell? GetCoveringCell(int row, int column) + { + ValidateAddress(row, column); + return _coveringCells[row, column]; + } + + /// Gets whether a position is covered by an anchor at a different address. + /// Whether another anchor covers the position. + internal bool IsCovered(int row, int column) + => GetCoveringCell(row, column) is { } cell && (cell.RowIndex != row || cell.ColumnIndex != column); + + /// + public IEnumerator GetEnumerator() + { + for (int row = 0; row < RowCount; row++) + { + for (int column = 0; column < ColumnCount; column++) + { + yield return _cells[row, column]; + } + } + } + + IEnumerator IEnumerable.GetEnumerator() => GetEnumerator(); + + private void ValidateCanAdd(ExtractionDocumentTableCell cell) + { + if (cell.Table is not null) + { + throw new InvalidOperationException("The table cell is already owned by a table."); + } + + if (ReferenceEquals(cell.Content, _owner)) + { + throw new InvalidOperationException("Adding the cell content would create an invalid table relationship."); + } + } + + private void ValidateSpan(int row, int column, ExtractionDocumentTableCell cell, ExtractionDocumentTableCell? replaced) + { + if (cell.RowSpan > RowCount - row || cell.ColumnSpan > ColumnCount - column) + { + Throw.ArgumentException(nameof(cell), "A cell span must fit within the table."); + } + + for (int r = row; r < row + cell.RowSpan; r++) + { + for (int c = column; c < column + cell.ColumnSpan; c++) + { + if (GetCoveringCell(r, c) is { } existing && !ReferenceEquals(existing, replaced)) + { + throw new InvalidOperationException("Cell spans cannot overlap another cell."); + } + } + } + } + + private void ValidateAddress(int row, int column) + { + _ = Throw.IfLessThan(row, 0, nameof(row)); + _ = Throw.IfGreaterThanOrEqual(row, RowCount, nameof(row)); + _ = Throw.IfLessThan(column, 0, nameof(column)); + _ = Throw.IfGreaterThanOrEqual(column, ColumnCount, nameof(column)); + } + + private void SetCoverage(ExtractionDocumentTableCell cell, ExtractionDocumentTableCell? covering) + { + for (int row = cell.RowIndex; row < cell.RowIndex + cell.RowSpan; row++) + { + for (int column = cell.ColumnIndex; column < cell.ColumnIndex + cell.ColumnSpan; column++) + { + _coveringCells[row, column] = covering; + } + } + } +} diff --git a/src/Libraries/Microsoft.Extensions.Documents.Abstractions/Microsoft.Extensions.Documents.Abstractions.csproj b/src/Libraries/Microsoft.Extensions.Documents.Abstractions/Microsoft.Extensions.Documents.Abstractions.csproj new file mode 100644 index 00000000000..64739325141 --- /dev/null +++ b/src/Libraries/Microsoft.Extensions.Documents.Abstractions/Microsoft.Extensions.Documents.Abstractions.csproj @@ -0,0 +1,28 @@ + + + $(TargetFrameworks);netstandard2.0 + Microsoft.Extensions.Documents + Provider-neutral abstractions for structured documents. + RAG + documents;document-processing;extraction;content + dev + EXTEXP0019 + 80 + 75 + true + false + + + $(NoWarn);CA1002;CA1307;CA1721;CA1814;CA1822;IDE0021;IDE0032;IDE0058;S2302;S3060;S3967;S4059;SA1402;SA1600;SA1649 + + + + true + + + + + + + diff --git a/src/Libraries/Microsoft.Extensions.Documents.Abstractions/Microsoft.Extensions.Documents.Abstractions.json b/src/Libraries/Microsoft.Extensions.Documents.Abstractions/Microsoft.Extensions.Documents.Abstractions.json new file mode 100644 index 00000000000..3afedeffe51 --- /dev/null +++ b/src/Libraries/Microsoft.Extensions.Documents.Abstractions/Microsoft.Extensions.Documents.Abstractions.json @@ -0,0 +1,407 @@ +{ + "Name": "Microsoft.Extensions.Documents.Abstractions, Version=10.10.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35", + "Types": [ + { + "Type": "sealed class Microsoft.Extensions.Documents.ExtractionDocument", + "Stage": "Experimental", + "Methods": [ + { + "Member": "Microsoft.Extensions.Documents.ExtractionDocument.ExtractionDocument(string identifier, Microsoft.Extensions.AI.AIContent? content = null);", + "Stage": "Experimental" + }, + { + "Member": "System.Collections.Generic.IEnumerable Microsoft.Extensions.Documents.ExtractionDocument.EnumerateContent();", + "Stage": "Experimental" + } + ], + "Properties": [ + { + "Member": "Microsoft.Extensions.AI.AIContent? Microsoft.Extensions.Documents.ExtractionDocument.Content { get; set; }", + "Stage": "Experimental" + }, + { + "Member": "string Microsoft.Extensions.Documents.ExtractionDocument.Identifier { get; }", + "Stage": "Experimental" + }, + { + "Member": "System.Collections.Generic.Dictionary Microsoft.Extensions.Documents.ExtractionDocument.Metadata { get; }", + "Stage": "Experimental" + }, + { + "Member": "object? Microsoft.Extensions.Documents.ExtractionDocument.RawRepresentation { get; set; }", + "Stage": "Experimental" + }, + { + "Member": "System.Collections.Generic.List Microsoft.Extensions.Documents.ExtractionDocument.Sections { get; }", + "Stage": "Experimental" + }, + { + "Member": "System.Collections.Generic.List Microsoft.Extensions.Documents.ExtractionDocument.SourcePages { get; }", + "Stage": "Experimental" + } + ] + }, + { + "Type": "enum Microsoft.Extensions.Documents.ExtractionDocumentCoordinateOrigin", + "Stage": "Experimental", + "Methods": [ + { + "Member": "Microsoft.Extensions.Documents.ExtractionDocumentCoordinateOrigin.ExtractionDocumentCoordinateOrigin();", + "Stage": "Experimental" + } + ], + "Fields": [ + { + "Member": "const Microsoft.Extensions.Documents.ExtractionDocumentCoordinateOrigin Microsoft.Extensions.Documents.ExtractionDocumentCoordinateOrigin.BottomLeft", + "Stage": "Experimental", + "Value": "1" + }, + { + "Member": "const Microsoft.Extensions.Documents.ExtractionDocumentCoordinateOrigin Microsoft.Extensions.Documents.ExtractionDocumentCoordinateOrigin.TopLeft", + "Stage": "Experimental", + "Value": "0" + } + ] + }, + { + "Type": "enum Microsoft.Extensions.Documents.ExtractionDocumentCoordinateUnit", + "Stage": "Experimental", + "Methods": [ + { + "Member": "Microsoft.Extensions.Documents.ExtractionDocumentCoordinateUnit.ExtractionDocumentCoordinateUnit();", + "Stage": "Experimental" + } + ], + "Fields": [ + { + "Member": "const Microsoft.Extensions.Documents.ExtractionDocumentCoordinateUnit Microsoft.Extensions.Documents.ExtractionDocumentCoordinateUnit.Inch", + "Stage": "Experimental", + "Value": "2" + }, + { + "Member": "const Microsoft.Extensions.Documents.ExtractionDocumentCoordinateUnit Microsoft.Extensions.Documents.ExtractionDocumentCoordinateUnit.Normalized", + "Stage": "Experimental", + "Value": "3" + }, + { + "Member": "const Microsoft.Extensions.Documents.ExtractionDocumentCoordinateUnit Microsoft.Extensions.Documents.ExtractionDocumentCoordinateUnit.Pixel", + "Stage": "Experimental", + "Value": "0" + }, + { + "Member": "const Microsoft.Extensions.Documents.ExtractionDocumentCoordinateUnit Microsoft.Extensions.Documents.ExtractionDocumentCoordinateUnit.Point", + "Stage": "Experimental", + "Value": "1" + } + ] + }, + { + "Type": "abstract class Microsoft.Extensions.Documents.ExtractionDocumentElement", + "Stage": "Experimental", + "Methods": [ + { + "Member": "Microsoft.Extensions.Documents.ExtractionDocumentElement.ExtractionDocumentElement(Microsoft.Extensions.AI.AIContent? content);", + "Stage": "Experimental" + } + ], + "Properties": [ + { + "Member": "Microsoft.Extensions.AI.AIContent? Microsoft.Extensions.Documents.ExtractionDocumentElement.Content { get; set; }", + "Stage": "Experimental" + }, + { + "Member": "System.Collections.Generic.List Microsoft.Extensions.Documents.ExtractionDocumentElement.Sources { get; }", + "Stage": "Experimental" + } + ] + }, + { + "Type": "sealed class Microsoft.Extensions.Documents.ExtractionDocumentImageElement : Microsoft.Extensions.Documents.ExtractionDocumentElement", + "Stage": "Experimental", + "Methods": [ + { + "Member": "Microsoft.Extensions.Documents.ExtractionDocumentImageElement.ExtractionDocumentImageElement(Microsoft.Extensions.AI.AIContent? content = null, string? text = null);", + "Stage": "Experimental" + } + ], + "Properties": [ + { + "Member": "string? Microsoft.Extensions.Documents.ExtractionDocumentImageElement.AlternativeText { get; set; }", + "Stage": "Experimental" + }, + { + "Member": "System.Uri? Microsoft.Extensions.Documents.ExtractionDocumentImageElement.Source { get; set; }", + "Stage": "Experimental" + }, + { + "Member": "string? Microsoft.Extensions.Documents.ExtractionDocumentImageElement.Text { get; set; }", + "Stage": "Experimental" + } + ] + }, + { + "Type": "readonly struct Microsoft.Extensions.Documents.ExtractionDocumentPageDimensions : System.IEquatable", + "Stage": "Experimental", + "Methods": [ + { + "Member": "Microsoft.Extensions.Documents.ExtractionDocumentPageDimensions.ExtractionDocumentPageDimensions(double width, double height);", + "Stage": "Experimental" + }, + { + "Member": "Microsoft.Extensions.Documents.ExtractionDocumentPageDimensions.ExtractionDocumentPageDimensions();", + "Stage": "Experimental" + }, + { + "Member": "bool Microsoft.Extensions.Documents.ExtractionDocumentPageDimensions.Equals(Microsoft.Extensions.Documents.ExtractionDocumentPageDimensions other);", + "Stage": "Experimental" + }, + { + "Member": "override bool Microsoft.Extensions.Documents.ExtractionDocumentPageDimensions.Equals(object? obj);", + "Stage": "Experimental" + }, + { + "Member": "override int Microsoft.Extensions.Documents.ExtractionDocumentPageDimensions.GetHashCode();", + "Stage": "Experimental" + }, + { + "Member": "static bool Microsoft.Extensions.Documents.ExtractionDocumentPageDimensions.operator ==(Microsoft.Extensions.Documents.ExtractionDocumentPageDimensions left, Microsoft.Extensions.Documents.ExtractionDocumentPageDimensions right);", + "Stage": "Experimental" + }, + { + "Member": "static bool Microsoft.Extensions.Documents.ExtractionDocumentPageDimensions.operator !=(Microsoft.Extensions.Documents.ExtractionDocumentPageDimensions left, Microsoft.Extensions.Documents.ExtractionDocumentPageDimensions right);", + "Stage": "Experimental" + } + ], + "Properties": [ + { + "Member": "double Microsoft.Extensions.Documents.ExtractionDocumentPageDimensions.Height { get; }", + "Stage": "Experimental" + }, + { + "Member": "double Microsoft.Extensions.Documents.ExtractionDocumentPageDimensions.Width { get; }", + "Stage": "Experimental" + } + ] + }, + { + "Type": "readonly struct Microsoft.Extensions.Documents.ExtractionDocumentPoint : System.IEquatable", + "Stage": "Experimental", + "Methods": [ + { + "Member": "Microsoft.Extensions.Documents.ExtractionDocumentPoint.ExtractionDocumentPoint(double x, double y);", + "Stage": "Experimental" + }, + { + "Member": "Microsoft.Extensions.Documents.ExtractionDocumentPoint.ExtractionDocumentPoint();", + "Stage": "Experimental" + }, + { + "Member": "bool Microsoft.Extensions.Documents.ExtractionDocumentPoint.Equals(Microsoft.Extensions.Documents.ExtractionDocumentPoint other);", + "Stage": "Experimental" + }, + { + "Member": "override bool Microsoft.Extensions.Documents.ExtractionDocumentPoint.Equals(object? obj);", + "Stage": "Experimental" + }, + { + "Member": "override int Microsoft.Extensions.Documents.ExtractionDocumentPoint.GetHashCode();", + "Stage": "Experimental" + }, + { + "Member": "static bool Microsoft.Extensions.Documents.ExtractionDocumentPoint.operator ==(Microsoft.Extensions.Documents.ExtractionDocumentPoint left, Microsoft.Extensions.Documents.ExtractionDocumentPoint right);", + "Stage": "Experimental" + }, + { + "Member": "static bool Microsoft.Extensions.Documents.ExtractionDocumentPoint.operator !=(Microsoft.Extensions.Documents.ExtractionDocumentPoint left, Microsoft.Extensions.Documents.ExtractionDocumentPoint right);", + "Stage": "Experimental" + } + ], + "Properties": [ + { + "Member": "double Microsoft.Extensions.Documents.ExtractionDocumentPoint.X { get; }", + "Stage": "Experimental" + }, + { + "Member": "double Microsoft.Extensions.Documents.ExtractionDocumentPoint.Y { get; }", + "Stage": "Experimental" + } + ] + }, + { + "Type": "sealed class Microsoft.Extensions.Documents.ExtractionDocumentSection : Microsoft.Extensions.Documents.ExtractionDocumentElement", + "Stage": "Experimental", + "Methods": [ + { + "Member": "Microsoft.Extensions.Documents.ExtractionDocumentSection.ExtractionDocumentSection(Microsoft.Extensions.AI.AIContent? content = null);", + "Stage": "Experimental" + } + ], + "Properties": [ + { + "Member": "System.Collections.Generic.List Microsoft.Extensions.Documents.ExtractionDocumentSection.Elements { get; }", + "Stage": "Experimental" + } + ] + }, + { + "Type": "sealed class Microsoft.Extensions.Documents.ExtractionDocumentSourcePage", + "Stage": "Experimental", + "Methods": [ + { + "Member": "Microsoft.Extensions.Documents.ExtractionDocumentSourcePage.ExtractionDocumentSourcePage(string identifier, int? pageNumber, Microsoft.Extensions.Documents.ExtractionDocumentPageDimensions? dimensions = null, Microsoft.Extensions.Documents.ExtractionDocumentCoordinateUnit? coordinateUnit = null, Microsoft.Extensions.Documents.ExtractionDocumentCoordinateOrigin? coordinateOrigin = null);", + "Stage": "Experimental" + } + ], + "Properties": [ + { + "Member": "Microsoft.Extensions.Documents.ExtractionDocumentCoordinateOrigin? Microsoft.Extensions.Documents.ExtractionDocumentSourcePage.CoordinateOrigin { get; }", + "Stage": "Experimental" + }, + { + "Member": "Microsoft.Extensions.Documents.ExtractionDocumentCoordinateUnit? Microsoft.Extensions.Documents.ExtractionDocumentSourcePage.CoordinateUnit { get; }", + "Stage": "Experimental" + }, + { + "Member": "Microsoft.Extensions.Documents.ExtractionDocumentPageDimensions? Microsoft.Extensions.Documents.ExtractionDocumentSourcePage.Dimensions { get; }", + "Stage": "Experimental" + }, + { + "Member": "string Microsoft.Extensions.Documents.ExtractionDocumentSourcePage.Identifier { get; }", + "Stage": "Experimental" + }, + { + "Member": "int? Microsoft.Extensions.Documents.ExtractionDocumentSourcePage.PageNumber { get; }", + "Stage": "Experimental" + } + ] + }, + { + "Type": "sealed class Microsoft.Extensions.Documents.ExtractionDocumentSourceReference", + "Stage": "Experimental", + "Methods": [ + { + "Member": "Microsoft.Extensions.Documents.ExtractionDocumentSourceReference.ExtractionDocumentSourceReference(Microsoft.Extensions.Documents.ExtractionDocumentSourcePage page, System.Collections.Generic.IEnumerable? polygon = null, object? rawRepresentation = null);", + "Stage": "Experimental" + }, + { + "Member": "object? Microsoft.Extensions.Documents.ExtractionDocumentSourceReference.GetRawRepresentation();", + "Stage": "Experimental" + } + ], + "Properties": [ + { + "Member": "Microsoft.Extensions.Documents.ExtractionDocumentSourcePage Microsoft.Extensions.Documents.ExtractionDocumentSourceReference.Page { get; }", + "Stage": "Experimental" + }, + { + "Member": "System.Collections.Generic.IReadOnlyList Microsoft.Extensions.Documents.ExtractionDocumentSourceReference.Polygon { get; }", + "Stage": "Experimental" + } + ] + }, + { + "Type": "sealed class Microsoft.Extensions.Documents.ExtractionDocumentTableCell", + "Stage": "Experimental", + "Methods": [ + { + "Member": "Microsoft.Extensions.Documents.ExtractionDocumentTableCell.ExtractionDocumentTableCell(Microsoft.Extensions.Documents.ExtractionDocumentElement content, int rowSpan = 1, int columnSpan = 1, string? role = null);", + "Stage": "Experimental" + }, + { + "Member": "Microsoft.Extensions.Documents.ExtractionDocumentTableCell.ExtractionDocumentTableCell(int rowSpan = 1, int columnSpan = 1, string? role = null);", + "Stage": "Experimental" + } + ], + "Properties": [ + { + "Member": "int Microsoft.Extensions.Documents.ExtractionDocumentTableCell.ColumnIndex { get; internal set; }", + "Stage": "Experimental" + }, + { + "Member": "int Microsoft.Extensions.Documents.ExtractionDocumentTableCell.ColumnSpan { get; }", + "Stage": "Experimental" + }, + { + "Member": "Microsoft.Extensions.Documents.ExtractionDocumentElement? Microsoft.Extensions.Documents.ExtractionDocumentTableCell.Content { get; }", + "Stage": "Experimental" + }, + { + "Member": "string? Microsoft.Extensions.Documents.ExtractionDocumentTableCell.Role { get; }", + "Stage": "Experimental" + }, + { + "Member": "int Microsoft.Extensions.Documents.ExtractionDocumentTableCell.RowIndex { get; internal set; }", + "Stage": "Experimental" + }, + { + "Member": "int Microsoft.Extensions.Documents.ExtractionDocumentTableCell.RowSpan { get; }", + "Stage": "Experimental" + }, + { + "Member": "System.Collections.Generic.List Microsoft.Extensions.Documents.ExtractionDocumentTableCell.Sources { get; }", + "Stage": "Experimental" + } + ] + }, + { + "Type": "sealed class Microsoft.Extensions.Documents.ExtractionDocumentTableCellCollection : System.Collections.Generic.IEnumerable, System.Collections.IEnumerable", + "Stage": "Experimental", + "Methods": [ + { + "Member": "System.Collections.Generic.IEnumerator Microsoft.Extensions.Documents.ExtractionDocumentTableCellCollection.GetEnumerator();", + "Stage": "Experimental" + } + ], + "Properties": [ + { + "Member": "int Microsoft.Extensions.Documents.ExtractionDocumentTableCellCollection.ColumnCount { get; }", + "Stage": "Experimental" + }, + { + "Member": "Microsoft.Extensions.Documents.ExtractionDocumentTableCell? Microsoft.Extensions.Documents.ExtractionDocumentTableCellCollection.this[int row, int column] { get; set; }", + "Stage": "Experimental" + }, + { + "Member": "int Microsoft.Extensions.Documents.ExtractionDocumentTableCellCollection.RowCount { get; }", + "Stage": "Experimental" + } + ] + }, + { + "Type": "sealed class Microsoft.Extensions.Documents.ExtractionDocumentTableElement : Microsoft.Extensions.Documents.ExtractionDocumentElement", + "Stage": "Experimental", + "Methods": [ + { + "Member": "Microsoft.Extensions.Documents.ExtractionDocumentTableElement.ExtractionDocumentTableElement(Microsoft.Extensions.AI.AIContent? content, int rowCount, int columnCount);", + "Stage": "Experimental" + } + ], + "Properties": [ + { + "Member": "Microsoft.Extensions.Documents.ExtractionDocumentTableCellCollection Microsoft.Extensions.Documents.ExtractionDocumentTableElement.Cells { get; }", + "Stage": "Experimental" + } + ] + }, + { + "Type": "sealed class Microsoft.Extensions.Documents.ExtractionDocumentTextElement : Microsoft.Extensions.Documents.ExtractionDocumentElement", + "Stage": "Experimental", + "Methods": [ + { + "Member": "Microsoft.Extensions.Documents.ExtractionDocumentTextElement.ExtractionDocumentTextElement(Microsoft.Extensions.AI.TextContent content, string? role = null);", + "Stage": "Experimental" + } + ], + "Properties": [ + { + "Member": "int? Microsoft.Extensions.Documents.ExtractionDocumentTextElement.HeadingLevel { get; set; }", + "Stage": "Experimental" + }, + { + "Member": "string? Microsoft.Extensions.Documents.ExtractionDocumentTextElement.Role { get; }", + "Stage": "Experimental" + } + ] + } + ] +} \ No newline at end of file diff --git a/src/Libraries/Microsoft.Extensions.Documents.Abstractions/README.md b/src/Libraries/Microsoft.Extensions.Documents.Abstractions/README.md new file mode 100644 index 00000000000..8442a233aa3 --- /dev/null +++ b/src/Libraries/Microsoft.Extensions.Documents.Abstractions/README.md @@ -0,0 +1,65 @@ +# Microsoft.Extensions.Documents.Abstractions + +`Microsoft.Extensions.Documents.Abstractions` is an **experimental**, provider-neutral in-memory model for structured documents. It provides a shared handoff so independently implemented producers and consumers can compose without depending on each other's SDKs or an ingestion framework. It is not an extraction engine or a durable interchange format. + +Extraction adapters, application-created content, source viewers and ingestion integrations are examples of components that can use this boundary. Payloads use the standard `AIContent` types from `Microsoft.Extensions.AI.Abstractions`. The model does not depend on DataIngestion, Markdig, provider SDKs, credentials or network calls. + +The model contains an ordered section hierarchy. Sections contain ordered `ExtractionDocumentElement` instances, including nested sections, text, images and tables. Applications can derive their own element types when needed. `ExtractionDocument.EnumerateContent()` preserves its depth-first traversal of non-section elements: it returns tables as elements, not flattened cells, and does not return document/section-local payloads. Inspect the hierarchy and grid directly for those payloads. This package has no structural renderer or public rendering methods. + +## Intentional API boundaries + +- `ExtractionDocumentElement.Content` and `ExtractionDocument.Content` hold optional **local** `AIContent` payloads. Use `TextContent` for text, `DataContent` for bytes with MIME, and `UriContent` for references with MIME. Structural containers can have null content. Do not populate ancestors with aggregate copies of their descendants. +- `TextContent.Text` is the sole authoritative text for text elements. Plain text and producer-supplied formatted text are preserved without conversion or a required Markdown convention. There is no duplicate general plain-text property. +- `ExtractionDocumentImageElement.Content` is inherited from `ExtractionDocumentElement`, not a second byte-valued slot. MIME is supplied by `DataContent` or `UriContent`; there is no separate mutable `MediaType` to disagree with it. `Source` is the original asset reference, independent of any `UriContent` payload URI, and can coexist with bytes. Image `Text` retains OCR/transcription independently of payload and `AlternativeText`. Captions and descriptions belong in `AlternativeText`, not duplicated into OCR. No URI is fetched or fabricated. +- `ExtractionDocumentTextElement.Role` is optional: unspecified text needs no classification. Common roles are `heading`, `pageHeader` and `pageFooter`; custom values are retained verbatim. Consumers should compare recognized roles case-insensitively and treat unrecognized roles as ordinary text. Repeated page headers are not document headings. Optional `HeadingLevel` is positive when supplied; an absent level does not imply a hierarchy level. +- `Metadata` is an application-property bag on the document, not on every element. For example, an application can retain the original file's hash for citation identity. Provider-specific confidence, detections and transforms are not standardized by this model; native observations remain available through source references. +- `Sources` on an element or table cell contains `ExtractionDocumentSourceReference` instances: a typed source page, an optional polygon and explicit borrowed native-observation access. A page-only reference has no polygon. References preserve order and duplicates; they do not verify content or establish durable citation identity. +- `ExtractionDocumentSourcePage` identifies an originating page and coordinate frame separately from assembly order. `PageNumber` is nullable and positive when supplied; named or unnumbered frames keep their identity without fabricating a number. Dimensions, coordinate unit and origin are optional: unknown values stay unknown. Default dimensions and explicit `(0,0)` dimensions are the same empty value, but source pages reject empty dimensions and use `null` for unknown size. Nonempty dimensions must be finite and positive in both axes. Geometry uses explicit readonly value structs with coordinate-based equality. A source reference snapshots any supplied vertex sequence once in order; it does not reduce rotated regions to rectangles. +- Table cells are constructed through the row/column indexer and can contain an element, including an image or a section with ordered mixed content, or retain an empty anchor with sources. Use a section's `Elements` for multiple paragraphs and images in one cell; its local `Content` is not an aggregate copy. Positive row/column spans describe merged cells; covered positions do not contain a second anchor. The indexer returns `null` for both empty and covered positions; edit a covered position through its anchor. Optional `Role` describes a cell classification such as `columnHeader` or `rowHeader`, not the content's CLR type. The grid rejects overlapping/out-of-bounds spans and reuse of a cell instance at multiple addresses. This is a constructible exchange model, not a document editor. +- Mutable collections use ordinary `List` and `Dictionary` properties. Composition does not attach elements to a parent, register sources, or track mutation versions. Elements can be shared. Structural traversal rejects null entries and cyclic section paths while returning every occurrence of shared acyclic content. It does not recurse into table cells; the typed grid validates its own cell coordinates and spans. Consumers performing additional recursive traversal must validate their active paths. +- Applications supply their own durable identifiers and revisions; the model has no editing-framework ownership, address, mutation-version or disposal bookkeeping. + +## Native inspection and lifetime + +`SourcePages` is an ordinary mutable list. Producers explicitly add frames with `document.SourcePages.Add(frame)`, including blank frames with no content elements. Adding elements or source references does not populate the list. Assembly order and physical page numbering remain independent; duplicate entries are not deduplicated and identifiers are not registered or made unique. + +`ExtractionDocument.RawRepresentation` exposes an optional borrowed native document result, including when there are zero sections and no local payload. It is excluded from default System.Text.Json serialization. Standard `AIContent.RawRepresentation` and source-reference `GetRawRepresentation()` remain available for payload and region observations. These objects are not implicitly disposed or deep-cloned. The shared contract does not guarantee original HTTP bytes, detachment, response-content status or durable serialization. Producers remain responsible for their owned parser, response, stream and temporary-resource cleanup, including on failure or cancellation; caller streams and borrowed native objects remain borrowed. + +Native representations, source references and metadata do not enter text or local payloads automatically. There is no automatic logging, embedding, persistence or document wire serialization contract. Consumers must deliberately select which supporting data to inspect or persist and protect sensitive native data. Null structural content is distinct from an explicitly empty `TextContent`; neither fabricates a text payload for a structural container. + +## Payload ownership and memory + +Wrapping an existing string in `TextContent` reuses that string, but allocates a payload object. `DataContent` retains supplied byte memory rather than detaching it. Producers must copy provider-owned/recycled buffers before publishing; stable application-owned buffers can be reused. Payloads, their metadata and their source references are not deep-cloned by this model. + +Payloads remain mutable. Replacing `Content`, changing `TextContent.Text` or editing collections does not notify the document. A consumer that retains an independently serialized snapshot must refresh it explicitly after mutation. + +`ExtractionDocumentTextElement` requires nonnull `TextContent`, including subsequent assignment through the inherited `Content` property or a base reference. Invalid assignments fail before replacing the existing payload. Other elements and custom subclasses retain flexible nullable `AIContent`. The document does not freeze or dispose its borrowed payload objects. + +The memory improvement comes from not storing repeated descendant aggregates. Explicitly serializing `DataContent` can create and retain a base64 data URI alongside its original bytes. Text-only consumers should deliberately select semantic text or reject media; they must not obtain embeddings by converting binary payloads to strings. + +Generalized annotations/confidence, opaque evidence/page-reference wrappers, per-element metadata/artifact bags, a generic extension envelope, first-class list/item/nesting semantics and normalized barcode/language/link/email/address schemas are outside this first-pass surface. Provider-specific information remains available through native inspection; the package does not perform recognition, infer grounding or define provider-specific feature flags. + +The API is subject to change during preview and API review. It is not a replacement for the existing `Microsoft.Extensions.DataIngestion` APIs in this slice. + +The package's public API is marked experimental with diagnostic `EXTEXP0019`. Consuming applications can suppress that diagnostic explicitly while evaluating the package; it does not provide compatibility or serialization guarantees. + +## Example + +```csharp +using Microsoft.Extensions.Documents; +using Microsoft.Extensions.AI; + +ExtractionDocument document = new("invoice-42"); +ExtractionDocumentSection section = new(); +section.Elements.Add(new ExtractionDocumentTextElement(new TextContent("# Invoice"), role: "heading") { HeadingLevel = 1 }); +section.Elements.Add(new ExtractionDocumentTextElement(new TextContent("Total: $10"))); +document.Sections.Add(section); + +foreach (ExtractionDocumentElement element in document.EnumerateContent()) +{ + if (element is ExtractionDocumentTextElement text) + { + Console.WriteLine(((TextContent)text.Content!).Text); + } +} +``` diff --git a/src/Shared/DiagnosticIds/DiagnosticIds.cs b/src/Shared/DiagnosticIds/DiagnosticIds.cs index fd5a3780f3e..86fbaa8ea65 100644 --- a/src/Shared/DiagnosticIds/DiagnosticIds.cs +++ b/src/Shared/DiagnosticIds/DiagnosticIds.cs @@ -45,6 +45,7 @@ internal static class Experiments internal const string DocumentDb = "EXTEXP0011"; internal const string AutoActivation = "EXTEXP0012"; internal const string HttpLogging = "EXTEXP0013"; + internal const string Documents = "EXTEXP0019"; // All AI experiments share a diagnostic ID but have different // constants to manage which experiment each API belongs to. diff --git a/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentAnnotationTestData.cs b/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentAnnotationTestData.cs new file mode 100644 index 00000000000..3e061935dae --- /dev/null +++ b/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentAnnotationTestData.cs @@ -0,0 +1,49 @@ +// Licensed to the .NET Foundation under one or more agreements. +// The .NET Foundation licenses this file to you under the MIT license. + +using System; +using System.IO; +using System.Text; + +namespace Microsoft.Extensions.Documents.Tests; + +internal static class DocumentAnnotationTestData +{ + internal const string RawBody = "{\"unknown\":{\"z\":[3,1]},\"marker\":\"RAW_BODY_ONLY_91\",\"pages\":[7,2]}"; + + internal static byte[] OriginalBytes() => Encoding.UTF8.GetBytes(RawBody); + + internal static ExtractionDocumentPoint[] Polygon() => + [ + new(10.25, 20.5), new(40.75, 18.25), new(44.5, 60.125), + new(12.875, 58.75), new(8.5, 35.25) + ]; + + internal static ExtractionDocumentSourcePage PdfPage() => + new("urn:frame:pdf-A", 7, new ExtractionDocumentPageDimensions(200, 100), + ExtractionDocumentCoordinateUnit.Point, ExtractionDocumentCoordinateOrigin.BottomLeft); + + internal sealed class CountingStream(byte[] bytes) : MemoryStream(bytes) + { + internal int DisposeCount { get; private set; } + + protected override void Dispose(bool disposing) + { + if (disposing) + { + DisposeCount++; + } + + base.Dispose(disposing); + } + } + + internal sealed class BorrowedNative : IDisposable + { + internal string Marker { get; } = "NATIVE_ONLY_92"; + + internal int DisposeCount { get; private set; } + + public void Dispose() => DisposeCount++; + } +} diff --git a/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentElementTests.cs b/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentElementTests.cs new file mode 100644 index 00000000000..639011a1904 --- /dev/null +++ b/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentElementTests.cs @@ -0,0 +1,270 @@ +// Licensed to the .NET Foundation under one or more agreements. +// The .NET Foundation licenses this file to you under the MIT license. + +using System; +using System.IO; +using System.Linq; +using Microsoft.Extensions.AI; +using Microsoft.Extensions.Documents; +using Xunit; + +namespace Microsoft.Extensions.Documents.Tests; + +public class DocumentElementTests +{ + [Fact] + public void NullSectionContent_PreservesDescendantsWithoutStoredAggregate() + { + ExtractionDocumentSection section = new(null); + section.Elements.Add(new ExtractionDocumentTextElement(new TextContent("semantic paragraph"))); + + Assert.Null(section.Content); + Assert.Equal("semantic paragraph", Assert.IsType(Assert.Single(section.Elements).Content).Text); + } + + [Fact] + public void TextPayload_IsAuthoritativeAndCanBeChanged() + { + ExtractionDocumentTextElement element = new(new TextContent("stored markdown")); + + Assert.Equal("stored markdown", Assert.IsType(element.Content).Text); + + element.Content = new TextContent("updated markdown"); + + Assert.Equal("updated markdown", Assert.IsType(element.Content).Text); + } + + [Fact] + public void Sources_PreserveDuplicateInsertionOrder() + { + ExtractionDocumentTextElement element = new(new TextContent("content")); + ExtractionDocumentSourcePage page = new("page-1", 1); + ExtractionDocumentSourceReference first = new(page); + ExtractionDocumentSourceReference duplicate = new(page); + ExtractionDocumentSourceReference last = new(new("page-2", 2)); + + element.Sources.Add(first); + element.Sources.Add(duplicate); + element.Sources.Add(first); + element.Sources.Add(last); + + Assert.Equal(new[] { first, duplicate, first, last }, element.Sources); + Assert.Equal(new[] { "page-1", "page-1", "page-1", "page-2" }, element.Sources.Select(reference => reference.Page.Identifier)); + } + + [Fact] + public void Sources_InsertReplaceRemoveAndClear_KeepExplicitRegistriesIndependent() + { + ExtractionDocument document = new("edits"); + ExtractionDocumentSection section = new(null); + ExtractionDocumentTextElement element = new(new TextContent("content")); + section.Elements.Add(element); + document.Sections.Add(section); + ExtractionDocumentSourceReference first = new(new("first", 1)); + ExtractionDocumentSourceReference second = new(new("second", 2)); + element.Sources.Insert(0, first); + element.Sources[0] = second; + Assert.Empty(document.SourcePages); + document.SourcePages.Add(first.Page); + document.SourcePages.Add(second.Page); + Assert.Same(second, Assert.Single(element.Sources)); + Assert.Equal(new[] { first.Page, second.Page }, document.SourcePages); + element.Sources.RemoveAt(0); + element.Sources.Add(first); + element.Sources.Clear(); + Assert.Empty(element.Sources); + Assert.Equal(2, document.SourcePages.Count); + } + + [Fact] + public void BorrowedSourceObjects_PreserveIdentityAndOrder() + { + ExtractionDocumentTextElement element = new(new TextContent("content")); + using MemoryStream firstContent = new(new byte[] { 1 }); + using MemoryStream secondContent = new(new byte[] { 2 }); + + ExtractionDocumentSourceReference firstSource = new(new("first-page", 1), rawRepresentation: firstContent); + ExtractionDocumentSourceReference secondSource = new(new("second-page", 2), rawRepresentation: secondContent); + element.Sources.Add(firstSource); + element.Sources.Add(secondSource); + element.Sources.Add(firstSource); + + Assert.Equal(new[] { firstSource, secondSource, firstSource }, element.Sources); + Assert.Same(firstContent, firstSource.GetRawRepresentation()); + Assert.Same(secondContent, secondSource.GetRawRepresentation()); + ExtractionDocument document = new("ordered-bodies"); + ExtractionDocumentSection section = new(null); + section.Elements.Add(element); + document.Sections.Add(section); + document.SourcePages.Add(firstSource.Page); + document.SourcePages.Add(secondSource.Page); + Assert.Equal(new[] { firstSource.Page, secondSource.Page }, document.SourcePages); + } + + [Fact] + public void RawMetadataAndSources_AreOrdinaryMutableCollections() + { + ExtractionDocument document = new("document"); + ExtractionDocumentSection section = new(null); + ExtractionDocumentTextElement element = new(new TextContent("content")); + document.Sections.Add(section); + section.Elements.Add(element); + + ExtractionDocumentSourceReference page = new(new("page-raw", 1)); + document.Metadata["provider-key"] = "provider-value"; + element.Sources.Add(page); + document.SourcePages.Add(page.Page); + + Assert.Equal("provider-value", document.Metadata["provider-key"]); + Assert.Same(page, element.Sources[0]); + Assert.Same(page.Page, Assert.Single(document.SourcePages)); + } + + [Fact] + public void StructuralTraversal_RejectsSelfAndAncestorCycles() + { + ExtractionDocument document = new("cycles"); + ExtractionDocumentSection section = new(null); + document.Sections.Add(section); + + section.Elements.Add(section); + InvalidOperationException selfException = Assert.Throws(() => document.EnumerateContent().ToArray()); + section.Elements.Clear(); + + ExtractionDocumentSection child = new(null); + section.Elements.Add(child); + child.Elements.Add(section); + InvalidOperationException ancestorException = Assert.Throws(() => document.EnumerateContent().ToArray()); + + Assert.Contains("cyclic", selfException.Message, StringComparison.OrdinalIgnoreCase); + Assert.Contains("cyclic", ancestorException.Message, StringComparison.OrdinalIgnoreCase); + Assert.Single(section.Elements); + Assert.Same(section, Assert.Single(child.Elements)); + } + + [Fact] + public void SameScalarAssignments_PreserveContentAndRole() + { + ExtractionDocument document = new("document"); + ExtractionDocumentSection section = new(null); + ExtractionDocumentTextElement element = new(new TextContent("stored"), role: "heading") + { + HeadingLevel = 2 + }; + document.Sections.Add(section); + section.Elements.Add(element); + AIContent? payload = element.Content; + + element.Content = payload; + element.HeadingLevel = 2; + + Assert.Same(payload, element.Content); + Assert.Equal("heading", element.Role); + } + + [Fact] + public void Constructor_AllowsEmptyTextPayload() + { + ExtractionDocument document = new("empty-constructor"); + ExtractionDocumentSection section = new(null); + ExtractionDocumentTextElement element = new(new TextContent("")); + Assert.Equal("", Assert.IsType(element.Content).Text); + document.Sections.Add(section); + section.Elements.Add(element); + + AIContent? payload = element.Content; + element.Content = payload; + Assert.Same(payload, element.Content); + } + + [Fact] + public void Constructor_RejectsNullTextContent() + { + Assert.Throws( + "content", + () => new ExtractionDocumentTextElement(null!)); + } + + [Fact] + public void Associations_PreserveAbsentAndPartialGeometryWithoutFabrication() + { + ExtractionDocument document = new("partial"); + ExtractionDocumentSection section = new(null); + ExtractionDocumentTextElement text = new(new TextContent("visible")); + ExtractionDocumentSourcePage dimensionsOnly = new("dimensions-only", 7, new ExtractionDocumentPageDimensions(200, 100)); + ExtractionDocumentSourcePage polygonOnly = new("polygon-only", 2); + ExtractionDocumentSourceReference region = new(polygonOnly, DocumentAnnotationTestData.Polygon()); + Assert.Empty(text.Sources); + text.Sources.Add(region); + section.Elements.Add(text); + document.Sections.Add(section); + document.SourcePages.Add(polygonOnly); + document.SourcePages.Add(dimensionsOnly); + + Assert.Same(region, Assert.Single(text.Sources)); + Assert.Null(region.GetRawRepresentation()); + Assert.Null(polygonOnly.Dimensions); + Assert.Null(polygonOnly.CoordinateUnit); + Assert.Null(polygonOnly.CoordinateOrigin); + Assert.Equal(DocumentAnnotationTestData.Polygon(), region.Polygon); + Assert.Equal(new ExtractionDocumentPageDimensions(200, 100), dimensionsOnly.Dimensions); + Assert.Null(dimensionsOnly.CoordinateUnit); + Assert.Null(dimensionsOnly.CoordinateOrigin); + Assert.Equal(new[] { polygonOnly, dimensionsOnly }, document.SourcePages); + Assert.Equal("visible", Assert.IsType(text.Content).Text); + } + + [Fact] + public void EmptyTextContent_IsValidButNullMutationIsRejectedAtomically() + { + ExtractionDocument document = new("empty"); + ExtractionDocumentSection section = new(null); + ExtractionDocumentTextElement text = new(new TextContent("")); + section.Elements.Add(text); + document.Sections.Add(section); + Assert.Equal("", Assert.IsType(text.Content).Text); + + text.Content = new TextContent("temporary"); + text.Content = new TextContent(""); + Assert.Equal("", Assert.IsType(text.Content).Text); + AIContent? previous = text.Content; + Assert.Throws("value", () => text.Content = null); + Assert.Same(previous, text.Content); + } + + [Fact] + public void LocalPayloads_KeepRawBodiesAndNativeMarkersSeparate() + { + ExtractionDocument document = new("projections", null); + using DocumentAnnotationTestData.BorrowedNative native = new(); + ExtractionDocumentSection section = new(null); + ExtractionDocumentTextElement text = new(new TextContent("visible **text**")); + ExtractionDocumentImageElement image = new(new TextContent("")) { Source = new Uri("urn:image:page7"), AlternativeText = "diagram only" }; + ExtractionDocumentTextElement extension = new(new TextContent("extension"), role: "vendor-extra"); + ExtractionDocumentElement[] elements = [section, text, image, extension]; + ExtractionDocumentSourcePage page = new("page", 1); + document.SourcePages.Add(page); + foreach (ExtractionDocumentElement element in elements) + { + element.Sources.Add(new ExtractionDocumentSourceReference(page, rawRepresentation: native)); + } + + section.Elements.Add(text); + section.Elements.Add(image); + section.Elements.Add(extension); + document.Sections.Add(section); + + Assert.Equal(new ExtractionDocumentElement[] { text, image, extension }, document.EnumerateContent()); + Assert.DoesNotContain(native.Marker, Assert.IsType(text.Content).Text, StringComparison.Ordinal); + Assert.DoesNotContain("RAW_BODY_ONLY_91", Assert.IsType(text.Content).Text, StringComparison.Ordinal); + Assert.Null(document.Content); + Assert.Null(section.Content); + Assert.Equal("", Assert.IsType(image.Content).Text); + Assert.Equal("visible **text**", Assert.IsType(text.Content).Text); + Assert.Null(image.Text); + Assert.Equal("extension", Assert.IsType(extension.Content).Text); + Assert.Same(native, text.Sources[0].GetRawRepresentation()); + Assert.DoesNotContain(typeof(ExtractionDocumentSourceReference).GetProperties(), property => property.Name == "RawRepresentation"); + Assert.Equal(0, native.DisposeCount); + } +} diff --git a/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentExtensionElementTests.cs b/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentExtensionElementTests.cs new file mode 100644 index 00000000000..fd343602771 --- /dev/null +++ b/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentExtensionElementTests.cs @@ -0,0 +1,99 @@ +// Licensed to the .NET Foundation under one or more agreements. +// The .NET Foundation licenses this file to you under the MIT license. + +using System; +using Microsoft.Extensions.AI; +using Microsoft.Extensions.Documents; +using Xunit; + +namespace Microsoft.Extensions.Documents.Tests; + +public class DocumentExtensionElementTests +{ + [Fact] + public void Cleanup_RemovesObsoletePublicTypesAndMembers() + { + var assembly = typeof(ExtractionDocument).Assembly; + foreach (string name in new[] { "DocumentArtifactCollection", "DocumentExtensionElement", "DocumentTextKind" }) + { + Assert.Null(assembly.GetType("Microsoft.Extensions.Documents." + name)); + } + + foreach (Type type in new[] + { + typeof(ExtractionDocument), typeof(ExtractionDocumentElement), typeof(ExtractionDocumentSection), + typeof(ExtractionDocumentTextElement), typeof(ExtractionDocumentImageElement), typeof(ExtractionDocumentTableElement) + }) + { + Assert.Null(type.GetProperty("StoredMarkdown")); + Assert.Null(type.GetMethod("GetMarkdown")); + Assert.Null(type.GetProperty("Markdown")); + Assert.Equal(typeof(AIContent), type.GetProperty("Content")!.PropertyType); + } + + foreach (string name in new[] { "Metadata", "HasMetadata", "Artifacts" }) + { + Assert.Null(typeof(ExtractionDocumentElement).GetProperty(name)); + Assert.Null(typeof(ExtractionDocumentElement).GetProperty(name, + System.Reflection.BindingFlags.Instance | System.Reflection.BindingFlags.NonPublic)); + } + + Assert.Null(typeof(ExtractionDocumentTextElement).GetProperty("HeaderLevel")); + Assert.Null(typeof(ExtractionDocumentTextElement).GetProperty("Kind")); + Assert.Equal(typeof(int?), typeof(ExtractionDocumentTextElement).GetProperty("HeadingLevel")!.PropertyType); + Assert.Equal(typeof(string), typeof(ExtractionDocumentTextElement).GetProperty("Role")!.PropertyType); + Assert.False(typeof(ExtractionDocumentTextElement).GetProperty("Role")!.CanWrite); + var parameters = Assert.Single(typeof(ExtractionDocumentTextElement).GetConstructors()).GetParameters(); + Assert.Equal(2, parameters.Length); + Assert.Equal("content", parameters[0].Name); + Assert.Equal("role", parameters[1].Name); + Assert.Equal(typeof(TextContent), parameters[0].ParameterType); + Assert.Equal(typeof(string), parameters[1].ParameterType); + Assert.False(parameters[0].IsOptional); + Assert.True(parameters[1].IsOptional); + Assert.Null(parameters[1].DefaultValue); + Assert.Equal(typeof(System.Collections.Generic.Dictionary), + typeof(ExtractionDocument).GetProperty("Metadata")!.PropertyType); + Assert.Null(typeof(ExtractionDocument).GetProperty("Artifacts")); + } + + [Fact] + public void RootMetadataAndSources_PreserveOpaqueNestedPayloadAndNativeObservations() + { + ExtractionDocument document = new("payload"); + using DocumentAnnotationTestData.BorrowedNative nestedNative = new(); + var payload = new { kind = "vendor-extra", nested = new { unknown = new object[] { 3, "x" }, native = nestedNative } }; + var attributes = new { vendorFlag = "kept", provenance = "urn:synthetic:engine:v1", native = nestedNative }; + ExtractionDocumentTextElement extension = new(new TextContent("visible **text**"), role: "vendor-extra"); + ExtractionDocumentSourceReference first = new(DocumentAnnotationTestData.PdfPage(), DocumentAnnotationTestData.Polygon(), attributes); + ExtractionDocumentSourceReference second = new(new ExtractionDocumentSourcePage("frame-2", 2), DocumentAnnotationTestData.Polygon()); + extension.Sources.Add(first); + extension.Sources.Add(second); + document.SourcePages.Add(first.Page); + document.SourcePages.Add(second.Page); + document.RawRepresentation = payload; + document.Metadata["vendor-extra"] = payload; + document.Metadata["vendorFlag"] = "kept"; + ExtractionDocumentSection section = new(null); + section.Elements.Add(extension); + document.Sections.Add(section); + + Assert.Same(payload, document.Metadata["vendor-extra"]); + Assert.Equal("vendor-extra", extension.Role); + Assert.Equal(new object[] { 3, "x" }, payload.nested.unknown); + Assert.Same(attributes, first.GetRawRepresentation()); + Assert.Equal("kept", attributes.vendorFlag); + Assert.Equal("urn:synthetic:engine:v1", attributes.provenance); + Assert.Equal(new[] { first, second }, extension.Sources); + Assert.Equal(new[] { first.Page, second.Page }, document.SourcePages); + Assert.Same(extension, Assert.Single(document.EnumerateContent())); + Assert.Equal("kept", document.Metadata["vendorFlag"]); + Assert.Equal("visible **text**", Assert.IsType(extension.Content).Text); + Assert.Throws(() => ((System.Collections.Generic.IList)first.Polygon).Clear()); + Assert.Same(payload, document.RawRepresentation); + Assert.Same(attributes, first.GetRawRepresentation()); + Assert.Same(nestedNative, payload.nested.native); + Assert.Same(nestedNative, attributes.native); + Assert.Equal(0, nestedNative.DisposeCount); + } +} diff --git a/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentImageElementTests.cs b/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentImageElementTests.cs new file mode 100644 index 00000000000..d54f208f7c9 --- /dev/null +++ b/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentImageElementTests.cs @@ -0,0 +1,120 @@ +// Licensed to the .NET Foundation under one or more agreements. +// The .NET Foundation licenses this file to you under the MIT license. + +using System; +using Microsoft.Extensions.AI; +using Microsoft.Extensions.Documents; +using Xunit; + +namespace Microsoft.Extensions.Documents.Tests; + +public class DocumentImageElementTests +{ + [Fact] + public void PreservesContentMediaTypeSourceAndAlternativeText() + { + ExtractionDocumentImageElement image = new(new TextContent("stored image")); + ReadOnlyMemory content = new byte[] { 1, 2, 3 }; + Uri source = new("urn:image:opaque-7"); + + DataContent payload = new(content, "image/png"); + image.Content = payload; + image.Source = source; + image.AlternativeText = "diagram"; + + Assert.Same(payload, image.Content); + Assert.Equal(content.ToArray(), Assert.IsType(image.Content).Data.ToArray()); + Assert.Equal("image/png", payload.MediaType); + Assert.Same(source, image.Source); + Assert.Equal("diagram", image.AlternativeText); + } + + [Fact] + public void SourceAndAlternativeText_DoNotReplaceLocalPayload() + { + ExtractionDocumentImageElement image = new(new TextContent("stored image")) + { + Source = new Uri("urn:image:opaque-8"), + AlternativeText = "a diagram" + }; + + Assert.Equal("stored image", Assert.IsType(image.Content).Text); + Assert.Equal("urn:image:opaque-8", image.Source!.ToString()); + Assert.Equal("a diagram", image.AlternativeText); + } + + [Fact] + public void AbsentSource_DoesNotDiscardLocalPayloadOrAlternativeText() + { + ExtractionDocumentImageElement image = new(new TextContent("stored image markdown")) + { + AlternativeText = "unused alternative text" + }; + + Assert.Null(image.Source); + Assert.Equal("stored image markdown", Assert.IsType(image.Content).Text); + Assert.Equal("unused alternative text", image.AlternativeText); + } + + [Fact] + public void SameScalarAssignments_PreserveImagePayloadAndDescription() + { + ExtractionDocument document = new("document"); + ExtractionDocumentSection section = new(null); + ReadOnlyMemory content = new byte[] { 4, 5 }; + Uri source = new("urn:image:opaque-9"); + DataContent payload = new(content, "image/jpeg"); + ExtractionDocumentImageElement image = new(payload) + { + Source = source, + AlternativeText = "photo" + }; + document.Sections.Add(section); + section.Elements.Add(image); + + image.Content = payload; + image.Source = source; + image.AlternativeText = "photo"; + + Assert.Same(payload, image.Content); + Assert.Equal("image/jpeg", payload.MediaType); + Assert.Same(source, image.Source); + Assert.Equal("photo", image.AlternativeText); + } + + [Fact] + public void ImageOnlyContent_PreservesBytesSourceDescriptionAndBorrowedNativePayload() + { + ExtractionDocument document = new("image-only", null); + byte[] bytes = [0x89, 0x50, 0x4E, 0x47, 0x01, 0x02]; + using DocumentAnnotationTestData.CountingStream stream = new(bytes); + Uri source = new("urn:image:page7"); + DataContent payload = new(bytes, "image/png") { RawRepresentation = stream }; + ExtractionDocumentImageElement image = new(payload) + { + Source = source, + AlternativeText = "diagram only" + }; + ExtractionDocumentSourcePage page = DocumentAnnotationTestData.PdfPage(); + document.SourcePages.Add(page); + image.Sources.Add(new ExtractionDocumentSourceReference(page, DocumentAnnotationTestData.Polygon())); + ExtractionDocumentSection section = new(null); + section.Elements.Add(image); + document.Sections.Add(section); + + Assert.Same(payload, image.Content); + Assert.Same(stream, payload.RawRepresentation); + Assert.Equal(bytes, Assert.IsType(image.Content).Data.ToArray()); + Assert.Equal(bytes, stream.ToArray()); + Assert.Equal("image/png", payload.MediaType); + Assert.Same(source, image.Source); + Assert.Equal("diagram only", image.AlternativeText); + Assert.Null(image.Text); + Assert.Null(document.Content); + Assert.Same(image, Assert.Single(document.EnumerateContent())); + Assert.Same(page, Assert.Single(document.SourcePages)); + Assert.Equal(0, stream.DisposeCount); + stream.Dispose(); + Assert.Equal(bytes, Assert.IsType(image.Content).Data.ToArray()); + } +} diff --git a/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentReferencesTests.cs b/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentReferencesTests.cs new file mode 100644 index 00000000000..24ebd895f79 --- /dev/null +++ b/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentReferencesTests.cs @@ -0,0 +1,395 @@ +// Licensed to the .NET Foundation under one or more agreements. +// The .NET Foundation licenses this file to you under the MIT license. + +using System; +using System.Collections.Generic; +using System.Linq; +using Microsoft.Extensions.AI; +using Microsoft.Extensions.Documents; +using Xunit; + +namespace Microsoft.Extensions.Documents.Tests; + +public class DocumentReferencesTests +{ + [Fact] + public void ReducedApi_ExposesTypedSourcesWithoutOwnershipContract() + { + var assembly = typeof(ExtractionDocument).Assembly; + foreach (string name in new[] { "DocumentAnnotation", "DocumentRegion", "DocumentConfidence", "DocumentPageReference", "DocumentEvidenceReference" }) + { + Assert.Null(assembly.GetType("Microsoft.Extensions.Documents." + name)); + } + + foreach (Type type in new[] { typeof(ExtractionDocument), typeof(ExtractionDocumentElement), typeof(ExtractionDocumentTableCell) }) + { + foreach (string name in new[] { "Annotations", "Evidence", "PageReferences", "HasMetadata", "Address", "LocalId", "Version", "IsDisposed" }) + { + Assert.Null(type.GetProperty(name)); + } + } + + Assert.Null(typeof(ExtractionDocument).GetProperty("Sources")); + Assert.Null(typeof(ExtractionDocument).GetProperty("Artifacts")); + foreach (Type type in new[] { typeof(ExtractionDocumentElement), typeof(ExtractionDocumentTableCell) }) + { + var property = type.GetProperty("Sources")!; + Assert.Equal(typeof(System.Collections.Generic.List), property.PropertyType); + Assert.False(property.CanWrite); + } + + Assert.False(typeof(ExtractionDocumentSourceReference).GetProperty("Page")!.CanWrite); + Assert.False(typeof(ExtractionDocumentSourceReference).GetProperty("Polygon")!.CanWrite); + Assert.False(typeof(ExtractionDocument).GetProperty("SourcePages")!.CanWrite); + foreach (string name in new[] { "SetContent", "GetCoveringCell", "IsCovered" }) + { + Assert.Null(typeof(ExtractionDocumentTableCellCollection).GetMethod(name)); + } + + foreach (string name in new[] { "GetCoveringCell", "IsCovered" }) + { + var method = typeof(ExtractionDocumentTableCellCollection).GetMethod(name, + System.Reflection.BindingFlags.Instance | System.Reflection.BindingFlags.NonPublic)!; + Assert.True(method.IsAssembly); + } + + Assert.Null(typeof(ExtractionDocumentTableCell).GetProperty("Kind")); + Assert.Null(typeof(ExtractionDocumentTableCell).GetProperty("CellKind")); + Assert.Equal(typeof(string), typeof(ExtractionDocumentTableCell).GetProperty("Role")!.PropertyType); + Assert.False(typeof(ExtractionDocumentTableCell).GetProperty("Role")!.CanWrite); + var indexer = typeof(ExtractionDocumentTableCellCollection).GetProperty("Item")!; + Assert.Equal(typeof(ExtractionDocumentTableCell), indexer.PropertyType); + Assert.True(indexer.CanRead); + Assert.True(indexer.CanWrite); + Assert.All(typeof(ExtractionDocumentTableCell).GetConstructors(), constructor => + { + var parameters = constructor.GetParameters(); + var role = parameters[parameters.Length - 1]; + Assert.Equal("role", role.Name); + Assert.Equal(typeof(string), role.ParameterType); + Assert.True(role.IsOptional); + Assert.Null(role.DefaultValue); + }); + } + + [Theory] + [InlineData(false)] + [InlineData(true)] + public void SourceReference_NullOrEmptyPolygonIsPageOnly(bool empty) + { + ExtractionDocumentSourcePage page = new("unknown", 3); + using DocumentAnnotationTestData.BorrowedNative native = new(); + ExtractionDocumentSourceReference reference = new(page, empty ? Array.Empty() : null, native); + ExtractionDocumentSourceReference omitted = new(page); + Assert.Same(page, reference.Page); + Assert.Empty(reference.Polygon); + Assert.Empty(omitted.Polygon); + Assert.Null(omitted.GetRawRepresentation()); + Assert.Same(native, reference.GetRawRepresentation()); + Assert.Null(page.Dimensions); + Assert.Null(page.CoordinateUnit); + Assert.Null(page.CoordinateOrigin); + Assert.Equal(0, native.DisposeCount); + } + + [Theory] + [InlineData(1)] + [InlineData(2)] + public void SourceReference_RejectsShortPolygons(int count) + { + Assert.Throws("polygon", () => new ExtractionDocumentSourceReference(new("page", 1), new ExtractionDocumentPoint[count])); + } + + [Fact] + public void SourceReference_MinimumTriangleSnapshotsVerticesAndBorrowsNative() + { + ExtractionDocumentPoint[] points = [new(1, 2), new(3, 4), new(5, 6)]; + using DocumentAnnotationTestData.BorrowedNative native = new(); + ExtractionDocumentSourcePage page = new("triangle", 1); + ExtractionDocumentSourceReference reference = new(page, points, native); + points[2] = new(9, 10); + Assert.Equal(new[] { new ExtractionDocumentPoint(1, 2), new ExtractionDocumentPoint(3, 4), new ExtractionDocumentPoint(5, 6) }, reference.Polygon); + Assert.Same(page, reference.Page); + Assert.Same(native, reference.GetRawRepresentation()); + Assert.Equal(0, native.DisposeCount); + } + + [Fact] + public void SourceReference_IteratorPolygonIsEnumeratedOnceAndSnapshotsMutableList() + { + List points = [new(1.25, 2.5), new(3.75, 4.5), new(5.25, 6.5)]; + ExtractionDocumentPoint[] expected = points.ToArray(); + int enumerations = 0; + ExtractionDocumentSourcePage page = DocumentAnnotationTestData.PdfPage(); + using DocumentAnnotationTestData.BorrowedNative native = new(); + + IEnumerable EnumerateOnce() + { + if (++enumerations != 1) + { + throw new InvalidOperationException("The polygon must only be enumerated once."); + } + + foreach (ExtractionDocumentPoint point in points) + { + yield return point; + } + } + + ExtractionDocumentSourceReference reference = new(page, EnumerateOnce(), native); + Assert.Equal(1, enumerations); + points[0] = new(99, 100); + points.RemoveAt(2); + points.Add(new(101, 102)); + points.Add(new(103, 104)); + + Assert.Equal(expected, reference.Polygon); + Assert.Equal(expected, reference.Polygon.ToArray()); + Assert.Equal(1, enumerations); + Assert.Same(page, reference.Page); + Assert.Same(native, reference.GetRawRepresentation()); + Assert.Equal(0, native.DisposeCount); + IList polygon = Assert.IsAssignableFrom>(reference.Polygon); + Assert.True(polygon.IsReadOnly); + Assert.Throws(() => polygon[0] = default); + Assert.Throws(() => polygon.Add(new(7, 8))); + Assert.Throws(() => polygon.Clear()); + Assert.Equal(expected, reference.Polygon); + } + + [Theory] + [InlineData(0)] + [InlineData(1)] + [InlineData(2)] + public void SourceReference_IteratorPolygonPreservesEmptyAndShortValidation(int count) + { + int enumerations = 0; + IEnumerable EnumerateOnce() + { + if (++enumerations != 1) + { + throw new InvalidOperationException("The polygon must only be enumerated once."); + } + + for (int i = 0; i < count; i++) + { + yield return new(i, i + 1); + } + } + + ExtractionDocumentSourcePage page = new("iterator", 1); + if (count == 0) + { + ExtractionDocumentSourceReference reference = new(page, EnumerateOnce()); + Assert.Empty(reference.Polygon); + Assert.Same(page, reference.Page); + Assert.Null(reference.GetRawRepresentation()); + } + else + { + Assert.Throws("polygon", () => new ExtractionDocumentSourceReference(page, EnumerateOnce())); + } + + Assert.Equal(1, enumerations); + } + + [Theory] + [InlineData(null)] + [InlineData("")] + public void SourceIdentifiers_NullOrEmptyValue_Throws(string? value) + { + Assert.ThrowsAny(() => new ExtractionDocumentSourcePage(value!, 1)); + } + + [Fact] + public void Geometry_PreservesOrderedFractionalVerticesAndFrameIdentity() + { + ExtractionDocument document = new("geometry"); + ExtractionDocumentPoint[] supplied = DocumentAnnotationTestData.Polygon(); + ExtractionDocumentSourcePage page = DocumentAnnotationTestData.PdfPage(); + ExtractionDocumentSourceReference region = new(page, supplied); + supplied[0] = new ExtractionDocumentPoint(999, 999); + ExtractionDocumentTextElement text = new(new TextContent("visible")); + text.Sources.Add(region); + ExtractionDocumentSection section = new(null); + section.Elements.Add(text); + document.Sections.Add(section); + document.SourcePages.Add(page); + + Assert.Equal(DocumentAnnotationTestData.Polygon(), region.Polygon); + Assert.Same(page, region.Page); + Assert.Same(page, Assert.Single(document.SourcePages)); + Assert.Equal("urn:frame:pdf-A", page.Identifier); + Assert.Equal(7, page.PageNumber); + Assert.Equal(new ExtractionDocumentPageDimensions(200, 100), page.Dimensions); + Assert.Equal(ExtractionDocumentCoordinateUnit.Point, page.CoordinateUnit); + Assert.Equal(ExtractionDocumentCoordinateOrigin.BottomLeft, page.CoordinateOrigin); + Assert.Throws(() => ((System.Collections.Generic.IList)region.Polygon)[0] = default); + } + + [Fact] + public void Geometry_KnownPdfAndRasterFixturesProduceDistinctExpectedOverlayVertices() + { + ExtractionDocumentSourceReference pdf = new(DocumentAnnotationTestData.PdfPage(), DocumentAnnotationTestData.Polygon()); + ExtractionDocumentPoint[] expected = + [ + new(20.5, 159), new(81.5, 163.5), new(89, 79.75), + new(25.75, 82.5), new(17, 129.5) + ]; + ExtractionDocumentSourcePage rasterPage = new("urn:frame:raster-A", 7, new ExtractionDocumentPageDimensions(400, 200), + ExtractionDocumentCoordinateUnit.Pixel, ExtractionDocumentCoordinateOrigin.TopLeft); + ExtractionDocumentSourceReference raster = new(rasterPage, expected); + + Assert.Equal(expected, ProjectKnownOverlay(pdf)); + Assert.Equal(expected, ProjectKnownOverlay(raster)); + Assert.Equal(DocumentAnnotationTestData.Polygon(), pdf.Polygon); + Assert.Equal(new ExtractionDocumentPageDimensions(400, 200), raster.Page.Dimensions); + Assert.NotEqual(pdf.Polygon[0], raster.Polygon[0]); + } + + [Theory] + [InlineData(true)] + [InlineData(false)] + public void Geometry_UnknownUnitOrOriginDoesNotGuessConversion(bool unknownUnit) + { + ExtractionDocumentSourcePage page = new("partial", 7, new ExtractionDocumentPageDimensions(200, 100), + unknownUnit ? null : ExtractionDocumentCoordinateUnit.Point, + unknownUnit ? ExtractionDocumentCoordinateOrigin.BottomLeft : null); + ExtractionDocumentSourceReference region = new(page, DocumentAnnotationTestData.Polygon()); + + Assert.Null(ProjectKnownOverlay(region)); + Assert.Equal(DocumentAnnotationTestData.Polygon(), region.Polygon); + Assert.Equal(new ExtractionDocumentPageDimensions(200, 100), page.Dimensions); + Assert.Equal(unknownUnit ? null : ExtractionDocumentCoordinateUnit.Point, page.CoordinateUnit); + Assert.Equal(unknownUnit ? ExtractionDocumentCoordinateOrigin.BottomLeft : null, page.CoordinateOrigin); + } + + [Fact] + public void Geometry_UnknownDimensionsDoNotInferSizeFromKnownFrameOrPolygon() + { + ExtractionDocumentSourcePage page = new("no-size", 7, coordinateUnit: ExtractionDocumentCoordinateUnit.Point, + coordinateOrigin: ExtractionDocumentCoordinateOrigin.BottomLeft); + ExtractionDocumentSourceReference reference = new(page, DocumentAnnotationTestData.Polygon()); + Assert.Null(page.Dimensions); + Assert.Equal(ExtractionDocumentCoordinateUnit.Point, page.CoordinateUnit); + Assert.Equal(ExtractionDocumentCoordinateOrigin.BottomLeft, page.CoordinateOrigin); + Assert.Equal(DocumentAnnotationTestData.Polygon(), reference.Polygon); + Assert.Null(ProjectKnownOverlay(reference)); + } + + [Theory] + [InlineData(double.NaN)] + [InlineData(double.PositiveInfinity)] + [InlineData(double.NegativeInfinity)] + public void Geometry_RejectsNonFiniteValues(double value) + { + Assert.Throws("x", () => new ExtractionDocumentPoint(value, 2)); + Assert.Throws("y", () => new ExtractionDocumentPoint(2, value)); + Assert.Throws("width", () => new ExtractionDocumentPageDimensions(value, 100)); + Assert.Throws("height", () => new ExtractionDocumentPageDimensions(200, value)); + Assert.Throws("width", () => new ExtractionDocumentPageDimensions(value, 0)); + Assert.Throws("height", () => new ExtractionDocumentPageDimensions(0, value)); + ExtractionDocumentSourceReference valid = new(DocumentAnnotationTestData.PdfPage(), DocumentAnnotationTestData.Polygon()); + Assert.Equal(5, valid.Polygon.Count); + Assert.Equal(60.125, valid.Polygon[2].Y); + } + + [Fact] + public void Dimensions_ExplicitEmptyEqualsDefaultWithoutTreatingPositiveDimensionsAsEmpty() + { + ExtractionDocumentPageDimensions empty = new(0, 0); + ExtractionDocumentPageDimensions defaultDimensions = default; + Assert.Equal(0, empty.Width); + Assert.Equal(0, empty.Height); + Assert.Equal(defaultDimensions, empty); + Assert.True(empty.Equals(defaultDimensions)); + Assert.True(empty.Equals((object)defaultDimensions)); + Assert.True(empty == defaultDimensions); + Assert.False(empty != defaultDimensions); + Assert.Equal(defaultDimensions.GetHashCode(), empty.GetHashCode()); + + ExtractionDocumentPageDimensions positive = new(double.Epsilon, double.Epsilon); + Assert.Equal(double.Epsilon, positive.Width); + Assert.Equal(double.Epsilon, positive.Height); + Assert.NotEqual(empty, positive); + Assert.False(empty == positive); + Assert.True(empty != positive); + ExtractionDocumentSourcePage page = new("tiny", 1, positive); + Assert.Equal(positive, page.Dimensions); + } + + [Theory] + [InlineData(-1, 100, "width")] + [InlineData(200, -1, "height")] + [InlineData(-double.Epsilon, 100, "width")] + [InlineData(200, -double.Epsilon, "height")] + [InlineData(0, 100, "width")] + [InlineData(200, 0, "height")] + [InlineData(0, double.Epsilon, "width")] + [InlineData(double.Epsilon, 0, "height")] + [InlineData(-1, 0, "width")] + [InlineData(0, -1, "width")] + public void Dimensions_RejectsNegativeAndOneSidedZero(double width, double height, string parameter) + { + Assert.Throws(parameter, () => new ExtractionDocumentPageDimensions(width, height)); + } + + [Theory] + [InlineData(false)] + [InlineData(true)] + public void SourcePage_RejectsExplicitAndDefaultEmptyDimensionsButAllowsUnknown(bool explicitEmpty) + { + ExtractionDocumentPageDimensions dimensions = explicitEmpty ? new(0, 0) : default; + Assert.Throws("dimensions", () => new ExtractionDocumentSourcePage("empty", 1, dimensions)); + + ExtractionDocumentSourcePage unknown = new("unknown", 1, dimensions: null); + Assert.Null(unknown.Dimensions); + Assert.Equal("unknown", unknown.Identifier); + Assert.Equal(1, unknown.PageNumber); + Assert.Null(unknown.CoordinateUnit); + Assert.Null(unknown.CoordinateOrigin); + } + + [Fact] + public void SourceCarriers_RejectInvalidFramesAndReferences() + { + ExtractionDocumentSourcePage page = DocumentAnnotationTestData.PdfPage(); + Assert.Throws("width", () => new ExtractionDocumentPageDimensions(0, 100)); + Assert.Throws("height", () => new ExtractionDocumentPageDimensions(200, -1)); + Assert.Throws("pageNumber", () => new ExtractionDocumentSourcePage("frame", 0)); + Assert.Throws("dimensions", () => new ExtractionDocumentSourcePage("frame", 1, default(ExtractionDocumentPageDimensions))); + Assert.Throws("coordinateUnit", () => new ExtractionDocumentSourcePage("frame", 1, coordinateUnit: (ExtractionDocumentCoordinateUnit)99)); + Assert.Throws("coordinateOrigin", () => new ExtractionDocumentSourcePage("frame", 1, coordinateOrigin: (ExtractionDocumentCoordinateOrigin)99)); + Assert.Throws("page", () => new ExtractionDocumentSourceReference(null!)); + Assert.Throws("polygon", () => new ExtractionDocumentSourceReference(page, new[] { new ExtractionDocumentPoint(1, 2), new ExtractionDocumentPoint(3, 4) })); + ExtractionDocumentTextElement text = new(new TextContent("visible")); + ExtractionDocumentTableCell cell = new(); + text.Sources.Add(null!); + cell.Sources.Add(null!); + Assert.Null(Assert.Single(text.Sources)); + Assert.Null(Assert.Single(cell.Sources)); + } + + // Consumer-owned oracle for these two known fixtures only; not a production conversion API. + private static ExtractionDocumentPoint[]? ProjectKnownOverlay(ExtractionDocumentSourceReference region) + { + if (region.Page.Dimensions == new ExtractionDocumentPageDimensions(200, 100) && + region.Page.CoordinateUnit == ExtractionDocumentCoordinateUnit.Point && + region.Page.CoordinateOrigin == ExtractionDocumentCoordinateOrigin.BottomLeft) + { + ExtractionDocumentPoint[] result = new ExtractionDocumentPoint[region.Polygon.Count]; + for (int i = 0; i < result.Length; i++) + { + result[i] = new ExtractionDocumentPoint(2 * region.Polygon[i].X, 2 * (100 - region.Polygon[i].Y)); + } + + return result; + } + + return region.Page.Dimensions == new ExtractionDocumentPageDimensions(400, 200) && + region.Page.CoordinateUnit == ExtractionDocumentCoordinateUnit.Pixel && + region.Page.CoordinateOrigin == ExtractionDocumentCoordinateOrigin.TopLeft + ? System.Linq.Enumerable.ToArray(region.Polygon) + : null; + } +} diff --git a/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentReviewFollowUpTests.cs b/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentReviewFollowUpTests.cs new file mode 100644 index 00000000000..71ce9977697 --- /dev/null +++ b/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentReviewFollowUpTests.cs @@ -0,0 +1,237 @@ +// Licensed to the .NET Foundation under one or more agreements. +// The .NET Foundation licenses this file to you under the MIT license. + +using System; +using System.Collections.Generic; +using System.Linq; +using Microsoft.Extensions.AI; +using Microsoft.Extensions.Documents; +using Xunit; + +namespace Microsoft.Extensions.Documents.Tests; + +public class DocumentReviewFollowUpTests +{ + [Fact] + public void DataOnlyApi_HasConcreteCollectionsWithoutParentOrDisposalContract() + { + ExtractionDocument document = new("data"); + ExtractionDocumentSection section = new(); + Assert.IsType>(document.Sections); + Assert.IsType>(document.Metadata); + Assert.IsType>(section.Elements); + Assert.IsType>(section.Sources); + Assert.IsType>(new ExtractionDocumentTableCell().Sources); + foreach (Type type in new[] { typeof(ExtractionDocument), typeof(ExtractionDocumentElement) }) + { + Assert.False(typeof(IDisposable).IsAssignableFrom(type)); + Assert.Null(type.GetMethod("Dispose")); + foreach (string name in new[] { "ParentSection", "Version", "Address", "LocalId", "IsDisposed", "IsDocumentOwned" }) + { + Assert.Null(type.GetProperty(name)); + } + } + + foreach (Type type in typeof(ExtractionDocument).Assembly.GetExportedTypes()) + { + Assert.Null(type.GetMethod("ToMarkdown")); + } + + Assert.Null(typeof(ExtractionDocument).Assembly.GetType("Microsoft.Extensions.Documents.ExtractionDocumentMarkdownFormatter")); + } + + [Fact] + public void OrdinaryLists_AllowSharedElementsAndObserveCurrentOrderWithoutAttachmentState() + { + ExtractionDocument first = new("first"); + ExtractionDocument second = new("second"); + ExtractionDocumentSection section = new(); + ExtractionDocumentTextElement text = new(new TextContent("original")); + section.Elements.AddRange([text, text]); + first.Sections.Add(section); + second.Sections.Add(section); + Assert.Equal(new[] { text, text }, first.EnumerateContent()); + Assert.Equal(new[] { text, text }, second.EnumerateContent()); + section.Elements.RemoveAt(0); + text.Content = new TextContent("changed"); + first.Sections.Clear(); + Assert.Empty(first.EnumerateContent()); + Assert.Equal("changed", Assert.IsType(text.Content).Text); + Assert.Same(text, Assert.Single(second.EnumerateContent())); + } + + [Theory] + [InlineData(false)] + [InlineData(true)] + public void CyclicSections_AreRejectedDuringTraversal(bool self) + { + ExtractionDocument document = new("cycle"); + ExtractionDocumentSection root = new(); + ExtractionDocumentSection child = new(); + document.Sections.Add(root); + root.Elements.Add(self ? root : child); + if (!self) + { + child.Elements.Add(root); + } + + Assert.Throws(() => document.EnumerateContent().ToArray()); + } + + [Theory] + [InlineData(true)] + [InlineData(false)] + public void NullListEntries_FailExplicitlyAtTraversal(bool root) + { + ExtractionDocument document = new("invalid"); + ExtractionDocumentSection section = new(); + document.Sections.Add(root ? null! : section); + if (!root) + { + section.Elements.Add(null!); + } + + Assert.Throws(() => document.EnumerateContent().ToArray()); + } + + [Fact] + public void NontransparentPaths_PreserveSharedSectionsAndRejectAncestorCycles() + { + ExtractionDocument document = new("shared"); + ExtractionDocumentSection root = new(new TextContent("local")); + ExtractionDocumentSection shared = new(); + ExtractionDocumentTextElement text = new(new TextContent("body")); + shared.Elements.Add(text); + root.Elements.Add(shared); + root.Elements.Add(shared); + document.Sections.Add(root); + Assert.Equal(new[] { text, text }, document.EnumerateContent()); + + shared.Elements.Add(root); + Assert.Throws(() => document.EnumerateContent().ToArray()); + + shared.Elements.RemoveAt(1); + document.Sections.Add(root); + Assert.Equal(new[] { text, text, text, text }, document.EnumerateContent()); + } + + [Fact] + public void NestedTables_SharedContentAndCyclesAreNotFlattenedByStructuralTraversal() + { + ExtractionDocumentTableElement outer = new(null, 1, 2); + ExtractionDocumentTableElement inner = new(null, 1, 1); + ExtractionDocumentTextElement shared = new(new TextContent("value")); + outer.Cells[0, 0] = new(inner); + outer.Cells[0, 1] = new(inner); + inner.Cells[0, 0] = new(shared); + Assert.Same(inner, outer.Cells[0, 0]!.Content); + Assert.Same(inner, outer.Cells[0, 1]!.Content); + Assert.Same(shared, inner.Cells[0, 0]!.Content); + ExtractionDocument document = new("tables"); + ExtractionDocumentSection section = new(); + section.Elements.AddRange([outer, outer]); + document.Sections.Add(section); + Assert.Equal(new[] { outer, outer }, document.EnumerateContent()); + inner.Cells[0, 0] = new(outer); + Assert.Equal(new[] { outer, outer }, document.EnumerateContent()); + Assert.Same(outer, inner.Cells[0, 0]!.Content); + } + + [Theory] + [InlineData(false)] + [InlineData(true)] + public void SourceRelationships_AreExplicitRegardlessOfCompositionOrder(bool composeFirst) + { + ExtractionDocument document = new("explicit"); + ExtractionDocumentSection section = new(); + ExtractionDocumentTextElement text = new(new TextContent("visible")); + ExtractionDocumentTableElement table = new(null, 1, 1); + ExtractionDocumentTableCell cell = new(text); + ExtractionDocumentSourcePage page = new("named-frame", null); + ExtractionDocumentSourceReference reference = new(page); + if (composeFirst) + { + table.Cells[0, 0] = cell; + section.Elements.Add(table); + document.Sections.Add(section); + } + + cell.Sources.Add(reference); + text.Sources.Add(reference); + section.Sources.Add(reference); + if (!composeFirst) + { + table.Cells[0, 0] = cell; + section.Elements.Add(table); + document.Sections.Add(section); + } + + Assert.Empty(document.SourcePages); + document.SourcePages.Add(page); + Assert.Same(page, Assert.Single(document.SourcePages)); + cell.Sources.Clear(); + section.Elements.Clear(); + Assert.Same(page, Assert.Single(document.SourcePages)); + Assert.Same(reference, Assert.Single(text.Sources)); + Assert.Null(page.PageNumber); + } + + [Fact] + public void NamedUnnumberedAndOutOfOrderFrames_NeverInferAssemblyPageNumbers() + { + ExtractionDocument document = new("mixed"); + ExtractionDocumentSourcePage named = new("OneNote:Ideas", null); + ExtractionDocumentSourcePage seven = new("pdf:7", 7); + ExtractionDocumentSourcePage two = new("pdf:2", 2); + document.SourcePages.Add(named); + document.SourcePages.Add(seven); + document.SourcePages.Add(two); + ExtractionDocumentSection section = new(); + ExtractionDocumentTextElement text = new(new TextContent("named page")); + text.Sources.Add(new(named)); + section.Elements.Add(text); + document.Sections.Insert(0, section); + Assert.Equal(new int?[] { null, 7, 2 }, document.SourcePages.Select(page => page.PageNumber)); + Assert.Equal("OneNote:Ideas", text.Sources[0].Page.Identifier); + Assert.Null(text.Sources[0].Page.PageNumber); + } + + [Theory] + [InlineData(0)] + [InlineData(-1)] + public void SourcePage_RejectsNonPositiveNumbers(int number) + { + Assert.Throws("pageNumber", () => new ExtractionDocumentSourcePage("frame", number)); + } + + [Fact] + public void Geometry_ExplicitValuesHaveCoordinateEqualityHashAndOperators() + { + ExtractionDocumentPoint point = new(1.25, -2.5); + ExtractionDocumentPoint equalPoint = new(1.25, -2.5); + ExtractionDocumentPoint differentPoint = new(1.25, 2.5); + Assert.True(point == equalPoint); + Assert.False(point != equalPoint); + Assert.True(point != differentPoint); + Assert.False(point == differentPoint); + Assert.True(point.Equals((object)equalPoint)); + Assert.False(point.Equals(null)); + Assert.False(point.Equals("not a point")); + Assert.Equal(point.GetHashCode(), equalPoint.GetHashCode()); + Assert.True(new ExtractionDocumentPoint(0, -0.0) == default); + Assert.Equal(default(ExtractionDocumentPoint).GetHashCode(), new ExtractionDocumentPoint(0, -0.0).GetHashCode()); + ExtractionDocumentPageDimensions size = new(200, 100); + ExtractionDocumentPageDimensions equalSize = new(200, 100); + ExtractionDocumentPageDimensions differentSize = new(100, 200); + Assert.True(size == equalSize); + Assert.False(size != equalSize); + Assert.True(size != differentSize); + Assert.False(size == differentSize); + Assert.True(size.Equals((object)equalSize)); + Assert.False(size.Equals(point)); + Assert.False(size.Equals(null)); + Assert.Equal(size.GetHashCode(), equalSize.GetHashCode()); + Assert.Throws("dimensions", + () => new ExtractionDocumentSourcePage("frame", null, default(ExtractionDocumentPageDimensions))); + } +} diff --git a/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentSectionTests.cs b/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentSectionTests.cs new file mode 100644 index 00000000000..aadf7d55c07 --- /dev/null +++ b/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentSectionTests.cs @@ -0,0 +1,56 @@ +// Licensed to the .NET Foundation under one or more agreements. +// The .NET Foundation licenses this file to you under the MIT license. + +using System.Linq; +using Microsoft.Extensions.AI; +using Microsoft.Extensions.Documents; +using Xunit; + +namespace Microsoft.Extensions.Documents.Tests; + +public class DocumentSectionTests +{ + [Fact] + public void StoresLocalPayloadAndStartsWithEmptyElements() + { + ExtractionDocumentSection section = new(new TextContent("stored section markdown")); + + Assert.Equal("stored section markdown", Assert.IsType(section.Content).Text); + Assert.Empty(section.Elements); + } + + [Fact] + public void LocalPayloadMutation_DoesNotPopulateSectionElements() + { + ExtractionDocumentSection section = new(new TextContent("stored section markdown")); + + Assert.IsType(section.Content).Text = "plain section text"; + Assert.Equal("plain section text", Assert.IsType(section.Content).Text); + Assert.Empty(section.Elements); + } + + [Fact] + public void NestedSections_AreEnumeratedDepthFirst() + { + ExtractionDocument document = new("document"); + ExtractionDocumentSection root = new(null); + ExtractionDocumentTextElement first = new(new TextContent("first")); + ExtractionDocumentSection nested = new(null); + ExtractionDocumentTextElement nestedFirst = new(new TextContent("nested-first")); + ExtractionDocumentTextElement nestedLast = new(new TextContent("nested-last")); + ExtractionDocumentTextElement last = new(new TextContent("last")); + + nested.Elements.Add(nestedFirst); + nested.Elements.Add(nestedLast); + root.Elements.Add(first); + root.Elements.Add(nested); + root.Elements.Add(last); + document.Sections.Add(root); + + ExtractionDocumentElement[] content = document.EnumerateContent().ToArray(); + + Assert.Equal(new ExtractionDocumentElement[] { first, nestedFirst, nestedLast, last }, content); + Assert.DoesNotContain(nested, content); + } + +} diff --git a/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentTableCellCollectionTests.cs b/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentTableCellCollectionTests.cs new file mode 100644 index 00000000000..e54f96a06e0 --- /dev/null +++ b/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentTableCellCollectionTests.cs @@ -0,0 +1,596 @@ +// Licensed to the .NET Foundation under one or more agreements. +// The .NET Foundation licenses this file to you under the MIT license. + +using System; +using System.Linq; +using Microsoft.Extensions.AI; +using Microsoft.Extensions.Documents; +using Xunit; + +namespace Microsoft.Extensions.Documents.Tests; + +public class DocumentTableCellCollectionTests +{ + [Fact] + public void EnumeratesNullableCellsInRowMajorOrder() + { + ExtractionDocumentTableElement table = new(null, 2, 3); + ExtractionDocumentTextElement firstContent = new(new TextContent("first")); + ExtractionDocumentTextElement lastContent = new(new TextContent("last")); + + table.Cells[0, 1] = new ExtractionDocumentTableCell(firstContent); + table.Cells[1, 2] = new ExtractionDocumentTableCell(lastContent); + + ExtractionDocumentTableCell?[] cells = table.Cells.ToArray(); + + Assert.Equal(6, cells.Length); + Assert.Null(cells[0]); + Assert.Same(firstContent, cells[1]!.Content); + Assert.Null(cells[2]); + Assert.Null(cells[3]); + Assert.Null(cells[4]); + Assert.Same(lastContent, cells[5]!.Content); + Assert.Equal( + new ExtractionDocumentTableCell?[] { null, cells[1], null, null, null, cells[5] }, + cells); + } + + [Fact] + public void Indexer_PreservesNonSectionElement() + { + ExtractionDocument document = new("document"); + ExtractionDocumentSection section = new(null); + ExtractionDocumentTableElement table = new(null, 1, 1); + ExtractionDocumentTextElement content = new(new TextContent("cell")); + document.Sections.Add(section); + section.Elements.Add(table); + + table.Cells[0, 0] = new ExtractionDocumentTableCell(content); + + ExtractionDocumentTableCell cell = table.Cells[0, 0]!; + Assert.Same(content, cell.Content); + Assert.Same(cell, table.Cells[0, 0]); + } + + [Fact] + public void SupportsImageCellContent() + { + ExtractionDocumentTableElement table = new(null, 1, 1); + ReadOnlyMemory imageContent = new byte[] { 1, 2, 3 }; + Uri source = new("urn:table-image:opaque-1"); + ExtractionDocumentImageElement image = new(new TextContent("stored image")) + { + Content = new DataContent(imageContent, "image/png"), + Source = source, + AlternativeText = "diagram" + }; + + table.Cells[0, 0] = new ExtractionDocumentTableCell(image); + + ExtractionDocumentImageElement actual = Assert.IsType(table.Cells[0, 0]!.Content); + Assert.Same(image, actual); + Assert.Equal(imageContent.ToArray(), Assert.IsType(actual.Content).Data.ToArray()); + Assert.Equal("image/png", Assert.IsType(actual.Content).MediaType); + Assert.Same(source, actual.Source); + Assert.Equal("diagram", actual.AlternativeText); + } + + [Fact] + public void ReplacesAndRemovesContent_ReleasesCellGridAssociation() + { + ExtractionDocument document = new("document"); + ExtractionDocumentSection section = new(null); + ExtractionDocumentTableElement table = new(null, 1, 1); + ExtractionDocumentTextElement oldContent = new(new TextContent("old")); + ExtractionDocumentTextElement replacementContent = new(new TextContent("replacement")); + document.Sections.Add(section); + section.Elements.Add(table); + + table.Cells[0, 0] = new ExtractionDocumentTableCell(oldContent); + ExtractionDocumentTableCell oldCell = table.Cells[0, 0]!; + + table.Cells[0, 0] = new ExtractionDocumentTableCell(replacementContent); + + ExtractionDocumentTableCell replacementCell = table.Cells[0, 0]!; + Assert.NotSame(oldCell, replacementCell); + Assert.Null(oldCell.Table); + Assert.Same(oldContent, oldCell.Content); + Assert.Same(replacementContent, replacementCell.Content); + + table.Cells[0, 0] = null; + + Assert.Null(table.Cells[0, 0]); + Assert.Null(replacementCell.Table); + Assert.Same(replacementContent, replacementCell.Content); + } + + [Fact] + public void RejectsAlreadyOwnedCell() + { + ExtractionDocumentTableElement firstTable = new(null, 1, 1); + ExtractionDocumentTableElement secondTable = new(null, 1, 1); + ExtractionDocumentTextElement content = new(new TextContent("cell")); + ExtractionDocumentTableCell cell = new(content); + firstTable.Cells[0, 0] = cell; + + Assert.Throws(() => secondTable.Cells[0, 0] = cell); + + Assert.Same(cell, firstTable.Cells[0, 0]); + Assert.Null(secondTable.Cells[0, 0]); + Assert.Same(content, firstTable.Cells[0, 0]!.Content); + Assert.Equal(0, cell.RowIndex); + Assert.Equal(0, cell.ColumnIndex); + } + + [Theory] + [InlineData(false)] + [InlineData(true)] + public void MixedSectionCell_PreservesOrderedLocalPayloadsSourcesAndSpans(bool useUriContent) + { + ExtractionDocument document = new("mixed-cell"); + ExtractionDocumentSection root = new(); + ExtractionDocumentTableElement table = new(null, 2, 3); + root.Elements.Add(table); + document.Sections.Add(root); + ExtractionDocumentSourcePage page = DocumentAnnotationTestData.PdfPage(); + document.SourcePages.Add(page); + ExtractionDocumentSourceReference cellSource = new(page, DocumentAnnotationTestData.Polygon()); + ExtractionDocumentSourceReference firstSource = new(page, [new(1.25, 2.5), new(3.75, 2.5), new(1.25, 4.5)]); + ExtractionDocumentSourceReference imageSource = new(page, [new(5.25, 6.5), new(7.75, 6.5), new(5.25, 8.5)]); + ExtractionDocumentSourceReference lastSource = new(page, [new(9.25, 10.5), new(11.75, 10.5), new(9.25, 12.5)]); + TextContent paragraphA = new("Paragraph A **before** the image."); + TextContent paragraphB = new("Paragraph B *after* the image."); + ExtractionDocumentTextElement first = new(paragraphA, "paragraph"); + ExtractionDocumentTextElement last = new(paragraphB, "paragraph"); + byte[] bytes = [11, 22, 33, 44]; + Uri payloadUri = new("urn:mixed-cell:payload"); + Uri originalAsset = new("urn:mixed-cell:original"); + AIContent imagePayload = useUriContent + ? new UriContent(payloadUri, "image/png") + : new DataContent(bytes, "image/png"); + ExtractionDocumentImageElement image = new(imagePayload, "OCR 17 & 23") + { + Source = originalAsset, + AlternativeText = "A diagram, not its transcription." + }; + first.Sources.Add(firstSource); + image.Sources.Add(imageSource); + last.Sources.Add(lastSource); + ExtractionDocumentSection mixed = new(); + mixed.Elements.Add(first); + mixed.Elements.Add(image); + mixed.Elements.Add(last); + ExtractionDocumentTableCell cell = new(mixed, 2, 2, "rowHeader"); + cell.Sources.Add(cellSource); + + table.Cells[0, 1] = cell; + + Assert.Same(cell, table.Cells[0, 1]); + Assert.Same(table, cell.Table); + Assert.Equal(0, cell.RowIndex); + Assert.Equal(1, cell.ColumnIndex); + Assert.Equal(2, cell.RowSpan); + Assert.Equal(2, cell.ColumnSpan); + Assert.Equal("rowHeader", cell.Role); + Assert.Null(table.Cells[0, 0]); + foreach ((int row, int column) in new[] { (0, 2), (1, 1), (1, 2) }) + { + Assert.Null(table.Cells[row, column]); + Assert.True(table.Cells.IsCovered(row, column)); + Assert.Same(cell, table.Cells.GetCoveringCell(row, column)); + } + + Assert.Same(mixed, cell.Content); + Assert.Equal(3, mixed.Elements.Count); + Assert.Same(first, mixed.Elements[0]); + Assert.Same(image, mixed.Elements[1]); + Assert.Same(last, mixed.Elements[2]); + Assert.Same(paragraphA, first.Content); + Assert.Same(paragraphB, last.Content); + Assert.NotSame(first, last); + Assert.NotSame(paragraphA, paragraphB); + Assert.Equal("Paragraph A **before** the image.", Assert.IsType(first.Content).Text); + Assert.Equal("Paragraph B *after* the image.", Assert.IsType(last.Content).Text); + Assert.Equal("paragraph", first.Role); + Assert.Equal("paragraph", last.Role); + Assert.Same(imagePayload, image.Content); + if (useUriContent) + { + UriContent payload = Assert.IsType(image.Content); + Assert.Same(payloadUri, payload.Uri); + Assert.Equal("image/png", payload.MediaType); + } + else + { + DataContent payload = Assert.IsType(image.Content); + Assert.Equal(new byte[] { 11, 22, 33, 44 }, payload.Data.ToArray()); + Assert.Equal("image/png", payload.MediaType); + } + + Assert.Same(originalAsset, image.Source); + Assert.Equal("OCR 17 & 23", image.Text); + Assert.Equal("A diagram, not its transcription.", image.AlternativeText); + Assert.Same(cellSource, Assert.Single(cell.Sources)); + Assert.Same(firstSource, Assert.Single(first.Sources)); + Assert.Same(imageSource, Assert.Single(image.Sources)); + Assert.Same(lastSource, Assert.Single(last.Sources)); + Assert.Equal(DocumentAnnotationTestData.Polygon(), cellSource.Polygon); + Assert.Equal(new ExtractionDocumentPoint[] { new(1.25, 2.5), new(3.75, 2.5), new(1.25, 4.5) }, firstSource.Polygon); + Assert.Equal(new ExtractionDocumentPoint[] { new(5.25, 6.5), new(7.75, 6.5), new(5.25, 8.5) }, imageSource.Polygon); + Assert.Equal(new ExtractionDocumentPoint[] { new(9.25, 10.5), new(11.75, 10.5), new(9.25, 12.5) }, lastSource.Polygon); + Assert.All(new[] { cellSource, firstSource, imageSource, lastSource }, source => Assert.Same(page, source.Page)); + Assert.Same(page, Assert.Single(document.SourcePages)); + Assert.Equal(new ExtractionDocumentPageDimensions(200, 100), page.Dimensions); + Assert.Equal(ExtractionDocumentCoordinateUnit.Point, page.CoordinateUnit); + Assert.Equal(ExtractionDocumentCoordinateOrigin.BottomLeft, page.CoordinateOrigin); + Assert.Null(document.Content); + Assert.Null(root.Content); + Assert.Null(table.Content); + Assert.Null(mixed.Content); + Assert.Empty(root.Sources); + Assert.Empty(table.Sources); + Assert.Empty(mixed.Sources); + Assert.Same(table, Assert.Single(document.EnumerateContent())); + + image.Text = "Corrected OCR 17 & 28"; + Assert.Equal("Corrected OCR 17 & 28", image.Text); + Assert.Equal("A diagram, not its transcription.", image.AlternativeText); + image.AlternativeText = "Revised caption."; + Assert.Equal("Revised caption.", image.AlternativeText); + Assert.Equal("Corrected OCR 17 & 28", image.Text); + Assert.Same(imagePayload, image.Content); + Assert.Same(originalAsset, image.Source); + Assert.Same(paragraphA, first.Content); + Assert.Same(paragraphB, last.Content); + Assert.Null(mixed.Content); + } + + [Theory] + [InlineData(false)] + [InlineData(true)] + public void MixedSectionCell_PostAttachmentCyclesDoNotExpandPublicTraversal(bool includeInnerTable) + { + ExtractionDocument document = new("mixed-cycle"); + ExtractionDocumentSection root = new(); + ExtractionDocumentTableElement table = new(null, 1, 1); + ExtractionDocumentSection mixed = new(); + ExtractionDocumentTextElement paragraph = new(new TextContent("cell-only paragraph")); + mixed.Elements.Add(paragraph); + ExtractionDocumentTableCell cell = new(mixed); + table.Cells[0, 0] = cell; + root.Elements.Add(table); + document.Sections.Add(root); + Assert.Same(table, Assert.Single(document.EnumerateContent())); + + ExtractionDocumentTableElement? innerTable = null; + if (includeInnerTable) + { + innerTable = new(null, 1, 1); + mixed.Elements.Add(innerTable); + innerTable.Cells[0, 0] = new ExtractionDocumentTableCell(root); + } + else + { + mixed.Elements.Add(root); + } + + // A cycle behind a cell boundary is outside structural traversal. + Assert.Same(table, Assert.Single(document.EnumerateContent())); + Assert.Same(cell, table.Cells[0, 0]); + Assert.Same(mixed, cell.Content); + Assert.Same(paragraph, mixed.Elements[0]); + Assert.Equal("cell-only paragraph", Assert.IsType(paragraph.Content).Text); + if (includeInnerTable) + { + Assert.Same(innerTable, mixed.Elements[1]); + Assert.Same(root, innerTable!.Cells[0, 0]!.Content); + } + else + { + Assert.Same(root, mixed.Elements[1]); + } + + Assert.Null(document.Content); + Assert.Null(table.Content); + Assert.Null(mixed.Content); + } + + [Fact] + public void RejectsTableSelfContent() + { + ExtractionDocumentTableElement table = new(null, 1, 1); + + Assert.Throws(() => table.Cells[0, 0] = new ExtractionDocumentTableCell(table)); + + Assert.Null(table.Cells[0, 0]); + } + + [Fact] + public void IndirectTableCycles_DoNotCauseStructuralTraversalToRecurseIntoCells() + { + ExtractionDocumentTableElement outerTable = new(null, 1, 1); + ExtractionDocumentTableElement innerTable = new(null, 1, 1); + + outerTable.Cells[0, 0] = new ExtractionDocumentTableCell(innerTable); + + innerTable.Cells[0, 0] = new ExtractionDocumentTableCell(outerTable); + ExtractionDocument document = new("cycle"); + ExtractionDocumentSection section = new(); + section.Elements.Add(outerTable); + document.Sections.Add(section); + Assert.Same(outerTable, Assert.Single(document.EnumerateContent())); + + Assert.Same(innerTable, outerTable.Cells[0, 0]!.Content); + Assert.Same(outerTable, innerTable.Cells[0, 0]!.Content); + } + + [Fact] + public void SameCellAssignment_PreservesGridAndPayload() + { + ExtractionDocument document = new("document"); + ExtractionDocumentSection section = new(null); + ExtractionDocumentTableElement table = new(null, 1, 1); + ExtractionDocumentTextElement content = new(new TextContent("content")); + document.Sections.Add(section); + section.Elements.Add(table); + + table.Cells[0, 0] = new ExtractionDocumentTableCell(content); + ExtractionDocumentTableCell cell = table.Cells[0, 0]!; + + table.Cells[0, 0] = cell; + + Assert.Same(cell, table.Cells[0, 0]); + Assert.Same(content, cell.Content); + + table.Cells[0, 0] = null; + table.Cells[0, 0] = null; + + Assert.Null(table.Cells[0, 0]); + Assert.Null(cell.Table); + } + + [Fact] + public void MergedCells_PreserveAnchorSpansRolesAndDistinctCoveredPositions() + { + ExtractionDocument document = new("merged"); + ExtractionDocumentSection section = new(null); + ExtractionDocumentTableElement table = new(null, 3, 3); + ExtractionDocumentTableCell anchor = new(new ExtractionDocumentTextElement(new TextContent("MERGED_A")), 2, 2, "header"); + ExtractionDocumentTableCell ordinary = new(new ExtractionDocumentTextElement(new TextContent("B"))); + table.Cells[0, 0] = anchor; + table.Cells[2, 0] = ordinary; + section.Elements.Add(table); + document.Sections.Add(section); + + Assert.Equal(2, anchor.RowSpan); + Assert.Equal(2, anchor.ColumnSpan); + Assert.Equal("header", anchor.Role); + Assert.False(table.Cells.IsCovered(0, 0)); + foreach ((int row, int column) in new[] { (0, 1), (1, 0), (1, 1) }) + { + Assert.Null(table.Cells[row, column]); + Assert.True(table.Cells.IsCovered(row, column)); + Assert.Same(anchor, table.Cells.GetCoveringCell(row, column)); + } + + Assert.Null(table.Cells[2, 2]); + Assert.False(table.Cells.IsCovered(2, 2)); + Assert.Null(table.Cells.GetCoveringCell(2, 2)); + Assert.Equal(new ExtractionDocumentTableCell?[] { anchor, null, null, null, null, null, ordinary, null, null }, table.Cells.ToArray()); + } + + [Fact] + public void MergedCells_OverlapCoveredEditsAndReuseRejectWithoutMutation() + { + ExtractionDocument document = new("invalid-merged"); + ExtractionDocumentSection section = new(null); + ExtractionDocumentTableElement table = new(null, 3, 3); + ExtractionDocumentTextElement text = new(new TextContent("MERGED_A")); + using DocumentAnnotationTestData.CountingStream stream = new(new byte[] { 1, 2, 3 }); + text.Sources.Add(new(new("merged-page", 1), rawRepresentation: stream)); + ExtractionDocumentTableCell anchor = new(text, 2, 2); + table.Cells[0, 0] = anchor; + section.Elements.Add(table); + document.Sections.Add(section); + ExtractionDocumentTableCell?[] before = table.Cells.ToArray(); + ExtractionDocumentTableCell overlap = new(2, 1); + ExtractionDocumentTableCell candidate = new(); + + Assert.Throws(() => table.Cells[0, 1] = candidate); + Assert.Throws(() => table.Cells[1, 1] = null); + Assert.Throws(() => table.Cells[1, 0] = null); + table.Cells[2, 2] = candidate; + Assert.Throws(() => table.Cells[1, 2] = overlap); + Assert.Throws(() => table.Cells[2, 1] = candidate); + table.Cells[2, 2] = null; + Assert.Equal(before, table.Cells.ToArray()); + Assert.Equal(new byte[] { 1, 2, 3 }, stream.ToArray()); + Assert.Equal(0, stream.DisposeCount); + + table.Cells[0, 0] = null; + Assert.False(table.Cells.IsCovered(1, 1)); + Assert.Null(table.Cells.GetCoveringCell(1, 1)); + Assert.Equal(0, stream.DisposeCount); + } + + [Theory] + [InlineData(2, 1)] + [InlineData(1, 2)] + public void MergedCells_OutOfBoundsSpanRejectsWithoutTakingOwnership(int rowSpan, int columnSpan) + { + ExtractionDocument document = new("bounds"); + ExtractionDocumentSection section = new(null); + ExtractionDocumentTableElement table = new(null, 3, 3); + section.Elements.Add(table); + document.Sections.Add(section); + ExtractionDocumentTableCell candidate = new(rowSpan, columnSpan); + + Assert.Throws("cell", () => table.Cells[2, 2] = candidate); + Assert.Null(table.Cells[2, 2]); + table.Cells[0, 0] = candidate; + } + + [Fact] + public void MergedCells_ProspectiveSpanCrossingCoveredSlotOnlyRejectsWithoutMutation() + { + ExtractionDocument document = new("covered-slot-overlap"); + ExtractionDocumentSection section = new(null); + ExtractionDocumentTableElement table = new(null, 3, 3); + ExtractionDocumentTextElement anchorText = new(new TextContent("MERGED_A")); + ExtractionDocumentTableCell anchor = new(anchorText, 2, 2); + table.Cells[1, 1] = anchor; + section.Elements.Add(table); + document.Sections.Add(section); + using DocumentAnnotationTestData.CountingStream stream = new(new byte[] { 61, 62, 63 }); + ExtractionDocumentTextElement candidateText = new(new TextContent("candidate **value**")); + candidateText.Sources.Add(new(new("candidate-page", 1), rawRepresentation: stream)); + ExtractionDocumentTableCell candidate = new(candidateText, 2, 1); + ExtractionDocumentTableCell?[] before = table.Cells.ToArray(); + + // Candidate occupies (0,2) and (1,2), never the existing anchor at (1,1). + Assert.Null(table.Cells[0, 2]); + Assert.False(table.Cells.IsCovered(0, 2)); + Assert.Null(table.Cells.GetCoveringCell(0, 2)); + Assert.Null(table.Cells[1, 2]); + Assert.True(table.Cells.IsCovered(1, 2)); + Assert.Same(anchor, table.Cells.GetCoveringCell(1, 2)); + + Assert.Throws(() => table.Cells[0, 2] = candidate); + + Assert.Equal(before, table.Cells.ToArray()); + for (int row = 0; row < 3; row++) + { + for (int column = 0; column < 3; column++) + { + bool inAnchor = row >= 1 && column >= 1; + Assert.Equal(inAnchor && (row != 1 || column != 1), table.Cells.IsCovered(row, column)); + Assert.Same(inAnchor ? anchor : null, table.Cells.GetCoveringCell(row, column)); + } + } + + Assert.Same(anchor, table.Cells[1, 1]); + Assert.Empty(document.SourcePages); + Assert.Equal(new byte[] { 61, 62, 63 }, stream.ToArray()); + Assert.Equal(0, stream.DisposeCount); + + // Success in another attached table proves rejection took neither cell nor content ownership. + ExtractionDocument other = new("candidate-owner"); + ExtractionDocumentSection otherSection = new(null); + ExtractionDocumentTableElement otherTable = new(null, 2, 1); + otherSection.Elements.Add(otherTable); + other.Sections.Add(otherSection); + otherTable.Cells[0, 0] = candidate; + other.SourcePages.Add(candidateText.Sources[0].Page); + Assert.Same(candidate, otherTable.Cells[0, 0]); + Assert.Same(candidate, otherTable.Cells.GetCoveringCell(1, 0)); + Assert.True(otherTable.Cells.IsCovered(1, 0)); + Assert.Same(candidateText.Sources[0].Page, Assert.Single(other.SourcePages)); + Assert.Equal("candidate **value**", Assert.IsType(candidateText.Content).Text); + Assert.Equal(before, table.Cells.ToArray()); + + Assert.Equal(0, stream.DisposeCount); + Assert.Equal(new byte[] { 61, 62, 63 }, stream.ToArray()); + Assert.Equal(0, stream.DisposeCount); + stream.Dispose(); + Assert.False(stream.CanRead); + } + + [Fact] + public void MergedAnchorReplacement_ReleasesCoveredSlotsAndRetainsExplicitSourceData() + { + ExtractionDocument document = new("replacement-lifetime"); + using DocumentAnnotationTestData.CountingStream stream = new(DocumentAnnotationTestData.OriginalBytes()); + using DocumentAnnotationTestData.BorrowedNative native = new(); + document.RawRepresentation = native; + ExtractionDocumentSourcePage frame = DocumentAnnotationTestData.PdfPage(); + document.SourcePages.Add(frame); + ExtractionDocumentTextElement oldText = new(new TextContent("lO0? &")); + ExtractionDocumentTableCell oldAnchor = new(oldText, 2, 2, "rowHeader"); + oldAnchor.Sources.Add(new ExtractionDocumentSourceReference(frame, DocumentAnnotationTestData.Polygon())); + ExtractionDocumentTableElement table = new(null, 4, 4); + table.Cells[0, 0] = oldAnchor; + ExtractionDocumentSection section = new(null); + section.Elements.Add(table); + document.Sections.Add(section); + Assert.Same(oldAnchor, table.Cells.GetCoveringCell(1, 1)); + Assert.True(table.Cells.IsCovered(1, 1)); + + ExtractionDocumentTextElement replacementText = new(new TextContent("replacement?")); + ExtractionDocumentTableCell replacement = new(replacementText); + table.Cells[0, 0] = replacement; + + Assert.Same(replacement, table.Cells.GetCoveringCell(0, 0)); + foreach ((int row, int column) in new[] { (0, 1), (1, 0), (1, 1) }) + { + Assert.Null(table.Cells[row, column]); + Assert.Null(table.Cells.GetCoveringCell(row, column)); + Assert.False(table.Cells.IsCovered(row, column)); + } + + Assert.Same(frame, Assert.Single(document.SourcePages)); + Assert.Equal(0, stream.DisposeCount); + Assert.True(stream.CanRead); + Assert.Equal(DocumentAnnotationTestData.OriginalBytes(), stream.ToArray()); + + ExtractionDocumentTableCell empty = new(); + table.Cells[0, 1] = empty; + Assert.Same(empty, table.Cells.GetCoveringCell(0, 1)); + Assert.False(table.Cells.IsCovered(0, 1)); + table.Cells[2, 2] = oldAnchor; + + Assert.Equal(4, table.Cells.RowCount); + Assert.Equal(4, table.Cells.ColumnCount); + Assert.Equal(2, oldAnchor.RowIndex); + Assert.Equal(2, oldAnchor.ColumnIndex); + Assert.Equal(2, oldAnchor.RowSpan); + Assert.Equal(2, oldAnchor.ColumnSpan); + Assert.Equal("rowHeader", oldAnchor.Role); + Assert.Equal("lO0? &", Assert.IsType(oldText.Content).Text); + Assert.Equal("replacement?", Assert.IsType(replacementText.Content).Text); + Assert.Null(empty.Content); + for (int row = 0; row < 4; row++) + { + for (int column = 0; column < 4; column++) + { + ExtractionDocumentTableCell? covering = null; + if (row >= 2 && column >= 2) + { + covering = oldAnchor; + } + else if (row == 0 && column == 0) + { + covering = replacement; + } + else if (row == 0 && column == 1) + { + covering = empty; + } + + Assert.Same(covering, table.Cells.GetCoveringCell(row, column)); + Assert.Equal(row >= 2 && column >= 2 && (row != 2 || column != 2), table.Cells.IsCovered(row, column)); + } + } + + Assert.Equal( + new ExtractionDocumentTableCell?[] + { + replacement, empty, null, null, null, null, null, null, + null, null, oldAnchor, null, null, null, null, null + }, + table.Cells.ToArray()); + Assert.Null(table.Content); + Assert.Same(frame, Assert.Single(document.SourcePages)); + Assert.Same(frame, oldAnchor.Sources[0].Page); + Assert.Equal(DocumentAnnotationTestData.Polygon(), oldAnchor.Sources[0].Polygon); + Assert.Same(native, document.RawRepresentation); + Assert.Equal(0, stream.DisposeCount); + Assert.Equal(0, native.DisposeCount); + Assert.True(stream.CanRead); + Assert.Equal(DocumentAnnotationTestData.OriginalBytes(), stream.ToArray()); + + stream.Dispose(); + Assert.Equal(1, stream.DisposeCount); + Assert.False(stream.CanRead); + Assert.Equal(0, native.DisposeCount); + } +} diff --git a/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentTableCellTests.cs b/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentTableCellTests.cs new file mode 100644 index 00000000000..f8812c9f9be --- /dev/null +++ b/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentTableCellTests.cs @@ -0,0 +1,212 @@ +// Licensed to the .NET Foundation under one or more agreements. +// The .NET Foundation licenses this file to you under the MIT license. + +using System; +using Microsoft.Extensions.AI; +using Microsoft.Extensions.Documents; +using Xunit; + +namespace Microsoft.Extensions.Documents.Tests; + +public class DocumentTableCellTests +{ + [Fact] + public void HasRowAndColumnAddressWithinGrid() + { + ExtractionDocument document = new("document"); + ExtractionDocumentSection section = new(null); + ExtractionDocumentTableElement table = new(null, 2, 2); + ExtractionDocumentTextElement content = new(new TextContent("cell")); + + table.Cells[1, 0] = new ExtractionDocumentTableCell(content); + section.Elements.Add(table); + document.Sections.Add(section); + + ExtractionDocumentTableCell cell = table.Cells[1, 0]!; + + Assert.Equal(1, cell.RowIndex); + Assert.Equal(0, cell.ColumnIndex); + } + + [Fact] + public void GridCoordinates_AreIndependentOfSectionOrder() + { + ExtractionDocument document = new("document"); + ExtractionDocumentSection firstSection = new(null); + ExtractionDocumentSection secondSection = new(null); + ExtractionDocumentTableElement table = new(null, 1, 1); + ExtractionDocumentTextElement content = new(new TextContent("cell")); + + table.Cells[0, 0] = new ExtractionDocumentTableCell(content); + firstSection.Elements.Add(table); + document.Sections.Add(firstSection); + document.Sections.Add(secondSection); + + ExtractionDocumentTableCell cell = table.Cells[0, 0]!; + + firstSection.Elements.Remove(table); + + secondSection.Elements.Add(table); + Assert.Same(cell, table.Cells[0, 0]); + Assert.Same(content, cell.Content); + Assert.Equal(0, cell.RowIndex); + Assert.Equal(0, cell.ColumnIndex); + Assert.Empty(firstSection.Elements); + Assert.Same(table, Assert.Single(secondSection.Elements)); + } + + [Fact] + public void Constructor_RejectsNullContent() + { + Assert.Throws( + "content", + () => new ExtractionDocumentTableCell(null!)); + } + + [Theory] + [InlineData(null)] + [InlineData("columnHeader")] + [InlineData("rowHeader")] + [InlineData("ColumnHeader")] + [InlineData("vendor\"role")] + [InlineData(" custom ")] + public void Constructors_PreserveRolesForContentAndEmptyCellsThroughIndexer(string? role) + { + ExtractionDocument document = new("cell-roles", null); + ExtractionDocumentSection section = new(null); + ExtractionDocumentTableElement table = new(null, 1, 2); + ExtractionDocumentTextElement text = new(new TextContent("cell")); + ExtractionDocumentTableCell content = new(text, role: role); + ExtractionDocumentTableCell empty = new(role: role); + table.Cells[0, 0] = content; + table.Cells[0, 1] = empty; + section.Elements.Add(table); + document.Sections.Add(section); + + Assert.Equal(role, content.Role); + Assert.Equal(role, empty.Role); + Assert.Equal(1, content.RowSpan); + Assert.Equal(1, empty.ColumnSpan); + Assert.Same(text, content.Content); + Assert.Null(empty.Content); + Assert.Equal(new ExtractionDocumentTableCell?[] { content, empty }, table.Cells); + Assert.Equal("cell", Assert.IsType(text.Content).Text); + Assert.Equal("cell", Assert.IsType(text.Content).Text); + Assert.Null(table.Content); + Assert.Null(document.Content); + } + + [Theory] + [InlineData("")] + [InlineData(" ")] + [InlineData("\t\r\n")] + public void Constructors_RejectWhitespaceRolesWithoutAttachingContent(string role) + { + ExtractionDocumentTextElement text = new(new TextContent("cell")); + + Assert.Throws(nameof(role), () => new ExtractionDocumentTableCell(text, role: role)); + Assert.Throws(nameof(role), () => new ExtractionDocumentTableCell(role: role)); + Assert.Equal("cell", Assert.IsType(text.Content).Text); + } + + [Fact] + public void EmptyCell_PreservesGeometryWithoutText() + { + ExtractionDocument document = new("empty-cell"); + ExtractionDocumentSection section = new(null); + ExtractionDocumentTableElement table = new(null, 3, 3); + ExtractionDocumentTableCell empty = new(); + ExtractionDocumentSourcePage page = DocumentAnnotationTestData.PdfPage(); + document.SourcePages.Add(page); + empty.Sources.Add(new ExtractionDocumentSourceReference(page, DocumentAnnotationTestData.Polygon())); + table.Cells[2, 2] = empty; + section.Elements.Add(table); + document.Sections.Add(section); + + Assert.Null(empty.Content); + Assert.Equal(2, empty.RowIndex); + Assert.Equal(2, empty.ColumnIndex); + Assert.Equal(1, empty.RowSpan); + Assert.Equal(1, empty.ColumnSpan); + Assert.False(table.Cells.IsCovered(2, 2)); + Assert.Same(empty, table.Cells.GetCoveringCell(2, 2)); + Assert.Null(table.Cells.GetCoveringCell(1, 2)); + Assert.Equal(DocumentAnnotationTestData.Polygon(), empty.Sources[0].Polygon); + Assert.Same(page, Assert.Single(document.SourcePages)); + empty.Sources.Add(new ExtractionDocumentSourceReference(page)); + Assert.Equal(2, empty.Sources.Count); + } + + [Theory] + [InlineData(0, 1, "rowSpan")] + [InlineData(-1, 1, "rowSpan")] + [InlineData(1, 0, "columnSpan")] + [InlineData(1, -1, "columnSpan")] + public void Constructors_RejectNonPositiveSpans(int rowSpan, int columnSpan, string parameter) + { + ExtractionDocumentTextElement text = new(new TextContent("content")); + Assert.Throws(parameter, () => new ExtractionDocumentTableCell(rowSpan, columnSpan)); + Assert.Throws(parameter, () => new ExtractionDocumentTableCell(text, rowSpan, columnSpan)); + } + + [Fact] + public void CellFrames_ResolveMultipleCoordinateSystemsAfterTableReparenting() + { + ExtractionDocument document = new("multi-frame-cell"); + ExtractionDocumentSourcePage pdf = DocumentAnnotationTestData.PdfPage(); + ExtractionDocumentSourcePage raster = new("raster-frame", 7, new ExtractionDocumentPageDimensions(400, 200), + ExtractionDocumentCoordinateUnit.Pixel, ExtractionDocumentCoordinateOrigin.TopLeft); + document.SourcePages.Add(pdf); + document.SourcePages.Add(raster); + ExtractionDocumentPoint[] rasterPolygon = + [ + new(20.5, 159), new(81.5, 163.5), new(89, 79.75), new(25.75, 82.5), new(17, 129.5) + ]; + ExtractionDocumentTableCell empty = new(); + empty.Sources.Add(new ExtractionDocumentSourceReference(pdf, DocumentAnnotationTestData.Polygon())); + empty.Sources.Add(new ExtractionDocumentSourceReference(raster, rasterPolygon)); + ExtractionDocumentTextElement text = new(new TextContent("lO0 ??")); + ExtractionDocumentTableCell ordinary = new(text); + document.Metadata["vendor unknown margin"] = -12.5; + ExtractionDocumentTableElement table = new(null, 1, 3); + table.Cells[0, 1] = empty; + table.Cells[0, 2] = ordinary; + ExtractionDocumentSection first = new(null); + ExtractionDocumentSection second = new(null); + first.Elements.Add(new ExtractionDocumentTextElement(new TextContent("first"))); + second.Elements.Add(new ExtractionDocumentTextElement(new TextContent("second"))); + first.Elements.Add(table); + document.Sections.Add(first); + document.Sections.Add(second); + + Assert.Equal(new[] { pdf, raster }, document.SourcePages); + + Assert.True(first.Elements.Remove(table)); + Assert.Equal(new[] { pdf, raster }, document.SourcePages); + second.Elements.Add(table); + + Assert.Null(empty.Content); + Assert.Same(empty, table.Cells.GetCoveringCell(0, 1)); + Assert.False(table.Cells.IsCovered(0, 1)); + Assert.Null(table.Cells.GetCoveringCell(0, 0)); + Assert.Equal(new[] { pdf, raster }, document.SourcePages); + var sources = table.Cells.GetCoveringCell(0, 1)!.Sources; + Assert.Equal(2, sources.Count); + Assert.Same(document.SourcePages[0], sources[0].Page); + Assert.Same(document.SourcePages[1], sources[1].Page); + Assert.Equal(DocumentAnnotationTestData.Polygon(), sources[0].Polygon); + Assert.Equal(rasterPolygon, sources[1].Polygon); + Assert.Equal(7, sources[0].Page.PageNumber); + Assert.Equal(7, sources[1].Page.PageNumber); + Assert.Equal(new ExtractionDocumentPageDimensions(200, 100), sources[0].Page.Dimensions); + Assert.Equal(new ExtractionDocumentPageDimensions(400, 200), sources[1].Page.Dimensions); + Assert.Equal(ExtractionDocumentCoordinateUnit.Point, sources[0].Page.CoordinateUnit); + Assert.Equal(ExtractionDocumentCoordinateOrigin.BottomLeft, sources[0].Page.CoordinateOrigin); + Assert.Equal(ExtractionDocumentCoordinateUnit.Pixel, sources[1].Page.CoordinateUnit); + Assert.Equal(ExtractionDocumentCoordinateOrigin.TopLeft, sources[1].Page.CoordinateOrigin); + Assert.Empty(table.Cells.GetCoveringCell(0, 2)!.Content!.Sources); + Assert.Equal(-12.5, document.Metadata["vendor unknown margin"]); + Assert.Equal("lO0 ??", Assert.IsType(text.Content).Text); + Assert.Null(table.Content); + } +} diff --git a/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentTableElementTests.cs b/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentTableElementTests.cs new file mode 100644 index 00000000000..7f9faae177b --- /dev/null +++ b/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentTableElementTests.cs @@ -0,0 +1,422 @@ +// Licensed to the .NET Foundation under one or more agreements. +// The .NET Foundation licenses this file to you under the MIT license. + +using System; +using System.Linq; +using Microsoft.Extensions.AI; +using Microsoft.Extensions.Documents; +using Xunit; + +namespace Microsoft.Extensions.Documents.Tests; + +public class DocumentTableElementTests +{ + [Fact] + public void NestedTables_PreserveHierarchyAndLiteralText() + { + ExtractionDocumentTextElement leaf = new(new TextContent("L|R")); + ExtractionDocumentTableElement inner = new(null, 1, 1); + ExtractionDocumentTableElement middle = new(null, 1, 1); + ExtractionDocumentTableElement outer = new(null, 1, 1); + inner.Cells[0, 0] = new ExtractionDocumentTableCell(leaf); + middle.Cells[0, 0] = new ExtractionDocumentTableCell(inner); + outer.Cells[0, 0] = new ExtractionDocumentTableCell(middle); + + Assert.Same(leaf, inner.Cells[0, 0]!.Content); + Assert.Same(inner, middle.Cells[0, 0]!.Content); + Assert.Same(middle, outer.Cells[0, 0]!.Content); + Assert.Equal("L|R", Assert.IsType(leaf.Content).Text); + } + + [Fact] + public void NestedTable_PreservesLiteralRoleTextAndImageAlternative() + { + ExtractionDocumentTextElement text = new(new TextContent("A|<&")); + ExtractionDocumentImageElement image = new(new UriContent("urn:image", "image/png")) + { + AlternativeText = "alt|\"<&" + }; + ExtractionDocumentTableElement inner = new(null, 1, 2); + ExtractionDocumentTableCell first = new(text, role: "vendor|\"<"); + inner.Cells[0, 0] = first; + inner.Cells[0, 1] = new ExtractionDocumentTableCell(image); + ExtractionDocumentTableElement outer = new(null, 1, 1); + outer.Cells[0, 0] = new ExtractionDocumentTableCell(inner); + + Assert.Equal("vendor|\"<", first.Role); + Assert.Equal("alt|\"<&", image.AlternativeText); + Assert.Equal("A|<&", Assert.IsType(text.Content).Text); + Assert.Same(image, inner.Cells[0, 1]!.Content); + Assert.Equal(1, inner.Cells.RowCount); + Assert.Equal(2, inner.Cells.ColumnCount); + } + + [Fact] + public void Coverage_TracksSpanReplacementRemovalAndRejectedEdits() + { + ExtractionDocument document = new("coverage"); + ExtractionDocumentSection section = new(null); + ExtractionDocumentTableElement table = new(null, 3, 4); + section.Elements.Add(table); + document.Sections.Add(section); + ExtractionDocumentTableCell wide = new(new ExtractionDocumentTextElement(new TextContent("wide")), 2, 3); + ExtractionDocumentTableCell corner = new(new ExtractionDocumentTextElement(new TextContent("corner")), role: "rowHeader"); + table.Cells[0, 0] = wide; + table.Cells[2, 3] = corner; + AssertCoverage(wide, 2, 3); + + Assert.Throws(() => table.Cells[1, 1] = new ExtractionDocumentTableCell()); + Assert.Throws(() => table.Cells[0, 3] = new ExtractionDocumentTableCell(3, 1)); + Assert.Throws(() => table.Cells[0, 0] = new ExtractionDocumentTableCell(4, 1)); + AssertCoverage(wide, 2, 3); + + ExtractionDocumentTableCell small = new(new ExtractionDocumentTextElement(new TextContent("small"))); + table.Cells[0, 0] = small; + AssertCoverage(small, 1, 1); + table.Cells[0, 0] = null; + AssertCoverage(null, 0, 0); + table.Cells[0, 0] = wide; + AssertCoverage(wide, 2, 3); + + void AssertCoverage(ExtractionDocumentTableCell? anchor, int rows, int columns) + { + for (int row = 0; row < 3; row++) + { + for (int column = 0; column < 4; column++) + { + bool inSpan = row < rows && column < columns; + ExtractionDocumentTableCell? cornerCell = row == 2 && column == 3 ? corner : null; + ExtractionDocumentTableCell? expected = inSpan ? anchor : cornerCell; + Assert.Same(expected, table.Cells.GetCoveringCell(row, column)); + Assert.Equal(inSpan && (row != 0 || column != 0), + table.Cells.IsCovered(row, column)); + Assert.Same(row == 0 && column == 0 ? anchor : cornerCell, + table.Cells[row, column]); + } + } + } + } + + [Fact] + public void StoresDimensionsAndCreatesNullableCells() + { + ExtractionDocumentTableElement table = new(new TextContent("stored table"), 2, 3); + + Assert.Equal("stored table", Assert.IsType(table.Content).Text); + Assert.Equal(2, table.Cells.RowCount); + Assert.Equal(3, table.Cells.ColumnCount); + Assert.Equal( + new ExtractionDocumentTableCell?[] { null, null, null, null, null, null }, + table.Cells.ToArray()); + } + + [Theory] + [InlineData(-1, 0, "rowCount")] + [InlineData(0, -1, "columnCount")] + public void RejectsNegativeDimensions(int rowCount, int columnCount, string parameterName) + { + Assert.Throws( + parameterName, + () => new ExtractionDocumentTableElement(null, rowCount, columnCount)); + } + + [Theory] + [InlineData(0, 2)] + [InlineData(2, 0)] + public void ZeroDimensions_RetainLocalPayloadWithoutFabricatingCells(int rowCount, int columnCount) + { + ExtractionDocumentTableElement table = new(new TextContent("stored table"), rowCount, columnCount); + + Assert.Equal(rowCount, table.Cells.RowCount); + Assert.Equal(columnCount, table.Cells.ColumnCount); + Assert.Empty(table.Cells); + Assert.Equal("stored table", Assert.IsType(table.Content).Text); + } + + [Theory] + [InlineData(-1, 0, "row")] + [InlineData(2, 0, "row")] + [InlineData(0, -1, "column")] + [InlineData(0, 2, "column")] + public void RejectsInvalidCellAddresses(int row, int column, string parameterName) + { + ExtractionDocumentTableElement table = new(null, 2, 2); + ExtractionDocumentTextElement text = new(new TextContent("candidate")); + ExtractionDocumentTableCell candidate = new(text); + + Assert.Throws( + parameterName, + () => _ = table.Cells[row, column]); + Assert.Throws( + parameterName, + () => table.Cells[row, column] = candidate); + Assert.Throws( + parameterName, + () => table.Cells[row, column] = null); + + Assert.Null(candidate.Table); + Assert.Equal( + new ExtractionDocumentTableCell?[] { null, null, null, null }, + table.Cells.ToArray()); + } + + [Fact] + public void CellGrid_PreservesPayloadsAndNullPositions() + { + ExtractionDocumentTableElement table = new(null, 2, 3); + table.Cells[0, 1] = new ExtractionDocumentTableCell(new ExtractionDocumentTextElement(new TextContent("one"))); + table.Cells[1, 0] = new ExtractionDocumentTableCell(new ExtractionDocumentTextElement(new TextContent("two"))); + + Assert.Equal(6, table.Cells.Count()); + Assert.Null(table.Cells[0, 0]); + Assert.Null(table.Cells[0, 2]); + Assert.Null(table.Cells[1, 1]); + Assert.Null(table.Cells[1, 2]); + Assert.Equal("one", Assert.IsType(table.Cells[0, 1]!.Content!.Content).Text); + Assert.Equal("two", Assert.IsType(table.Cells[1, 0]!.Content!.Content).Text); + } + + [Fact] + public void CellPayload_PreservesLiteralPipes() + { + ExtractionDocumentTableElement table = new(null, 1, 1); + table.Cells[0, 0] = new ExtractionDocumentTableCell(new ExtractionDocumentTextElement(new TextContent("left|right"))); + + Assert.Equal("left|right", Assert.IsType(table.Cells[0, 0]!.Content!.Content).Text); + } + + [Fact] + public void AbsentTablePayload_DoesNotAggregateCellPayloads() + { + ExtractionDocumentTableElement table = new(null, 1, 1); + table.Cells[0, 0] = new ExtractionDocumentTableCell(new ExtractionDocumentTextElement(new TextContent("semantic cell"))); + + Assert.Null(table.Content); + Assert.Equal("semantic cell", Assert.IsType(table.Cells[0, 0]!.Content!.Content).Text); + } + + [Fact] + public void MergedCells_PreserveAnchorContentRolesAndCoveredPositions() + { + ExtractionDocumentTableElement table = new(null, 3, 3); + ExtractionDocumentTableCell anchor = new(new ExtractionDocumentTextElement(new TextContent("MERGED_A<&")), 2, 2, "columnHeader"); + table.Cells[0, 0] = anchor; + table.Cells[2, 0] = new ExtractionDocumentTableCell(new ExtractionDocumentTextElement(new TextContent("B")), role: "rowHeader"); + ExtractionDocumentTableCell empty = new(role: "vendor\"role"); + table.Cells[2, 2] = empty; + ExtractionDocumentTableCell?[] before = table.Cells.ToArray(); + + Assert.Equal(before, table.Cells.ToArray()); + Assert.Equal("columnHeader", anchor.Role); + Assert.Equal("MERGED_A<&", Assert.IsType(anchor.Content!.Content).Text); + Assert.Equal("rowHeader", table.Cells[2, 0]!.Role); + Assert.Equal("vendor\"role", empty.Role); + Assert.Same(anchor, table.Cells.GetCoveringCell(1, 1)); + Assert.Null(table.Cells[1, 1]); + Assert.False(table.Cells.IsCovered(2, 2)); + Assert.Null(empty.Content); + Assert.Null(table.Content); + } + + [Theory] + [InlineData(null)] + [InlineData("columnHeader")] + [InlineData("rowHeader")] + [InlineData("ColumnHeader")] + [InlineData("header")] + [InlineData("vendor\"role")] + public void CellRoles_AreExplicitWithoutCorrectingTranscription(string? role) + { + ExtractionDocument document = new("explicit-roles", null); + ExtractionDocumentSection section = new(null); + ExtractionDocumentTableElement table = new(null, 1, 1); + + // Header text is not permission to invent a table-cell role or repair recognition. + ExtractionDocumentTextElement text = new(new TextContent(" INV0ICE 1O0? <&| "), role: "heading"); + ExtractionDocumentTableCell cell = new(text, role: role); + table.Cells[0, 0] = cell; + section.Elements.Add(table); + document.Sections.Add(section); + + Assert.Null(table.Content); + Assert.Null(document.Content); + Assert.Equal(" INV0ICE 1O0? <&| ", Assert.IsType(text.Content).Text); + Assert.Equal(" INV0ICE 1O0? <&| ", Assert.IsType(text.Content).Text); + Assert.Equal(role, cell.Role); + Assert.Same(cell, table.Cells.GetCoveringCell(0, 0)); + Assert.False(table.Cells.IsCovered(0, 0)); + } + + [Theory] + [InlineData(2, 1)] + [InlineData(1, 3)] + public void NonOriginSingleAxisSpans_RespectDeclaredGrid(int rowSpan, int columnSpan) + { + ExtractionDocument document = new("single-axis"); + ExtractionDocumentSection section = new(null); + ExtractionDocumentTableElement table = new(null, 3, 4); + ExtractionDocumentTableCell empty = new(); + ExtractionDocumentTextElement text = new(new TextContent("A|<")); + ExtractionDocumentTableCell anchor = new(text, rowSpan, columnSpan); + table.Cells[0, 0] = empty; + table.Cells[1, 1] = anchor; + section.Elements.Add(table); + document.Sections.Add(section); + + Assert.Equal(3, table.Cells.RowCount); + Assert.Equal(4, table.Cells.ColumnCount); + Assert.Equal(1, anchor.RowIndex); + Assert.Equal(1, anchor.ColumnIndex); + Assert.Equal(rowSpan, anchor.RowSpan); + Assert.Equal(columnSpan, anchor.ColumnSpan); + Assert.Equal("A|<", Assert.IsType(text.Content).Text); + Assert.Null(anchor.Role); + Assert.Equal( + new ExtractionDocumentTableCell?[] { empty, null, null, null, null, anchor, null, null, null, null, null, null }, + table.Cells.ToArray()); + for (int row = 0; row < 3; row++) + { + for (int column = 0; column < 4; column++) + { + bool inSpan = row >= 1 && row < 1 + rowSpan && column >= 1 && column < 1 + columnSpan; + ExtractionDocumentTableCell? covering = inSpan ? anchor : null; + if (row == 0 && column == 0) + { + covering = empty; + } + + Assert.Same(covering, table.Cells.GetCoveringCell(row, column)); + Assert.Equal(inSpan && (row != 1 || column != 1), table.Cells.IsCovered(row, column)); + } + } + + Assert.Null(table.Content); + Assert.Same(table, Assert.Single(document.EnumerateContent())); + } + + [Fact] + public void EmptyCellSources_RemainDistinctFromMissingCells() + { + ExtractionDocument document = new("projection-loss", null); + ExtractionDocumentSection section = new(null); + ExtractionDocumentTableElement table = new(null, 1, 3); + ExtractionDocumentTableCell empty = new(); + ExtractionDocumentSourcePage frame = DocumentAnnotationTestData.PdfPage(); + document.SourcePages.Add(frame); + empty.Sources.Add(new ExtractionDocumentSourceReference(frame, DocumentAnnotationTestData.Polygon(), "NATIVE_ONLY")); + ExtractionDocumentTextElement text = new(new TextContent("INV0ICE 1O0?")); + table.Cells[0, 1] = empty; + table.Cells[0, 2] = new ExtractionDocumentTableCell(text); + section.Elements.Add(table); + document.Sections.Add(section); + + Assert.Null(table.Cells[0, 0]); + Assert.Null(table.Cells.GetCoveringCell(0, 0)); + Assert.False(table.Cells.IsCovered(0, 0)); + Assert.Same(empty, table.Cells.GetCoveringCell(0, 1)); + Assert.False(table.Cells.IsCovered(0, 1)); + Assert.Null(empty.Content); + Assert.Same(frame, Assert.Single(empty.Sources).Page); + Assert.Same(frame, Assert.Single(document.SourcePages)); + Assert.Equal(DocumentAnnotationTestData.Polygon(), empty.Sources[0].Polygon); + Assert.Equal("NATIVE_ONLY", empty.Sources[0].GetRawRepresentation()); + Assert.Equal("INV0ICE 1O0?", Assert.IsType(text.Content).Text); + Assert.Null(table.Content); + Assert.Null(document.Content); + + // Removing a cell does not remove its explicitly registered source frame. + table.Cells[0, 1] = null; + + Assert.Null(table.Cells[0, 1]); + Assert.Null(table.Cells.GetCoveringCell(0, 1)); + Assert.Same(frame, Assert.Single(document.SourcePages)); + } + + [Fact] + public void NoSuppliedCells_RetainSourceAndEmptyGrid() + { + string providerMarkdown = $"|A|B|{Environment.NewLine}|---|---|{Environment.NewLine}|1O0?|B|"; + ExtractionDocument document = new("unstructured-table"); + ExtractionDocumentSection section = new(null); + ExtractionDocumentTableElement table = new(null, 2, 2); + table.Sources.Add(new ExtractionDocumentSourceReference(new ExtractionDocumentSourcePage("provider-page", 1), rawRepresentation: providerMarkdown)); + section.Elements.Add(table); + document.Sections.Add(section); + + Assert.Equal(2, table.Cells.RowCount); + Assert.Equal(2, table.Cells.ColumnCount); + Assert.Equal(new ExtractionDocumentTableCell?[] { null, null, null, null }, table.Cells.ToArray()); + Assert.Null(table.Cells.GetCoveringCell(0, 0)); + Assert.False(table.Cells.IsCovered(0, 0)); + Assert.Same(table, Assert.Single(document.EnumerateContent())); + Assert.Null(table.Content); + Assert.Same(providerMarkdown, table.Sources[0].GetRawRepresentation()); + Assert.Null(document.Content); + Assert.Equal(new ExtractionDocumentTableCell?[] { null, null, null, null }, table.Cells.ToArray()); + } + + [Fact] + public void ExplicitEmptyCell_RetainsSourceAndGridPosition() + { + string providerMarkdown = $"|A|B|{Environment.NewLine}|---|---|{Environment.NewLine}|1O0?|B|"; + ExtractionDocument document = new("explicit-empty-table"); + ExtractionDocumentSection section = new(null); + ExtractionDocumentTableElement table = new(null, 2, 2); + table.Sources.Add(new ExtractionDocumentSourceReference(new ExtractionDocumentSourcePage("provider-page", 1), rawRepresentation: providerMarkdown)); + ExtractionDocumentTableCell empty = new(); + table.Cells[1, 1] = empty; + section.Elements.Add(table); + document.Sections.Add(section); + + Assert.Null(table.Content); + Assert.Same(providerMarkdown, table.Sources[0].GetRawRepresentation()); + Assert.Null(document.Content); + Assert.Equal(new ExtractionDocumentTableCell?[] { null, null, null, empty }, table.Cells.ToArray()); + Assert.Null(empty.Content); + Assert.Same(empty, table.Cells.GetCoveringCell(1, 1)); + Assert.False(table.Cells.IsCovered(1, 1)); + Assert.Null(table.Cells.GetCoveringCell(0, 0)); + } + + [Fact] + public void RemovingAllCells_RetainsSourceAndCurrentEmptyGrid() + { + string providerMarkdown = $"|A|B|{Environment.NewLine}|---|---|{Environment.NewLine}|1O0?|B|"; + ExtractionDocument document = new("cleared-table"); + ExtractionDocumentSection section = new(null); + ExtractionDocumentTableElement table = new(null, 2, 2); + table.Sources.Add(new ExtractionDocumentSourceReference(new ExtractionDocumentSourcePage("provider-page", 1), rawRepresentation: providerMarkdown)); + ExtractionDocumentTextElement text = new(new TextContent("mapped A")); + ExtractionDocumentTableCell populated = new(text); + ExtractionDocumentTableCell empty = new(); + table.Cells[0, 0] = populated; + table.Cells[1, 1] = empty; + section.Elements.Add(table); + document.Sections.Add(section); + + Assert.Null(table.Content); + Assert.Same(providerMarkdown, table.Sources[0].GetRawRepresentation()); + + table.Cells[0, 0] = null; + + Assert.Same(empty, table.Cells.GetCoveringCell(1, 1)); + table.Cells[1, 1] = null; + + Assert.Null(table.Content); + Assert.Null(document.Content); + Assert.Equal(new ExtractionDocumentTableCell?[] { null, null, null, null }, table.Cells.ToArray()); + Assert.Equal(2, table.Cells.RowCount); + Assert.Equal(2, table.Cells.ColumnCount); + Assert.Equal("mapped A", Assert.IsType(text.Content).Text); + Assert.Equal("mapped A", Assert.IsType(text.Content).Text); + Assert.Same(table, Assert.Single(document.EnumerateContent())); + for (int row = 0; row < 2; row++) + { + for (int column = 0; column < 2; column++) + { + Assert.Null(table.Cells.GetCoveringCell(row, column)); + Assert.False(table.Cells.IsCovered(row, column)); + } + } + } +} diff --git a/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentTests.Composition.cs b/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentTests.Composition.cs new file mode 100644 index 00000000000..a53865c56eb --- /dev/null +++ b/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentTests.Composition.cs @@ -0,0 +1,112 @@ +// Licensed to the .NET Foundation under one or more agreements. +// The .NET Foundation licenses this file to you under the MIT license. + +using System; +using Microsoft.Extensions.AI; +using Microsoft.Extensions.Documents; +using Xunit; + +namespace Microsoft.Extensions.Documents.Tests; + +public partial class DocumentTests +{ + [Theory] + [InlineData("section", false)] + [InlineData("section", true)] + [InlineData("text", false)] + [InlineData("text", true)] + [InlineData("image", false)] + [InlineData("image", true)] + [InlineData("table", false)] + [InlineData("table", true)] + [InlineData("empty-cell", false)] + [InlineData("empty-cell", true)] + [InlineData("cell-content", false)] + [InlineData("cell-content", true)] + public void Sources_EachOwnerRetainsAssociationsWithExplicitRegistration(string owner, bool attachFirst) + { + ExtractionDocument document = new("all-owners"); + ExtractionDocumentSection section = new(null); + ExtractionDocumentTableElement table = new(null, 1, 2); + ExtractionDocumentTableCell empty = new(); + ExtractionDocumentTextElement cellText = new(new TextContent("cell")); + table.Cells[0, 0] = empty; + table.Cells[0, 1] = new ExtractionDocumentTableCell(cellText); + ExtractionDocumentElement element = owner switch + { + "text" => new ExtractionDocumentTextElement(new TextContent("visible")), + "image" => new ExtractionDocumentImageElement(new TextContent("visible")), + _ => table + }; + section.Elements.Add(element); + var sources = owner switch + { + "section" => section.Sources, + "empty-cell" => empty.Sources, + "cell-content" => cellText.Sources, + _ => element.Sources + }; + if (attachFirst) + { + document.Sections.Add(section); + } + + using DocumentAnnotationTestData.CountingStream stream = new(new byte[] { 31, 32 }); + using DocumentAnnotationTestData.BorrowedNative native = new(); + document.RawRepresentation = native; + ExtractionDocumentSourcePage page = new("frame", 4); + ExtractionDocumentSourceReference reference = new(page, rawRepresentation: native); + sources.Add(reference); + if (!attachFirst) + { + Assert.Empty(document.SourcePages); + document.Sections.Add(section); + } + + Assert.Empty(document.SourcePages); + document.SourcePages.Add(page); + Assert.Same(reference, Assert.Single(sources)); + Assert.Same(page, Assert.Single(document.SourcePages)); + Assert.Equal(new byte[] { 31, 32 }, stream.ToArray()); + sources.Clear(); + Assert.Same(page, Assert.Single(document.SourcePages)); + Assert.Equal(0, stream.DisposeCount); + stream.Dispose(); + Assert.Same(native, reference.GetRawRepresentation()); + Assert.Same(native, document.RawRepresentation); + Assert.Equal(0, native.DisposeCount); + } + + [Fact] + public void ApplicationOnlyComposition_PreservesNestedContentWithoutSources() + { + ExtractionDocument document = new("application", null); + ExtractionDocumentSection section = new(null); + ExtractionDocumentSection nested = new(null); + ExtractionDocumentTextElement text = new(new TextContent("**local**")); + ExtractionDocumentImageElement image = new(new TextContent("")) { Source = new Uri("urn:local:image"), AlternativeText = "local diagram" }; + ExtractionDocumentTextElement extension = new(new TextContent("extension"), role: "application-extra"); + ExtractionDocumentTableElement table = new(null, 1, 2); + ExtractionDocumentTextElement cellText = new(new TextContent("cell|value")); + table.Cells[0, 0] = new ExtractionDocumentTableCell(cellText); + table.Cells[0, 1] = new ExtractionDocumentTableCell(); + image.Content = new DataContent(new byte[] { 7, 8 }, "image/png"); + nested.Elements.Add(text); + nested.Elements.Add(table); + section.Elements.Add(nested); + section.Elements.Add(image); + section.Elements.Add(extension); + document.Sections.Add(section); + + Assert.Null(document.Content); + Assert.Equal("**local**", Assert.IsType(text.Content).Text); + Assert.Equal("cell|value", Assert.IsType(cellText.Content).Text); + Assert.Equal("application-extra", extension.Role); + Assert.Equal(new byte[] { 7, 8 }, Assert.IsType(image.Content).Data.ToArray()); + Assert.Equal(new ExtractionDocumentElement[] { text, table, image, extension }, document.EnumerateContent()); + Assert.All(new ExtractionDocumentElement[] { section, nested, text, table, cellText, image, extension }, element => Assert.Empty(element.Sources)); + Assert.All(table.Cells, cell => Assert.Empty(cell!.Sources)); + Assert.Empty(document.SourcePages); + Assert.Equal(new byte[] { 7, 8 }, Assert.IsType(image.Content).Data.ToArray()); + } +} diff --git a/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentTests.StandardContent.cs b/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentTests.StandardContent.cs new file mode 100644 index 00000000000..5f6431e4272 --- /dev/null +++ b/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentTests.StandardContent.cs @@ -0,0 +1,459 @@ +// Licensed to the .NET Foundation under one or more agreements. +// The .NET Foundation licenses this file to you under the MIT license. + +using System; +using System.Linq; +using System.Runtime.InteropServices; +using System.Text.Json; +using Microsoft.Extensions.AI; +using Microsoft.Extensions.Documents; +using Xunit; + +namespace Microsoft.Extensions.Documents.Tests; + +public partial class DocumentTests +{ + [Fact] + public void RootOnlyPayload_ReusesCurrentStringWithoutFormatting() + { + string markdown = new('x', 4096); + TextContent payload = new(markdown); + ExtractionDocument document = new("root-only", payload); + + Assert.Same(payload, document.Content); + Assert.Same(markdown, Assert.IsType(document.Content).Text); + payload.Text = "**changed**"; + Assert.Equal("**changed**", Assert.IsType(document.Content).Text); + document.Content = null; + Assert.Null(document.Content); + Assert.Empty(document.EnumerateContent()); + } + + [Fact] + public void LeafSectionPayload_RemainsLocalAndNullable() + { + string markdown = new('x', 4096); + ExtractionDocumentSection section = new(new TextContent(markdown)); + + Assert.Same(markdown, Assert.IsType(section.Content).Text); + Assert.Empty(section.Elements); + section.Content = null; + Assert.Null(section.Content); + } + + [Fact] + public void TransparentContainers_PreserveSingleDescendantAndPayloadIdentity() + { + string markdown = new('x', 4096); + TextContent payload = new(markdown); + ExtractionDocumentTextElement text = new(payload); + ExtractionDocumentSection inner = new(); + ExtractionDocumentSection outer = new(); + inner.Elements.Add(text); + outer.Elements.Add(inner); + ExtractionDocument document = new("transparent"); + document.Sections.Add(outer); + + Assert.Null(document.Content); + Assert.Null(outer.Content); + Assert.Null(inner.Content); + Assert.Same(inner, Assert.Single(outer.Elements)); + Assert.Same(text, Assert.Single(inner.Elements)); + Assert.Same(text, Assert.Single(document.EnumerateContent())); + Assert.Same(payload, text.Content); + Assert.Same(markdown, payload.Text); + payload.Text = "updated"; + Assert.Equal("updated", Assert.IsType(text.Content).Text); + } + + [Fact] + public void FlatTextPayloads_PreserveEmptyEntriesAndObserveEdits() + { + TextContent first = new("**first**"); + ExtractionDocumentSection section = new(); + section.Elements.Add(new ExtractionDocumentTextElement(first)); + section.Elements.Add(new ExtractionDocumentTextElement(new TextContent(string.Empty))); + section.Elements.Add(new ExtractionDocumentTextElement(new TextContent("last|value"))); + ExtractionDocument document = new("flat"); + document.Sections.Add(section); + + Assert.Equal(new[] { "**first**", "", "last|value" }, + document.EnumerateContent().Select(element => Assert.IsType(element.Content).Text)); + first.Text = "changed"; + Assert.Equal(new[] { "changed", "", "last|value" }, + document.EnumerateContent().Select(element => Assert.IsType(element.Content).Text)); + } + + [Fact] + public void EmptyLocalPayloads_AreDistinctFromAbsentPayloads() + { + ExtractionDocument document = new("empty-local", new TextContent(string.Empty)); + ExtractionDocumentSection section = new(new TextContent(string.Empty)); + section.Elements.Add(new ExtractionDocumentTextElement(new TextContent("child"))); + document.Sections.Add(section); + + Assert.Equal("", Assert.IsType(document.Content).Text); + Assert.Equal("", Assert.IsType(section.Content).Text); + document.Content = null; + Assert.Null(document.Content); + Assert.Equal("", Assert.IsType(section.Content).Text); + section.Content = null; + Assert.Null(section.Content); + Assert.Equal("child", Assert.IsType(Assert.Single(document.EnumerateContent()).Content).Text); + } + + [Fact] + public void CurrentPayloadKind_RemainsVisibleWithoutImplicitConversion() + { + ExtractionDocumentSection section = new(); + section.Elements.Add(new ExtractionDocumentTextElement(new TextContent("first"))); + section.Elements.Add(new CustomElement(new AIContent())); + ExtractionDocument document = new("unsupported-flat"); + document.Sections.Add(section); + + Assert.Equal(section.Elements, document.EnumerateContent()); + Assert.IsType(section.Elements[1].Content); + Assert.Equal("first", Assert.IsType(section.Elements[0].Content).Text); + } + + [Fact] + public void CustomElements_PreserveLocalPayloadAndGridIdentity() + { + CustomElement custom = new(new TextContent("custom|value")); + ExtractionDocumentSection section = new(); + section.Elements.Add(custom); + ExtractionDocument document = new("custom-projection"); + document.Sections.Add(section); + + Assert.Same(custom, Assert.Single(document.EnumerateContent())); + Assert.Equal("custom|value", Assert.IsType(custom.Content).Text); + section.Elements.Insert(0, new ExtractionDocumentTextElement(new TextContent("prefix"))); + Assert.Equal(section.Elements, document.EnumerateContent()); + + CustomElement cellContent = new(new TextContent("cell|value")); + ExtractionDocumentTableElement table = new(null, 1, 1); + table.Cells[0, 0] = new ExtractionDocumentTableCell(cellContent); + section.Elements.Add(table); + Assert.Equal(section.Elements, document.EnumerateContent()); + Assert.Same(cellContent, table.Cells[0, 0]!.Content); + Assert.Equal("cell|value", Assert.IsType(cellContent.Content).Text); + } + + [Fact] + public void StandardTextContent_PreservesSharedAuthoritativeStringPayload() + { + string markdown = new(['*', '*', 'O', 'C', 'R', '*', '*']); + TextContent payload = new(markdown); + ExtractionDocument document = new("shared-text", payload); + ExtractionDocumentSection section = new(payload); + ExtractionDocumentTextElement text = new(payload, role: "heading") { HeadingLevel = 2 }; + section.Elements.Add(text); + document.Sections.Add(section); + + Assert.Same(payload, document.Content); + Assert.Same(payload, section.Content); + Assert.Same(payload, text.Content); + Assert.Same(markdown, payload.Text); + Assert.Equal("**OCR**", Assert.IsType(text.Content).Text); + Assert.Equal("heading", text.Role); + Assert.Equal(2, text.HeadingLevel); + } + + [Fact] + public void NullableContainers_KeepLocalContentSeparateFromDescendants() + { + ExtractionDocument document = new("local", new TextContent("root introduction")); + ExtractionDocumentSection section = new(new TextContent("section introduction")); + ExtractionDocumentSection transparent = new(); + ExtractionDocumentTableElement table = new(new TextContent("table caption"), 1, 1); + ExtractionDocumentTextElement cellText = new(new TextContent("leaf|value")); + table.Cells[0, 0] = new ExtractionDocumentTableCell(cellText); + transparent.Elements.Add(table); + section.Elements.Add(transparent); + document.Sections.Add(section); + + Assert.Equal("root introduction", Assert.IsType(document.Content).Text); + Assert.Equal("section introduction", Assert.IsType(section.Content).Text); + Assert.Null(transparent.Content); + Assert.Same(table, Assert.Single(document.EnumerateContent())); + Assert.Same(cellText, table.Cells[0, 0]!.Content); + Assert.Equal("leaf|value", Assert.IsType(cellText.Content).Text); + + cellText.Content = new TextContent("edited"); + Assert.Equal("edited", Assert.IsType(table.Cells[0, 0]!.Content!.Content).Text); + Assert.Equal("edited", Assert.IsType(cellText.Content).Text); + Assert.Equal("table caption", Assert.IsType(table.Content).Text); + } + + [Fact] + public void NullPayloads_AreAbsentRatherThanFabricatedText() + { + ExtractionDocument document = new("empty"); + ExtractionDocumentSection section = new(); + ExtractionDocumentImageElement image = new(); + section.Elements.Add(image); + document.Sections.Add(section); + + Assert.Null(document.Content); + Assert.Null(section.Content); + Assert.Null(image.Content); + Assert.Null(image.Text); + Assert.Null(image.AlternativeText); + Assert.Same(image, Assert.Single(document.EnumerateContent())); + } + + [Theory] + [InlineData("root", false)] + [InlineData("root", true)] + [InlineData("section", false)] + [InlineData("section", true)] + [InlineData("table", false)] + [InlineData("table", true)] + public void StructuralLocalImagePayloads_RemainIndependentOfChildren(string owner, bool uri) + { + AIContent payload = uri ? new UriContent("urn:local:image", "image/png") : + new DataContent(new byte[] { 1, 2, 3 }, "image/png"); + ExtractionDocument document = new("local-image", owner == "root" ? payload : null); + ExtractionDocumentSection section = new(owner == "section" ? payload : null); + ExtractionDocumentTableElement table = new(owner == "table" ? payload : null, 1, 1); + ExtractionDocumentTextElement text = new(new TextContent("cell")); + table.Cells[0, 0] = new ExtractionDocumentTableCell(text); + section.Elements.Add(table); + document.Sections.Add(section); + AIContent? selected = owner switch + { + "root" => document.Content, + "section" => section.Content, + _ => table.Content + }; + Assert.Same(payload, selected); + Assert.Same(text, table.Cells[0, 0]!.Content); + } + + [Fact] + public void BorrowedPayloadMutation_IsAuthoritativeAndVisible() + { + TextContent payload = new("first"); + ExtractionDocument document = new("mutable"); + ExtractionDocumentSection section = new(); + ExtractionDocumentTextElement text = new(payload); + section.Elements.Add(text); + document.Sections.Add(section); + + payload.Text = "second"; + + Assert.Equal("second", Assert.IsType(text.Content).Text); + Assert.Same(payload, text.Content); + text.Content = new TextContent("second"); + Assert.NotSame(payload, text.Content); + Assert.Equal("second", Assert.IsType(text.Content).Text); + } + + [Fact] + public void OwnedDataBuffer_IsBorrowedByActualImageWithoutCopy() + { + byte[] owned = [1, 2, 3]; + DataContent payload = new(owned, "image/png"); + ExtractionDocumentImageElement image = new(payload, "OCR diagram") { AlternativeText = "diagram" }; + + Assert.Same(payload, image.Content); + Assert.True(MemoryMarshal.TryGetArray(payload.Data, out ArraySegment segment)); + Assert.Same(owned, segment.Array); + Assert.Equal(0, segment.Offset); + Assert.Equal(3, segment.Count); + Assert.Equal(new byte[] { 1, 2, 3 }, payload.Data.ToArray()); + Assert.Equal("OCR diagram", image.Text); + } + + [Fact] + public void MutableProviderBuffer_RequiresExplicitCopyAtOwnershipBoundary() + { + byte[] providerBuffer = [1, 2, 3]; + ExtractionDocumentImageElement borrowed = new(new DataContent(providerBuffer, "image/png")); + + // The adapter, not ExtractionDocument or DataContent, owns the decision to retain a stable copy. + byte[] retained = providerBuffer.ToArray(); + ExtractionDocumentImageElement retainedImage = new(new DataContent(retained, "image/png")); + providerBuffer[0] = 9; + + DataContent borrowedPayload = Assert.IsType(borrowed.Content); + DataContent retainedPayload = Assert.IsType(retainedImage.Content); + Assert.Equal(new byte[] { 9, 2, 3 }, borrowedPayload.Data.ToArray()); + Assert.Equal(new byte[] { 1, 2, 3 }, retainedPayload.Data.ToArray()); + Assert.True(MemoryMarshal.TryGetArray(retainedPayload.Data, out ArraySegment segment)); + Assert.Same(retained, segment.Array); + Assert.NotSame(providerBuffer, segment.Array); + } + + [Theory] + [InlineData(false, false)] + [InlineData(false, true)] + [InlineData(true, false)] + [InlineData(true, true)] + public void StandardImagePayloads_KeepCanonicalReferenceAndProvenanceIndependent(bool data, bool provenance) + { + AIContent payload = data ? new DataContent(new byte[] { 1, 2, 3 }, "image/png") : + new UriContent(new Uri("urn:canonical:image"), "image/png"); + Uri? source = provenance ? new Uri("urn:provenance:image") : null; + ExtractionDocumentImageElement image = new(payload, "OCR text") + { + Source = source, + AlternativeText = "independent alternative" + }; + Assert.Same(payload, image.Content); + Assert.Same(source, image.Source); + Assert.Equal("OCR text", image.Text); + Assert.Equal("independent alternative", image.AlternativeText); + if (payload is UriContent uri) + { + Assert.Equal("urn:canonical:image", uri.Uri.ToString()); + Assert.Equal("image/png", uri.MediaType); + } + else + { + Assert.Equal(new byte[] { 1, 2, 3 }, Assert.IsType(payload).Data.ToArray()); + Assert.Equal("image/png", Assert.IsType(payload).MediaType); + } + } + + [Theory] + [InlineData("root")] + [InlineData("section")] + [InlineData("table")] + [InlineData("custom")] + [InlineData("image")] + public void ArbitraryStandardPayload_RemainsInspectableAtEachOwner(string owner) + { + AIContent payload = new(); + ExtractionDocument document = new("unsupported", owner == "root" ? payload : null); + ExtractionDocumentElement element = owner switch + { + "section" => new ExtractionDocumentSection(payload), + "table" => new ExtractionDocumentTableElement(payload, 1, 1), + "image" => new ExtractionDocumentImageElement(payload) { Source = new Uri("urn:must-not-mask-unsupported") }, + _ => new CustomElement(payload) + }; + if (owner != "root") + { + ExtractionDocumentSection section = new(); + section.Elements.Add(element); + document.Sections.Add(section); + Assert.Same(element, Assert.Single(section.Elements)); + if (element is ExtractionDocumentSection) + { + Assert.Empty(document.EnumerateContent()); + } + else + { + Assert.Same(element, Assert.Single(document.EnumerateContent())); + } + } + + Assert.Same(payload, owner == "root" ? document.Content : element.Content); + } + + [Theory] + [InlineData(false, false)] + [InlineData(false, true)] + [InlineData(true, false)] + [InlineData(true, true)] + public void NonImageDataAndUri_AreNotConvertedToText(bool uri, bool onImage) + { + AIContent payload = uri ? new UriContent("urn:raw:body", "application/json") : + new DataContent(new byte[] { 123, 125 }, "application/json"); + ExtractionDocument document = new("raw", onImage ? null : payload); + ExtractionDocumentImageElement image = new(payload, "semantic OCR") + { + Source = new Uri("urn:provenance:must-not-hide-invalid-type"), + AlternativeText = "raw is not an image" + }; + if (onImage) + { + ExtractionDocumentSection section = new(); + section.Elements.Add(image); + document.Sections.Add(section); + Assert.Same(image, Assert.Single(document.EnumerateContent())); + } + + Assert.Equal("semantic OCR", image.Text); + Assert.Same(payload, image.Content); + Assert.Same(payload, onImage ? image.Content : document.Content); + Assert.Equal("application/json", uri ? Assert.IsType(payload).MediaType : Assert.IsType(payload).MediaType); + } + + [Fact] + public void RealTableAndSourceMultiplicity_PreserveSharedPayloadAndDistinctElements() + { + ExtractionDocument document = new("table-identity"); + ExtractionDocumentSection section = new(); + ExtractionDocumentTableElement table = new(null, 1, 2); + TextContent shared = new("same|payload"); + ExtractionDocumentTextElement first = new(shared); + ExtractionDocumentTextElement second = new(shared); + ExtractionDocumentSourcePage page = new("page", 1); + document.SourcePages.Add(page); + ExtractionDocumentSourceReference reference = new(page); + first.Sources.Add(reference); + first.Sources.Add(reference); + second.Sources.Add(reference); + table.Sources.Add(reference); + ExtractionDocumentTableCell firstCell = new(first); + firstCell.Sources.Add(reference); + table.Cells[0, 0] = firstCell; + table.Cells[0, 1] = new ExtractionDocumentTableCell(second); + section.Elements.Add(table); + document.Sections.Add(section); + + Assert.Same(firstCell, table.Cells[0, 0]); + Assert.Same(first, table.Cells[0, 0]!.Content); + Assert.Same(second, table.Cells[0, 1]!.Content); + Assert.NotSame(first, second); + Assert.Same(shared, first.Content); + Assert.Same(shared, second.Content); + Assert.Equal(new[] { reference, reference }, first.Sources); + Assert.Same(reference, Assert.Single(firstCell.Sources)); + Assert.Same(reference, Assert.Single(table.Sources)); + Assert.Same(page, Assert.Single(document.SourcePages)); + shared.Text = "changed"; + Assert.Equal("changed", Assert.IsType(first.Content).Text); + Assert.Equal("changed", Assert.IsType(second.Content).Text); + } + + [Fact] + public void ActualMeaiSerializationAndTextSelection_ConsumeDocumentPayloadsWithoutDocumentWireContract() + { + ExtractionDocumentTextElement text = new(new TextContent("**literal markdown**")); + ExtractionDocumentImageElement image = new(new DataContent(new byte[] { 1, 2, 3 }, "image/png"), "diagram OCR") + { + AlternativeText = "diagram alternative", + Source = new Uri("urn:provenance") + }; + UriContent uriPayload = new("urn:canonical:image", "image/jpeg"); + ExtractionDocumentImageElement reference = new(uriPayload); + ChatMessage message = new(ChatRole.User, [text.Content!, image.Content!, reference.Content!]); + + string json = JsonSerializer.Serialize(message, AIJsonUtilities.DefaultOptions); + using JsonDocument wire = JsonDocument.Parse(json); + JsonElement contents = wire.RootElement.GetProperty("contents"); + Assert.Equal(3, contents.GetArrayLength()); + Assert.Equal("text", contents[0].GetProperty("$type").GetString()); + Assert.Equal("**literal markdown**", contents[0].GetProperty("text").GetString()); + Assert.Equal("data:image/png;base64,AQID", contents[1].GetProperty("uri").GetString()); + Assert.Equal("urn:canonical:image", contents[2].GetProperty("uri").GetString()); + Assert.Equal("image/jpeg", contents[2].GetProperty("mediaType").GetString()); + Assert.Equal("**literal markdown**", message.Text); + Assert.Same(image.Content, message.Contents[1]); + Assert.Same(uriPayload, message.Contents[2]); + + // Image OCR is independently selected; text payloads need no alternate plain-text view. + ChatMessage semantic = new(ChatRole.User, [text.Content!, new TextContent(image.Text!)]); + Assert.Equal("**literal markdown**diagram OCR", semantic.Text); + Assert.DoesNotContain("AQID", semantic.Text, StringComparison.Ordinal); + Assert.DoesNotContain("urn:", semantic.Text, StringComparison.Ordinal); + Assert.DoesNotContain("diagram alternative", semantic.Text, StringComparison.Ordinal); + Assert.Equal("diagram alternative", image.AlternativeText); + Assert.Equal("urn:provenance", image.Source!.ToString()); + } + + private sealed class CustomElement(AIContent? content) : ExtractionDocumentElement(content); +} diff --git a/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentTests.cs b/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentTests.cs new file mode 100644 index 00000000000..e69c6a7ecaa --- /dev/null +++ b/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentTests.cs @@ -0,0 +1,249 @@ +// Licensed to the .NET Foundation under one or more agreements. +// The .NET Foundation licenses this file to you under the MIT license. + +using System; +using System.IO; +using System.Linq; +using Microsoft.Extensions.AI; +using Microsoft.Extensions.Documents; +using Xunit; + +namespace Microsoft.Extensions.Documents.Tests; + +public partial class DocumentTests +{ + [Fact] + public void StoresIdentifierAndInitialState() + { + ExtractionDocument document = new("document-id", new TextContent("stored document")); + + Assert.Equal("document-id", document.Identifier); + Assert.Equal("stored document", Assert.IsType(document.Content).Text); + Assert.Empty(document.Sections); + } + + [Theory] + [InlineData(null)] + [InlineData("")] + public void RejectsNullOrEmptyIdentifier(string? identifier) + { + Assert.ThrowsAny(() => new ExtractionDocument(identifier!)); + } + + [Fact] + public void LocalTextPayload_RetainsExactSuppliedValue() + { + ExtractionDocument document = new("document", new TextContent("stored markdown")); + + Assert.Equal("stored markdown", Assert.IsType(document.Content).Text); + } + + [Theory] + [InlineData(null)] + [InlineData("")] + public void NullableRootPayload_PreservesMissingVersusEmptyText(string? markdown) + { + ExtractionDocument document = new("document", markdown is null ? null : new TextContent(markdown)); + + Assert.Equal(markdown, (document.Content as TextContent)?.Text); + } + + [Fact] + public void Sections_RetainImagePayloadWithoutStoredAncestorAggregate() + { + ExtractionDocument document = new("document", null); + ExtractionDocumentSection section = new(null); + section.Elements.Add(new ExtractionDocumentImageElement(new TextContent("stored image markdown")) + { + Source = new Uri("urn:image:semantic"), + AlternativeText = "semantic image" + }); + + document.Sections.Add(section); + + Assert.Null(document.Content); + ExtractionDocumentImageElement image = Assert.IsType(Assert.Single(document.EnumerateContent())); + Assert.Equal("stored image markdown", Assert.IsType(image.Content).Text); + Assert.Equal("urn:image:semantic", image.Source!.ToString()); + Assert.Equal("semantic image", image.AlternativeText); + } + + [Fact] + public void MultipleSections_PreserveContentOrderWithoutJoiningPayloads() + { + ExtractionDocument document = new("document", null); + ExtractionDocumentSection first = new(null); + ExtractionDocumentSection second = new(null); + first.Elements.Add(new ExtractionDocumentTextElement(new TextContent("first semantic"))); + second.Elements.Add(new ExtractionDocumentTextElement(new TextContent("second semantic"))); + document.Sections.Add(first); + document.Sections.Add(second); + + Assert.Equal(new[] { first, second }, document.Sections); + Assert.Equal(new[] { "first semantic", "second semantic" }, + document.EnumerateContent().Select(element => Assert.IsType(element.Content).Text)); + } + + [Fact] + public void Content_SameReferencePreservesPayload() + { + ExtractionDocument document = new("document", new TextContent("stored markdown")); + AIContent? payload = document.Content; + + document.Content = payload; + + Assert.Same(payload, document.Content); + } + + [Fact] + public void Content_ChangedReferenceUpdatesPayload() + { + ExtractionDocument document = new("document", new TextContent("stored markdown")); + Assert.Equal("stored markdown", Assert.IsType(document.Content).Text); + document.Content = new TextContent("updated markdown"); + + Assert.Equal("updated markdown", Assert.IsType(document.Content).Text); + } + + [Fact] + public void EnumerateContent_ReturnsOrdinaryAndNestedElementsInDepthFirstOrder() + { + ExtractionDocument document = new("document"); + ExtractionDocumentSection first = new(null); + ExtractionDocumentTextElement firstText = new(new TextContent("first text")); + ExtractionDocumentSection nested = new(null); + ExtractionDocumentTextElement nestedText = new(new TextContent("nested text")); + ExtractionDocumentImageElement image = new(new TextContent("image")); + ExtractionDocumentTextElement extension = new(new TextContent("extension"), role: "application-extra"); + ExtractionDocumentTableElement table = new(null, 1, 1); + ExtractionDocumentSection second = new(null); + ExtractionDocumentTextElement secondText = new(new TextContent("second text")); + + nested.Elements.Add(nestedText); + first.Elements.Add(firstText); + first.Elements.Add(nested); + first.Elements.Add(image); + first.Elements.Add(extension); + first.Elements.Add(table); + second.Elements.Add(secondText); + document.Sections.Add(first); + document.Sections.Add(second); + + ExtractionDocumentElement[] content = document.EnumerateContent().ToArray(); + + Assert.Equal( + new ExtractionDocumentElement[] { firstText, nestedText, image, extension, table, secondText }, + content); + } + + [Fact] + public void EnumerateContent_DoesNotReturnSectionNodes() + { + ExtractionDocument document = new("document"); + ExtractionDocumentSection root = new(null); + ExtractionDocumentSection nested = new(null); + root.Elements.Add(nested); + nested.Elements.Add(new ExtractionDocumentTextElement(new TextContent("content"))); + document.Sections.Add(root); + + ExtractionDocumentElement[] content = document.EnumerateContent().ToArray(); + + Assert.NotEmpty(content); + Assert.All(content, element => Assert.False(element is ExtractionDocumentSection)); + } + + [Fact] + public void DocumentTraversal_PreservesOriginIdentityAcrossHierarchyChanges() + { + ExtractionDocument document = new("origin"); + ExtractionDocumentSourcePage page7 = DocumentAnnotationTestData.PdfPage(); + ExtractionDocumentSourcePage page2 = new("urn:frame:page2", 2); + ExtractionDocumentTextElement text7 = new(new TextContent("same text")); + ExtractionDocumentTextElement text2 = new(new TextContent("same text")); + ExtractionDocumentSourceReference region = new(page7, DocumentAnnotationTestData.Polygon()); + text7.Sources.Add(region); + text2.Sources.Add(new ExtractionDocumentSourceReference(page2, DocumentAnnotationTestData.Polygon())); + ExtractionDocumentSection first = new(null); + ExtractionDocumentSection second = new(null); + first.Elements.Add(text7); + second.Elements.Add(text2); + document.Sections.Add(first); + document.Sections.Add(second); + document.SourcePages.Add(page7); + document.SourcePages.Add(page2); + Assert.Equal(new[] { page7, page2 }, document.SourcePages); + + first.Elements.Remove(text7); + second.Elements.Insert(0, text7); + + Assert.Equal(new[] { text7, text2 }, document.EnumerateContent()); + Assert.Equal(new int?[] { 7, 2 }, document.SourcePages.Select(page => page.PageNumber)); + Assert.Same(page7, text7.Sources[0].Page); + Assert.Equal("urn:frame:pdf-A", region.Page.Identifier); + Assert.Equal(DocumentAnnotationTestData.Polygon(), region.Polygon); + } + + [Fact] + public void BlankPage_PreservesSourceFrameWithoutFabricatedSemanticContent() + { + ExtractionDocument document = new("blank"); + ExtractionDocumentSourcePage page = new("urn:frame:blank-page2", 2, new ExtractionDocumentPageDimensions(200, 100), + ExtractionDocumentCoordinateUnit.Point, ExtractionDocumentCoordinateOrigin.BottomLeft); + document.SourcePages.Add(page); + document.Sections.Add(new ExtractionDocumentSection()); + + Assert.Null(document.Content); + Assert.Empty(document.EnumerateContent()); + Assert.Same(page, Assert.Single(document.SourcePages)); + Assert.Equal(2, page.PageNumber); + Assert.Equal("urn:frame:blank-page2", page.Identifier); + Assert.Equal(new ExtractionDocumentPageDimensions(200, 100), page.Dimensions); + Assert.Equal(ExtractionDocumentCoordinateUnit.Point, page.CoordinateUnit); + Assert.Equal(ExtractionDocumentCoordinateOrigin.BottomLeft, page.CoordinateOrigin); + } + + [Fact] + public void DocumentNativeResult_PageInventoryPreservesDuplicatesWithoutSemanticLeakage() + { + ExtractionDocument document = new("shared-body", new TextContent("visible")); + using DocumentAnnotationTestData.CountingStream stream = new(DocumentAnnotationTestData.OriginalBytes()); + using DocumentAnnotationTestData.BorrowedNative native = new(); + document.RawRepresentation = native; + ExtractionDocumentSourcePage page7 = DocumentAnnotationTestData.PdfPage(); + ExtractionDocumentSourcePage page2 = new("frame-2", 2); + document.SourcePages.Add(page7); + document.SourcePages.Add(page2); + document.SourcePages.Add(page7); + + Assert.Equal(new[] { page7, page2, page7 }, document.SourcePages); + Assert.Same(native, document.RawRepresentation); + Assert.Equal(DocumentAnnotationTestData.OriginalBytes(), stream.ToArray()); + Assert.Equal("visible", Assert.IsType(document.Content).Text); + Assert.Empty(document.EnumerateContent()); + Assert.Equal(0, stream.DisposeCount); + Assert.Equal(0, native.DisposeCount); + } + + [Fact] + public void DocumentMetadataAndSources_AreConsumableWithoutExtractionResult() + { + ExtractionDocument document = new("shared-annotations"); + ExtractionDocumentSection section = new(null); + ExtractionDocumentTextElement text = new(new TextContent("visible **text**")); + section.Elements.Add(text); + document.Sections.Add(section); + var payload = new { target = text, nested = new { unknown = new object[] { 3, "x" } }, vendorFlag = "kept" }; + ExtractionDocumentSourcePage page = DocumentAnnotationTestData.PdfPage(); + document.SourcePages.Add(page); + document.Metadata["vendor-extra"] = payload; + text.Sources.Add(new ExtractionDocumentSourceReference(page, DocumentAnnotationTestData.Polygon())); + + Assert.Same(payload, document.Metadata["vendor-extra"]); + Assert.Same(text, payload.target); + Assert.Equal(new object[] { 3, "x" }, payload.nested.unknown); + Assert.Equal("kept", payload.vendorFlag); + Assert.Same(page, Assert.Single(document.SourcePages)); + Assert.Same(text, Assert.Single(document.EnumerateContent())); + Assert.Equal("visible **text**", Assert.IsType(text.Content).Text); + } +} diff --git a/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentTextElementTests.cs b/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentTextElementTests.cs new file mode 100644 index 00000000000..624b8f0d16d --- /dev/null +++ b/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/DocumentTextElementTests.cs @@ -0,0 +1,132 @@ +// Licensed to the .NET Foundation under one or more agreements. +// The .NET Foundation licenses this file to you under the MIT license. + +using System; +using Microsoft.Extensions.AI; +using Microsoft.Extensions.Documents; +using Xunit; + +namespace Microsoft.Extensions.Documents.Tests; + +public class DocumentTextElementTests +{ + [Fact] + public void StoresRoleAndAuthoritativePayload() + { + ExtractionDocumentTextElement element = new(new TextContent("stored markdown"), role: "pageFooter"); + + Assert.Equal("pageFooter", element.Role); + Assert.Equal("stored markdown", Assert.IsType(element.Content).Text); + } + + [Theory] + [InlineData(null)] + [InlineData("heading")] + [InlineData("pageHeader")] + [InlineData("pageFooter")] + [InlineData("vendor:caption")] + [InlineData("HeAdInG")] + [InlineData(" Custom Role ")] + public void Role_NullKnownAndCustomValuesPreserveTextSourcesAndPayload(string? role) + { + ExtractionDocument document = new("role", null); + ExtractionDocumentSection section = new(null); + ExtractionDocumentTextElement element = new(new TextContent("**citation** [1]"), role: role); + ExtractionDocumentSourcePage page = new("citation-page", 7); + document.SourcePages.Add(page); + ExtractionDocumentSourceReference citation = new(page, DocumentAnnotationTestData.Polygon()); + element.Sources.Add(citation); + section.Elements.Add(element); + document.Sections.Add(section); + + Assert.Equal(role, element.Role); + Assert.Null(element.HeadingLevel); + Assert.Equal("**citation** [1]", Assert.IsType(element.Content).Text); + Assert.Null(document.Content); + Assert.Same(citation, Assert.Single(element.Sources)); + Assert.Same(page, Assert.Single(document.SourcePages)); + Assert.Equal(DocumentAnnotationTestData.Polygon(), citation.Polygon); + } + + [Theory] + [InlineData("")] + [InlineData(" ")] + [InlineData("\t\r\n")] + public void Role_EmptyOrWhitespaceRejected(string role) + { + Assert.Throws(nameof(role), () => new ExtractionDocumentTextElement(new TextContent("markdown"), role: role)); + } + + [Fact] + public void HeadingAndPageHeader_AreDistinguishedByRoleWithoutChangingPayload() + { + ExtractionDocumentTextElement heading = new(new TextContent("Title"), role: "heading") { HeadingLevel = 1 }; + ExtractionDocumentTextElement pageHeader = new(new TextContent("Title"), role: "pageHeader"); + ExtractionDocumentTextElement custom = new(new TextContent("ordinary **text**"), role: "VendorHeading") { HeadingLevel = 10 }; + + Assert.Equal("heading", heading.Role); + Assert.Equal("pageHeader", pageHeader.Role); + Assert.NotEqual(heading.Role, pageHeader.Role); + Assert.Equal(1, heading.HeadingLevel); + Assert.Null(pageHeader.HeadingLevel); + Assert.Equal("VendorHeading", custom.Role); + Assert.Equal(10, custom.HeadingLevel); + } + + [Theory] + [InlineData(1)] + [InlineData(2)] + [InlineData(3)] + [InlineData(4)] + [InlineData(5)] + [InlineData(6)] + [InlineData(7)] + [InlineData(8)] + [InlineData(9)] + [InlineData(10)] + [InlineData(11)] + [InlineData(int.MaxValue)] + public void HeadingLevel_AcceptsPositiveValues(int level) + { + ExtractionDocumentTextElement element = new(new TextContent("header"), role: "heading") + { + HeadingLevel = level + }; + + Assert.Equal(level, element.HeadingLevel); + } + + [Theory] + [InlineData(0)] + [InlineData(-1)] + [InlineData(int.MinValue)] + public void HeadingLevel_RejectsNonpositiveValues(int level) + { + ExtractionDocumentTextElement element = new(new TextContent("header"), role: "heading") + { + HeadingLevel = 5 + }; + + Assert.Throws("value", () => element.HeadingLevel = level); + Assert.Equal(5, element.HeadingLevel); + } + + [Fact] + public void HeadingLevel_SameValuePreservesHeadingAndPayload() + { + ExtractionDocument document = new("document"); + ExtractionDocumentSection section = new(null); + ExtractionDocumentTextElement element = new(new TextContent("header"), role: "heading") + { + HeadingLevel = 3 + }; + document.Sections.Add(section); + section.Elements.Add(element); + + element.HeadingLevel = 3; + + element.HeadingLevel = null; + Assert.Null(element.HeadingLevel); + Assert.Equal("heading", element.Role); + } +} diff --git a/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/Microsoft.Extensions.Documents.Abstractions.Tests.csproj b/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/Microsoft.Extensions.Documents.Abstractions.Tests.csproj new file mode 100644 index 00000000000..f3e72525311 --- /dev/null +++ b/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/Microsoft.Extensions.Documents.Abstractions.Tests.csproj @@ -0,0 +1,11 @@ + + + + Unit tests for Microsoft.Extensions.Documents.Abstractions. + + + + + + + diff --git a/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/PreviewContractTests.cs b/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/PreviewContractTests.cs new file mode 100644 index 00000000000..184b957bc6b --- /dev/null +++ b/test/Libraries/Microsoft.Extensions.Documents.Abstractions.Tests/PreviewContractTests.cs @@ -0,0 +1,153 @@ +// Licensed to the .NET Foundation under one or more agreements. +// The .NET Foundation licenses this file to you under the MIT license. + +using System; +using System.Collections.Generic; +using System.Diagnostics.CodeAnalysis; +using System.Text.Json; +using Microsoft.Extensions.AI; +using Xunit; + +namespace Microsoft.Extensions.Documents.Tests; + +public sealed class PreviewContractTests +{ + [Fact] + public void TextContent_BaseMutationRejectsNullAndOtherKindsWithoutLosingPayload() + { + TextContent original = new("**literal** <&| OCR 1O0?"); + ExtractionDocumentTextElement text = new(original, role: "Vendor.Custom") { HeadingLevel = int.MaxValue }; + ExtractionDocumentElement element = text; + + Assert.Throws("value", () => element.Content = null); + Assert.Same(original, element.Content); + foreach (AIContent invalid in new AIContent[] { new(), new DataContent(new byte[] { 1 }, "image/png"), new UriContent("urn:asset", "image/png") }) + { + Assert.Throws("value", () => element.Content = invalid); + Assert.Same(original, text.Content); + } + + TextContent replacement = new("plain unchanged"); + element.Content = replacement; + Assert.Same(replacement, text.Content); + replacement.Text = "mutated **literal**"; + Assert.Equal("mutated **literal**", Assert.IsType(element.Content).Text); + Assert.Equal("Vendor.Custom", text.Role); + Assert.Equal(int.MaxValue, text.HeadingLevel); + Assert.Null(typeof(ExtractionDocumentElement).GetProperty("Text")); + Assert.Null(typeof(ExtractionDocumentTextElement).GetProperty("Text")); + } + + [Fact] + public void OtherElements_KeepFlexibleSinglePayloadState() + { + ExtractionDocumentElement[] elements = [new ExtractionDocumentSection(), new ExtractionDocumentTableElement(null, 1, 1), new ExtractionDocumentImageElement(), new CustomElement()]; + foreach (ExtractionDocumentElement element in elements) + { + AIContent payload = new(); + element.Content = payload; + Assert.Same(payload, element.Content); + element.Content = null; + Assert.Null(element.Content); + } + } + + [Fact] + public void RootRawRepresentation_ZeroSectionsAndNoPayloadRetainsBorrowedIdentityAndIsJsonIgnored() + { + using Native native = new(); + ExtractionDocument document = new("empty") { RawRepresentation = native }; + + Assert.Null(document.Content); + Assert.Empty(document.Sections); + Assert.Empty(document.EnumerateContent()); + Assert.Same(native, document.RawRepresentation); + using JsonDocument wire = JsonDocument.Parse(JsonSerializer.Serialize(document)); + Assert.False(wire.RootElement.TryGetProperty(nameof(document.RawRepresentation), out _)); + Assert.Equal("empty", wire.RootElement.GetProperty(nameof(document.Identifier)).GetString()); + Assert.Equal(0, native.InspectionCount); + Assert.Equal(0, native.DisposeCount); + + object replacement = new(); + document.RawRepresentation = replacement; + Assert.Same(replacement, document.RawRepresentation); + Assert.Equal(0, native.DisposeCount); + document.RawRepresentation = null; + Assert.Null(document.RawRepresentation); + } + + [Fact] + public void SourcePages_OrdinaryListPreservesBlankNamedDuplicateAndMultiPageFrames() + { + ExtractionDocument document = new("layout"); + ExtractionDocumentSourcePage named = new("Notebook:Ideas", null); + ExtractionDocumentSourcePage seven = new("physical:7", 7, new(200, 100), + ExtractionDocumentCoordinateUnit.Point, ExtractionDocumentCoordinateOrigin.BottomLeft); + ExtractionDocumentSourcePage blank = new("blank:2", 2); + Assert.IsType>(document.SourcePages); + document.SourcePages.AddRange([named, seven, blank, named]); + ExtractionDocumentTextElement text = new(new TextContent("unmodified")); + ExtractionDocumentPoint[] polygon = [new(10, 20), new(30, 10), new(40, 35)]; + text.Sources.Add(new(named)); + text.Sources.Add(new(seven, polygon)); + ExtractionDocumentSection section = new(); + section.Elements.Add(text); + document.Sections.Add(section); + + Assert.Equal(new[] { named, seven, blank, named }, document.SourcePages); + Assert.Null(named.PageNumber); + Assert.Equal(7, seven.PageNumber); + Assert.Equal(2, blank.PageNumber); + Assert.Equal(new ExtractionDocumentPageDimensions(200, 100), seven.Dimensions); + Assert.Equal(ExtractionDocumentCoordinateUnit.Point, seven.CoordinateUnit); + Assert.Equal(ExtractionDocumentCoordinateOrigin.BottomLeft, seven.CoordinateOrigin); + Assert.Empty(text.Sources[0].Polygon); + Assert.Equal(polygon, text.Sources[1].Polygon); + Assert.Same(text, Assert.Single(document.EnumerateContent())); + Assert.Null(typeof(ExtractionDocumentSourcePage).GetProperty("SourceOutput")); + foreach (string removed in new[] { "ExtractionDocumentSourceOutput", "ExtractionDocumentArtifact", "ExtractionDocumentRawContentStatus" }) + { + Assert.Null(typeof(ExtractionDocument).Assembly.GetType("Microsoft.Extensions.Documents." + removed)); + } + } + + [Fact] + public void Image_OcrAlternativeAndOriginalAssetAreIndependentOfPayloadUri() + { + UriContent payload = new("urn:payload", "image/png"); + ExtractionDocumentImageElement image = new(payload, text: "OCR 1O0?") + { + AlternativeText = "Figure caption", + Source = new("urn:original") + }; + Assert.Equal("urn:payload", payload.Uri.ToString()); + Assert.Equal("urn:original", image.Source.ToString()); + Assert.Equal("OCR 1O0?", image.Text); + Assert.Equal("Figure caption", image.AlternativeText); + image.Text = null; + Assert.Null(image.Text); + Assert.Same(payload, image.Content); + Assert.Equal("Figure caption", image.AlternativeText); + } + + private sealed class CustomElement() : ExtractionDocumentElement(null); + + private sealed class Native : IDisposable + { + internal int DisposeCount { get; private set; } + internal int InspectionCount { get; private set; } + + [SuppressMessage("Major Code Smell", "S1144:Unused private types or members should be removed", + Justification = "Public getter is inspected by System.Text.Json if the root's JsonIgnore protection is removed.")] + public string Value + { + get + { + InspectionCount++; + throw new InvalidOperationException("Native results must not be serialized."); + } + } + + public void Dispose() => DisposeCount++; + } +}