@hia-doc/dotnetdoc-runner 0.1.5 → 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.
Files changed (3) hide show
  1. package/README.md +8 -0
  2. package/package.json +5 -5
  3. package/src/index.mjs +168 -1
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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hia-doc/dotnetdoc-runner",
3
- "version": "0.1.5",
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.5",
40
- "@hia-doc/dotnet-xml-doc-extractor": "0.1.5",
41
- "@hia-doc/dotnetdoc-adapter": "0.1.5",
42
- "@hia-doc/dotnetdoc-spec": "0.1.5"
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.5";
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.
@@ -438,6 +477,130 @@ function unresolvedMember(reason, side, record, member) {
438
477
  };
439
478
  }
440
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
+
441
604
  async function processXmlDocInput(input, request) {
442
605
  const xmlPath = path.join(request.workspaceRoot, input.path);
443
606
  const xmlText = await readFile(xmlPath, "utf8");
@@ -641,6 +804,10 @@ function normalizeSafeGlobPattern(value, label) {
641
804
  return normalized;
642
805
  }
643
806
 
807
+ function normalizeDiagnosticPath(value) {
808
+ return value.replaceAll("\\", "/");
809
+ }
810
+
644
811
  function normalizeSafeProjectPath(value, label) {
645
812
  const normalized = normalizeSafeRelativePath(value, label);
646
813
  if (path.extname(normalized).toLowerCase() !== ".csproj") {