@hia-doc/dotnetdoc-runner 0.1.12 → 1.0.0-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,284 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://mandolin.github.io/HIA-Documentation/schemas/dotnetdoc-config-0.1.0-draft.schema.json",
4
+ "title": "DotNetDoc Config",
5
+ "type": "object",
6
+ "additionalProperties": false,
7
+ "required": [
8
+ "schemaVersion",
9
+ "workspaceRoot",
10
+ "outputDirectory",
11
+ "inputs"
12
+ ],
13
+ "properties": {
14
+ "$schema": {
15
+ "const": "https://mandolin.github.io/HIA-Documentation/schemas/dotnetdoc-config-0.1.0-draft.schema.json"
16
+ },
17
+ "schemaVersion": {
18
+ "const": "0.1.0-draft"
19
+ },
20
+ "workspaceRoot": {
21
+ "type": "string",
22
+ "minLength": 1,
23
+ "not": {
24
+ "anyOf": [
25
+ {
26
+ "pattern": "^(?:[A-Za-z]:|/|\\\\|[A-Za-z][A-Za-z0-9+.-]*:)"
27
+ },
28
+ {
29
+ "pattern": ":"
30
+ },
31
+ {
32
+ "pattern": "(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)"
33
+ }
34
+ ]
35
+ }
36
+ },
37
+ "outputDirectory": {
38
+ "type": "string",
39
+ "minLength": 1,
40
+ "not": {
41
+ "anyOf": [
42
+ {
43
+ "pattern": "^(?:[A-Za-z]:|/|\\\\|[A-Za-z][A-Za-z0-9+.-]*:)"
44
+ },
45
+ {
46
+ "pattern": ":"
47
+ },
48
+ {
49
+ "pattern": "(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)"
50
+ }
51
+ ]
52
+ }
53
+ },
54
+ "inputs": {
55
+ "type": "array",
56
+ "minItems": 1,
57
+ "items": {
58
+ "type": "object",
59
+ "additionalProperties": false,
60
+ "required": [
61
+ "kind"
62
+ ],
63
+ "anyOf": [
64
+ {
65
+ "required": [
66
+ "path"
67
+ ]
68
+ },
69
+ {
70
+ "required": [
71
+ "paths"
72
+ ]
73
+ },
74
+ {
75
+ "required": [
76
+ "projectPath"
77
+ ]
78
+ },
79
+ {
80
+ "required": [
81
+ "glob"
82
+ ]
83
+ },
84
+ {
85
+ "required": [
86
+ "globs"
87
+ ]
88
+ }
89
+ ],
90
+ "properties": {
91
+ "kind": {
92
+ "enum": [
93
+ "dotnet-xml-doc",
94
+ "dotnet-csharp-source",
95
+ "dotnet-aspnet-surface",
96
+ "dotnet-markup-comments",
97
+ "dotnet-project"
98
+ ]
99
+ },
100
+ "path": {
101
+ "type": "string",
102
+ "minLength": 1,
103
+ "not": {
104
+ "anyOf": [
105
+ {
106
+ "pattern": "^(?:[A-Za-z]:|/|\\\\|[A-Za-z][A-Za-z0-9+.-]*:)"
107
+ },
108
+ {
109
+ "pattern": ":"
110
+ },
111
+ {
112
+ "pattern": "(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)"
113
+ }
114
+ ]
115
+ }
116
+ },
117
+ "paths": {
118
+ "type": "array",
119
+ "minItems": 1,
120
+ "items": {
121
+ "type": "string",
122
+ "minLength": 1,
123
+ "not": {
124
+ "anyOf": [
125
+ {
126
+ "pattern": "^(?:[A-Za-z]:|/|\\\\|[A-Za-z][A-Za-z0-9+.-]*:)"
127
+ },
128
+ {
129
+ "pattern": ":"
130
+ },
131
+ {
132
+ "pattern": "(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)"
133
+ }
134
+ ]
135
+ }
136
+ }
137
+ },
138
+ "projectPath": {
139
+ "type": "string",
140
+ "minLength": 1,
141
+ "not": {
142
+ "anyOf": [
143
+ {
144
+ "pattern": "^(?:[A-Za-z]:|/|\\\\|[A-Za-z][A-Za-z0-9+.-]*:)"
145
+ },
146
+ {
147
+ "pattern": ":"
148
+ },
149
+ {
150
+ "pattern": "(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)"
151
+ }
152
+ ]
153
+ }
154
+ },
155
+ "glob": {
156
+ "type": "string",
157
+ "minLength": 1,
158
+ "not": {
159
+ "anyOf": [
160
+ {
161
+ "pattern": "^(?:[A-Za-z]:|/|\\\\|[A-Za-z][A-Za-z0-9+.-]*:)"
162
+ },
163
+ {
164
+ "pattern": ":"
165
+ },
166
+ {
167
+ "pattern": "(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)"
168
+ }
169
+ ]
170
+ }
171
+ },
172
+ "globs": {
173
+ "type": "array",
174
+ "minItems": 1,
175
+ "items": {
176
+ "type": "string",
177
+ "minLength": 1,
178
+ "not": {
179
+ "anyOf": [
180
+ {
181
+ "pattern": "^(?:[A-Za-z]:|/|\\\\|[A-Za-z][A-Za-z0-9+.-]*:)"
182
+ },
183
+ {
184
+ "pattern": ":"
185
+ },
186
+ {
187
+ "pattern": "(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)"
188
+ }
189
+ ]
190
+ }
191
+ }
192
+ },
193
+ "excludeGlobs": {
194
+ "type": "array",
195
+ "minItems": 1,
196
+ "items": {
197
+ "type": "string",
198
+ "minLength": 1,
199
+ "not": {
200
+ "anyOf": [
201
+ {
202
+ "pattern": "^(?:[A-Za-z]:|/|\\\\|[A-Za-z][A-Za-z0-9+.-]*:)"
203
+ },
204
+ {
205
+ "pattern": ":"
206
+ },
207
+ {
208
+ "pattern": "(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)"
209
+ }
210
+ ]
211
+ }
212
+ }
213
+ },
214
+ "applicationRoot": {
215
+ "type": "string",
216
+ "minLength": 1,
217
+ "not": {
218
+ "anyOf": [
219
+ {
220
+ "pattern": "^(?:[A-Za-z]:|/|\\\\|[A-Za-z][A-Za-z0-9+.-]*:)"
221
+ },
222
+ {
223
+ "pattern": ":"
224
+ },
225
+ {
226
+ "pattern": "(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)"
227
+ }
228
+ ]
229
+ }
230
+ },
231
+ "artifactBasePath": {
232
+ "type": "string",
233
+ "minLength": 1,
234
+ "not": {
235
+ "anyOf": [
236
+ {
237
+ "pattern": "^(?:[A-Za-z]:|/|\\\\|[A-Za-z][A-Za-z0-9+.-]*:)"
238
+ },
239
+ {
240
+ "pattern": ":"
241
+ },
242
+ {
243
+ "pattern": "(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)"
244
+ }
245
+ ]
246
+ }
247
+ },
248
+ "hiaDocumentId": {
249
+ "type": "string",
250
+ "minLength": 1
251
+ },
252
+ "title": {
253
+ "type": "string",
254
+ "minLength": 1
255
+ }
256
+ }
257
+ }
258
+ },
259
+ "options": {
260
+ "type": "object",
261
+ "additionalProperties": false,
262
+ "properties": {
263
+ "writeResultManifest": {
264
+ "type": "boolean"
265
+ },
266
+ "writeSourceRelationArtifact": {
267
+ "type": "boolean"
268
+ },
269
+ "writeDocSourceMapArtifact": {
270
+ "type": "boolean"
271
+ }
272
+ }
273
+ },
274
+ "profileIds": {
275
+ "type": "array",
276
+ "minItems": 1,
277
+ "uniqueItems": true,
278
+ "items": {
279
+ "type": "string",
280
+ "pattern": "^[a-z0-9][a-z0-9._-]*$"
281
+ }
282
+ }
283
+ }
284
+ }
@@ -0,0 +1,283 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://mandolin.github.io/HIA-Documentation/schemas/dotnetdoc-config-1.0.0.schema.json",
4
+ "$comment": "中文:当前配置保留目录省略默认、要求显式输入kind并拒绝null;验证不授权执行。 English: Current config retains omission defaults, requires explicit input kinds and rejects null; validation grants no execution permission.",
5
+ "title": "DotNetDoc Config",
6
+ "type": "object",
7
+ "additionalProperties": false,
8
+ "required": [
9
+ "schemaVersion",
10
+ "inputs"
11
+ ],
12
+ "properties": {
13
+ "$schema": {
14
+ "const": "https://mandolin.github.io/HIA-Documentation/schemas/dotnetdoc-config-1.0.0.schema.json"
15
+ },
16
+ "schemaVersion": {
17
+ "const": "1.0.0"
18
+ },
19
+ "workspaceRoot": {
20
+ "type": "string",
21
+ "minLength": 1,
22
+ "not": {
23
+ "anyOf": [
24
+ {
25
+ "pattern": "^(?:[A-Za-z]:|/|\\\\|[A-Za-z][A-Za-z0-9+.-]*:)"
26
+ },
27
+ {
28
+ "pattern": ":"
29
+ },
30
+ {
31
+ "pattern": "(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)"
32
+ }
33
+ ]
34
+ }
35
+ },
36
+ "outputDirectory": {
37
+ "type": "string",
38
+ "minLength": 1,
39
+ "not": {
40
+ "anyOf": [
41
+ {
42
+ "pattern": "^(?:[A-Za-z]:|/|\\\\|[A-Za-z][A-Za-z0-9+.-]*:)"
43
+ },
44
+ {
45
+ "pattern": ":"
46
+ },
47
+ {
48
+ "pattern": "(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)"
49
+ }
50
+ ]
51
+ }
52
+ },
53
+ "inputs": {
54
+ "type": "array",
55
+ "minItems": 1,
56
+ "items": {
57
+ "type": "object",
58
+ "additionalProperties": false,
59
+ "required": [
60
+ "kind"
61
+ ],
62
+ "anyOf": [
63
+ {
64
+ "required": [
65
+ "path"
66
+ ]
67
+ },
68
+ {
69
+ "required": [
70
+ "paths"
71
+ ]
72
+ },
73
+ {
74
+ "required": [
75
+ "projectPath"
76
+ ]
77
+ },
78
+ {
79
+ "required": [
80
+ "glob"
81
+ ]
82
+ },
83
+ {
84
+ "required": [
85
+ "globs"
86
+ ]
87
+ }
88
+ ],
89
+ "properties": {
90
+ "kind": {
91
+ "enum": [
92
+ "dotnet-xml-doc",
93
+ "dotnet-csharp-source",
94
+ "dotnet-aspnet-surface",
95
+ "dotnet-markup-comments",
96
+ "dotnet-project"
97
+ ]
98
+ },
99
+ "path": {
100
+ "type": "string",
101
+ "minLength": 1,
102
+ "not": {
103
+ "anyOf": [
104
+ {
105
+ "pattern": "^(?:[A-Za-z]:|/|\\\\|[A-Za-z][A-Za-z0-9+.-]*:)"
106
+ },
107
+ {
108
+ "pattern": ":"
109
+ },
110
+ {
111
+ "pattern": "(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)"
112
+ }
113
+ ]
114
+ }
115
+ },
116
+ "paths": {
117
+ "type": "array",
118
+ "minItems": 1,
119
+ "items": {
120
+ "type": "string",
121
+ "minLength": 1,
122
+ "not": {
123
+ "anyOf": [
124
+ {
125
+ "pattern": "^(?:[A-Za-z]:|/|\\\\|[A-Za-z][A-Za-z0-9+.-]*:)"
126
+ },
127
+ {
128
+ "pattern": ":"
129
+ },
130
+ {
131
+ "pattern": "(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)"
132
+ }
133
+ ]
134
+ }
135
+ }
136
+ },
137
+ "projectPath": {
138
+ "type": "string",
139
+ "minLength": 1,
140
+ "not": {
141
+ "anyOf": [
142
+ {
143
+ "pattern": "^(?:[A-Za-z]:|/|\\\\|[A-Za-z][A-Za-z0-9+.-]*:)"
144
+ },
145
+ {
146
+ "pattern": ":"
147
+ },
148
+ {
149
+ "pattern": "(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)"
150
+ }
151
+ ]
152
+ }
153
+ },
154
+ "glob": {
155
+ "type": "string",
156
+ "minLength": 1,
157
+ "not": {
158
+ "anyOf": [
159
+ {
160
+ "pattern": "^(?:[A-Za-z]:|/|\\\\|[A-Za-z][A-Za-z0-9+.-]*:)"
161
+ },
162
+ {
163
+ "pattern": ":"
164
+ },
165
+ {
166
+ "pattern": "(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)"
167
+ }
168
+ ]
169
+ }
170
+ },
171
+ "globs": {
172
+ "type": "array",
173
+ "minItems": 1,
174
+ "items": {
175
+ "type": "string",
176
+ "minLength": 1,
177
+ "not": {
178
+ "anyOf": [
179
+ {
180
+ "pattern": "^(?:[A-Za-z]:|/|\\\\|[A-Za-z][A-Za-z0-9+.-]*:)"
181
+ },
182
+ {
183
+ "pattern": ":"
184
+ },
185
+ {
186
+ "pattern": "(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)"
187
+ }
188
+ ]
189
+ }
190
+ }
191
+ },
192
+ "excludeGlobs": {
193
+ "type": "array",
194
+ "minItems": 1,
195
+ "items": {
196
+ "type": "string",
197
+ "minLength": 1,
198
+ "not": {
199
+ "anyOf": [
200
+ {
201
+ "pattern": "^(?:[A-Za-z]:|/|\\\\|[A-Za-z][A-Za-z0-9+.-]*:)"
202
+ },
203
+ {
204
+ "pattern": ":"
205
+ },
206
+ {
207
+ "pattern": "(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)"
208
+ }
209
+ ]
210
+ }
211
+ }
212
+ },
213
+ "applicationRoot": {
214
+ "type": "string",
215
+ "minLength": 1,
216
+ "not": {
217
+ "anyOf": [
218
+ {
219
+ "pattern": "^(?:[A-Za-z]:|/|\\\\|[A-Za-z][A-Za-z0-9+.-]*:)"
220
+ },
221
+ {
222
+ "pattern": ":"
223
+ },
224
+ {
225
+ "pattern": "(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)"
226
+ }
227
+ ]
228
+ }
229
+ },
230
+ "artifactBasePath": {
231
+ "type": "string",
232
+ "minLength": 1,
233
+ "not": {
234
+ "anyOf": [
235
+ {
236
+ "pattern": "^(?:[A-Za-z]:|/|\\\\|[A-Za-z][A-Za-z0-9+.-]*:)"
237
+ },
238
+ {
239
+ "pattern": ":"
240
+ },
241
+ {
242
+ "pattern": "(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)"
243
+ }
244
+ ]
245
+ }
246
+ },
247
+ "hiaDocumentId": {
248
+ "type": "string",
249
+ "minLength": 1
250
+ },
251
+ "title": {
252
+ "type": "string",
253
+ "minLength": 1
254
+ }
255
+ }
256
+ }
257
+ },
258
+ "options": {
259
+ "type": "object",
260
+ "additionalProperties": false,
261
+ "properties": {
262
+ "writeResultManifest": {
263
+ "type": "boolean"
264
+ },
265
+ "writeSourceRelationArtifact": {
266
+ "type": "boolean"
267
+ },
268
+ "writeDocSourceMapArtifact": {
269
+ "type": "boolean"
270
+ }
271
+ }
272
+ },
273
+ "profileIds": {
274
+ "type": "array",
275
+ "minItems": 1,
276
+ "uniqueItems": true,
277
+ "items": {
278
+ "type": "string",
279
+ "pattern": "^[a-z0-9][a-z0-9._-]*$"
280
+ }
281
+ }
282
+ }
283
+ }
@@ -8,6 +8,7 @@ import path from 'node:path';
8
8
  import { extractDotnetProjectDiscovery, extractDotnetSourceFiles } from '@hia-doc/dotnet-source-extractor';
9
9
  import { dotnetXmlDocsToHiaDocument } from '@hia-doc/dotnetdoc-adapter';
10
10
  import { DOTNETDOC_XML_DOC_EXTRACTION_CONTRACT, DOTNETDOC_CSHARP_SOURCE_EXTRACTION_CONTRACT, DOTNETDOC_PROJECT_DISCOVERY_CONTRACT } from '@hia-doc/dotnetdoc-spec';
11
+ import { hasUnpairedSurrogate } from './doc-source-map.mjs';
11
12
 
12
13
  /**
13
14
  * @lang zh-CN 按完整成员ID选声明;同次抽取的真实partial类型选主声明,重复注册/跨抽取冲突仍拒绝。
@@ -15,7 +16,7 @@ import { DOTNETDOC_XML_DOC_EXTRACTION_CONTRACT, DOTNETDOC_CSHARP_SOURCE_EXTRACTI
15
16
  * @param {object} member <lang><zh-CN>XML成员身份。</zh-CN><en>XML member identity.</en></lang>
16
17
  * @param {object[]} candidates <lang><zh-CN>声明及其程序集身份。</zh-CN><en>Declarations with assembly identities.</en></lang>
17
18
  * @param {string|null} assembly <lang><zh-CN>XML声明的程序集。</zh-CN><en>Assembly declared by the XML input.</en></lang>
18
- * @returns {{declaration?:object,status:string,candidateCount:number,selectionRule?:string}} <lang><zh-CN>精确/partial主声明或missing/ambiguous,含候选数与选择规则;不按简称或参数数量回退。</zh-CN><en>Exact/partial primary declaration or missing/ambiguous, with candidate count and selection rule; no short-name or arity fallback.</en></lang>
19
+ * @returns {{declaration?:object,origin?:object,status:string,candidateCount:number,selectionRule?:string}} <lang><zh-CN>精确/partial主声明及其抽取事实,或missing/ambiguous;不按简称或参数数量回退。</zh-CN><en>Exact/partial primary declaration and its extraction fact, or missing/ambiguous; no short-name or arity fallback.</en></lang>
19
20
  */
20
21
  export function selectExactDeclaration(member, candidates, assembly) {
21
22
  // <lang><zh-CN>完整ID及签名类型先验证;相同位置重复注册不自动合并为同一输入事实。</zh-CN><en>Validate complete IDs and signature types first; duplicate registrations at the same location do not automatically become one input fact.</en></lang>
@@ -25,13 +26,13 @@ export function selectExactDeclaration(member, candidates, assembly) {
25
26
  if (assembly && candidate.assembly && candidate.assembly !== 'DotNetDoc.SourceExtraction' && candidate.assembly !== assembly) continue;
26
27
  unique.push(candidate);
27
28
  }
28
- if(unique.length===1) return {status:'resolved',declaration:unique[0].member,candidateCount:1,selectionRule:'exact-documentation-id'};
29
+ if(unique.length===1) return {status:'resolved',declaration:unique[0].member,origin:unique[0].origin,candidateCount:1,selectionRule:'exact-documentation-id'};
29
30
  // <lang><zh-CN>partial必须来自同一编译事实、同一程序集且位置各异;普通重复不能靠排序变成有效声明。</zh-CN><en>Partial declarations must share a compilation and assembly with distinct locations; ordering cannot legitimize ordinary duplicates.</en></lang>
30
31
  const first=unique[0];
31
32
  const locations=new Set(unique.map(candidate=>`${candidate.member.source?.path}:${candidate.member.source?.range?.start?.line}:${candidate.member.source?.range?.start?.column}`));
32
33
  if(unique.length>1 && first.origin && locations.size===unique.length && unique.every(candidate=>candidate.origin===first.origin && candidate.assembly===first.assembly && candidate.member.kind==='dotnet-type' && candidate.member.semantic?.declaration?.isPartialType===true && candidate.member.semantic.declaration.declarationCount===unique.length)){
33
34
  const ranked=[...unique].sort(compareDeclarations);
34
- return {status:'resolved',declaration:ranked[0].member,candidateCount:unique.length,selectionRule:'non-generated-path-line'};
35
+ return {status:'resolved',declaration:ranked[0].member,origin:ranked[0].origin,candidateCount:unique.length,selectionRule:'non-generated-path-line'};
35
36
  }
36
37
  return {status:unique.length===0?'missing':'ambiguous',candidateCount:unique.length};
37
38
  }
@@ -109,7 +110,8 @@ export async function enrichXmlSourceLocations(records, request) {
109
110
  summary.resolved += 1;
110
111
  if(selected.selectionRule==='non-generated-path-line') summary.resolvedPartial+=1;
111
112
  members.push({ ...member, source: declaration.source, semantic: { ...member.semantic, ...declaration.semantic } });
112
- resolutions.push({status:'resolved',candidateCount:selected.candidateCount,selectionRule:selected.selectionRule});
113
+ // <lang><zh-CN>只记录当前 Roslyn 事实的固定类别和错误存在性,映射不能凭 XML 或外来名称自行升格。</zh-CN><en>Record only the current Roslyn fact category and error presence, so maps cannot promote XML or foreign labels on their own.</en></lang>
114
+ resolutions.push({status:'resolved',candidateCount:selected.candidateCount,selectionRule:selected.selectionRule,...(request.options?.writeDocSourceMapArtifact ? {sourceRangeSource:declaration.source.rangeSource,sourceHasErrors:(selected.origin?.diagnostics??[]).some(item=>item.severity==='error')} : {})});
113
115
  } catch { summary.missing += 1; members.push(member); resolutions.push({status:'missing',reason:'missing',detail:'unsafe-or-invalid-declaration-location',candidateCount:selected.candidateCount}); }
114
116
  }
115
117
  const document = dotnetXmlDocsToHiaDocument({ ...record.artifact, members }, { id: record.input.hiaDocumentId, title: record.input.title });
@@ -149,7 +151,7 @@ async function readProjectCandidates(project, root, referenceDirectory) {
149
151
 
150
152
  /** @lang zh-CN 双重路径包含检查,不读取越界symlink目标正文。 @lang en Checks lexical and real-path containment without reading bodies behind escaping symlinks. */
151
153
  async function assertContainedFile(root, relative) {
152
- if (typeof relative !== 'string' || /^(?:[/\\]|[a-z][a-z0-9+.-]*:)/iu.test(relative) || relative.replaceAll('\\', '/').split('/').includes('..')) throw new Error('Unsafe source locator');
154
+ if (typeof relative !== 'string' || hasUnpairedSurrogate(relative) || relative.includes(':') || /^(?:[/\\]|[a-z][a-z0-9+.-]*:)/iu.test(relative) || relative.replaceAll('\\', '/').split('/').includes('..')) throw new Error('Unsafe source locator');
153
155
  const [realRoot, realFile] = await Promise.all([realpath(root), realpath(path.resolve(root, relative))]);
154
156
  const inside = path.relative(realRoot, realFile);
155
157
  if (path.isAbsolute(inside) || inside === '..' || inside.startsWith(`..${path.sep}`)) throw new Error('Source leaves workspace');