@hia-doc/dotnetdoc-runner 0.1.5 → 0.1.7
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 +8 -0
- package/package.json +5 -5
- 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.
|
|
3
|
+
"version": "0.1.7",
|
|
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.
|
|
40
|
-
"@hia-doc/dotnet-xml-doc-extractor": "0.1.
|
|
41
|
-
"@hia-doc/dotnetdoc-adapter": "0.1.
|
|
42
|
-
"@hia-doc/dotnetdoc-spec": "0.1.
|
|
39
|
+
"@hia-doc/dotnet-source-extractor": "0.1.7",
|
|
40
|
+
"@hia-doc/dotnet-xml-doc-extractor": "0.1.7",
|
|
41
|
+
"@hia-doc/dotnetdoc-adapter": "0.1.7",
|
|
42
|
+
"@hia-doc/dotnetdoc-spec": "0.1.7"
|
|
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.
|
|
24
|
+
export const DOTNETDOC_RUNNER_VERSION = "0.1.7";
|
|
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") {
|