@hia-doc/dotnetdoc-runner 0.1.4 → 0.1.6

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.
package/README.md CHANGED
@@ -16,6 +16,14 @@ This package emits DotNetDoc extraction artifacts, HIA document artifacts,
16
16
  optional source relation artifacts, ASP.NET endpoint extraction artifacts and a
17
17
  documentation producer result manifest without embedding private source text.
18
18
 
19
+ It also exposes `classifyDotnetBuildDiagnostics()` for target scripts that need
20
+ to turn compiler XML documentation warnings such as `CS1591` into a
21
+ generated/designer/manual-source evidence summary.
22
+
23
+ 它也导出 `classifyDotnetBuildDiagnostics()`,供目标项目脚本把 `CS1591` 等
24
+ 编译器 XML documentation warning 分类为 generated / designer / manual source
25
+ 边界 evidence。
26
+
19
27
  `dotnet-markup-comments` inputs emit `dotnetdoc-markup-comment-extraction` and
20
28
  matching HIA document artifacts for `.aspx`, `.ascx`, `.cshtml` and `.razor`
21
29
  files.
@@ -30,6 +38,22 @@ the workspace and never accepts absolute paths or `..` traversal.
30
38
  配置输入支持原有单个 `path`、显式 `paths`,以及工作区相对的 `glob` /
31
39
  `globs`。glob 展开只在工作区内执行,不接受绝对路径或 `..` 路径穿越。
32
40
 
41
+ For `dotnet-csharp-source`, config inputs can also provide `projectPath` to let
42
+ the runner resolve `.cs` files from a `.csproj` before invoking the lightweight
43
+ Roslyn source extractor.
44
+
45
+ 对 `dotnet-csharp-source`,配置也可以提供 `projectPath`,由 runner 先从
46
+ `.csproj` 推导源码文件集合,再调用轻量 Roslyn source extractor。
47
+
48
+ ```json
49
+ {
50
+ "kind": "dotnet-csharp-source",
51
+ "projectPath": "src/Portal.Components/Portal.Components.csproj",
52
+ "artifactBasePath": "source/Portal.Components",
53
+ "title": "Portal Components Source API"
54
+ }
55
+ ```
56
+
33
57
  ```json
34
58
  {
35
59
  "kind": "dotnet-markup-comments",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hia-doc/dotnetdoc-runner",
3
- "version": "0.1.4",
3
+ "version": "0.1.6",
4
4
  "description": "Standalone .NET XML documentation runner and CLI.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -36,9 +36,9 @@
36
36
  "LICENSE"
37
37
  ],
38
38
  "dependencies": {
39
- "@hia-doc/dotnet-source-extractor": "0.1.4",
40
- "@hia-doc/dotnet-xml-doc-extractor": "0.1.4",
41
- "@hia-doc/dotnetdoc-adapter": "0.1.4",
42
- "@hia-doc/dotnetdoc-spec": "0.1.4"
39
+ "@hia-doc/dotnet-source-extractor": "0.1.6",
40
+ "@hia-doc/dotnet-xml-doc-extractor": "0.1.6",
41
+ "@hia-doc/dotnetdoc-adapter": "0.1.6",
42
+ "@hia-doc/dotnetdoc-spec": "0.1.6"
43
43
  }
44
44
  }
package/src/index.mjs CHANGED
@@ -21,14 +21,19 @@ export {
21
21
  } from "./schema.mjs";
22
22
  import { DOTNETDOC_CONFIG_SCHEMA_ID, DOTNETDOC_CONFIG_SCHEMA_VERSION } from "./schema.mjs";
23
23
 
24
- export const DOTNETDOC_RUNNER_VERSION = "0.1.4";
24
+ export const DOTNETDOC_RUNNER_VERSION = "0.1.6";
25
25
  export const DOTNETDOC_INPUT_KINDS = Object.freeze(["dotnet-xml-doc", "dotnet-csharp-source", "dotnet-aspnet-surface", "dotnet-markup-comments", "dotnet-project"]);
26
26
  export const DOTNETDOC_OUTPUT_KINDS = Object.freeze(["dotnetdoc-extraction", "hia-document", "dotnetdoc-source-relation", "dotnetdoc-aspnet-endpoint-extraction", "dotnetdoc-markup-comment-extraction", "dotnetdoc-project-discovery"]);
27
+ export const DOTNETDOC_BUILD_WARNING_CLASSIFICATION_CONTRACT = "dotnetdoc-build-warning-classification";
28
+ export const DOTNETDOC_BUILD_WARNING_CLASSIFICATION_CONTRACT_VERSION = "0.1.0-draft";
27
29
 
28
30
  const RESULT_CONTRACT = "documentation-producer-result";
29
31
  const RESULT_CONTRACT_VERSION = "0.1.0-draft";
30
32
  const PRODUCER_ID = "dotnetdoc";
31
33
  const SAFE_ID_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
34
+ const DESIGNER_CODE_PATTERN = /(?:^|[\\/])[^\\/]+\.designer\.(?:cs|vb)$/iu;
35
+ const GENERATED_CODE_PATTERN = /(?:^|[\\/])(?:obj|bin|generated|generatedcode)(?:[\\/]|$)|\.(?:g|g\.i|generated)\.(?:cs|vb)$/iu;
36
+ const COMPILER_DIAGNOSTIC_PATTERN = /^(?<path>.+?)\((?<line>\d+),(?<column>\d+)\):\s*(?<severity>warning|error)\s+(?<code>[A-Z]+\d+):\s*(?<message>.+)$/iu;
32
37
 
33
38
  /**
34
39
  * 执行一次 .NET XML documentation 文档构建,并返回 documentation producer result。
@@ -122,6 +127,40 @@ export async function runDotnetDoc(request, context = {}) {
122
127
  return result;
123
128
  }
124
129
 
130
+ /**
131
+ * 将 .NET build / MSBuild 文本诊断分类为 manual、designer 或 generated 边界。
132
+ * Classifies .NET build / MSBuild textual diagnostics into manual, designer or generated boundaries.
133
+ *
134
+ * @param {Array<string|object>} diagnostics <lang><en>Compiler diagnostic lines or normalized diagnostic objects.</en><zh-CN>编译器诊断文本行或规范化诊断对象。</zh-CN></lang>
135
+ * @returns {object} <lang><en>Warning classification artifact that contains no source body.</en><zh-CN>不含源码正文的 warning 分类产物。</zh-CN></lang>
136
+ * @lang zh-CN 对 .NET build warning 进行 generated/designer 边界分类。
137
+ */
138
+ export function classifyDotnetBuildDiagnostics(diagnostics) {
139
+ if (!Array.isArray(diagnostics)) {
140
+ throw new TypeError("DotNet build diagnostics must be an array.");
141
+ }
142
+
143
+ const classifiedDiagnostics = diagnostics.map((item, index) => classifyBuildDiagnostic(item, index));
144
+ const summary = summarizeBuildWarningClassifications(classifiedDiagnostics);
145
+
146
+ return {
147
+ contract: DOTNETDOC_BUILD_WARNING_CLASSIFICATION_CONTRACT,
148
+ contractVersion: DOTNETDOC_BUILD_WARNING_CLASSIFICATION_CONTRACT_VERSION,
149
+ producer: {
150
+ name: "@hia-doc/dotnetdoc-runner",
151
+ version: DOTNETDOC_RUNNER_VERSION
152
+ },
153
+ policy: {
154
+ name: "dotnetdoc-generated-designer-warning-policy",
155
+ version: "0.1.0-draft",
156
+ defaultDocumentationGate: "do-not-block-on-generated-or-designer-cs1591",
157
+ sourcesContentPolicy: "none"
158
+ },
159
+ summary,
160
+ diagnostics: classifiedDiagnostics
161
+ };
162
+ }
163
+
125
164
  /**
126
165
  * 读取 versioned DotNetDoc JSON config 并转成 runner request。
127
166
  * Loads a versioned DotNetDoc JSON config and converts it into a runner request.
@@ -182,12 +221,15 @@ function normalizeRequest(request) {
182
221
 
183
222
  function normalizeInput(input, index) {
184
223
  assertRecord(input, `inputs[${index}] must be an object.`);
185
- assertKnownKeys(input, ["kind", "path", "paths", "glob", "globs", "excludeGlobs", "globPatterns", "excludeGlobPatterns", "applicationRoot", "artifactBasePath", "hiaDocumentId", "title"], `inputs[${index}]`);
224
+ assertKnownKeys(input, ["kind", "path", "paths", "projectPath", "glob", "globs", "excludeGlobs", "globPatterns", "excludeGlobPatterns", "applicationRoot", "artifactBasePath", "hiaDocumentId", "title"], `inputs[${index}]`);
186
225
  if (!DOTNETDOC_INPUT_KINDS.includes(input.kind)) {
187
226
  throw new TypeError(`inputs[${index}].kind must be one of: ${DOTNETDOC_INPUT_KINDS.join(", ")}.`);
188
227
  }
189
228
 
190
229
  const explicitPaths = normalizeInputPathList(input, index);
230
+ const projectPath = input.projectPath == null
231
+ ? null
232
+ : normalizeSafeProjectPath(input.projectPath, `inputs[${index}].projectPath`);
191
233
  const globPatterns = uniqueStrings([
192
234
  ...normalizeInputGlobList(input, index, "glob", "globs"),
193
235
  ...normalizeInternalGlobList(input.globPatterns, index, "globPatterns")
@@ -196,19 +238,20 @@ function normalizeInput(input, index) {
196
238
  ...normalizeInputGlobList(input, index, null, "excludeGlobs"),
197
239
  ...normalizeInternalGlobList(input.excludeGlobPatterns, index, "excludeGlobPatterns")
198
240
  ]);
199
- if (explicitPaths.length === 0 && globPatterns.length === 0) {
200
- throw new TypeError(`inputs[${index}] must define path, paths, glob or globs.`);
241
+ if (explicitPaths.length === 0 && globPatterns.length === 0 && !projectPath) {
242
+ throw new TypeError(`inputs[${index}] must define path, paths, projectPath, glob or globs.`);
201
243
  }
202
244
 
203
- const inputPath = explicitPaths[0] ?? `${input.kind}-group`;
245
+ const inputPath = explicitPaths[0] ?? projectPath ?? `${input.kind}-group`;
204
246
  const artifactBasePath = input.artifactBasePath
205
247
  ? normalizeSafeRelativePath(input.artifactBasePath, `inputs[${index}].artifactBasePath`)
206
- : (explicitPaths[0] ? stripKnownInputExtension(explicitPaths[0]) : `${input.kind}-group`);
248
+ : (explicitPaths[0] ? stripKnownInputExtension(explicitPaths[0]) : projectPath ? stripKnownInputExtension(projectPath) : `${input.kind}-group`);
207
249
 
208
250
  return {
209
251
  kind: input.kind,
210
252
  path: inputPath,
211
253
  paths: explicitPaths,
254
+ projectPath,
212
255
  globPatterns,
213
256
  excludeGlobPatterns,
214
257
  applicationRoot: input.applicationRoot ? normalizeSafeRelativePath(input.applicationRoot, `inputs[${index}].applicationRoot`) : ".",
@@ -434,6 +477,130 @@ function unresolvedMember(reason, side, record, member) {
434
477
  };
435
478
  }
436
479
 
480
+ function classifyBuildDiagnostic(value, index) {
481
+ const normalized = normalizeBuildDiagnostic(value, index);
482
+ const boundary = classifyDiagnosticSourceBoundary(normalized.path);
483
+ const isMissingXmlDocWarning = normalized.code === "CS1591";
484
+ const generatedLike = boundary.kind === "designer-code" || boundary.kind === "generated-code";
485
+ const gateSeverity = isMissingXmlDocWarning && generatedLike ? "info" : normalized.severity;
486
+
487
+ return {
488
+ ...normalized,
489
+ boundary,
490
+ gate: {
491
+ severity: gateSeverity,
492
+ defaultAction: isMissingXmlDocWarning && generatedLike
493
+ ? "exclude-from-documentation-warning-gate"
494
+ : "keep-in-documentation-warning-gate",
495
+ blocksDefaultDocumentation: isMissingXmlDocWarning && generatedLike ? false : normalized.severity === "error",
496
+ rationale: generatedLike
497
+ ? "Generated or designer code is documented through the source template or generated artifact boundary."
498
+ : "Manual source diagnostics remain visible for target-owner documentation governance."
499
+ }
500
+ };
501
+ }
502
+
503
+ function normalizeBuildDiagnostic(value, index) {
504
+ if (typeof value === "string") {
505
+ const match = COMPILER_DIAGNOSTIC_PATTERN.exec(value.trim());
506
+ if (!match?.groups) {
507
+ return {
508
+ id: `dotnet-build-diagnostic:${index + 1}`,
509
+ path: null,
510
+ range: null,
511
+ severity: "warning",
512
+ code: "DOTNET_BUILD_DIAGNOSTIC_UNPARSED",
513
+ message: value,
514
+ raw: value
515
+ };
516
+ }
517
+ return {
518
+ id: `dotnet-build-diagnostic:${index + 1}`,
519
+ path: normalizeDiagnosticPath(match.groups.path),
520
+ range: {
521
+ start: {
522
+ line: Number(match.groups.line),
523
+ column: Number(match.groups.column)
524
+ }
525
+ },
526
+ severity: match.groups.severity.toLowerCase(),
527
+ code: match.groups.code.toUpperCase(),
528
+ message: match.groups.message,
529
+ raw: value
530
+ };
531
+ }
532
+ assertRecord(value, `diagnostics[${index}] must be a string or object.`);
533
+ return {
534
+ id: typeof value.id === "string" ? value.id : `dotnet-build-diagnostic:${index + 1}`,
535
+ path: value.path ? normalizeDiagnosticPath(String(value.path)) : null,
536
+ range: value.range ?? null,
537
+ severity: value.severity === "error" ? "error" : "warning",
538
+ code: typeof value.code === "string" ? value.code.toUpperCase() : "DOTNET_BUILD_DIAGNOSTIC",
539
+ message: typeof value.message === "string" ? value.message : "",
540
+ raw: typeof value.raw === "string" ? value.raw : null
541
+ };
542
+ }
543
+
544
+ function classifyDiagnosticSourceBoundary(sourcePath) {
545
+ if (!sourcePath) {
546
+ return {
547
+ kind: "unknown-source",
548
+ confidence: "low",
549
+ reason: "diagnostic-path-missing"
550
+ };
551
+ }
552
+ if (DESIGNER_CODE_PATTERN.test(sourcePath)) {
553
+ return {
554
+ kind: "designer-code",
555
+ confidence: "high",
556
+ reason: "designer-file-name"
557
+ };
558
+ }
559
+ if (GENERATED_CODE_PATTERN.test(sourcePath)) {
560
+ return {
561
+ kind: "generated-code",
562
+ confidence: "high",
563
+ reason: "generated-path-or-file-name"
564
+ };
565
+ }
566
+ return {
567
+ kind: "manual-source",
568
+ confidence: "medium",
569
+ reason: "no-generated-pattern"
570
+ };
571
+ }
572
+
573
+ function summarizeBuildWarningClassifications(classifiedDiagnostics) {
574
+ const countsByBoundary = {};
575
+ const countsByCode = {};
576
+ let generatedOrDesignerCount = 0;
577
+ let manualSourceCount = 0;
578
+ let defaultBlockingCount = 0;
579
+
580
+ for (const diagnostic of classifiedDiagnostics) {
581
+ countsByBoundary[diagnostic.boundary.kind] = (countsByBoundary[diagnostic.boundary.kind] ?? 0) + 1;
582
+ countsByCode[diagnostic.code] = (countsByCode[diagnostic.code] ?? 0) + 1;
583
+ if (diagnostic.boundary.kind === "designer-code" || diagnostic.boundary.kind === "generated-code") {
584
+ generatedOrDesignerCount += 1;
585
+ }
586
+ if (diagnostic.boundary.kind === "manual-source") {
587
+ manualSourceCount += 1;
588
+ }
589
+ if (diagnostic.gate.blocksDefaultDocumentation) {
590
+ defaultBlockingCount += 1;
591
+ }
592
+ }
593
+
594
+ return {
595
+ diagnosticCount: classifiedDiagnostics.length,
596
+ generatedOrDesignerCount,
597
+ manualSourceCount,
598
+ defaultBlockingCount,
599
+ countsByBoundary,
600
+ countsByCode
601
+ };
602
+ }
603
+
437
604
  async function processXmlDocInput(input, request) {
438
605
  const xmlPath = path.join(request.workspaceRoot, input.path);
439
606
  const xmlText = await readFile(xmlPath, "utf8");
@@ -441,10 +608,14 @@ async function processXmlDocInput(input, request) {
441
608
  }
442
609
 
443
610
  async function processCSharpSourceInput(input, request) {
444
- return extractDotnetSourceFiles({
611
+ const sourceRequest = {
445
612
  workspaceRoot: request.workspaceRoot,
446
613
  paths: input.paths
447
- });
614
+ };
615
+ if (input.projectPath) {
616
+ sourceRequest.projectPath = input.projectPath;
617
+ }
618
+ return extractDotnetSourceFiles(sourceRequest);
448
619
  }
449
620
 
450
621
  async function processAspNetEndpointInput(input, request) {
@@ -502,7 +673,7 @@ async function expandInputs(request) {
502
673
  const expandedPaths = await expandInputPaths(request.workspaceRoot, input);
503
674
  expandedInputs.push({
504
675
  ...input,
505
- path: expandedPaths[0],
676
+ path: expandedPaths[0] ?? input.path,
506
677
  paths: expandedPaths,
507
678
  globPatterns: undefined,
508
679
  excludeGlobPatterns: undefined
@@ -516,6 +687,9 @@ async function expandInputPaths(workspaceRoot, input) {
516
687
  ? []
517
688
  : await expandGlobPatterns(workspaceRoot, input.globPatterns, input.excludeGlobPatterns);
518
689
  const paths = uniqueStrings([...input.paths, ...matchedPaths]);
690
+ if (paths.length === 0 && input.projectPath) {
691
+ return [];
692
+ }
519
693
  if (paths.length === 0) {
520
694
  throw new TypeError(`Input ${input.kind} did not resolve any paths.`);
521
695
  }
@@ -630,6 +804,18 @@ function normalizeSafeGlobPattern(value, label) {
630
804
  return normalized;
631
805
  }
632
806
 
807
+ function normalizeDiagnosticPath(value) {
808
+ return value.replaceAll("\\", "/");
809
+ }
810
+
811
+ function normalizeSafeProjectPath(value, label) {
812
+ const normalized = normalizeSafeRelativePath(value, label);
813
+ if (path.extname(normalized).toLowerCase() !== ".csproj") {
814
+ throw new TypeError(`${label} must reference a .csproj file.`);
815
+ }
816
+ return normalized;
817
+ }
818
+
633
819
  function uniqueStrings(values) {
634
820
  return [...new Set(values)];
635
821
  }
package/src/schema.mjs CHANGED
@@ -40,6 +40,7 @@ export const DOTNETDOC_CONFIG_JSON_SCHEMA = Object.freeze({
40
40
  anyOf: [
41
41
  { required: ["path"] },
42
42
  { required: ["paths"] },
43
+ { required: ["projectPath"] },
43
44
  { required: ["glob"] },
44
45
  { required: ["globs"] }
45
46
  ],
@@ -47,6 +48,7 @@ export const DOTNETDOC_CONFIG_JSON_SCHEMA = Object.freeze({
47
48
  kind: { enum: ["dotnet-xml-doc", "dotnet-csharp-source", "dotnet-aspnet-surface", "dotnet-markup-comments", "dotnet-project"] },
48
49
  path: relativePath,
49
50
  paths: relativePathArray,
51
+ projectPath: relativePath,
50
52
  glob: relativePath,
51
53
  globs: relativePathArray,
52
54
  excludeGlobs: relativePathArray,