web: api/docs quality hardening + clearer labels + sitemap/source fixes

[PrzemyslawKlys]

Summary

• improve sitemap canonicalization by collapsing .html aliases when slash routes exist and disambiguating duplicate HTML sitemap titles
• improve API docs readability by disambiguating duplicate short type names in docs UI
• add displayNameMode (short|namespace-suffix|full) for API docs labels and JSON artifacts
• add API docs diagnostics for duplicate member signature groups ([PFWEB.APIDOCS.MEMBER.SIGNATURES])
• normalize relative source mapping paths (./, ../) for stable source URL mappings
• wire displayNameMode through pipeline + CLI help/docs

Why

These changes target adoption-critical pain points vs DocFX/Hugo/Jekyll class generators: ambiguous type/member labeling, noisy/duplicate sitemap output, and brittle source-link mapping.

Validation

• dotnet test .\\PSPublishModule.sln -c Release --filter WebApiDocsGeneratorDisplayNameTests --nologo
• dotnet test .\\PSPublishModule.sln -c Release --filter WebApiDocsGeneratorMemberSignatureWarningsTests --nologo
• dotnet test .\\PSPublishModule.sln -c Release --filter WebApiDocsGenerator --nologo
• dotnet test .\\PSPublishModule.sln -c Release --filter "WebApiDocsGenerator|WebPipelineRunnerApiDocsPreflightTests|WebCliApiDocsPreflightTests" --nologo

Commit Breakdown

1. 689eafd sitemap canonicalization + title disambiguation
2. 03faf44 API docs duplicate short-name disambiguation in UI
3. b02c2c1 display-name modes + JSON aliases + member signature diagnostics
4. abe50bb source mapping normalization for relative roots
5. 84637b0 pipeline/docs cleanup wiring for display-name mode

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

[claude]

Code Review - PR #113

Overall, this is a high-quality PR that significantly improves API documentation clarity and sitemap quality. The implementation is well-tested, secure, and follows good practices.

✅ Strengths

1. Excellent Test Coverage: 443 lines of comprehensive tests covering all scenarios
2. Well-Documented: Clear documentation updates in both API docs and pipeline docs
3. Backwards Compatible: Graceful fallback to default mode with warnings
4. Security: Proper HTML encoding throughout, no injection vulnerabilities
5. Good Structure: Clean separation of concerns with the new partial class

🔧 Recommendations

1. Code Duplication - DRY Principle

The TrimLeadingRelativeSegments logic is duplicated:

• WebApiDocsGenerator.ApiDocs.Models.cs:931-945
• WebApiDocsGenerator.ApiDocs.SourceValidation.cs:956-966

Suggestion: Extract to a shared helper method to avoid maintenance issues.

2. Modern C# Syntax

Lines using Substring could use range operators for better readability:

// Current (lines 938-942, 958-962)
normalized = normalized.StartsWith("../", StringComparison.Ordinal)
    ? normalized.Substring(3)
    : normalized.Substring(2);

// Suggested
normalized = normalized.StartsWith("../", StringComparison.Ordinal)
    ? normalized[3..]
    : normalized[2..];

3. Minor Logic Clarification

In WebApiDocsGenerator.cs:1179-1181, 1217-1219, 1237-1239, the fallback to ResolveTypeAliases should never execute since typeAliasMap is pre-built for all types. Consider simplifying or adding a debug assertion to catch logic errors.

📊 Analysis Summary

• Code Quality: ⭐⭐⭐⭐⭐ (5/5)
• Test Coverage: ⭐⭐⭐⭐⭐ (5/5)
• Security: ✅ No concerns
• Performance: ✅ Appropriate for build-time operation
• Documentation: ⭐⭐⭐⭐⭐ (5/5)

🎯 Verdict

APPROVE - This PR is ready to merge. The recommendations above are minor improvements that could be addressed in a follow-up PR if desired, but they don't block this excellent work.

The features implemented (display name modes, duplicate signature detection, sitemap canonicalization) directly address real pain points and the implementation is solid.

Great work! 🚀

[PrzemyslawKlys]

Addressed Claude review suggestions in 7ac6a08:

• deduplicated relative-path trimming into shared helper (WebApiDocsGenerator.ApiDocs.PathNormalization.cs)
• replaced duplicated Substring usage in those paths via shared range-based implementation
• simplified alias-map access by introducing GetTypeAliases(...) with Debug.Fail guard for unexpected missing entries

Validation rerun:

• dotnet test .\\PSPublishModule.sln -c Release --filter "WebApiDocsGeneratorSourceAndCssTests|WebApiDocsGeneratorDisplayNameTests|WebApiDocsGeneratorMemberSignatureWarningsTests" --nologo

[claude]

Code Review: PR #113

Summary

This PR introduces comprehensive improvements to API documentation display names, sitemap canonicalization, and source path handling. Overall code quality is high with excellent test coverage.

Critical Issues

None found. The code is production-ready from a correctness perspective.

Performance Concerns

1. Inefficient Uniqueness Checking

File: PowerForge.Web/Services/WebApiDocsGenerator.ApiDocs.DisplayAndValidation.cs:685

The Values.Contains() check is O(m) for each candidate type, making the disambiguation algorithm O(n×d×m).
Recommendation: Use a HashSet for O(1) lookups instead.

2. Repeated String Splitting

File: PowerForge.Web/Services/WebApiDocsGenerator.ApiDocs.DisplayAndValidation.cs:672-674

Namespace strings are split multiple times.
Recommendation: Pre-compute and cache split namespace parts.

Code Quality

Strengths

• Security: Proper HTML encoding, XXE prevention
• Null Safety: Consistent null handling
• String Comparisons: Proper use of StringComparer.OrdinalIgnoreCase
• Immutability: Good use of IReadOnlyList/IReadOnlyDictionary
• Path Traversal Prevention: Strips ../ and ./ prefixes

Minor Issues

1. Debug.Fail only executes in debug builds (DisplayAndValidation.cs:767)
2. Consider adding loop safety counter (PathNormalization.cs:964)
3. Add comment for magic number maxSamples = 10 (DisplayAndValidation.cs:787)

Test Coverage

Excellent coverage with 443 lines of new tests covering all display modes, signature detection, and canonicalization.

Minor gaps: No tests for deep namespaces (10+ levels), Unicode, or stress tests with 100+ duplicates.

Feature Quality

Display Name Modes are well-designed with smart defaults. Sitemap Canonicalization and Source Path Normalization address real pain points.

Documentation

Clear, comprehensive, with examples and new warning codes documented.

Verdict

Approve with Minor Recommendations

This PR is production-ready with comprehensive tests and excellent documentation.

Strengths:

• Solves real adoption pain points
• High-quality test coverage
• Secure implementation
• Backward compatible

Follow-up Recommendations:

1. Optimize duplicate disambiguation (use HashSet)
2. Replace Debug.Fail with Trace.TraceWarning
3. Add loop safety counter
4. Expand edge case tests

None of the issues block merging. Performance concerns only affect pathological inputs (50+ duplicate types).

Nice work!

---

Review completed with Claude Code