Add deterministic shared-output index ownership

[jeffpatton1971]

Summary

Addresses #63 by defining deterministic ownership of the shared index.md output.

• Adds RendererOptions.GenerateIndex, defaulting to true
• Adds CLI --no-index and JSON GenerateIndex support
• Adds the MSBuild Xml2Doc_GenerateIndex property
• Excludes index.md from planned outputs when generation is disabled
• Limits MSBuild GeneratedFiles to files owned by the current invocation
• Adds regression coverage
• Adds proposed ADR-011 for generated-output ownership and lifecycle
• Updates the roadmap and documentation

Verification

dotnet test .\Xml2Doc\Xml2Doc.sln --configuration Release

Build succeeded
Tests: 11 passed, 0 failed, 0 skipped

[Copilot]

Pull request overview

This PR addresses nondeterministic overwrites of the shared index.md in per-type output mode by introducing an explicit “index ownership” switch across Core, CLI, and MSBuild, and by basing MSBuild’s reported outputs on the renderer’s deterministic output plan.

Changes:

• Adds RendererOptions.GenerateIndex (default true) and updates rendering/planning to conditionally include index.md.
• Exposes the option via CLI (--no-index + JSON GenerateIndex) and MSBuild (Xml2Doc_GenerateIndex), and updates MSBuild output reporting to use PlanOutputs.
• Adds a regression test plus supporting documentation/ADR and roadmap updates.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
Xml2Doc/tests/Xml2Doc.Tests/RenderSnapshots.cs	Adds regression test ensuring GenerateIndex=false omits index.md from plan and output.
Xml2Doc/src/Xml2Doc.MSBuild/README.md	Documents Xml2Doc_GenerateIndex and guidance for shared output directories.
Xml2Doc/src/Xml2Doc.MSBuild/GenerateMarkdownFromXmlDoc.cs	Wires MSBuild GenerateIndex into Core options; shifts GeneratedFiles to deterministic planning.
Xml2Doc/src/Xml2Doc.MSBuild/build/Xml2Doc.MSBuild.targets	Passes Xml2Doc_GenerateIndex to the task and includes it in the incremental options fingerprint.
Xml2Doc/src/Xml2Doc.MSBuild/build/Xml2Doc.MSBuild.props	Introduces default Xml2Doc_GenerateIndex=true.
Xml2Doc/src/Xml2Doc.Core/RendererOptions.cs	Adds GenerateIndex option to the public renderer options record.
Xml2Doc/src/Xml2Doc.Core/README.md	Mentions the new per-type index generation option.
Xml2Doc/src/Xml2Doc.Core/MarkdownRenderer.cs	Conditionally writes/plans index.md based on GenerateIndex.
Xml2Doc/src/Xml2Doc.Cli/xml2doc.cs	Adds --no-index, config merge support for GenerateIndex, and passes option into Core.
Xml2Doc/src/Xml2Doc.Cli/Config.cs	Adds JSON config property GenerateIndex.
README.md	Documents MSBuild property and shared-output guidance.
docs/roadmap.md	Adds roadmap item for explicit ownership controls and references ADR-011.
docs/adr/README.md	Lists ADR-011.
docs/adr/ADR-011-generated-output-ownership.md	Adds proposed ADR describing generated-output ownership/lifecycle direction.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated no new comments.

Suppressed comments (2)

Xml2Doc/src/Xml2Doc.Core/MarkdownRenderer.cs:129

• RenderToDirectory orders types with the default string comparer (OrderBy(t => t.Id)), which is culture-sensitive and can produce different ordering across environments. Since this PR is about deterministic shared outputs (and PlanOutputs already uses StringComparer.Ordinal), use an ordinal comparer here so the generated per-type ordering and index.md ordering are stable.

            if (_opt.GenerateIndex)
                File.WriteAllText(Path.Combine(outDir, "index.md"), RenderIndex(types, useAnchors: false));

Xml2Doc/src/Xml2Doc.MSBuild/GenerateMarkdownFromXmlDoc.cs:291

• The GeneratedFiles = renderer.PlanOutputs(outDir) assignment is misindented compared to the surrounding block, which makes the MSBuild task harder to read/maintain. Align this statement with the other statements in the else branch.

GeneratedFiles = renderer.PlanOutputs(outDir)
    .Select(p => (ITaskItem)new TaskItem(p))
    .ToArray();

[Copilot]

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated no new comments.

Suppressed comments (2)

Xml2Doc/src/Xml2Doc.Core/MarkdownRenderer.cs:129

• types are sorted with the default string comparer (OrderBy(t => t.Id)), which is culture-sensitive and can produce different ordering across environments. Since PlanOutputs() already uses StringComparer.Ordinal for determinism, RenderToDirectory() should use the same ordinal sort to keep rendered content (including index.md) stable and consistent with planned outputs.

            if (_opt.GenerateIndex)
                File.WriteAllText(Path.Combine(outDir, "index.md"), RenderIndex(types, useAnchors: false));

Xml2Doc/src/Xml2Doc.MSBuild/GenerateMarkdownFromXmlDoc.cs:291

• These GeneratedFiles = renderer.PlanOutputs(...) lines appear unintentionally de-indented compared to the rest of the else block, which hurts readability and may fail formatting/linting checks.

GeneratedFiles = renderer.PlanOutputs(outDir)
    .Select(p => (ITaskItem)new TaskItem(p))
    .ToArray();