Fix Markdown heading fragment resolution

DEVELOPER_GUIDE.md

@@ -638,6 +638,7 @@ Do not add mutable static caches, shared `StringBuilder` instances, reused `Matc
 |---|---|---|
 | `accessor` | Accessor declarations when extracted separately from their owning property | Search/filter symbol |
 | `add` | Dockerfile `ADD` destination paths | Dependency/file-flow search symbol |
+| `anchor` | Explicit Markdown HTML anchors, preserving exact ID case and punctuation after HTML entity decoding | Definition target for path-scoped Markdown fragment references |
 | `annotation` | Annotation declarations or annotation-like language constructs | Metadata/search symbol |
 | `async_function` | JavaScript/TypeScript async function declarations | Callable definition; participates in callers/callees through reference rows |
 | `async_generator` | JavaScript/TypeScript async generator declarations | Callable definition; participates in callers/callees through reference rows |
@@ -659,7 +660,7 @@ Do not add mutable static caches, shared `StringBuilder` instances, reused `Matc
 | `file_module` | File-scoped module/package declarations | Namespace-like context symbol |
 | `function` | Functions, methods, constructors, delegates, tasks, and callable bindings that do not have a narrower kind | Primary callable definition; participates in callers/callees through reference rows |
 | `generator` | JavaScript/TypeScript generator declarations | Callable definition; participates in callers/callees through reference rows |
-| `heading` | Markdown headings and language section markers such as C# regions, Python module docstrings, and JavaScript/TypeScript `@module` docblocks | Outline symbol |
+| `heading` | Markdown headings and language section markers such as C# regions, Python module docstrings, and JavaScript/TypeScript `@module` docblocks | Outline symbol; Markdown headings are definition targets for path-scoped fragment references |
 | `hook` | JavaScript/TypeScript React custom hook bindings | Callable-like search/filter symbol |
 | `implements` | Razor `@implements` directives | Context/search symbol |
 | `import` | Imports, using directives, aliases, and package includes | Search/filter symbol |
@@ -3784,6 +3785,7 @@ filter、downstream JSON consumer が同じ値を理解できるようにして
 |---|---|---|
 | `accessor` | owning property から別 symbol として抽出される accessor declaration | Search/filter symbol |
 | `add` | Dockerfile `ADD` の destination path | dependency / file-flow search symbol |
+| `anchor` | HTML entity の decode 後も ID の大文字小文字と句読点を正確に保持する Markdown 内の明示的な HTML anchor | path に限定した Markdown fragment reference の定義対象 |
 | `annotation` | annotation declaration または annotation-like な言語構文 | Metadata/search symbol |
 | `async_function` | JavaScript / TypeScript の async function declaration | Callable definition。reference row 経由で callers/callees に参加 |
 | `async_generator` | JavaScript / TypeScript の async generator declaration | Callable definition。reference row 経由で callers/callees に参加 |
@@ -3805,7 +3807,7 @@ filter、downstream JSON consumer が同じ値を理解できるようにして
 | `file_module` | file-scoped module / package declaration | Namespace-like context symbol |
 | `function` | 関数、method、constructor、delegate、task、およびより狭い kind がない callable binding | Primary callable definition。reference row 経由で callers/callees に参加 |
 | `generator` | JavaScript / TypeScript generator declaration | Callable definition。reference row 経由で callers/callees に参加 |
-| `heading` | Markdown heading、C# region、Python module docstring、JavaScript / TypeScript `@module` docblock などの language section marker | Outline symbol |
+| `heading` | Markdown heading、C# region、Python module docstring、JavaScript / TypeScript `@module` docblock などの language section marker | Outline symbol。Markdown heading は path に限定した fragment reference の定義対象 |
 | `hook` | JavaScript / TypeScript React custom hook binding | Callable-like search/filter symbol |
 | `implements` | Razor `@implements` directive | Context/search symbol |
 | `import` | import、using directive、alias、package include | Search/filter symbol |

USER_GUIDE.md

@@ -2478,7 +2478,7 @@ All indexed languages are searchable through FTS5. Rows with **Symbols = yes** a
 - Dynamic/declarative graph languages: Crystal, Groovy, Tcl, and Prolog expose conservative declarations, imports, and call relationships. Crystal, Groovy, and Prolog parenthesized calls use the shared extractor; command-style calls are limited to callables declared in the same file. Tcl recognizes command substitutions and common control-command script arguments without treating ordinary `name()` words as calls, while Tcl proc / Prolog predicate bodies preserve caller containers.
   An index created before this graph contract reports `reference_graph_complete=false` and `graph_data_current=false` with `dynamic_reference_graph_contract_stale`; rerun `cdidx index <projectPath>` to refresh affected rows before treating absent edges as authoritative.
 - Scientific and native-extension graphs: Julia, MATLAB, Nim, D, Cython, and Ada emit bounded language-aware import/module, base/type, and call references. Julia macro invocations and Ada procedure-style calls without parentheses are also represented.
-- Markdown, JSON/YAML, and CSS: Markdown heading and local-anchor symbols are indexed; JSON/YAML configuration keys are indexed as structural key paths; CSS variables, placeholders, and `@extend` references are indexed.
+- Markdown, JSON/YAML, and CSS: Markdown headings and explicit HTML anchors are indexed as definitions, while local and cross-document fragment links are indexed as path-scoped references. Heading slugs use rendered inline text; explicit HTML IDs preserve exact case and punctuation after HTML entity decoding. JSON/YAML configuration keys are indexed as structural key paths; CSS variables, placeholders, and `@extend` references are indexed.
 - Dockerfile, Assembly, Common Lisp, and Racket: `ARG` build args, labels/PROC/MACRO blocks, package/module forms, definitions, classes/structs, requires, and provides are surfaced as symbols where applicable.
 - Shell, PowerShell, and Batch: command-style function calls, functions/filters, classes/enums, imports, labels, `goto` / `call` targets, and inline control-flow forms are indexed where the language supports them.
 - C# and Java: modern C# partial members remain visible to `symbols`, `definition`, and `outline`; Java sealed `permits` lists are recorded as `type_reference` graph edges.
@@ -2526,7 +2526,7 @@ entries with the unsupported capability, an explanatory message, and
 | Shell / PowerShell / Batch / Makefile / CMake / Justfile / MSBuild / Gradle | functions, labels, targets, recipes, tasks, imports where applicable | command-style calls, target dependencies, and control-flow targets | Runtime command construction is not resolved. |
 | Solution / application manifest | solution projects and manifest identity/settings | solution project references; application manifests are symbol-only | `.sln` project paths are graph edges for repository structure; use `symbols --lang app_manifest` for Windows manifest metadata. |
 | SQL / Terraform / Dockerfile | statements/resources/stages/labels | table/resource/stage references, Dockerfile stage dependencies, Terraform dotted refs | SQL hotspot grouping defaults to statements; Dockerfile `COPY --from=<stage>` follows named stages. |
-| Markdown / HTML / CSS / Sass / Stylus / XML / XAML / GraphQL / Protobuf | headings, anchors, selectors, UI elements, generic XML element/attribute paths, schema types/messages where supported | links/assets/components, local anchors, CSS/Sass/Stylus imports, variables, mixins/functions, XAML resources/bindings/handlers, schema references where supported | Generic non-XAML XML emits bounded structural symbols; use `search` for prose and generated markup. |
+| Markdown / HTML / CSS / Sass / Stylus / XML / XAML / GraphQL / Protobuf | headings, explicit anchors, selectors, UI elements, generic XML element/attribute paths, schema types/messages where supported | links/assets/components, path-scoped local and cross-document fragments, CSS/Sass/Stylus imports, variables, mixins/functions, XAML resources/bindings/handlers, schema references where supported | Markdown fragment references resolve only against headings or explicit anchors in the linked document. Generic non-XAML XML emits bounded structural symbols; use `search` for prose and generated markup. |
 | Dependency manifests / lockfiles | none | none | Use `--lang dependency_manifest` or `--lang dependency_lock` for dependency/security audits. |
 | Other indexed text formats | file/chunk search only unless `languages` reports symbols | no graph unless `languages` reports support | `cdidx search "literal" --lang yaml` is the reliable fallback. |
 
@@ -5568,7 +5568,7 @@ indexing はファイル単位の SQLite transaction を commit します。長
 - 動的・宣言型言語の graph 対応: Crystal、Groovy、Tcl、Prolog は保守的な宣言、import、call relationship を公開します。Crystal、Groovy、Prolog の括弧付き call は共通 extractor を使い、command-style call は同一ファイルで宣言済みの callable に限定します。Tcl は通常の `name()` word を call とみなさず、command substitution と主要な制御 command の script 引数を認識し、Tcl proc / Prolog predicate の本体では caller container を保持します。
   この graph contract より前に作成された index は `dynamic_reference_graph_contract_stale` とともに `reference_graph_complete=false`、`graph_data_current=false` を報告します。欠落 edge を authoritative とみなす前に `cdidx index <projectPath>` を再実行して対象 row を更新してください。
 - 科学技術・ネイティブ拡張言語のグラフ: Julia、MATLAB、Nim、D、Cython、Ada は、言語構文に応じた import/module、基底型/type、call 参照を上限付きで出力します。Julia の macro invocation と、括弧を伴わない Ada の procedure call も記録します。
-- Markdown、JSON/YAML、CSS: Markdown の heading / local anchor、JSON/YAML の configuration key path、CSS の variable、placeholder、`@extend` をシンボルとして扱います。
+- Markdown、JSON/YAML、CSS: Markdown の heading と明示的な HTML anchor は定義として、同一文書・文書間の fragment link は対象 path に限定した参照として索引します。heading slug は表示される inline text から作り、明示的な HTML ID は HTML entity の decode 後も大文字小文字と句読点を正確に保持します。JSON/YAML の configuration key path、CSS の variable、placeholder、`@extend` もシンボルとして扱います。
 - Dockerfile、Assembly、Common Lisp、Racket: `ARG` build arg、label、PROC/MACRO、package/module form、definition、class/struct、require/provide を必要に応じて表面化します。
 - Shell、PowerShell、Batch: command-style function call、function/filter、class/enum、import、label、`goto` / `call` target、inline control-flow を言語仕様に合わせて索引します。
 - C# と Java: C# の近年の partial member は `symbols`、`definition`、`outline` から見えます。Java の sealed `permits` list は `type_reference` graph edge として記録します。
@@ -5610,7 +5610,7 @@ indexing はファイル単位の SQLite transaction を commit します。長
 | Shell / PowerShell / Batch / Makefile / CMake / Justfile / MSBuild / Gradle | function、label、target、recipe、task、対応言語の import | command-style call、target dependency、control-flow target | runtime で組み立てられる command は解決しません。 |
 | ソリューション / アプリケーションマニフェスト | solution project、manifest identity / setting | `.sln` の project reference。manifest は symbol-only | `.sln` の project path はリポジトリ構造の graph edge です。Windows manifest metadata は `symbols --lang app_manifest` で確認できます。 |
 | SQL / Terraform / Dockerfile | statement/resource/stage/label | table/resource/stage reference、Dockerfile stage dependency、Terraform dotted refs | SQL hotspot grouping は既定で statement、Dockerfile `COPY --from=<stage>` は named stage を追跡します。 |
-| Markdown / HTML / CSS / Sass / Stylus / XML / XAML / GraphQL / Protobuf | heading、anchor、selector、UI element、汎用 XML の要素・属性パス、対応 schema type/message | link/asset/component、local anchor、CSS/Sass/Stylus の import・variable・mixin/function、XAML resource / binding / handler、対応 schema reference | 汎用の非 XAML XML は上限付きの構造シンボルを出力します。prose や generated markup には `search` を使ってください。 |
+| Markdown / HTML / CSS / Sass / Stylus / XML / XAML / GraphQL / Protobuf | heading、明示的な anchor、selector、UI element、汎用 XML の要素・属性パス、対応 schema type/message | link/asset/component、path に限定した同一文書・文書間の fragment、CSS/Sass/Stylus の import・variable・mixin/function、XAML resource / binding / handler、対応 schema reference | Markdown の fragment reference は、リンク先文書内の heading または明示的な anchor にのみ解決します。汎用の非 XAML XML は上限付きの構造シンボルを出力します。prose や generated markup には `search` を使ってください。 |
 | Dependency manifest / lockfile | なし | なし | dependency / security audit には `--lang dependency_manifest` または `--lang dependency_lock` を使います。 |
 | その他の indexed text format | `languages` が symbol 対応を示す場合を除き file/chunk search のみ | `languages` が graph 対応を示す場合を除きなし | `cdidx search "literal" --lang yaml` が信頼できる fallback です。 |
 

changelog.d/unreleased/4846.fixed.md

@@ -0,0 +1,35 @@
+---
+category: fixed
+issues:
+  - 4846
+affected:
+  - src/CodeIndex/Database/DbContext.ConnectionFunctions.cs
+  - src/CodeIndex/Database/DbContext.SchemaMetadata.cs
+  - src/CodeIndex/Indexer/MarkdownAnchorIdentity.cs
+  - src/CodeIndex/Models/SymbolKindCatalog.cs
+  - src/CodeIndex/Indexer/Symbols/SymbolExtractor.Markup.cs
+  - src/CodeIndex/Indexer/Symbols/SymbolExtractor.Contracts.cs
+  - src/CodeIndex/Indexer/References/Languages/MarkupSchemaReferenceExtractor.cs
+  - src/CodeIndex/Indexer/References/ReferenceExtractor.CoreReferenceLoop.cs
+  - src/CodeIndex/Indexer/References/ReferenceExtractor.ReferenceRecords.cs
+  - src/CodeIndex/Database/DbSymbolReader.Definitions.cs
+  - src/CodeIndex/Database/DbSymbolReader.Search.cs
+  - src/CodeIndex/Database/DbWriter.FoldBackfill.cs
+  - src/CodeIndex/Database/DbWriter.References.cs
+  - src/CodeIndex/Database/DbWriter.ReferenceGraphRefreshScope.cs
+  - tests/CodeIndex.Tests/DbReaderFileDependencyTests.cs
+  - tests/CodeIndex.Tests/DatabaseTests.cs
+  - tests/CodeIndex.Tests/ReferenceExtractorTests.cs
+  - tests/CodeIndex.Tests/SymbolExtractorTests.cs
+  - tests/CodeIndex.Tests/IndexCommandRunnerUpdateTests.cs
+  - USER_GUIDE.md
+  - DEVELOPER_GUIDE.md
+---
+
+## English
+
+- **Markdown fragment links now resolve to path-scoped heading and explicit-anchor definitions (#4846)** — local and cross-document links use rendered heading text for normalized slugs, preserve exact case and punctuation for entity-decoded explicit HTML IDs, refresh references when only the target document changes, keep duplicate heading slugs distinct, and no longer create false dependency edges from equal heading names in unrelated documents. This completes the Markdown definition follow-up to #4113.
+
+## 日本語
+
+- **Markdown の fragment link が path に限定された heading と明示的な anchor の定義へ解決されるようになりました (#4846)** — 同一文書・文書間の link は表示される heading text から正規化した slug を作り、entity を decode した明示的な HTML ID の大文字小文字と句読点を正確に保持し、対象文書だけが変わった場合も参照を更新し、重複する heading slug を区別します。また、無関係な文書の同名 heading による誤った依存 edge を作らなくなりました。これは #4113 に続く Markdown definition の修正です。

src/CodeIndex/Database/DbContext.ConnectionFunctions.cs

@@ -31,6 +31,11 @@ internal static void RegisterConnectionFunctions(SqliteConnection connection)
         connection.CreateFunction(
             "markdown_resolve_path",
             (string? sourcePath, string? targetPath) => DbReader.ResolveMarkdownDependencyPath(sourcePath, targetPath));
+        connection.CreateFunction(
+            "markdown_normalize_fragment",
+            (string? fragment) => fragment == null
+                ? null
+                : MarkdownAnchorIdentity.NormalizeHeadingFragment(fragment));
         connection.CreateFunction(
             "python_import_resolves",
             (string? sourcePath, string? targetPath, string? referenceName, string? referenceKind, string? context, long? columnNumber, string? signature) =>

src/CodeIndex/Database/DbContext.SchemaMetadata.cs

@@ -62,13 +62,15 @@ public static string BuildIncompleteHotspotFamilyMarkerFingerprint(string? finge
     public const string SqlGraphContractVersionMetaKey = "sql_graph_contract_version";
     public const int HdlGraphContractVersion = 1;
     public const string HdlGraphContractVersionMetaKey = "hdl_graph_contract_version";
-    // Version 4 (#4845) invalidates dependency-lock candidates written before resolution
-    // became file-local. Version 3 (#4825) previously invalidated C# type-reference
-    // candidates written before type-like kind and compatible generic-arity constraints.
-    // バージョン 4 (#4845) では、解決を file 内に限定する前に書かれた dependency-lock
-    // candidate を無効化する。バージョン 3 (#4825) では、それ以前に C# 型参照の
-    // type-like kind / 互換 generic arity 制約より前に書かれた candidate を無効化した。
-    public const int ReferenceIdentityContractVersion = 4;
+    // Version 5 (#4846) invalidates name-only Markdown candidates written before
+    // fragment resolution became document/path-scoped. Version 4 (#4845) previously
+    // invalidated dependency-lock candidates written before resolution became file-local,
+    // and version 3 (#4825) constrained C# type-reference candidates by kind and arity.
+    // バージョン 5 (#4846) では、Markdown fragment の解決を document/path 内に限定する
+    // 前に書かれた name-only candidate を無効化する。バージョン 4 (#4845) では、それ以前の
+    // dependency-lock candidate を file 内に限定し、バージョン 3 (#4825) では C# 型参照を
+    // kind と arity で制約した。
+    public const int ReferenceIdentityContractVersion = 5;
     public const string ReferenceIdentityContractVersionMetaKey = "reference_identity_contract_version";
     public static string GetDynamicReferenceGraphContractVersionMetaKey(string lang) =>
         $"dynamic_reference_graph_contract_version_{lang}";