tests

Author: KSemenenko

AGENTS.md

@@ -62,8 +62,8 @@ Target capabilities:
 - Tests must verify the real Markdown -> graph -> query/search flow, including success, malformed input, and empty/no-match paths where relevant.
 - Tests must not use mocks, stubs, or fakes, except one local test implementation of `Microsoft.Extensions.AI.IChatClient` used to prove the LLM extraction boundary without network access.
 - Use TUnit for tests and Shouldly for assertions.
-- Fallbacks are forbidden. Do not silently substitute generic/default behaviour when parsing, extraction, graph building, query execution, or AI extraction fails; fail explicitly or skip the invalid fact with a caller-visible test.
-- Legacy or leftover old code is forbidden. Do not keep deprecated duplicate paths, compatibility shims, or unused old implementations; remove them immediately unless an ADR documents a temporary migration path.
+- Silent substitution paths are forbidden. Do not replace parsing, extraction, graph building, query execution, or AI extraction failures with generic/default behaviour; fail explicitly or skip the invalid fact with a caller-visible test.
+- Old leftover code is forbidden. Do not keep deprecated duplicate paths, compatibility shims, or unused old implementations; remove them immediately unless an ADR documents a temporary migration path.
 
 ## Global Skills
 
@@ -87,9 +87,9 @@ List only the skills this solution actually uses.
 
 - `restore`: `dotnet restore MarkdownLd.Kb.slnx`
 - `build`: `dotnet build MarkdownLd.Kb.slnx --no-restore`
-- `test`: `dotnet test MarkdownLd.Kb.slnx --configuration Release`
+- `test`: `dotnet test --solution MarkdownLd.Kb.slnx --configuration Release`
 - `format`: `dotnet format MarkdownLd.Kb.slnx --verify-no-changes`
-- `coverage`: `dotnet test MarkdownLd.Kb.slnx --configuration Release -- --coverage --coverage-output-format cobertura --coverage-output "$PWD/TestResults/TUnitCoverage/coverage.cobertura.xml" --coverage-settings "$PWD/CodeCoverage.runsettings"`
+- `coverage`: `dotnet test --solution MarkdownLd.Kb.slnx --configuration Release -- --coverage --coverage-output-format cobertura --coverage-output "$PWD/TestResults/TUnitCoverage/coverage.cobertura.xml" --coverage-settings "$PWD/CodeCoverage.runsettings"`
 
 `.NET` runner policy:
 

CodeCoverage.runsettings

@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="utf-8"?>
+<RunSettings>
+  <DataCollectionRunSettings>
+    <DataCollectors>
+      <DataCollector friendlyName="Code Coverage" uri="datacollector://Microsoft/CodeCoverage/2.0">
+        <Configuration>
+          <CodeCoverage>
+            <ModulePaths>
+              <Include>
+                <ModulePath>.*ManagedCode\.MarkdownLd\.Kb\.dll$</ModulePath>
+              </Include>
+              <Exclude>
+                <ModulePath>.*ManagedCode\.MarkdownLd\.Kb\.Tests\.dll$</ModulePath>
+              </Exclude>
+            </ModulePaths>
+            <Sources>
+              <Exclude>
+                <Source>.*[\\/]obj[\\/].*</Source>
+              </Exclude>
+            </Sources>
+            <UseVerifiableInstrumentation>True</UseVerifiableInstrumentation>
+            <AllowLowIntegrityProcesses>True</AllowLowIntegrityProcesses>
+            <CollectFromChildProcesses>True</CollectFromChildProcesses>
+            <CollectAspDotNet>False</CollectAspDotNet>
+          </CodeCoverage>
+        </Configuration>
+      </DataCollector>
+    </DataCollectors>
+  </DataCollectionRunSettings>
+</RunSettings>

README.md

@@ -1,33 +1,51 @@
 # Markdown-LD Knowledge Bank
 
-Markdown-LD Knowledge Bank is a .NET 10 library for turning Markdown knowledge-base files into an in-memory RDF graph that can be searched and queried with read-only SPARQL.
+Markdown-LD Knowledge Bank is a .NET 10 library for turning Markdown knowledge-base files into an in-memory RDF graph that can be searched, queried with read-only SPARQL, exported as RDF, and rendered as a diagram.
 
 It ports the core idea from [lqdev/markdown-ld-kb](https://github.com/lqdev/markdown-ld-kb) into a C# library package. The runtime is local and in-memory: no localhost server, no Azure Functions host, no database server, and no hosted graph service are required.
 
+Use it when you want plain Markdown notes to become a queryable knowledge graph without making your application depend on a specific model provider, graph server, or hosted indexing service.
+
 ## What It Does
 
 ```mermaid
 flowchart LR
-    Source["Markdown, MDX, text, JSON, YAML, CSV"] --> Converter["KnowledgeSourceDocumentConverter"]
-    Converter --> Parser["MarkdownDocumentParser"]
-    Parser --> Deterministic["Deterministic fact extraction"]
-    Parser --> Chat["Optional IChatClient extraction"]
-    Deterministic --> Merge["Fact merge and canonicalization"]
+    Source["Markdown / MDX / text\nJSON / YAML / CSV"] --> Converter["KnowledgeSourceDocumentConverter"]
+    Converter --> Parser["MarkdownDocumentParser\n→ MarkdownDocument"]
+    Parser --> Det["DeterministicKnowledgeFactExtractor\n→ entities, assertions"]
+    Parser --> Chat["ChatClientKnowledgeFactExtractor\n(optional IChatClient)"]
+    Det --> Merge["KnowledgeFactMerger\n→ merged KnowledgeExtractionResult"]
     Chat --> Merge
-    Merge --> Graph["dotNetRDF in-memory graph"]
-    Graph --> Search["SearchAsync"]
-    Graph --> Sparql["SELECT and ASK SPARQL"]
-    Graph --> Export["Turtle and JSON-LD"]
+    Merge --> Builder["KnowledgeGraphBuilder\n→ dotNetRDF in-memory graph"]
+    Builder --> Search["SearchAsync"]
+    Builder --> Sparql["ExecuteSelectAsync\nExecuteAskAsync"]
+    Builder --> Snap["ToSnapshot"]
+    Builder --> Diagram["SerializeMermaidFlowchart\nSerializeDotGraph"]
+    Builder --> Export["SerializeTurtle\nSerializeJsonLd"]
 ```
 
-The pipeline extracts:
+**Deterministic extraction** produces facts without any network call:
 
 - article identity, title, summary, dates, tags, authors, and topics from YAML front matter
-- heading sections and document identity from Markdown
+- heading sections and document identity from Markdown structure
 - Markdown links such as `[SPARQL](https://www.w3.org/TR/sparql11-query/)`
 - optional wikilinks such as `[[RDF]]`
 - optional assertion arrows such as `article --mentions--> RDF`
-- optional LLM-produced entities and assertions through `Microsoft.Extensions.AI.IChatClient`
+
+**Optional AI extraction** enriches the graph with LLM-produced entities and assertions through `Microsoft.Extensions.AI.IChatClient`. No provider-specific SDK is required in the core library.
+
+**Graph outputs:**
+
+- `ToSnapshot()` — stable `KnowledgeGraphSnapshot` with `Nodes` and `Edges`
+- `SerializeMermaidFlowchart()` — Mermaid `graph LR` diagram
+- `SerializeDotGraph()` — Graphviz DOT diagram
+- `SerializeTurtle()` — Turtle RDF serialization
+- `SerializeJsonLd()` — JSON-LD serialization
+- `ExecuteSelectAsync(sparql)` — read-only SPARQL SELECT returning `SparqlQueryResult`
+- `ExecuteAskAsync(sparql)` — read-only SPARQL ASK returning `bool`
+- `SearchAsync(term)` — case-insensitive search across `schema:name`, `schema:description`, and `schema:keywords`, returning matching graph subjects as `SparqlQueryResult`
+
+All async methods accept an optional `CancellationToken`.
 
 ## Install
 
@@ -122,11 +140,11 @@ internal static class FileGraphDemo
 }
 ```
 
-`KnowledgeSourceDocumentConverter` supports Markdown and other text-like knowledge inputs: `.md`, `.markdown`, `.mdx`, `.txt`, `.text`, `.log`, `.csv`, `.json`, `.jsonl`, `.yaml`, and `.yml`.
+`KnowledgeSourceDocumentConverter` supports Markdown and other text-like knowledge inputs: `.md`, `.markdown`, `.mdx`, `.txt`, `.text`, `.log`, `.csv`, `.json`, `.jsonl`, `.yaml`, and `.yml`. Non-Markdown files are accepted as text sources and run through the same parsing, extraction, and graph build pipeline.
 
 You do not need to pass a base URI for normal use. Document identity is resolved in this order:
 
-- `canonicalUrl` or `canonical_url` in Markdown front matter
+- `KnowledgeDocumentConversionOptions.CanonicalUri` when you provide one
 - the file path, normalized the same way as the upstream project: `content/notes/rdf.md` becomes a stable document IRI
 - the generated inline document path when `BuildFromMarkdownAsync` is called without a path
 
@@ -179,12 +197,12 @@ ASK WHERE {
 
 The built-in chat extractor requests structured output through `GetResponseAsync<T>()`, normalizes the returned entity/assertion payload, merges it with deterministic facts, and then builds the same in-memory RDF graph used by search and SPARQL. Tests use one local non-network `IChatClient` implementation so the full extraction-to-graph flow is covered without a live model.
 
-## Query And Export
+## Query The Graph
 
 ```csharp
 using ManagedCode.MarkdownLd.Kb.Pipeline;
 
-internal static class QueryDemo
+internal static class QueryGraphDemo
 {
     private const string SelectQuery = """
 PREFIX schema: <https://schema.org/>
@@ -204,28 +222,71 @@ LIMIT 100
     public static async Task RunAsync(MarkdownKnowledgeBuildResult result)
     {
         var rows = await result.Graph.ExecuteSelectAsync(SelectQuery);
+        var search = await result.Graph.SearchAsync(SearchTerm);
+
         foreach (var row in rows.Rows)
         {
             Console.WriteLine(row.Values[ArticleKey]);
             Console.WriteLine(row.Values[TitleKey]);
         }
 
-        var search = await result.Graph.SearchAsync(SearchTerm);
-        var turtle = result.Graph.SerializeTurtle();
-        var jsonLd = result.Graph.SerializeJsonLd();
-
         Console.WriteLine(search.Rows.Count);
+    }
+}
+```
+
+SPARQL execution is intentionally read-only. `SELECT` and `ASK` are allowed; mutation forms such as `INSERT`, `DELETE`, `LOAD`, `CLEAR`, `DROP`, and `CREATE` are rejected before execution.
+
+## Export The Graph
+
+```csharp
+using ManagedCode.MarkdownLd.Kb.Pipeline;
+
+internal static class ExportGraphDemo
+{
+    public static void Run(MarkdownKnowledgeBuildResult result)
+    {
+        KnowledgeGraphSnapshot snapshot = result.Graph.ToSnapshot();
+        string mermaid = result.Graph.SerializeMermaidFlowchart();
+        string dot = result.Graph.SerializeDotGraph();
+        string turtle = result.Graph.SerializeTurtle();
+        string jsonLd = result.Graph.SerializeJsonLd();
+
+        Console.WriteLine(snapshot.Nodes.Count);
+        Console.WriteLine(snapshot.Edges.Count);
+        Console.WriteLine(mermaid);
+        Console.WriteLine(dot);
         Console.WriteLine(turtle.Length);
         Console.WriteLine(jsonLd.Length);
     }
 }
 ```
 
-SPARQL execution is intentionally read-only. `SELECT` and `ASK` are allowed; mutation forms such as `INSERT`, `DELETE`, `LOAD`, `CLEAR`, `DROP`, and `CREATE` are rejected before execution.
+`ToSnapshot()` returns a stable object graph with `Nodes` and `Edges` so callers can build their own UI, JSON endpoint, or visualization layer without touching dotNetRDF internals. URI node labels are resolved from `schema:name` when available, so diagram output is readable by default.
+
+Example Mermaid output shape:
+
+```mermaid
+graph LR
+  n0["Zero Cost Knowledge Graph"]
+  n1["RDF"]
+  n0 -->|"schema:mentions"| n1
+```
+
+Example DOT output shape:
+
+```dot
+digraph KnowledgeGraph {
+  rankdir=LR;
+  "n0" [label="Zero Cost Knowledge Graph"];
+  "n1" [label="RDF"];
+  "n0" -> "n1" [label="schema:mentions"];
+}
+```
 
 ## Thread Safety
 
-`KnowledgeGraph` is safe for shared in-memory read/write use through its public API. Search, read-only SPARQL, and serialization run under a read lock; `MergeAsync` snapshots a built graph and merges it under a write lock.
+`KnowledgeGraph` is safe for shared in-memory read/write use through its public API. Search, read-only SPARQL, snapshot export, diagram serialization, and RDF serialization run under a read lock; `MergeAsync` snapshots a built graph and merges it under a write lock.
 
 Use this when many workers convert Markdown independently and publish their results into one graph:
 
@@ -237,6 +298,21 @@ await shared.Graph.MergeAsync(next.Graph);
 var rows = await shared.Graph.SearchAsync("rdf");
 ```
 
+## Key Types
+
+| Type | Purpose |
+|---|---|
+| `MarkdownKnowledgePipeline` | Entry point. Orchestrates parsing, extraction, merge, and graph build. |
+| `MarkdownKnowledgeBuildResult` | Holds `Documents`, `Facts`, and the built `Graph`. |
+| `KnowledgeGraph` | In-memory dotNetRDF graph with query, search, export, and merge. |
+| `KnowledgeGraphSnapshot` | Immutable view with `Nodes` (`KnowledgeGraphNode`) and `Edges` (`KnowledgeGraphEdge`). |
+| `MarkdownDocument` | Pipeline parsed document: `FrontMatter`, `Body`, and `Sections`. |
+| `MarkdownFrontMatter` | Typed access to YAML front matter fields. |
+| `KnowledgeExtractionResult` | Merged collection of `KnowledgeEntityFact` and `KnowledgeAssertionFact`. |
+| `SparqlQueryResult` | Query result with `Variables` and `Rows` of `SparqlRow`. |
+| `KnowledgeSourceDocumentConverter` | Converts files and directories into pipeline-ready source documents. |
+| `ChatClientKnowledgeFactExtractor` | AI extraction adapter behind `IChatClient`. |
+
 ## Markdown Conventions
 
 ```markdown
@@ -257,6 +333,20 @@ about:
 Use [RDF](https://www.w3.org/RDF/) and [SPARQL](https://www.w3.org/TR/sparql11-query/).
 ```
 
+Recognized front matter keys:
+
+| Key | RDF property | Type |
+|---|---|---|
+| `title` | `schema:name` | string |
+| `description` / `summary` | `schema:description` | string |
+| `datePublished` | `schema:datePublished` | string (ISO date) |
+| `dateModified` | `schema:dateModified` | string (ISO date) |
+| `author` | `schema:author` | string or list |
+| `tags` / `keywords` | `schema:keywords` | list |
+| `about` | `schema:about` | list |
+| `canonicalUrl` / `canonical_url` | root parser document identity; use `KnowledgeDocumentConversionOptions.CanonicalUri` for pipeline identity | string (URL) |
+| `entity_hints` / `entityHints` | entity hints | list of `{label, type, sameAs}` |
+
 Optional advanced predicate forms:
 
 - `mentions` becomes `schema:mentions`
@@ -303,8 +393,8 @@ dotnet test --solution MarkdownLd.Kb.slnx --configuration Release -- --coverage
 
 Current verification baseline:
 
-- tests: 69 passed, 0 failed
-- line coverage: 96.06%
-- branch coverage: 85.22%
+- tests: 70 passed, 0 failed
+- line coverage: 95.93%
+- branch coverage: 84.55%
 - target framework: .NET 10
 - package version: 0.0.1

docs/ADR/ADR-0001-rdf-sparql-library.md

@@ -164,7 +164,7 @@ Mitigations:
 ### Test commands
 
 - build: `dotnet build MarkdownLd.Kb.slnx --no-restore`
-- test: `dotnet test MarkdownLd.Kb.slnx --configuration Release`
+- test: `dotnet test --solution MarkdownLd.Kb.slnx --configuration Release`
 - format: `dotnet format MarkdownLd.Kb.slnx --verify-no-changes`
 - coverage: `dotnet test --solution MarkdownLd.Kb.slnx --configuration Release -- --coverage --coverage-output-format cobertura --coverage-output "$PWD/TestResults/TUnitCoverage/coverage.cobertura.xml" --coverage-settings "$PWD/CodeCoverage.runsettings"`
 

docs/ADR/ADR-0002-llm-extraction-ichatclient.md

@@ -112,7 +112,7 @@ Mitigations:
 ### Test commands
 
 - build: `dotnet build MarkdownLd.Kb.slnx --no-restore`
-- test: `dotnet test MarkdownLd.Kb.slnx --configuration Release`
+- test: `dotnet test --solution MarkdownLd.Kb.slnx --configuration Release`
 - format: `dotnet format MarkdownLd.Kb.slnx --verify-no-changes`
 - coverage: `dotnet test --solution MarkdownLd.Kb.slnx --configuration Release -- --coverage --coverage-output-format cobertura --coverage-output "$PWD/TestResults/TUnitCoverage/coverage.cobertura.xml" --coverage-settings "$PWD/CodeCoverage.runsettings"`
 

docs/Architecture.md

@@ -90,6 +90,8 @@ flowchart LR
     Merge --> WriteLock["write lock"]
     Search["SearchAsync"] --> ReadLock["read lock"]
     Select["ExecuteSelectAsync / ExecuteAskAsync"] --> ReadLock
+    Snapshot["ToSnapshot"] --> ReadLock
+    Diagram["SerializeMermaidFlowchart / SerializeDotGraph"] --> ReadLock
     Serialize["SerializeTurtle / SerializeJsonLd"] --> ReadLock
     WriteLock --> DotNetRdf["dotNetRDF Graph"]
     ReadLock --> DotNetRdf

src/MarkdownLd.Kb/AGENTS.md

@@ -19,14 +19,14 @@ Purpose: Production library for Markdown-LD Knowledge Bank.
 - Do not add localhost, HTTP server, background service, database server, or hosted API dependencies. The production pipeline must build, store, query, and serialize graphs in memory.
 - Do not add embedding/vector provider dependencies to the core pipeline. Future semantic/vector search must be optional and provider-neutral.
 - Keep the root namespace, assembly name, and package ID as `ManagedCode.MarkdownLd.Kb`.
-- Do not implement fallbacks. Invalid parsing, extraction, graph, or query inputs must fail explicitly or be skipped by a documented validation rule with tests.
-- Do not keep legacy or leftover implementation paths in this project. Remove obsolete code instead of wrapping or preserving it.
+- Do not implement silent substitution paths. Invalid parsing, extraction, graph, or query inputs must fail explicitly or be skipped by a documented validation rule with tests.
+- Do not keep old leftover implementation paths in this project. Remove obsolete code instead of wrapping or preserving it.
 
 ## Commands
 
 - build: `dotnet build ../../MarkdownLd.Kb.slnx --no-restore`
-- test: `(cd ../.. && dotnet test MarkdownLd.Kb.slnx --configuration Release)`
-- coverage: `(cd ../.. && dotnet test MarkdownLd.Kb.slnx --configuration Release -- --coverage --coverage-output-format cobertura --coverage-output "$PWD/TestResults/TUnitCoverage/coverage.cobertura.xml" --coverage-settings "$PWD/CodeCoverage.runsettings")`
+- test: `(cd ../.. && dotnet test --solution MarkdownLd.Kb.slnx --configuration Release)`
+- coverage: `(cd ../.. && dotnet test --solution MarkdownLd.Kb.slnx --configuration Release -- --coverage --coverage-output-format cobertura --coverage-output "$PWD/TestResults/TUnitCoverage/coverage.cobertura.xml" --coverage-settings "$PWD/CodeCoverage.runsettings")`
 
 ## Local Risks
 

src/MarkdownLd.Kb/Extraction/MarkdownFrontMatterParser.cs

@@ -43,11 +43,8 @@ private static bool TryParseFrontMatter(string frontMatterBlock, out MarkdownFro
                 .IgnoreUnmatchedProperties()
                 .Build();
 
-            var values = deserializer.Deserialize<Dictionary<string, object?>>(new StringReader(frontMatterBlock));
-            if (values is null)
-            {
-                values = new Dictionary<string, object?>(StringComparer.OrdinalIgnoreCase);
-            }
+            var values = deserializer.Deserialize<Dictionary<string, object?>>(new StringReader(frontMatterBlock))
+                ?? new Dictionary<string, object?>(StringComparer.OrdinalIgnoreCase);
 
             frontMatter = new MarkdownFrontMatter
             {

src/MarkdownLd.Kb/Parsing/MarkdownFrontMatterParser.cs

@@ -38,11 +38,8 @@ private static bool TryParseFrontMatter(string rawYaml, out MarkdownFrontMatter
     {
         try
         {
-            var values = Deserializer.Deserialize<Dictionary<object, object?>>(rawYaml);
-            if (values is null)
-            {
-                values = new Dictionary<object, object?>();
-            }
+            var values = Deserializer.Deserialize<Dictionary<object, object?>>(rawYaml)
+                ?? new Dictionary<object, object?>();
 
             var normalized = NormalizeDictionary(values);
 

src/MarkdownLd.Kb/Pipeline/KnowledgeFactMerger.cs

@@ -6,22 +6,16 @@ public sealed class KnowledgeFactMerger(Uri? baseUri = null)
 {
     private readonly Uri _baseUri = KnowledgeNaming.NormalizeBaseUri(baseUri ?? new Uri(DefaultBaseUriText, UriKind.Absolute));
 
-    public KnowledgeExtractionResult Merge(params KnowledgeExtractionResult?[]? results)
+    public KnowledgeExtractionResult Merge(params KnowledgeExtractionResult[] results)
     {
+        ArgumentNullException.ThrowIfNull(results);
+
         var entities = new Dictionary<string, KnowledgeEntityFact>(StringComparer.OrdinalIgnoreCase);
         var assertions = new Dictionary<string, KnowledgeAssertionFact>(StringComparer.OrdinalIgnoreCase);
 
-        if (results is null)
-        {
-            return new KnowledgeExtractionResult();
-        }
-
         foreach (var result in results)
         {
-            if (result is null)
-            {
-                continue;
-            }
+            ArgumentNullException.ThrowIfNull(result);
 
             foreach (var entity in result.Entities)
             {