@hia-doc/dotnetdoc-runner 0.1.3 → 0.1.4

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
@@ -22,3 +22,20 @@ files.
22
22
 
23
23
  `dotnet-markup-comments` input 会为 `.aspx`、`.ascx`、`.cshtml`、`.razor`
24
24
  文件输出 `dotnetdoc-markup-comment-extraction` 与对应 HIA document。
25
+
26
+ Config inputs support the original single `path`, explicit `paths`, and
27
+ workspace-relative `glob` / `globs` patterns. Glob expansion is performed inside
28
+ the workspace and never accepts absolute paths or `..` traversal.
29
+
30
+ 配置输入支持原有单个 `path`、显式 `paths`,以及工作区相对的 `glob` /
31
+ `globs`。glob 展开只在工作区内执行,不接受绝对路径或 `..` 路径穿越。
32
+
33
+ ```json
34
+ {
35
+ "kind": "dotnet-markup-comments",
36
+ "globs": ["src/Web/**/*.{aspx,ascx,master,cshtml,razor}"],
37
+ "excludeGlobs": ["src/Web/**/bin/**", "src/Web/**/obj/**"],
38
+ "artifactBasePath": "web/markup-comments",
39
+ "title": "Web Markup Comments"
40
+ }
41
+ ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hia-doc/dotnetdoc-runner",
3
- "version": "0.1.3",
3
+ "version": "0.1.4",
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.3",
40
- "@hia-doc/dotnet-xml-doc-extractor": "0.1.3",
41
- "@hia-doc/dotnetdoc-adapter": "0.1.3",
42
- "@hia-doc/dotnetdoc-spec": "0.1.3"
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"
43
43
  }
44
44
  }
package/src/index.mjs CHANGED
@@ -1,4 +1,4 @@
1
- import { readFile, mkdir, writeFile } from "node:fs/promises";
1
+ import { readFile, mkdir, readdir, writeFile } from "node:fs/promises";
2
2
  import path from "node:path";
3
3
 
4
4
  import { extractAspNetEndpoints, extractDotnetMarkupComments, extractDotnetProjectDiscovery, extractDotnetSourceFiles } from "@hia-doc/dotnet-source-extractor";
@@ -21,7 +21,7 @@ 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.3";
24
+ export const DOTNETDOC_RUNNER_VERSION = "0.1.4";
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
27
 
@@ -40,7 +40,11 @@ const SAFE_ID_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
40
40
  * @lang zh-CN 执行 .NET XML documentation 构建。
41
41
  */
42
42
  export async function runDotnetDoc(request, context = {}) {
43
- const normalized = normalizeRequest(request);
43
+ const normalizedRequest = normalizeRequest(request);
44
+ const normalized = {
45
+ ...normalizedRequest,
46
+ inputs: await expandInputs(normalizedRequest)
47
+ };
44
48
  await mkdir(normalized.outputDirectory, { recursive: true });
45
49
 
46
50
  const artifacts = [];
@@ -178,19 +182,35 @@ function normalizeRequest(request) {
178
182
 
179
183
  function normalizeInput(input, index) {
180
184
  assertRecord(input, `inputs[${index}] must be an object.`);
181
- assertKnownKeys(input, ["kind", "path", "applicationRoot", "artifactBasePath", "hiaDocumentId", "title"], `inputs[${index}]`);
185
+ assertKnownKeys(input, ["kind", "path", "paths", "glob", "globs", "excludeGlobs", "globPatterns", "excludeGlobPatterns", "applicationRoot", "artifactBasePath", "hiaDocumentId", "title"], `inputs[${index}]`);
182
186
  if (!DOTNETDOC_INPUT_KINDS.includes(input.kind)) {
183
187
  throw new TypeError(`inputs[${index}].kind must be one of: ${DOTNETDOC_INPUT_KINDS.join(", ")}.`);
184
188
  }
185
189
 
186
- const inputPath = normalizeSafeRelativePath(input.path, `inputs[${index}].path`);
190
+ const explicitPaths = normalizeInputPathList(input, index);
191
+ const globPatterns = uniqueStrings([
192
+ ...normalizeInputGlobList(input, index, "glob", "globs"),
193
+ ...normalizeInternalGlobList(input.globPatterns, index, "globPatterns")
194
+ ]);
195
+ const excludeGlobPatterns = uniqueStrings([
196
+ ...normalizeInputGlobList(input, index, null, "excludeGlobs"),
197
+ ...normalizeInternalGlobList(input.excludeGlobPatterns, index, "excludeGlobPatterns")
198
+ ]);
199
+ if (explicitPaths.length === 0 && globPatterns.length === 0) {
200
+ throw new TypeError(`inputs[${index}] must define path, paths, glob or globs.`);
201
+ }
202
+
203
+ const inputPath = explicitPaths[0] ?? `${input.kind}-group`;
187
204
  const artifactBasePath = input.artifactBasePath
188
205
  ? normalizeSafeRelativePath(input.artifactBasePath, `inputs[${index}].artifactBasePath`)
189
- : stripKnownInputExtension(inputPath);
206
+ : (explicitPaths[0] ? stripKnownInputExtension(explicitPaths[0]) : `${input.kind}-group`);
190
207
 
191
208
  return {
192
209
  kind: input.kind,
193
210
  path: inputPath,
211
+ paths: explicitPaths,
212
+ globPatterns,
213
+ excludeGlobPatterns,
194
214
  applicationRoot: input.applicationRoot ? normalizeSafeRelativePath(input.applicationRoot, `inputs[${index}].applicationRoot`) : ".",
195
215
  artifactBasePath,
196
216
  hiaDocumentId: input.hiaDocumentId,
@@ -423,7 +443,7 @@ async function processXmlDocInput(input, request) {
423
443
  async function processCSharpSourceInput(input, request) {
424
444
  return extractDotnetSourceFiles({
425
445
  workspaceRoot: request.workspaceRoot,
426
- paths: [input.path]
446
+ paths: input.paths
427
447
  });
428
448
  }
429
449
 
@@ -431,21 +451,21 @@ async function processAspNetEndpointInput(input, request) {
431
451
  return extractAspNetEndpoints({
432
452
  workspaceRoot: request.workspaceRoot,
433
453
  applicationRoot: input.applicationRoot,
434
- paths: [input.path]
454
+ paths: input.paths
435
455
  });
436
456
  }
437
457
 
438
458
  async function processMarkupCommentInput(input, request) {
439
459
  return extractDotnetMarkupComments({
440
460
  workspaceRoot: request.workspaceRoot,
441
- paths: [input.path]
461
+ paths: input.paths
442
462
  });
443
463
  }
444
464
 
445
465
  async function processProjectDiscoveryInput(input, request) {
446
466
  return extractDotnetProjectDiscovery({
447
467
  workspaceRoot: request.workspaceRoot,
448
- path: input.path
468
+ paths: input.paths
449
469
  });
450
470
  }
451
471
 
@@ -476,6 +496,118 @@ function normalizeConfigDirectory(value, label) {
476
496
  return normalizeSafeRelativePath(value, label);
477
497
  }
478
498
 
499
+ async function expandInputs(request) {
500
+ const expandedInputs = [];
501
+ for (const input of request.inputs) {
502
+ const expandedPaths = await expandInputPaths(request.workspaceRoot, input);
503
+ expandedInputs.push({
504
+ ...input,
505
+ path: expandedPaths[0],
506
+ paths: expandedPaths,
507
+ globPatterns: undefined,
508
+ excludeGlobPatterns: undefined
509
+ });
510
+ }
511
+ return expandedInputs;
512
+ }
513
+
514
+ async function expandInputPaths(workspaceRoot, input) {
515
+ const matchedPaths = input.globPatterns.length === 0
516
+ ? []
517
+ : await expandGlobPatterns(workspaceRoot, input.globPatterns, input.excludeGlobPatterns);
518
+ const paths = uniqueStrings([...input.paths, ...matchedPaths]);
519
+ if (paths.length === 0) {
520
+ throw new TypeError(`Input ${input.kind} did not resolve any paths.`);
521
+ }
522
+ if (input.kind === "dotnet-xml-doc" && paths.length !== 1) {
523
+ throw new TypeError("dotnet-xml-doc inputs currently require exactly one XML documentation path.");
524
+ }
525
+ return paths;
526
+ }
527
+
528
+ async function expandGlobPatterns(workspaceRoot, patterns, excludePatterns) {
529
+ const includeRegexes = expandBracePatterns(patterns).map(globPatternToRegExp);
530
+ const excludeRegexes = expandBracePatterns(excludePatterns).map(globPatternToRegExp);
531
+ const matched = new Set();
532
+ for (const pattern of patterns) {
533
+ const searchRoot = globSearchRoot(pattern);
534
+ const files = await listWorkspaceFiles(workspaceRoot, searchRoot);
535
+ for (const filePath of files) {
536
+ if (includeRegexes.some((regex) => regex.test(filePath)) && !excludeRegexes.some((regex) => regex.test(filePath))) {
537
+ matched.add(filePath);
538
+ }
539
+ }
540
+ }
541
+ return [...matched].sort((left, right) => left.localeCompare(right));
542
+ }
543
+
544
+ async function listWorkspaceFiles(workspaceRoot, relativeDirectory) {
545
+ const root = path.join(workspaceRoot, relativeDirectory);
546
+ const result = [];
547
+
548
+ async function visit(absoluteDirectory, relativeDirectoryPath) {
549
+ let entries;
550
+ try {
551
+ entries = await readdir(absoluteDirectory, { withFileTypes: true });
552
+ } catch (error) {
553
+ if (error?.code === "ENOENT") {
554
+ return;
555
+ }
556
+ throw error;
557
+ }
558
+ for (const entry of entries) {
559
+ const relativePath = relativeDirectoryPath === "." ? entry.name : `${relativeDirectoryPath}/${entry.name}`;
560
+ const absolutePath = path.join(absoluteDirectory, entry.name);
561
+ if (entry.isDirectory()) {
562
+ await visit(absolutePath, relativePath);
563
+ } else if (entry.isFile()) {
564
+ result.push(relativePath.replaceAll("\\", "/"));
565
+ }
566
+ }
567
+ }
568
+
569
+ await visit(root, relativeDirectory);
570
+ return result;
571
+ }
572
+
573
+ function normalizeInputPathList(input, index) {
574
+ const paths = [];
575
+ if (input.path !== undefined) {
576
+ paths.push(normalizeSafeRelativePath(input.path, `inputs[${index}].path`));
577
+ }
578
+ if (input.paths !== undefined) {
579
+ if (!Array.isArray(input.paths) || input.paths.length === 0) {
580
+ throw new TypeError(`inputs[${index}].paths must be a non-empty array.`);
581
+ }
582
+ paths.push(...input.paths.map((value, pathIndex) => normalizeSafeRelativePath(value, `inputs[${index}].paths[${pathIndex}]`)));
583
+ }
584
+ return uniqueStrings(paths);
585
+ }
586
+
587
+ function normalizeInputGlobList(input, index, singularKey, pluralKey) {
588
+ const patterns = [];
589
+ if (singularKey && input[singularKey] !== undefined) {
590
+ patterns.push(normalizeSafeGlobPattern(input[singularKey], `inputs[${index}].${singularKey}`));
591
+ }
592
+ if (input[pluralKey] !== undefined) {
593
+ if (!Array.isArray(input[pluralKey]) || input[pluralKey].length === 0) {
594
+ throw new TypeError(`inputs[${index}].${pluralKey} must be a non-empty array.`);
595
+ }
596
+ patterns.push(...input[pluralKey].map((value, patternIndex) => normalizeSafeGlobPattern(value, `inputs[${index}].${pluralKey}[${patternIndex}]`)));
597
+ }
598
+ return uniqueStrings(patterns);
599
+ }
600
+
601
+ function normalizeInternalGlobList(values, index, key) {
602
+ if (values === undefined) {
603
+ return [];
604
+ }
605
+ if (!Array.isArray(values)) {
606
+ throw new TypeError(`inputs[${index}].${key} must be an array.`);
607
+ }
608
+ return values.map((value, patternIndex) => normalizeSafeGlobPattern(value, `inputs[${index}].${key}[${patternIndex}]`));
609
+ }
610
+
479
611
  function normalizeSafeRelativePath(value, label) {
480
612
  if (typeof value !== "string" || value.trim().length === 0) {
481
613
  throw new TypeError(`${label} must be a non-empty relative path.`);
@@ -487,6 +619,76 @@ function normalizeSafeRelativePath(value, label) {
487
619
  return normalized;
488
620
  }
489
621
 
622
+ function normalizeSafeGlobPattern(value, label) {
623
+ if (typeof value !== "string" || value.trim().length === 0) {
624
+ throw new TypeError(`${label} must be a non-empty relative glob pattern.`);
625
+ }
626
+ const normalized = value.replaceAll("\\", "/").replace(/^\.\//, "");
627
+ if (!normalized || normalized.startsWith("/") || /^[a-zA-Z]:\//.test(normalized) || normalized.split("/").includes("..")) {
628
+ throw new TypeError(`${label} must be a safe relative glob pattern.`);
629
+ }
630
+ return normalized;
631
+ }
632
+
633
+ function uniqueStrings(values) {
634
+ return [...new Set(values)];
635
+ }
636
+
637
+ function expandBracePatterns(patterns) {
638
+ return patterns.flatMap(expandBracePattern);
639
+ }
640
+
641
+ function expandBracePattern(pattern) {
642
+ const match = /\{([^{}]+)\}/.exec(pattern);
643
+ if (!match) {
644
+ return [pattern];
645
+ }
646
+ const before = pattern.slice(0, match.index);
647
+ const after = pattern.slice(match.index + match[0].length);
648
+ return match[1].split(",").flatMap((part) => expandBracePattern(`${before}${part.trim()}${after}`));
649
+ }
650
+
651
+ function globSearchRoot(pattern) {
652
+ const segments = pattern.split("/");
653
+ const staticSegments = [];
654
+ for (const segment of segments) {
655
+ if (/[*{}]/.test(segment)) {
656
+ break;
657
+ }
658
+ staticSegments.push(segment);
659
+ }
660
+ return staticSegments.length === 0 ? "." : staticSegments.join("/");
661
+ }
662
+
663
+ function globPatternToRegExp(pattern) {
664
+ let source = "^";
665
+ for (let index = 0; index < pattern.length;) {
666
+ const char = pattern[index];
667
+ if (char === "*") {
668
+ if (pattern[index + 1] === "*") {
669
+ if (pattern[index + 2] === "/") {
670
+ source += "(?:.*/)?";
671
+ index += 3;
672
+ } else {
673
+ source += ".*";
674
+ index += 2;
675
+ }
676
+ } else {
677
+ source += "[^/]*";
678
+ index += 1;
679
+ }
680
+ continue;
681
+ }
682
+ source += escapeRegExp(char);
683
+ index += 1;
684
+ }
685
+ return new RegExp(`${source}$`);
686
+ }
687
+
688
+ function escapeRegExp(value) {
689
+ return value.replace(/[\\^$.*+?()[\]{}|]/g, "\\$&");
690
+ }
691
+
490
692
  function stripKnownInputExtension(value) {
491
693
  return value.replace(/\.(?:xml|cs|csproj|sln|aspx|ascx|master|cshtml|razor)$/i, "");
492
694
  }
package/src/schema.mjs CHANGED
@@ -12,6 +12,12 @@ const relativePath = {
12
12
  }
13
13
  };
14
14
 
15
+ const relativePathArray = {
16
+ type: "array",
17
+ minItems: 1,
18
+ items: relativePath
19
+ };
20
+
15
21
  export const DOTNETDOC_CONFIG_JSON_SCHEMA = Object.freeze({
16
22
  $schema: "https://json-schema.org/draft/2020-12/schema",
17
23
  $id: DOTNETDOC_CONFIG_SCHEMA_ID,
@@ -30,10 +36,20 @@ export const DOTNETDOC_CONFIG_JSON_SCHEMA = Object.freeze({
30
36
  items: {
31
37
  type: "object",
32
38
  additionalProperties: false,
33
- required: ["kind", "path"],
39
+ required: ["kind"],
40
+ anyOf: [
41
+ { required: ["path"] },
42
+ { required: ["paths"] },
43
+ { required: ["glob"] },
44
+ { required: ["globs"] }
45
+ ],
34
46
  properties: {
35
47
  kind: { enum: ["dotnet-xml-doc", "dotnet-csharp-source", "dotnet-aspnet-surface", "dotnet-markup-comments", "dotnet-project"] },
36
48
  path: relativePath,
49
+ paths: relativePathArray,
50
+ glob: relativePath,
51
+ globs: relativePathArray,
52
+ excludeGlobs: relativePathArray,
37
53
  applicationRoot: relativePath,
38
54
  artifactBasePath: relativePath,
39
55
  hiaDocumentId: { type: "string", minLength: 1 },