Services

Remarks

AppSurface Docs accepts paths from several authoring surfaces: browser routes, source-relative Markdown metadata, generated canonical paths, and route-prefixed links. This resolver is the shared source of truth for trimming route separators, ignoring lookup fragments when selecting candidate buckets, preserving exact fragment matches when available, and ranking fallback candidates when a fragment-specific page is not present.

Remarks

Implementations combine configured include or exclude rules with traversal pruning so harvesters can avoid enumerating large excluded directory trees. All paths passed to this contract must be repository-relative and normalized with forward slashes. Absolute paths, parent-directory traversal, and platform-specific separators should be normalized by the caller before evaluation.

Remarks

Matching is case-insensitive. MatchFirst is order-dependent and returns the first configured pattern that matches the candidate. Directory helpers are conservative because pruning must never skip a file that a later allow pattern could include; callers should validate and normalize paths before invoking the matcher.

Remarks

Disabled optional harvesters are omitted from aggregate harvest-health accounting so a deliberately disabled feature cannot convert an otherwise all-failed snapshot into a degraded one. Direct calls to the harvester may still return an empty document set for compatibility.

Remarks

The helper reads at most maxFileSizeBytes + 1 bytes so oversized files can be rejected without loading the whole source into memory. Seekable streams still report their full file length in diagnostics when available.

Remarks

Callers should branch on Included before using Source. Skipped results are intended to let harvesters continue processing sibling files while surfacing a visible diagnostic.

Remarks

Candidates are produced only for variants that have a public route and a configured locale route prefix. Source paths and public route paths are normalized relative docs paths, not absolute URLs.

Remarks

The catalog deliberately separates source identity from public route identity: source path -> internal lookup and authoring provenance public route path -> browser-facing canonical URL redirect alias -> declared or Markdown source-shaped URL that redirects to public route Controllers render only public canonical winners. Declared aliases and Markdown source-shaped paths for public winners redirect to the canonical route, while non-Markdown source paths, collision losers, and reserved routes stay non-public. Link builders can still resolve source paths so authored Markdown stays source-friendly without rendering source-shaped URLs into the reader-facing surface.

Remarks

The verifier treats the version catalog as trusted host configuration. It proves that the local exact-version tree matches the digest pinned by that catalog; it does not prove who built the archive or replace future signed attestation support.

Remarks

The production adapter reads the physical release tree. Tests use custom adapters to exercise portable failure branches such as unreadable files without depending on platform-specific chmod behavior.

Remarks

The renderer accepts already-redacted progress snapshots and emits bounded markup for full pages and Turbo stream updates. It HTML-encodes text and attribute values, truncates activity to eight entries and diagnostics to four, and treats AppSurfaceDocsHarvestRunState.Completed and AppSurfaceDocsHarvestRunState.Failed as terminal states. The renderer intentionally does not accept request-derived return URLs; Razor views should emit those values through normal attribute or link rendering after validating that they are app-relative.

Remarks

This builder centralizes the route contract so controllers, view components, views, and client scripts do not each guess how the docs surface is rooted. RouteRootPath is the stable route-family root used for archive and exact-version routes. CurrentDocsRootPath is the live source-backed docs root used for current docs, search, and current search-index routes. Most consumers should copy Routes rather than assembling route strings or calling lower-level builder methods directly.

Remarks

Consumers should prefer this record when they need well-known AppSurface Docs destinations in host code, operator guidance, generated configuration, or documentation. The values are app-relative. Views and other presentation boundaries apply request PathBase separately before sending browser-facing URLs.

Remarks

This filter protects the docs-owned harvest progress channel even when a host registers an IRazorWireStreamAuthorizer after AddAppSurfaceDocs() and thereby replaces the normal Docs wrapper in Microsoft DI. The filter only gates the reserved AppSurface Docs channel; non-docs channels continue to the host authorizer unchanged.

Remarks

The manifest is an internal read model, not a second router. It contains only public canonical winners plus redirect aliases that should recover to those winners. Collision losers, reserved routes, and invalid routes stay represented by diagnostics so export and future consumers do not guess a destination for ambiguous paths.

Remarks

The aggregate health snapshot reads these diagnostics only after the harvester participates in the current snapshot. Failed, timed-out, canceled, or disabled harvesters surface through the primary harvester-health diagnostic instead.

Remarks

A harvested source path is the repository-relative or generated path assigned to a DocNode before AppSurface Docs publishes it. This helper is intentionally narrow: it exists for generated or imported non-Markdown sources such as XML API reference pages, generated JSON or YAML API specs, and imported HTML fragments that still use the historical .html route shape. Markdown documents should use DocRouteIdentityCatalog instead, because that catalog owns clean public routes, redirect aliases, collisions, and reserved-route diagnostics.

Remarks

AppSurface Docs starts from the HtmlSanitizer defaults, adds the package-owned content tags section, article, header, details, summary, pre, code, and span, and allows the class, id, open, and package-owned data-doc-code-language attributes. The sanitizer explicitly removes style from the default attribute set so harvested Markdown, generated API HTML, and server-side highlighted code can keep structural hooks while inline presentation and unsafe markup are stripped. Callers should pass already-rendered AppSurface Docs HTML through this sanitizer before display or export; supported semantic wrappers and token spans are preserved, while scripts, event handlers, inline styles, and unsupported attributes are discarded.

Remarks

The guard is intentionally filesystem-backed and fail-closed. AppSurface Docs uses it before mounting published release trees and before reading request-time files from a mounted tree so catalog metadata cannot redirect a public docs route outside the operator-owned release store.

Remarks

This adapter is intentionally local to the Docs package. It keeps the diagnostics-read policy independent from the internal Auth.AspNetCore evaluator while preserving ASP.NET Core policy authentication, challenge, forbid, and setup failure semantics for the harvest progress stream.

Remarks

This builder only uses DocsUrlBuilder and built-in public-section route contracts. It must not inspect harvested docs, search snapshots, or the missing request path. That constraint keeps standalone 404 pages deterministic during cold starts and prevents stale or hostile request paths from shaping recovery navigation. Callers that need search-result or representative-document fallback behavior should keep that logic in the search surface and adapt these links only as static route-safe entries.

Remarks

The warning is advisory and does not fail startup. This preserves compatibility for hosts that intentionally enforce diagnostics access through their application pipeline, reverse proxy, or network boundary, while making risky package exposure visible during deployment.

Remarks

AppSurfaceDocsCodeBlock stores only the first whitespace-delimited info-string token in Language because the renderer treats that token as the language hint. It does not parse full info-string attributes. Language may be null when the info string is omitted, and Code may be null when an upstream renderer provides no text, so callers must handle both defensively.

Remarks

Policy order is intentionally fixed: built-in source candidates are checked first, then global includes, source-specific includes, default exclusion groups and their allows, repository VCS ignore rules when a snapshot supplies them, global excludes, and source-specific excludes. Default groups protect build output, hidden directories, test projects, and C# source under examples. Directory pruning uses the same defaults and clear /** subtree excludes, but keeps a default-excluded subtree only when a configured group allow can match that directory or one of its descendants.

Remarks

Keep this helper as the single policy point for brand asset and home-link paths. The options post-configurator, validator, and resolved identity service all depend on the same rules so path behavior cannot drift between appsettings, environment variables, startup validation, and Razor rendering.

Remarks

Published search indexes are archive metadata, not a general URL surface. Archive payloads must store canonical /docs-rooted document paths so the published-tree rewriter can safely rebase them for aliases, exact versions, custom route roots, and request path bases at serve time. The served-path entry point is a defense-in-depth check for already-rebased browser links; it must not be used to validate immutable archive contents.

Remarks

Built-in harvesters treat the configured repository root as the read boundary. Candidate traversal therefore skips file and directory reparse points before a harvester can read content through a symlink, junction, or similar filesystem indirection. The helper preserves the existing lazy depth-first traversal shape and lets callers provide their own repository-relative directory-pruning policy.

Remarks

The resolver accepts the normalized featured_page_groups metadata on a landing document, matches each authored destination against harvested docs by source or canonical path, skips destinations that are missing, hidden, blank, or duplicated, and returns only groups that still contain at least one visible page. Logging is intentionally warning-level because curation mistakes degrade first-run docs navigation without breaking application startup.

Remarks

The harvester is enabled by default through AppSurfaceDocsJavaScriptHarvestOptions.Enabled and scans repository-relative JavaScript candidates that pass the shared harvest path policy. V1 is deliberately strict: broad discovery requires @public, treats @internal, @private, and @ignore as hard exclusions, skips file and directory reparse points before reads or descent, and turns unsupported public shapes into harvest diagnostics instead of partial docs.

Remarks

Host applications that implement IRazorWireStreamAuthorizer, or legacy IRazorWireChannelAuthorizer compatibility policies, should use IsHarvestProgressChannel(string?) when applying production authorization rules to the AppSurface Docs live harvest progress stream. Prefer the predicate over raw string comparison so future docs-owned stream naming remains centralized.

Remarks

This helper keeps the docs chrome's encoded wordmark markup in one place so layout and landing views share the same highlight splitting, CSS variable placement, and plain-text fallback. It only consumes resolved identity values; the options post-configuration and validator remain the source of truth for trimming, matching, and color safety.

Remarks

The resolved identity intentionally stores only app-relative or app-root paths. Razor views apply the current request path base at render time with Url.PathBaseAware(...), so singleton identity resolution stays safe for virtual-directory deployments and tests that render the same service provider under multiple path bases.

Remarks

The manifest stores both source paths, such as guides/start.md, and canonical browser paths, such as guides/start.md.html. Query strings and fragments are intentionally ignored because anchors and query parameters decorate a page target rather than defining a separate harvested document.

Remarks

This service accepts only validated, sanitized product-intelligence events. It stores no raw event payloads, raw search text, URLs, identity, cookies, request bodies, or free-form comments. The rolling window exists only to bound process memory while preserving enough recent aggregate signal for maintainer diagnostics.

Remarks

The service performs best-effort validation so a broken stored release tree becomes unavailable without preventing healthy versions or the live preview surface from loading. Validation is intentionally release-local: every version is checked independently for a readable tree root, the required landing and search pages, the search index, and the shared search runtime assets that exact-version pages depend on. Exact trees are otherwise treated as immutable, self-contained artifacts: outline-aware exports should include the page-local outline runtime they reference, while historical trees are not crawled or upgraded at host startup. Public AppSurfaceDocsResolvedVersion.AvailabilityIssue values are sanitized for archive UI consumption, while filesystem paths and exception details stay in structured logs only.

Remarks

Disabled means the host is running with versioning off, so callers should treat the live docs surface as the only public experience and skip published-release archive UI entirely.

EnabledWithoutCatalog means versioning was turned on but no catalog path was configured, so callers can still expose the live preview surface but should not expect any published releases to resolve.

PublicVersions preserves the ordering from Versions after filtering by AppSurfaceDocsVersionVisibility.Public only. Public-but-unavailable releases remain in that list so the archive can surface their degraded status instead of pretending they do not exist.

Remarks

Published trees are usually exported from the stable /docs surface and then mounted later under the configured route-family root or {RouteRootPath}/v/{version}. This handler resolves extensionless requests back to the exporter’s .html files and rewrites stable-root HTML or search-index payloads so the mounted tree stays version-local.

Remarks

When multiple AppSurfaceDocsPublishedTreeMount instances overlap, callers should treat the longest MountRootPath as the winning mount because the request handler resolves mounts from most-specific to least-specific roots before serving content. CanonicalRootPath controls only canonical-link metadata: normal navigation, search payloads, assets, and frozen-manifest redirects continue to use MountRootPath.

Remarks

Rewrites are mount-aware rather than file-aware. The active AppSurfaceDocsPublishedTreeMount decides which root wins, and then the rewriter adjusts exported stable-root URLs so they point at that mounted surface. The default stable /docs surface only needs HTML rewrites when the host adds a non-empty request PathBase; when the mount root and route root are still /docs and no PathBase applies, the exported HTML is already correct and is returned unchanged unless a distinct canonical root or public origin applies.

Remarks

Frozen manifests are archive-local read models. They preserve the route identity that existed when an exact release tree was exported, but they do not replace DocRouteIdentityCatalog for live source-backed docs.

Remarks

The graph is the Phase 1 localization handoff between harvesters, route identity, navigation, fallback, and search projection code. Consumers should use this graph instead of re-inferring locale state from source paths.

Remarks

Locale and translation key may be authored in metadata, inferred from a configured filename suffix, inferred from a locale folder when a translation key is authored, or defaulted to the configured default locale. Public route paths are null when route identity rejected the source path.

Remarks

This Phase 1 builder is intentionally internal. It records document identity and locale facts without changing the existing visible route or search behavior. Later slices should consume this graph instead of re-inferring locale state in controllers, views, or JavaScript.

Remarks

IAppSurfaceDocsHtmlSanitizer exists to normalize rendered package documentation fragments before AppSurface Docs displays them. It is not a general-purpose user-generated-content sanitizer, JavaScript policy, or replacement for a host-owned Content Security Policy. Unsupported elements or attributes may be removed.

Remarks

Use this abstraction when Markdown rendering needs package-owned code HTML without coupling callers to a specific highlighter implementation. Implementations must return HTML-safe output for direct insertion into docs rendering templates, including escaped plaintext fallback for unsupported languages or failed highlighting.

Remarks

The snapshot keeps VCS ignore parsing stable for a single aggregation pass and exposes only normalized, repository-relative decisions to harvesters through IHarvestPathPolicy. The configured policy is evaluated first, and VCS ignore decisions are applied as an additional exclusion layer with allow-glob restoration for intentionally public ignored content.