0
# remark-lint-no-duplicate-definitions
1

2
remark-lint-no-duplicate-definitions is a remark-lint rule plugin that warns when identifiers are defined multiple times in Markdown documents. It integrates with the unified ecosystem to detect duplicate link reference definitions and footnote definitions, helping maintain clean and error-free Markdown by catching potential conflicts that could lead to ambiguous references.
3

4
This package is built using the `unified-lint-rule` wrapper and follows the standard remark-lint plugin patterns for consistent error reporting and integration with the remark processing pipeline.
5

6
## Package Information
7

8
- **Package Name**: remark-lint-no-duplicate-definitions
9
- **Package Type**: npm
10
- **Language**: JavaScript (ES modules)
11
- **Installation**: `npm install remark-lint-no-duplicate-definitions`
12

13
## Core Imports
14

15
```javascript
16
import remarkLintNoDuplicateDefinitions from 'remark-lint-no-duplicate-definitions';
17
```
18

19
For CommonJS (not supported - ESM only):
20
```javascript
21
// Not supported - package is ESM only
22
```
23

24
Complete imports for typical usage:
25
```javascript
26
import {unified} from 'unified';
27
import remarkParse from 'remark-parse';
28
import remarkLint from 'remark-lint';
29
import remarkLintNoDuplicateDefinitions from 'remark-lint-no-duplicate-definitions';
30
import remarkStringify from 'remark-stringify';
31
import {read} from 'to-vfile';
32
import {reporter} from 'vfile-reporter';
33
```
34

35
## Basic Usage
36

37
```javascript
38
import {unified} from 'unified';
39
import remarkParse from 'remark-parse';
40
import remarkLint from 'remark-lint';
41
import remarkLintNoDuplicateDefinitions from 'remark-lint-no-duplicate-definitions';
42
import remarkStringify from 'remark-stringify';
43
import {read} from 'to-vfile';
44
import {reporter} from 'vfile-reporter';
45

46
const file = await read('example.md');
47

48
await unified()
49
  .use(remarkParse)
50
  .use(remarkLint)
51
  .use(remarkLintNoDuplicateDefinitions)
52
  .use(remarkStringify)
53
  .process(file);
54

55
console.error(reporter(file));
56
```
57

58
## Capabilities
59

60
### Lint Rule Plugin
61

62
The main and only export of this package is a unified plugin function created using `unified-lint-rule` that provides a remark-lint rule for detecting duplicate definitions.
63

64
```javascript { .api }
65
/**
66
 * remark-lint rule to warn when identifiers are defined multiple times
67
 * Created using unified-lint-rule wrapper with origin 'remark-lint:no-duplicate-definitions'
68
 * @returns Transform function (Transformer from unified)
69
 */
70
function remarkLintNoDuplicateDefinitions(): Transformer;
71
```
72

73
**Parameters**: None (the rule takes no configuration options)
74

75
**Returns**: Transform function that can be used with unified processors
76

77
**Implementation**: This plugin is created using the `lintRule` function from `unified-lint-rule` with the configuration:
78
- **Origin**: `'remark-lint:no-duplicate-definitions'`
79
- **URL**: Documentation URL for the rule
80
- **Rule function**: Processes the markdown AST to detect duplicate definitions
81

82
**Detection Capabilities**:
83
- **Link reference definitions**: Detects when `[identifier]: url` is defined multiple times
84
- **Footnote definitions**: Detects when `[^identifier]: content` is defined multiple times (GFM/GitHub Flavored Markdown)
85

86
**Error Messages**:
87
- For duplicate link definitions: "Unexpected definition with an already defined identifier (`identifier`), expected unique identifiers"
88
- For duplicate footnote definitions: "Unexpected footnote definition with an already defined identifier (`identifier`), expected unique identifiers"
89

90
## Usage Examples
91

92
### Valid Markdown (No Warnings)
93

94
```markdown
95
[mercury]: https://example.com/mercury/
96
[venus]: https://example.com/venus/
97
```
98

99
### Invalid Markdown (Produces Warning)
100

101
```markdown
102
[mercury]: https://example.com/mercury/
103
[mercury]: https://example.com/venus/
104
```
105

106
Warning: `2:1-2:38: Unexpected definition with an already defined identifier (mercury), expected unique identifiers`
107

108
### Footnote Definitions (GFM)
109

110
```markdown
111
Mercury[^mercury].
112

113
[^mercury]:
114
  Mercury is the first planet from the Sun and the smallest in the Solar System.
115

116
[^mercury]:
117
  Venus is the second planet from the Sun.
118
```
119

120
Warning: `7:1-7:12: Unexpected footnote definition with an already defined identifier (mercury), expected unique identifiers`
121

122
## Integration
123

124
### CLI Usage
125

126
```bash
127
remark --frail --use remark-lint --use remark-lint-no-duplicate-definitions .
128
```
129

130
### Configuration File
131

132
```json
133
{
134
  "remarkConfig": {
135
    "plugins": [
136
      "remark-lint",
137
      "remark-lint-no-duplicate-definitions"
138
    ]
139
  }
140
}
141
```
142

143
## Types
144

145
This package is written in JavaScript but includes TypeScript type definitions (published as `index.d.ts`). It follows the unified ecosystem patterns:
146

147
```typescript { .api }
148
// TypeScript definitions are available
149
import type {Transformer} from 'unified';
150
import type {Root} from 'mdast';
151
import type {Nodes} from 'mdast';
152

153
// The plugin function signature
154
function remarkLintNoDuplicateDefinitions(): Transformer<Root>;
155

156
// Internal types used by the implementation
157
type DefinitionNode = Extract<Nodes, {type: 'definition'}>;
158
type FootnoteDefinitionNode = Extract<Nodes, {type: 'footnoteDefinition'}>;
159
```
160

161
### Type Dependencies
162

163
The implementation uses these key type imports:
164
```typescript { .api }
165
import type {Nodes, Root} from 'mdast';
166
// From the source code internal types
167
```
168

169
## Error Handling
170

171
The plugin creates VFileMessage objects with detailed information:
172
- **Location**: Precise position information for both original and duplicate definitions
173
- **Context**: Full ancestor tree information for better error reporting
174
- **Cause**: References to the original definition location using nested VFileMessage
175
- **Source**: Always marked as 'remark-lint' with rule ID 'no-duplicate-definitions'
176

177
### VFileMessage Structure
178

179
When duplicate definitions are found, the plugin creates messages with this structure:
180
```javascript { .api }
181
// Primary error message
182
file.message(
183
  'Unexpected [footnote ]definition with an already defined identifier (`identifier`), expected unique identifiers',
184
  {
185
    ancestors: [...parents, node], // Full ancestry chain
186
    cause: new VFileMessage('Identifier already defined here', {
187
      ancestors: duplicateAncestors, // Original definition ancestry
188
      place: duplicate.position,     // Original definition position
189
      source: 'remark-lint',
190
      ruleId: 'no-duplicate-definitions'
191
    }),
192
    place: node.position // Current duplicate position
193
  }
194
);
195
```
196

197
## Implementation Notes
198

199
- **Performance**: Skips phrasing content during AST traversal using `mdast-util-phrasing` for optimal performance
200
- **Scope**: Only processes `definition` and `footnoteDefinition` nodes
201
- **Tracking**: Maintains separate `Map<string, Array<Nodes>>` objects for regular definitions and footnote definitions
202
- **Ancestry**: Preserves full parent chain information for detailed error reporting
203
- **Traversal**: Uses `unist-util-visit-parents` for efficient AST walking with ancestor tracking
204
- **Assertion**: Uses `devlop` package for development-time assertions
205

206
### Dependencies Used
207

208
The implementation relies on these core dependencies:
209
```javascript { .api }
210
import {ok as assert} from 'devlop';                    // Development assertions
211
import {phrasing} from 'mdast-util-phrasing';           // Skip phrasing content
212
import {lintRule} from 'unified-lint-rule';             // Lint rule wrapper
213
import {SKIP, visitParents} from 'unist-util-visit-parents'; // AST traversal
214
import {VFileMessage} from 'vfile-message';             // Error message creation
215
```
216

217
This rule is part of the `remark-preset-lint-recommended` preset and integrates seamlessly with other remark-lint rules and the broader unified ecosystem.