Add symbol-name registry for predictable, collision-free generated file names

.reviewmark.yaml

@@ -39,6 +39,7 @@ reviews:
       - requirements.yaml
       - docs/design/introduction.md
       - docs/sysml2/**/*.sysml
+      - docs/reqstream/quality.yaml
 
   # ApiMarkCore - Specials
   - id: ApiMark-Core-Architecture
@@ -115,6 +116,7 @@ reviews:
       - docs/verification/api-mark-core/emit-config.md
       - src/ApiMark.Core/EmitConfig.cs
       - src/ApiMark.Core/OutputFormat.cs
+      - test/ApiMark.Core.Tests/EmitConfigTests.cs
   - id: ApiMark-Core-IContext
     title: Review that ApiMark Core IContext Implementation is Correct
     context:
@@ -170,17 +172,22 @@ reviews:
       - docs/verification/api-mark-core/path-helpers.md
       - src/ApiMark.Core/PathHelpers.cs
       - test/ApiMark.Core.Tests/PathHelpersTests.cs
-  - id: ApiMark-Core-FileNameSanitizer
-    title: Review that ApiMark Core FileNameSanitizer Implementation is Correct
+  - id: ApiMark-Core-SymbolNameRegistry
+    title: Review that ApiMark Core SymbolNameRegistry Implementation is Correct
     context:
       - docs/design/api-mark-core.md
       - docs/reqstream/api-mark-core.yaml
     paths:
-      - docs/reqstream/api-mark-core/file-name-sanitizer.yaml
-      - docs/design/api-mark-core/file-name-sanitizer.md
-      - docs/verification/api-mark-core/file-name-sanitizer.md
-      - src/ApiMark.Core/FileNameSanitizer.cs
-      - test/ApiMark.Core.Tests/FileNameSanitizerTests.cs
+      - docs/reqstream/api-mark-core/symbol-name-registry.yaml
+      - docs/design/api-mark-core/symbol-name-registry.md
+      - docs/design/api-mark-core/file-naming-rules.md
+      - docs/verification/api-mark-core/symbol-name-registry.md
+      - src/ApiMark.Core/SymbolNameRegistry.cs
+      - src/ApiMark.Core/FileNameRules.cs
+      - src/ApiMark.Core/LinkPath.cs
+      - test/ApiMark.Core.Tests/SymbolNameRegistryTests.cs
+      - test/ApiMark.Core.Tests/FileNameRulesTests.cs
+      - test/ApiMark.Core.Tests/LinkPathTests.cs
   - id: ApiMark-Core-GlobFileCollector
     title: Review that ApiMark Core GlobFileCollector Implementation is Correct
     context:
@@ -300,6 +307,9 @@ reviews:
       - test/ApiMark.DotNet.Tests/DotNetEmitterGradualDisclosureGenericsTests.cs
       - test/ApiMark.DotNet.Tests/DotNetEmitterBreadcrumbTests.cs
       - test/ApiMark.DotNet.Tests/DotNetEmitterFileNameLegalityTests.cs
+      - src/ApiMark.DotNet/DotNetNames.cs
+      - test/ApiMark.DotNet.Tests/DotNetFileNamingTests.cs
+      - test/ApiMark.DotNet.Tests/DotNetSyntheticNamingTests.cs
       - test/ApiMark.DotNet.Fixtures/LegalNames/LegalNameShapes.cs
       - test/ApiMark.DotNet.Tests/DotNetEmitterOverloadIndexTests.cs
       - test/ApiMark.DotNet.Tests/DotNetEmitterInheritanceDocsTests.cs
@@ -460,6 +470,9 @@ reviews:
       - src/ApiMark.Cpp/CppEmitterGradualDisclosure.cs
       - test/ApiMark.Cpp.Fixtures/**/*.h
       - test/ApiMark.Cpp.Tests/CppEmitterGradualDisclosureTests.cs
+      - src/ApiMark.Cpp/CppNames.cs
+      - test/ApiMark.Cpp.Tests/CppFileNamingTests.cs
+      - test/ApiMark.Cpp.Tests/CppFixtureFileNamingTests.cs
   - id: ApiMark-Cpp-CppEmitterSingleFile
     title: Review that ApiMark Cpp CppEmitterSingleFile Implementation is Correct
     context: [docs/design/api-mark-cpp.md, docs/reqstream/api-mark-cpp.yaml]
@@ -501,6 +514,7 @@ reviews:
       - test/ApiMark.Cpp.Fixtures/**/*.h
       - test/ApiMark.Cpp.Tests/ClangAstParserTests.cs
       - test/ApiMark.Cpp.Tests/ClangDiscoveryTests.cs
+      - test/ApiMark.Cpp.Tests/ClangEnvironmentCollection.cs
   - id: ApiMark-Cpp-DocumentationCoverageChecker
     title: Review that ApiMark Cpp DocumentationCoverageChecker Implementation is
       Correct
@@ -582,6 +596,8 @@ reviews:
       - src/ApiMark.Vhdl/VhdlEmitterGradualDisclosure.cs
       - test/ApiMark.Vhdl.Tests/Fixtures/counter.vhd
       - test/ApiMark.Vhdl.Tests/VhdlEmitterGradualDisclosureTests.cs
+      - src/ApiMark.Vhdl/VhdlNames.cs
+      - test/ApiMark.Vhdl.Tests/VhdlFileNamingTests.cs
   - id: ApiMark-Vhdl-VhdlEmitterSingleFile
     title: Review that ApiMark Vhdl VhdlEmitterSingleFile Implementation is Correct
     context:
@@ -726,6 +742,7 @@ reviews:
       - docs/verification/api-mark-tool/program.md
       - src/ApiMark.Tool/Program.cs
       - test/ApiMark.Tool.Tests/ProgramTests.cs
+      - test/ApiMark.Tool.Tests/ConsoleCollection.cs
 
   # ApiMarkTool.Cli - Units
   - id: ApiMark-Tool-Cli
@@ -773,6 +790,7 @@ reviews:
       - docs/design/api-mark-tool/self-test/validation.md
       - docs/verification/api-mark-tool/self-test/validation.md
       - src/ApiMark.Tool/SelfTest/Validation.cs
+      - src/ApiMark.Tool/SelfTest/Validation.*.cs
       - test/ApiMark.Tool.Tests/SelfTest/ValidationTests.cs
 
   # OTS Items

docs/build_notes/introduction.md

@@ -41,6 +41,16 @@ Then build and test the solution:
 pwsh ./build.ps1
 ```
 
+## Breaking Changes
+
+Generated file names changed (for example `Foo-1.md` is now `Foo{1}.md`). All names now come from one
+symbol-name registry that resolves every collision before anything is written. Output is regenerated on
+each build, so no migration is needed. The rules are in
+`docs/design/api-mark-core/file-naming-rules.md`.
+
+The public `ApiMark.Core.FileNameSanitizer` type was removed. Use `SymbolNameRegistry`,
+`FileNameRules` and `LinkPath` instead.
+
 ## References
 
 [ApiMark releases](https://github.com/DemaConsulting/ApiMark/releases)

docs/design/api-mark-core.md

@@ -27,7 +27,7 @@ flowchart TD
     FileMarkdownWriter --> |implements| IMarkdownWriter
     IMarkdownWriterFactory --> |creates| IMarkdownWriter
     FileMarkdownWriterFactory --> |uses| PathHelpers
-    FileMarkdownWriterFactory --> |validates with| FileNameSanitizer
+    FileMarkdownWriterFactory --> |validates with| FileNameRules
     IApiEmitter --> |Emit uses| IMarkdownWriterFactory
     IApiEmitter --> |Emit uses| EmitConfig
     IApiEmitter --> |Emit uses| IContext
@@ -181,10 +181,12 @@ language-agnostic result types for a documentation-coverage scan.
 cross-platform path-normalization helpers used both internally by ApiMarkCore
 implementations and directly by other systems.
 
-**FileNameSanitizer (public)**: Public static utility that converts declaration names
-into file and folder name segments that are legal on Windows and Linux. Used by
-`FileMarkdownWriterFactory` for validation and by the language emitters for naming. See
-`docs/design/api-mark-core/file-name-sanitizer.md`.
+**SymbolNameRegistry (public)**: Registry that assigns every generated page a unique, legal
+file name before any file or link is written; **FileNameRules** is its character-level
+escaping and legality check, and **LinkPath** builds relative link paths. Used by the
+language emitters for naming and by `FileMarkdownWriterFactory` for validation. See
+`docs/design/api-mark-core/symbol-name-registry.md` and
+`docs/design/api-mark-core/file-naming-rules.md`.
 
 - *Type*: In-process .NET public API.
 - *Role*: Shared utility — `FileMarkdownWriterFactory` uses `SafePathCombine`

docs/design/api-mark-core/file-markdown-writer-factory.md

@@ -45,7 +45,7 @@ Creates a new `FileMarkdownWriter` targeting `{outputDirectory}/{subFolder}/{nam
 - *Algorithm*:
   1. Reject `name` if null or whitespace; throw `ArgumentException`.
   2. Reject `name`, and every `/`-separated segment of `subFolder`, that fails
-     `FileNameSanitizer.IsLegalSegment`; throw `ArgumentException`.
+     `FileNameRules.IsLegalSegment`; throw `ArgumentException`.
   3. Compute the target directory: when `subFolder` is null or whitespace, use
      `_outputDirectory` directly; otherwise call `PathHelpers.SafePathCombine`
      to combine `_outputDirectory` with `subFolder`.
@@ -78,7 +78,7 @@ Creates a new `FileMarkdownWriter` targeting `{outputDirectory}/{subFolder}/{nam
 
 - **PathHelpers** — `SafePathCombine` is used to combine the output root with the
   caller-supplied subFolder and the file name, preventing directory-traversal attacks.
-- **FileNameSanitizer** — `IsLegalSegment` validates each folder segment and the file name.
+- **FileNameRules** — `IsLegalSegment` validates each folder segment and the file name.
 
 ### Callers