@terra-symposium/hygiene 0.0.0-stage → 2.4.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 +70 -2
- package/dist/accessibility.d.ts +39 -0
- package/dist/accessibility.d.ts.map +1 -0
- package/dist/accessibility.js +524 -0
- package/dist/accessibility.js.map +1 -0
- package/dist/app/workspace-test-runner.d.ts +6 -0
- package/dist/app/workspace-test-runner.d.ts.map +1 -0
- package/dist/app/workspace-test-runner.js +39 -0
- package/dist/app/workspace-test-runner.js.map +1 -0
- package/dist/capabilities/core/analysis.d.ts +22 -0
- package/dist/capabilities/core/analysis.d.ts.map +1 -0
- package/dist/capabilities/core/analysis.js +44 -0
- package/dist/capabilities/core/analysis.js.map +1 -0
- package/dist/capabilities/core/cli.d.ts +19 -0
- package/dist/capabilities/core/cli.d.ts.map +1 -0
- package/dist/capabilities/core/cli.js +58 -0
- package/dist/capabilities/core/cli.js.map +1 -0
- package/dist/capabilities/core/config.d.ts +49 -0
- package/dist/capabilities/core/config.d.ts.map +1 -0
- package/dist/capabilities/core/config.js +88 -0
- package/dist/capabilities/core/config.js.map +1 -0
- package/dist/capabilities/core/index.d.ts +11 -0
- package/dist/capabilities/core/index.d.ts.map +1 -0
- package/dist/capabilities/core/index.js +11 -0
- package/dist/capabilities/core/index.js.map +1 -0
- package/dist/capabilities/core/lib/files.d.ts +55 -0
- package/dist/capabilities/core/lib/files.d.ts.map +1 -0
- package/dist/capabilities/core/lib/files.js +287 -0
- package/dist/capabilities/core/lib/files.js.map +1 -0
- package/dist/capabilities/core/lib/progress.d.ts +25 -0
- package/dist/capabilities/core/lib/progress.d.ts.map +1 -0
- package/dist/capabilities/core/lib/progress.js +40 -0
- package/dist/capabilities/core/lib/progress.js.map +1 -0
- package/dist/capabilities/core/lib/source-kind.d.ts +14 -0
- package/dist/capabilities/core/lib/source-kind.d.ts.map +1 -0
- package/dist/capabilities/core/lib/source-kind.js +29 -0
- package/dist/capabilities/core/lib/source-kind.js.map +1 -0
- package/dist/capabilities/core/types.d.ts +156 -0
- package/dist/capabilities/core/types.d.ts.map +1 -0
- package/dist/capabilities/core/types.js +35 -0
- package/dist/capabilities/core/types.js.map +1 -0
- package/dist/capabilities/documentation/cli.d.ts +3 -0
- package/dist/capabilities/documentation/cli.d.ts.map +1 -0
- package/dist/capabilities/documentation/cli.js +14 -0
- package/dist/capabilities/documentation/cli.js.map +1 -0
- package/dist/capabilities/documentation/index.d.ts +5 -0
- package/dist/capabilities/documentation/index.d.ts.map +1 -0
- package/dist/capabilities/documentation/index.js +5 -0
- package/dist/capabilities/documentation/index.js.map +1 -0
- package/dist/capabilities/documentation/lib/documentation.d.ts +108 -0
- package/dist/capabilities/documentation/lib/documentation.d.ts.map +1 -0
- package/dist/capabilities/documentation/lib/documentation.js +1007 -0
- package/dist/capabilities/documentation/lib/documentation.js.map +1 -0
- package/dist/capabilities/formatting/cli.d.ts +3 -0
- package/dist/capabilities/formatting/cli.d.ts.map +1 -0
- package/dist/capabilities/formatting/cli.js +15 -0
- package/dist/capabilities/formatting/cli.js.map +1 -0
- package/dist/capabilities/formatting/index.d.ts +8 -0
- package/dist/capabilities/formatting/index.d.ts.map +1 -0
- package/dist/capabilities/formatting/index.js +8 -0
- package/dist/capabilities/formatting/index.js.map +1 -0
- package/dist/capabilities/formatting/lib/collapse.d.ts +13 -0
- package/dist/capabilities/formatting/lib/collapse.d.ts.map +1 -0
- package/dist/capabilities/formatting/lib/collapse.js +179 -0
- package/dist/capabilities/formatting/lib/collapse.js.map +1 -0
- package/dist/capabilities/formatting/lib/inline-if.d.ts +13 -0
- package/dist/capabilities/formatting/lib/inline-if.d.ts.map +1 -0
- package/dist/capabilities/formatting/lib/inline-if.js +49 -0
- package/dist/capabilities/formatting/lib/inline-if.js.map +1 -0
- package/dist/capabilities/formatting/lib/run-formatting.d.ts +14 -0
- package/dist/capabilities/formatting/lib/run-formatting.d.ts.map +1 -0
- package/dist/capabilities/formatting/lib/run-formatting.js +134 -0
- package/dist/capabilities/formatting/lib/run-formatting.js.map +1 -0
- package/dist/capabilities/imports/cli.d.ts +3 -0
- package/dist/capabilities/imports/cli.d.ts.map +1 -0
- package/dist/capabilities/imports/cli.js +9 -0
- package/dist/capabilities/imports/cli.js.map +1 -0
- package/dist/capabilities/imports/index.d.ts +6 -0
- package/dist/capabilities/imports/index.d.ts.map +1 -0
- package/dist/capabilities/imports/index.js +6 -0
- package/dist/capabilities/imports/index.js.map +1 -0
- package/dist/capabilities/imports/lib/imports.d.ts +19 -0
- package/dist/capabilities/imports/lib/imports.d.ts.map +1 -0
- package/dist/capabilities/imports/lib/imports.js +88 -0
- package/dist/capabilities/imports/lib/imports.js.map +1 -0
- package/dist/capabilities/languages/cli.d.ts +3 -0
- package/dist/capabilities/languages/cli.d.ts.map +1 -0
- package/dist/capabilities/languages/cli.js +9 -0
- package/dist/capabilities/languages/cli.js.map +1 -0
- package/dist/capabilities/languages/index.d.ts +6 -0
- package/dist/capabilities/languages/index.d.ts.map +1 -0
- package/dist/capabilities/languages/index.js +6 -0
- package/dist/capabilities/languages/index.js.map +1 -0
- package/dist/capabilities/languages/lib/language-profiles.d.ts +110 -0
- package/dist/capabilities/languages/lib/language-profiles.d.ts.map +1 -0
- package/dist/capabilities/languages/lib/language-profiles.js +509 -0
- package/dist/capabilities/languages/lib/language-profiles.js.map +1 -0
- package/dist/capabilities/languages/lib/run-language-checks.d.ts +12 -0
- package/dist/capabilities/languages/lib/run-language-checks.d.ts.map +1 -0
- package/dist/capabilities/languages/lib/run-language-checks.js +109 -0
- package/dist/capabilities/languages/lib/run-language-checks.js.map +1 -0
- package/dist/capabilities/naming/cli.d.ts +3 -0
- package/dist/capabilities/naming/cli.d.ts.map +1 -0
- package/dist/capabilities/naming/cli.js +15 -0
- package/dist/capabilities/naming/cli.js.map +1 -0
- package/dist/capabilities/naming/index.d.ts +5 -0
- package/dist/capabilities/naming/index.d.ts.map +1 -0
- package/dist/capabilities/naming/index.js +5 -0
- package/dist/capabilities/naming/index.js.map +1 -0
- package/dist/capabilities/naming/lib/naming.d.ts +169 -0
- package/dist/capabilities/naming/lib/naming.d.ts.map +1 -0
- package/dist/capabilities/naming/lib/naming.js +908 -0
- package/dist/capabilities/naming/lib/naming.js.map +1 -0
- package/dist/capabilities/patterns/cli.d.ts +3 -0
- package/dist/capabilities/patterns/cli.d.ts.map +1 -0
- package/dist/capabilities/patterns/cli.js +30 -0
- package/dist/capabilities/patterns/cli.js.map +1 -0
- package/dist/capabilities/patterns/index.d.ts +5 -0
- package/dist/capabilities/patterns/index.d.ts.map +1 -0
- package/dist/capabilities/patterns/index.js +5 -0
- package/dist/capabilities/patterns/index.js.map +1 -0
- package/dist/capabilities/patterns/lib/patterns.d.ts +102 -0
- package/dist/capabilities/patterns/lib/patterns.d.ts.map +1 -0
- package/dist/capabilities/patterns/lib/patterns.js +1584 -0
- package/dist/capabilities/patterns/lib/patterns.js.map +1 -0
- package/dist/capabilities/refactoring/cli.d.ts +3 -0
- package/dist/capabilities/refactoring/cli.d.ts.map +1 -0
- package/dist/capabilities/refactoring/cli.js +15 -0
- package/dist/capabilities/refactoring/cli.js.map +1 -0
- package/dist/capabilities/refactoring/index.d.ts +6 -0
- package/dist/capabilities/refactoring/index.d.ts.map +1 -0
- package/dist/capabilities/refactoring/index.js +6 -0
- package/dist/capabilities/refactoring/index.js.map +1 -0
- package/dist/capabilities/refactoring/lib/object-forwarding.d.ts +42 -0
- package/dist/capabilities/refactoring/lib/object-forwarding.d.ts.map +1 -0
- package/dist/capabilities/refactoring/lib/object-forwarding.js +166 -0
- package/dist/capabilities/refactoring/lib/object-forwarding.js.map +1 -0
- package/dist/capabilities/refactoring/lib/single-use.d.ts +61 -0
- package/dist/capabilities/refactoring/lib/single-use.d.ts.map +1 -0
- package/dist/capabilities/refactoring/lib/single-use.js +1791 -0
- package/dist/capabilities/refactoring/lib/single-use.js.map +1 -0
- package/dist/capabilities/reports/cli.d.ts +3 -0
- package/dist/capabilities/reports/cli.d.ts.map +1 -0
- package/dist/capabilities/reports/cli.js +34 -0
- package/dist/capabilities/reports/cli.js.map +1 -0
- package/dist/capabilities/reports/index.d.ts +10 -0
- package/dist/capabilities/reports/index.d.ts.map +1 -0
- package/dist/capabilities/reports/index.js +10 -0
- package/dist/capabilities/reports/index.js.map +1 -0
- package/dist/capabilities/reports/lib/github-report.d.ts +94 -0
- package/dist/capabilities/reports/lib/github-report.d.ts.map +1 -0
- package/dist/capabilities/reports/lib/github-report.js +499 -0
- package/dist/capabilities/reports/lib/github-report.js.map +1 -0
- package/dist/capabilities/reports/lib/history-report.d.ts +58 -0
- package/dist/capabilities/reports/lib/history-report.d.ts.map +1 -0
- package/dist/capabilities/reports/lib/history-report.js +300 -0
- package/dist/capabilities/reports/lib/history-report.js.map +1 -0
- package/dist/capabilities/reports/lib/node-reporter.d.ts +79 -0
- package/dist/capabilities/reports/lib/node-reporter.d.ts.map +1 -0
- package/dist/capabilities/reports/lib/node-reporter.js +244 -0
- package/dist/capabilities/reports/lib/node-reporter.js.map +1 -0
- package/dist/capabilities/reports/lib/playwright-reporter.d.ts +100 -0
- package/dist/capabilities/reports/lib/playwright-reporter.d.ts.map +1 -0
- package/dist/capabilities/reports/lib/playwright-reporter.js +122 -0
- package/dist/capabilities/reports/lib/playwright-reporter.js.map +1 -0
- package/dist/capabilities/security/cli.d.ts +3 -0
- package/dist/capabilities/security/cli.d.ts.map +1 -0
- package/dist/capabilities/security/cli.js +9 -0
- package/dist/capabilities/security/cli.js.map +1 -0
- package/dist/capabilities/security/index.d.ts +5 -0
- package/dist/capabilities/security/index.d.ts.map +1 -0
- package/dist/capabilities/security/index.js +5 -0
- package/dist/capabilities/security/index.js.map +1 -0
- package/dist/capabilities/security/lib/security.d.ts +19 -0
- package/dist/capabilities/security/lib/security.d.ts.map +1 -0
- package/dist/capabilities/security/lib/security.js +115 -0
- package/dist/capabilities/security/lib/security.js.map +1 -0
- package/dist/capabilities/ui/cli.d.ts +3 -0
- package/dist/capabilities/ui/cli.d.ts.map +1 -0
- package/dist/capabilities/ui/cli.js +22 -0
- package/dist/capabilities/ui/cli.js.map +1 -0
- package/dist/capabilities/ui/index.d.ts +8 -0
- package/dist/capabilities/ui/index.d.ts.map +1 -0
- package/dist/capabilities/ui/index.js +8 -0
- package/dist/capabilities/ui/index.js.map +1 -0
- package/dist/capabilities/ui/lib/accessibility.d.ts +37 -0
- package/dist/capabilities/ui/lib/accessibility.d.ts.map +1 -0
- package/dist/capabilities/ui/lib/accessibility.js +676 -0
- package/dist/capabilities/ui/lib/accessibility.js.map +1 -0
- package/dist/capabilities/ui/lib/display-name.d.ts +42 -0
- package/dist/capabilities/ui/lib/display-name.d.ts.map +1 -0
- package/dist/capabilities/ui/lib/display-name.js +277 -0
- package/dist/capabilities/ui/lib/display-name.js.map +1 -0
- package/dist/capabilities/ui/lib/error-boundaries.d.ts +30 -0
- package/dist/capabilities/ui/lib/error-boundaries.d.ts.map +1 -0
- package/dist/capabilities/ui/lib/error-boundaries.js +401 -0
- package/dist/capabilities/ui/lib/error-boundaries.js.map +1 -0
- package/dist/capabilities/ui/lib/ui-recommendations.d.ts +45 -0
- package/dist/capabilities/ui/lib/ui-recommendations.d.ts.map +1 -0
- package/dist/capabilities/ui/lib/ui-recommendations.js +183 -0
- package/dist/capabilities/ui/lib/ui-recommendations.js.map +1 -0
- package/dist/display-name.d.ts +44 -0
- package/dist/display-name.d.ts.map +1 -0
- package/dist/display-name.js +256 -0
- package/dist/display-name.js.map +1 -0
- package/dist/index.d.ts +5 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +5 -0
- package/dist/index.js.map +1 -0
- package/dist/lib/accessibility.d.ts +5 -0
- package/dist/lib/accessibility.d.ts.map +1 -0
- package/dist/lib/accessibility.js +5 -0
- package/dist/lib/accessibility.js.map +1 -0
- package/dist/lib/collapse.d.ts +5 -0
- package/dist/lib/collapse.d.ts.map +1 -0
- package/dist/lib/collapse.js +5 -0
- package/dist/lib/collapse.js.map +1 -0
- package/dist/lib/dev.d.ts +3 -0
- package/dist/lib/dev.d.ts.map +1 -0
- package/dist/lib/dev.js +126 -0
- package/dist/lib/dev.js.map +1 -0
- package/dist/lib/display-name.d.ts +5 -0
- package/dist/lib/display-name.d.ts.map +1 -0
- package/dist/lib/display-name.js +5 -0
- package/dist/lib/display-name.js.map +1 -0
- package/dist/lib/documentation.d.ts +5 -0
- package/dist/lib/documentation.d.ts.map +1 -0
- package/dist/lib/documentation.js +5 -0
- package/dist/lib/documentation.js.map +1 -0
- package/dist/lib/error-boundaries-astro.d.ts +6 -0
- package/dist/lib/error-boundaries-astro.d.ts.map +1 -0
- package/dist/lib/error-boundaries-astro.js +6 -0
- package/dist/lib/error-boundaries-astro.js.map +1 -0
- package/dist/lib/error-boundaries-react.d.ts +6 -0
- package/dist/lib/error-boundaries-react.d.ts.map +1 -0
- package/dist/lib/error-boundaries-react.js +6 -0
- package/dist/lib/error-boundaries-react.js.map +1 -0
- package/dist/lib/error-boundaries.d.ts +5 -0
- package/dist/lib/error-boundaries.d.ts.map +1 -0
- package/dist/lib/error-boundaries.js +5 -0
- package/dist/lib/error-boundaries.js.map +1 -0
- package/dist/lib/eslint-api.d.ts +13 -0
- package/dist/lib/eslint-api.d.ts.map +1 -0
- package/dist/lib/eslint-api.js +24 -0
- package/dist/lib/eslint-api.js.map +1 -0
- package/dist/lib/files.d.ts +5 -0
- package/dist/lib/files.d.ts.map +1 -0
- package/dist/lib/files.js +5 -0
- package/dist/lib/files.js.map +1 -0
- package/dist/lib/formatting.d.ts +5 -0
- package/dist/lib/formatting.d.ts.map +1 -0
- package/dist/lib/formatting.js +5 -0
- package/dist/lib/formatting.js.map +1 -0
- package/dist/lib/github-report.d.ts +5 -0
- package/dist/lib/github-report.d.ts.map +1 -0
- package/dist/lib/github-report.js +5 -0
- package/dist/lib/github-report.js.map +1 -0
- package/dist/lib/history-report.d.ts +5 -0
- package/dist/lib/history-report.d.ts.map +1 -0
- package/dist/lib/history-report.js +5 -0
- package/dist/lib/history-report.js.map +1 -0
- package/dist/lib/imports.d.ts +5 -0
- package/dist/lib/imports.d.ts.map +1 -0
- package/dist/lib/imports.js +5 -0
- package/dist/lib/imports.js.map +1 -0
- package/dist/lib/index.d.ts +20 -0
- package/dist/lib/index.d.ts.map +1 -0
- package/dist/lib/index.js +20 -0
- package/dist/lib/index.js.map +1 -0
- package/dist/lib/inline-if.d.ts +5 -0
- package/dist/lib/inline-if.d.ts.map +1 -0
- package/dist/lib/inline-if.js +5 -0
- package/dist/lib/inline-if.js.map +1 -0
- package/dist/lib/language-checks.d.ts +5 -0
- package/dist/lib/language-checks.d.ts.map +1 -0
- package/dist/lib/language-checks.js +5 -0
- package/dist/lib/language-checks.js.map +1 -0
- package/dist/lib/language-profiles.d.ts +5 -0
- package/dist/lib/language-profiles.d.ts.map +1 -0
- package/dist/lib/language-profiles.js +5 -0
- package/dist/lib/language-profiles.js.map +1 -0
- package/dist/lib/naming.d.ts +5 -0
- package/dist/lib/naming.d.ts.map +1 -0
- package/dist/lib/naming.js +5 -0
- package/dist/lib/naming.js.map +1 -0
- package/dist/lib/node-reporter.d.ts +6 -0
- package/dist/lib/node-reporter.d.ts.map +1 -0
- package/dist/lib/node-reporter.js +6 -0
- package/dist/lib/node-reporter.js.map +1 -0
- package/dist/lib/object-forwarding.d.ts +5 -0
- package/dist/lib/object-forwarding.d.ts.map +1 -0
- package/dist/lib/object-forwarding.js +5 -0
- package/dist/lib/object-forwarding.js.map +1 -0
- package/dist/lib/patterns.d.ts +5 -0
- package/dist/lib/patterns.d.ts.map +1 -0
- package/dist/lib/patterns.js +5 -0
- package/dist/lib/patterns.js.map +1 -0
- package/dist/lib/playwright-reporter.d.ts +6 -0
- package/dist/lib/playwright-reporter.d.ts.map +1 -0
- package/dist/lib/playwright-reporter.js +6 -0
- package/dist/lib/playwright-reporter.js.map +1 -0
- package/dist/lib/port.d.ts +21 -0
- package/dist/lib/port.d.ts.map +1 -0
- package/dist/lib/port.js +81 -0
- package/dist/lib/port.js.map +1 -0
- package/dist/lib/progress.d.ts +5 -0
- package/dist/lib/progress.d.ts.map +1 -0
- package/dist/lib/progress.js +5 -0
- package/dist/lib/progress.js.map +1 -0
- package/dist/lib/reports.d.ts +5 -0
- package/dist/lib/reports.d.ts.map +1 -0
- package/dist/lib/reports.js +5 -0
- package/dist/lib/reports.js.map +1 -0
- package/dist/lib/runner.d.ts +150 -0
- package/dist/lib/runner.d.ts.map +1 -0
- package/dist/lib/runner.js +4522 -0
- package/dist/lib/runner.js.map +1 -0
- package/dist/lib/security.d.ts +5 -0
- package/dist/lib/security.d.ts.map +1 -0
- package/dist/lib/security.js +5 -0
- package/dist/lib/security.js.map +1 -0
- package/dist/lib/single-use.d.ts +6 -0
- package/dist/lib/single-use.d.ts.map +1 -0
- package/dist/lib/single-use.js +5 -0
- package/dist/lib/single-use.js.map +1 -0
- package/dist/lib/source-kind.d.ts +5 -0
- package/dist/lib/source-kind.d.ts.map +1 -0
- package/dist/lib/source-kind.js +5 -0
- package/dist/lib/source-kind.js.map +1 -0
- package/dist/lib/spinner-worker.d.ts +6 -0
- package/dist/lib/spinner-worker.d.ts.map +1 -0
- package/dist/lib/spinner-worker.js +33 -0
- package/dist/lib/spinner-worker.js.map +1 -0
- package/dist/lib/ui-quality.d.ts +5 -0
- package/dist/lib/ui-quality.d.ts.map +1 -0
- package/dist/lib/ui-quality.js +5 -0
- package/dist/lib/ui-quality.js.map +1 -0
- package/dist/lib/ui-recommendations.d.ts +5 -0
- package/dist/lib/ui-recommendations.d.ts.map +1 -0
- package/dist/lib/ui-recommendations.js +5 -0
- package/dist/lib/ui-recommendations.js.map +1 -0
- package/dist/spinner-worker.d.ts +6 -0
- package/dist/spinner-worker.d.ts.map +1 -0
- package/dist/spinner-worker.js +39 -0
- package/dist/spinner-worker.js.map +1 -0
- package/package.json +160 -5
- package/quality-configs/checkstyle.xml +29 -0
- package/quality-configs/pmd-rules.xml +11 -0
- package/quality.schema.json +392 -0
|
@@ -0,0 +1,1007 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* packages/hygiene/src/capabilities/documentation/lib/documentation.ts
|
|
3
|
+
* Reports source-documentation findings and checks Markdown command fences.
|
|
4
|
+
*/
|
|
5
|
+
/*//////////////////////////////////////////////////
|
|
6
|
+
IMPORTS
|
|
7
|
+
//////////////////////////////////////////////////*/
|
|
8
|
+
// API
|
|
9
|
+
import ts from 'typescript';
|
|
10
|
+
import { displayPath, srcFiles } from '@terra-symposium/hygiene/core';
|
|
11
|
+
import { extname, relative, resolve, sep } from 'node:path';
|
|
12
|
+
import { readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
|
|
13
|
+
import { spawnSync } from 'node:child_process';
|
|
14
|
+
/*//////////////////////////////////////////////////
|
|
15
|
+
REGEX
|
|
16
|
+
//////////////////////////////////////////////////*/
|
|
17
|
+
const N_REGEX = /(?<=\n)/;
|
|
18
|
+
const R_N_END_REGEX = /\r?\n$/;
|
|
19
|
+
/*//////////////////////////////////////////////////
|
|
20
|
+
REGEX
|
|
21
|
+
//////////////////////////////////////////////////*/
|
|
22
|
+
const TYPE_S_REGEX = /^type\s+/;
|
|
23
|
+
/*//////////////////////////////////////////////////
|
|
24
|
+
REGEX
|
|
25
|
+
//////////////////////////////////////////////////*/
|
|
26
|
+
const R_N_REGEX = /\r?\n/;
|
|
27
|
+
/*//////////////////////////////////////////////////
|
|
28
|
+
REGEX
|
|
29
|
+
//////////////////////////////////////////////////*/
|
|
30
|
+
const S_ONLY_REGEX = /^\s*$/;
|
|
31
|
+
// hygiene-ignore single-use -- Keep the documented S_S_G_REGEX declaration so its parameter and return contract remains attached.
|
|
32
|
+
/**
|
|
33
|
+
* Creates a fresh matcher for complete TSDoc comment blocks.
|
|
34
|
+
*
|
|
35
|
+
* @return Global regular expression that matches TSDoc comment blocks.
|
|
36
|
+
*/
|
|
37
|
+
const S_S_G_REGEX = () => /\/\*\*[\s\S]*?\*\//g;
|
|
38
|
+
/*//////////////////////////////////////////////////
|
|
39
|
+
REGEX
|
|
40
|
+
//////////////////////////////////////////////////*/
|
|
41
|
+
const S_REGEX = /^\s*/;
|
|
42
|
+
const S_CLASS_3 = /^\s*\* ?/;
|
|
43
|
+
const UFEFF_REGEX = /^\uFEFF/;
|
|
44
|
+
const C_M_JS_JSX_TS_TSX_REGEX = /(?:^|[\\/])[^\\/]+\.(?:c|m)?(?:js|jsx|ts|tsx)$/;
|
|
45
|
+
const S_CLASS_5 = /^\{[^}]+\}\s*/;
|
|
46
|
+
const SUPPORTED = new Set(['.cjs', '.cts', '.js', '.jsx', '.mjs', '.mts', '.ts', '.tsx']);
|
|
47
|
+
const IMPORT_SUPPORTED = new Set([...SUPPORTED, '.astro']);
|
|
48
|
+
const PNPM_FENCE = /^\s*```(?:sh|bash|zsh|shell)\s*$/i;
|
|
49
|
+
const FENCE_CLOSE = /^\s*```\s*$/;
|
|
50
|
+
const PNPM_DIR_FLAG = /^(\s*(?:\$\s*)?pnpm)\s+(?:-C|--prefix)(\s+)("[^"]+"|'[^']+'|\S+)(.*)$/;
|
|
51
|
+
/**
|
|
52
|
+
* Finds obsolete pnpm directory flags in configured Markdown shell fences.
|
|
53
|
+
*
|
|
54
|
+
* @param cfg Quality configuration containing documentation command roots.
|
|
55
|
+
*
|
|
56
|
+
* @return Deprecated pnpm directory commands found in configured Markdown.
|
|
57
|
+
*/
|
|
58
|
+
export function documentedCommandFindings(cfg) {
|
|
59
|
+
const roots = cfg.documentation?.commandRoots?.map(p => resolve(cfg.root, p)) ?? [];
|
|
60
|
+
if (!roots.length)
|
|
61
|
+
return [];
|
|
62
|
+
return srcFiles({ ...cfg, sourceRoots: roots, extensions: ['.md', '.mdx'] }).flatMap(f => {
|
|
63
|
+
let inShellFence = false;
|
|
64
|
+
return readFileSync(f, 'utf8')
|
|
65
|
+
.split(N_REGEX)
|
|
66
|
+
.flatMap((s, i) => {
|
|
67
|
+
const line = s.replace(R_N_END_REGEX, '');
|
|
68
|
+
if (!inShellFence) {
|
|
69
|
+
if (PNPM_FENCE.test(line))
|
|
70
|
+
inShellFence = true;
|
|
71
|
+
return [];
|
|
72
|
+
}
|
|
73
|
+
if (FENCE_CLOSE.test(line)) {
|
|
74
|
+
inShellFence = false;
|
|
75
|
+
return [];
|
|
76
|
+
}
|
|
77
|
+
return PNPM_DIR_FLAG.exec(line) ? [{ file: displayPath(cfg, f), line: i + 1, command: line.trim(), recommendation: 'replace the pnpm directory flag with --dir' }] : [];
|
|
78
|
+
});
|
|
79
|
+
});
|
|
80
|
+
}
|
|
81
|
+
/**
|
|
82
|
+
* Replaces only known deprecated pnpm directory flags in configured Markdown shell fences.
|
|
83
|
+
*
|
|
84
|
+
* @param cfg Quality configuration containing documentation command roots.
|
|
85
|
+
*
|
|
86
|
+
* @return Number of deprecated commands replaced.
|
|
87
|
+
*/
|
|
88
|
+
export function fixDocumentedCommands(cfg) {
|
|
89
|
+
const roots = cfg.documentation?.commandRoots?.map(p => resolve(cfg.root, p)) ?? [];
|
|
90
|
+
if (!roots.length)
|
|
91
|
+
return 0;
|
|
92
|
+
let fixed = 0;
|
|
93
|
+
for (const file of srcFiles({ ...cfg, sourceRoots: roots, extensions: ['.md', '.mdx'] })) {
|
|
94
|
+
const src = readFileSync(file, 'utf8');
|
|
95
|
+
let inShellFence = false;
|
|
96
|
+
const updated = src
|
|
97
|
+
.split(N_REGEX)
|
|
98
|
+
.map(s => {
|
|
99
|
+
const line = s.replace(R_N_END_REGEX, '');
|
|
100
|
+
if (!inShellFence) {
|
|
101
|
+
if (PNPM_FENCE.test(line))
|
|
102
|
+
inShellFence = true;
|
|
103
|
+
return s;
|
|
104
|
+
}
|
|
105
|
+
if (FENCE_CLOSE.test(line)) {
|
|
106
|
+
inShellFence = false;
|
|
107
|
+
return s;
|
|
108
|
+
}
|
|
109
|
+
const match = PNPM_DIR_FLAG.exec(line);
|
|
110
|
+
if (!match)
|
|
111
|
+
return s;
|
|
112
|
+
fixed++;
|
|
113
|
+
return `${match[1]} --dir${match[2]}${match[3]}${match[4]}${s.slice(line.length)}`;
|
|
114
|
+
})
|
|
115
|
+
.join('');
|
|
116
|
+
if (src !== updated)
|
|
117
|
+
writeFileSync(file, updated);
|
|
118
|
+
}
|
|
119
|
+
return fixed;
|
|
120
|
+
}
|
|
121
|
+
export const DOCUMENTATION_DESCRIPTION_NOTICE = 'Ask an agent for meaningful documentation prose; this check only reports missing descriptions and never generates them in bulk.';
|
|
122
|
+
const DESC_OPTIONAL_TAGS = new Set(['abstract', 'const', 'default', 'event', 'hideconstructor', 'internal', 'package', 'private', 'protected', 'public', 'readonly', 'sealed', 'virtual']);
|
|
123
|
+
/*//////////////////////////////////////////////////
|
|
124
|
+
HELPERS
|
|
125
|
+
//////////////////////////////////////////////////*/
|
|
126
|
+
// hygiene-ignore single-use -- Keep the documented writeValidatedSrc declaration so its parameter and return contract remains attached.
|
|
127
|
+
/**
|
|
128
|
+
* Writes a generated source update through a temporary file after validating
|
|
129
|
+
* that the candidate still has no TypeScript or JavaScript parse errors.
|
|
130
|
+
*
|
|
131
|
+
* @param fileName Source file to replace.
|
|
132
|
+
* @param src Candidate source text to validate and write.
|
|
133
|
+
*
|
|
134
|
+
* @return Nothing; throws before replacing the source when parsing fails.
|
|
135
|
+
*/
|
|
136
|
+
function writeValidatedSrc(fileName, src) {
|
|
137
|
+
try {
|
|
138
|
+
if (/\.d\.[cm]?ts$/.test(fileName)) {
|
|
139
|
+
if (ts.createSourceFile(fileName, src, ts.ScriptTarget.Latest, true, srcKind(fileName)).parseDiagnostics.length)
|
|
140
|
+
return false;
|
|
141
|
+
}
|
|
142
|
+
else {
|
|
143
|
+
if (ts.transpileModule(src, { fileName, reportDiagnostics: true, compilerOptions: { allowJs: true, jsx: ts.JsxEmit.Preserve, module: ts.ModuleKind.ESNext, target: ts.ScriptTarget.ESNext } })
|
|
144
|
+
.diagnostics?.length)
|
|
145
|
+
return false;
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
catch {
|
|
149
|
+
return false;
|
|
150
|
+
}
|
|
151
|
+
const temp = `${fileName}.${process.pid}.quality.tmp`;
|
|
152
|
+
try {
|
|
153
|
+
writeFileSync(temp, src);
|
|
154
|
+
renameSync(temp, fileName);
|
|
155
|
+
}
|
|
156
|
+
finally {
|
|
157
|
+
try {
|
|
158
|
+
unlinkSync(temp);
|
|
159
|
+
}
|
|
160
|
+
catch {
|
|
161
|
+
// The temporary file was renamed successfully.
|
|
162
|
+
}
|
|
163
|
+
}
|
|
164
|
+
return true;
|
|
165
|
+
}
|
|
166
|
+
/**
|
|
167
|
+
* Selects the TypeScript parser mode for a JavaScript or TypeScript filename.
|
|
168
|
+
*
|
|
169
|
+
* @param fileName Source filename whose extension determines the parser mode.
|
|
170
|
+
*
|
|
171
|
+
* @return TypeScript compiler script kind for the filename.
|
|
172
|
+
*/
|
|
173
|
+
function srcKind(fileName) {
|
|
174
|
+
return /\.[cm]?tsx?$/.test(fileName) && fileName.endsWith('x') ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
|
|
175
|
+
}
|
|
176
|
+
/**
|
|
177
|
+
* Selects import source text, extracting Astro frontmatter without parsing its template markup.
|
|
178
|
+
*
|
|
179
|
+
* @param fileName Source path whose extension determines whether frontmatter extraction is needed.
|
|
180
|
+
* @param text Complete source text read from the file.
|
|
181
|
+
*
|
|
182
|
+
* @return Parseable import text, its source offset and line offset, or `undefined` for malformed Astro frontmatter.
|
|
183
|
+
*/
|
|
184
|
+
function duplicateImportSrc(fileName, text) {
|
|
185
|
+
if (extname(fileName) !== '.astro')
|
|
186
|
+
return { text, offset: 0, lineOffset: 0 };
|
|
187
|
+
const match = text.match(/^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/u);
|
|
188
|
+
if (!match || match.index === undefined)
|
|
189
|
+
return undefined;
|
|
190
|
+
const offset = match.index + match[0].indexOf(match[1]);
|
|
191
|
+
return { text: match[1], offset, lineOffset: text.slice(0, offset).split(/\r?\n/u).length - 1 };
|
|
192
|
+
}
|
|
193
|
+
/**
|
|
194
|
+
* Canonical groups used to order and label source imports.
|
|
195
|
+
*
|
|
196
|
+
* @param name Local import name whose casing indicates its category.
|
|
197
|
+
*
|
|
198
|
+
* @return Import group for API, component, or uppercase data names.
|
|
199
|
+
*/
|
|
200
|
+
function importGroup(name) {
|
|
201
|
+
if (/^[A-Z][A-Z0-9_]*$/.test(name))
|
|
202
|
+
return 'DATA';
|
|
203
|
+
if (/^[A-Z]/.test(name))
|
|
204
|
+
return 'COMPONENTS';
|
|
205
|
+
return 'API';
|
|
206
|
+
}
|
|
207
|
+
/**
|
|
208
|
+
* Finds repeated named bindings that the source maintainer can merge without
|
|
209
|
+
* changing import evaluation order or side-effect-only imports.
|
|
210
|
+
*
|
|
211
|
+
* @param files Configured source files to inspect.
|
|
212
|
+
*
|
|
213
|
+
* @return One finding for each later import declaration that repeats a binding.
|
|
214
|
+
*/
|
|
215
|
+
export function duplicateImportFindings(files) {
|
|
216
|
+
const findings = [];
|
|
217
|
+
for (const file of files) {
|
|
218
|
+
if (!IMPORT_SUPPORTED.has(extname(file)))
|
|
219
|
+
continue;
|
|
220
|
+
const src = duplicateImportSrc(file, readFileSync(file, 'utf8'));
|
|
221
|
+
if (!src)
|
|
222
|
+
continue;
|
|
223
|
+
const parsed = ts.createSourceFile(file, src.text, ts.ScriptTarget.Latest, true, srcKind(file));
|
|
224
|
+
const seen = new Set();
|
|
225
|
+
for (const declaration of parsed.statements.filter(ts.isImportDeclaration)) {
|
|
226
|
+
if (!declaration.importClause || !ts.isStringLiteral(declaration.moduleSpecifier))
|
|
227
|
+
continue;
|
|
228
|
+
const keys = [];
|
|
229
|
+
if (declaration.importClause.name)
|
|
230
|
+
keys.push(`${declaration.moduleSpecifier.text}|${importGroup(declaration.importClause.name.text)}|${declaration.importClause.isTypeOnly ? 'type' : 'value'}|default:${declaration.importClause.name.text}`);
|
|
231
|
+
if (declaration.importClause.namedBindings && ts.isNamespaceImport(declaration.importClause.namedBindings))
|
|
232
|
+
keys.push(`${declaration.moduleSpecifier.text}|${importGroup(declaration.importClause.namedBindings.name.text)}|${declaration.importClause.isTypeOnly ? 'type' : 'value'}|namespace:${declaration.importClause.namedBindings.name.text}`);
|
|
233
|
+
if (declaration.importClause.namedBindings && ts.isNamedImports(declaration.importClause.namedBindings)) {
|
|
234
|
+
for (const el of declaration.importClause.namedBindings.elements) {
|
|
235
|
+
const typeOnly = declaration.importClause.isTypeOnly || el.isTypeOnly;
|
|
236
|
+
keys.push(`${declaration.moduleSpecifier.text}|${typeOnly ? 'TYPES' : importGroup(el.name.text)}|${typeOnly ? 'type' : 'value'}|${el.getText(parsed).replace(TYPE_S_REGEX, '')}`);
|
|
237
|
+
}
|
|
238
|
+
}
|
|
239
|
+
if (keys.some(k => seen.has(k))) {
|
|
240
|
+
const { line } = parsed.getLineAndCharacterOfPosition(declaration.getStart(parsed));
|
|
241
|
+
findings.push({ file, line: line + src.lineOffset + 1, module: declaration.moduleSpecifier.text });
|
|
242
|
+
}
|
|
243
|
+
for (const key of keys)
|
|
244
|
+
seen.add(key);
|
|
245
|
+
}
|
|
246
|
+
}
|
|
247
|
+
return findings;
|
|
248
|
+
}
|
|
249
|
+
/**
|
|
250
|
+
* Removes repeated, identical import declarations when their standalone lines carry no comments.
|
|
251
|
+
*
|
|
252
|
+
* @param files Configured source files to inspect and update.
|
|
253
|
+
*
|
|
254
|
+
* @return Number of duplicate declarations removed.
|
|
255
|
+
*/
|
|
256
|
+
export function fixDuplicateImports(files) {
|
|
257
|
+
let removed = 0;
|
|
258
|
+
for (const file of files) {
|
|
259
|
+
if (!IMPORT_SUPPORTED.has(extname(file)))
|
|
260
|
+
continue;
|
|
261
|
+
const text = readFileSync(file, 'utf8');
|
|
262
|
+
const src = duplicateImportSrc(file, text);
|
|
263
|
+
if (!src)
|
|
264
|
+
continue;
|
|
265
|
+
const parsed = ts.createSourceFile(file, src.text, ts.ScriptTarget.Latest, true, srcKind(file));
|
|
266
|
+
const seen = new Set();
|
|
267
|
+
const edits = [];
|
|
268
|
+
for (const declaration of parsed.statements.filter(ts.isImportDeclaration)) {
|
|
269
|
+
if (!declaration.importClause || !ts.isStringLiteral(declaration.moduleSpecifier) || declaration.attributes)
|
|
270
|
+
continue;
|
|
271
|
+
const signature = declaration.getText(parsed);
|
|
272
|
+
if (!seen.has(signature)) {
|
|
273
|
+
seen.add(signature);
|
|
274
|
+
continue;
|
|
275
|
+
}
|
|
276
|
+
if (ts.getLeadingCommentRanges(src.text, declaration.getFullStart())?.length || ts.getTrailingCommentRanges(src.text, declaration.end)?.length)
|
|
277
|
+
continue;
|
|
278
|
+
const lineStart = src.text.lastIndexOf('\n', declaration.getStart(parsed) - 1) + 1;
|
|
279
|
+
const newlineStart = src.text.indexOf('\n', declaration.end);
|
|
280
|
+
if (src.text.slice(lineStart, declaration.getStart(parsed)).trim() || src.text.slice(declaration.end, newlineStart < 0 ? src.text.length : newlineStart).trim())
|
|
281
|
+
continue;
|
|
282
|
+
edits.push({ start: src.offset + lineStart, end: src.offset + (newlineStart < 0 ? src.text.length : newlineStart + 1) });
|
|
283
|
+
}
|
|
284
|
+
if (!edits.length)
|
|
285
|
+
continue;
|
|
286
|
+
const updated = edits.sort((left, right) => right.start - left.start).reduce((src, edit) => `${src.slice(0, edit.start)}${src.slice(edit.end)}`, text);
|
|
287
|
+
if (updated === text)
|
|
288
|
+
continue;
|
|
289
|
+
writeFileSync(file, updated);
|
|
290
|
+
removed += edits.length;
|
|
291
|
+
}
|
|
292
|
+
return removed;
|
|
293
|
+
}
|
|
294
|
+
/**
|
|
295
|
+
* Retains the historical API without changing source comments or section labels.
|
|
296
|
+
*
|
|
297
|
+
* @param root Repository root retained for compatibility with existing callers.
|
|
298
|
+
* @param fileName Source file retained for compatibility with existing callers.
|
|
299
|
+
*
|
|
300
|
+
* @return Always `false`; source documentation remains agent-authored.
|
|
301
|
+
*/
|
|
302
|
+
export function maintainSrcFile(root, fileName) {
|
|
303
|
+
void root;
|
|
304
|
+
void fileName;
|
|
305
|
+
return false;
|
|
306
|
+
}
|
|
307
|
+
/**
|
|
308
|
+
* Retains the historical cleanup API without deleting source comments or section labels.
|
|
309
|
+
*
|
|
310
|
+
* @param fileName Source file retained for compatibility with existing callers.
|
|
311
|
+
*
|
|
312
|
+
* @return Always `false`; comment cleanup requires an agent review.
|
|
313
|
+
*/
|
|
314
|
+
export function removeNonCodeComments(fileName) {
|
|
315
|
+
void fileName;
|
|
316
|
+
return false;
|
|
317
|
+
}
|
|
318
|
+
/**
|
|
319
|
+
* Adds Prettier protection to one-line imports that exceed the configured print width.
|
|
320
|
+
*
|
|
321
|
+
* @param fileName Absolute path to the source file whose imports are inspected.
|
|
322
|
+
* @param printWidth Maximum line width before a Prettier ignore marker is inserted.
|
|
323
|
+
*
|
|
324
|
+
* @return `true` when one or more ignore markers were inserted.
|
|
325
|
+
*/
|
|
326
|
+
export function protectLongImports(fileName, printWidth = 200) {
|
|
327
|
+
if (!SUPPORTED.has(extname(fileName)))
|
|
328
|
+
return false;
|
|
329
|
+
const orig = readFileSync(fileName, 'utf8');
|
|
330
|
+
const eol = orig.includes('\r\n') ? '\r\n' : '\n';
|
|
331
|
+
const parsed = ts.createSourceFile(fileName, orig, ts.ScriptTarget.Latest, true, srcKind(fileName));
|
|
332
|
+
const lineStarts = parsed.getLineStarts();
|
|
333
|
+
const insertions = new Set();
|
|
334
|
+
for (const n of parsed.statements.filter(ts.isImportDeclaration)) {
|
|
335
|
+
const lineStart = lineStarts[parsed.getLineAndCharacterOfPosition(n.getStart(parsed)).line] ?? 0;
|
|
336
|
+
const nline = orig.indexOf('\n', n.end);
|
|
337
|
+
if (orig.slice(lineStart, nline < 0 ? orig.length : nline).replace(/\r$/, '').length <= printWidth || orig.slice(lineStart, n.getStart(parsed)).trim())
|
|
338
|
+
continue;
|
|
339
|
+
const prevLineEnd = lineStart > 0 ? lineStart - 1 : -1;
|
|
340
|
+
if (orig.slice(prevLineEnd >= 0 ? orig.lastIndexOf('\n', prevLineEnd - 1) + 1 : 0, prevLineEnd + 1).trim() === '// prettier-ignore')
|
|
341
|
+
continue;
|
|
342
|
+
insertions.add(lineStart);
|
|
343
|
+
}
|
|
344
|
+
if (!insertions.size)
|
|
345
|
+
return false;
|
|
346
|
+
let next = orig;
|
|
347
|
+
for (const offset of [...insertions].sort((a, b) => b - a)) {
|
|
348
|
+
const nLine = orig.indexOf('\n', offset);
|
|
349
|
+
next = `${next.slice(0, offset)}${orig.slice(offset, nLine < 0 ? orig.length : nLine).match(S_REGEX)?.[0] ?? ''}// prettier-ignore${eol}${next.slice(offset)}`;
|
|
350
|
+
}
|
|
351
|
+
return writeValidatedSrc(fileName, next);
|
|
352
|
+
}
|
|
353
|
+
// hygiene-ignore single-use -- Keep the documented documentationScriptKind declaration so its parameter and return contract remains attached.
|
|
354
|
+
/**
|
|
355
|
+
* Selects the TypeScript parser mode used by documentation checks.
|
|
356
|
+
*
|
|
357
|
+
* @param fileName Filename whose extension determines the parser mode.
|
|
358
|
+
*
|
|
359
|
+
* @return TypeScript compiler script kind for the filename.
|
|
360
|
+
*/
|
|
361
|
+
function documentationScriptKind(fileName) {
|
|
362
|
+
if (/\.[cm]?tsx$/.test(fileName))
|
|
363
|
+
return ts.ScriptKind.TSX;
|
|
364
|
+
if (/\.[cm]?jsx$/.test(fileName))
|
|
365
|
+
return ts.ScriptKind.JSX;
|
|
366
|
+
if (/\.[cm]?js$/.test(fileName))
|
|
367
|
+
return ts.ScriptKind.JS;
|
|
368
|
+
return ts.ScriptKind.TS;
|
|
369
|
+
}
|
|
370
|
+
/**
|
|
371
|
+
* Checks whether a filename is supported by the documentation policy.
|
|
372
|
+
*
|
|
373
|
+
* @param fileName Source filename to test.
|
|
374
|
+
*
|
|
375
|
+
* @return `true` for supported JavaScript and TypeScript extensions.
|
|
376
|
+
*/
|
|
377
|
+
function documentationSupported(fileName) {
|
|
378
|
+
return /\.(?:c|m)?(?:js|jsx|ts|tsx)$/.test(fileName);
|
|
379
|
+
}
|
|
380
|
+
/**
|
|
381
|
+
* Excludes generated and vendored sources from documentation policy checks.
|
|
382
|
+
*
|
|
383
|
+
* @param cfg Quality configuration defining the repository root.
|
|
384
|
+
* @param file Absolute source path to classify.
|
|
385
|
+
*
|
|
386
|
+
* @return Whether the file is outside generated and vendor directories.
|
|
387
|
+
*/
|
|
388
|
+
function documentationSrcIncluded(cfg, file) {
|
|
389
|
+
return !relative(cfg.root, file)
|
|
390
|
+
.split(sep)
|
|
391
|
+
.some(d => ['generated', 'vendor', 'target', 'out'].includes(d));
|
|
392
|
+
}
|
|
393
|
+
/**
|
|
394
|
+
* Audits Doxygen blocks on C prototypes and definitions using Clang's declaration AST.
|
|
395
|
+
*
|
|
396
|
+
* @param cfg Quality configuration used to render repository-relative diagnostics.
|
|
397
|
+
* @param file C or header source path passed to Clang for declaration parsing.
|
|
398
|
+
* @param src Source text whose documentation declarations are audited.
|
|
399
|
+
* @param documentedSignatures Signatures already documented by matching source/header blocks.
|
|
400
|
+
* @param missingTargets Map populated with missing declaration locations for duplicate suppression.
|
|
401
|
+
*
|
|
402
|
+
* @return Findings for missing, malformed, or misordered Doxygen documentation.
|
|
403
|
+
*/
|
|
404
|
+
function cDocumentationFindings(cfg, file, src, documentedSignatures = new Set(), missingTargets = new Map()) {
|
|
405
|
+
const parsed = spawnSync(cfg.tools?.clang ?? 'clang', ['-x', 'c', '-std=c11', '-fsyntax-only', '-Wno-everything', '-Wno-unknown-pragmas', '-Wno-ignored-attributes', '-Xclang', '-ast-dump=json', file], { cwd: cfg.root, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024 });
|
|
406
|
+
if (parsed.error || !parsed.stdout)
|
|
407
|
+
return [
|
|
408
|
+
{
|
|
409
|
+
file: displayPath(cfg, file),
|
|
410
|
+
line: 1,
|
|
411
|
+
column: 1,
|
|
412
|
+
name: 'clang',
|
|
413
|
+
kind: 'function',
|
|
414
|
+
reason: `Clang is required to inspect C documentation: ${parsed.error?.message ?? (parsed.stderr.trim() || 'no AST output')}`,
|
|
415
|
+
severity: 'error',
|
|
416
|
+
},
|
|
417
|
+
];
|
|
418
|
+
const declarations = [];
|
|
419
|
+
const walk = (node) => {
|
|
420
|
+
if (node.kind === 'FunctionDecl' && node.name && node.loc?.offset !== undefined && !node.loc.includedFrom && (!node.loc.file || resolve(node.loc.file) === resolve(file))) {
|
|
421
|
+
const children = node.inner ?? [];
|
|
422
|
+
declarations.push({
|
|
423
|
+
name: node.name,
|
|
424
|
+
signature: `${node.name}|${node.type?.qualType ?? ''}`,
|
|
425
|
+
line: node.loc.line ?? src.slice(0, node.loc.offset).split('\n').length,
|
|
426
|
+
params: children.filter(c => c.kind === 'ParmVarDecl').map(c => c.name ?? '<unnamed>'),
|
|
427
|
+
returnsValue: !/^void\s*\(/.test(node.type?.qualType ?? ''),
|
|
428
|
+
comment: children.find(c => c.kind === 'FullComment'),
|
|
429
|
+
});
|
|
430
|
+
}
|
|
431
|
+
for (const child of node.inner ?? [])
|
|
432
|
+
walk(child);
|
|
433
|
+
};
|
|
434
|
+
walk(JSON.parse(parsed.stdout));
|
|
435
|
+
const rel = relative(cfg.root, file).split(sep).join('/');
|
|
436
|
+
const author = Object.entries(cfg.documentation?.cAuthors ?? {})
|
|
437
|
+
.filter(([p]) => rel.startsWith(p.replace(/\/$/, '') + '/'))
|
|
438
|
+
.sort(([l], [r]) => r.length - l.length)[0]?.[1];
|
|
439
|
+
const findings = [];
|
|
440
|
+
const deduplicated = new Map();
|
|
441
|
+
for (const declaration of declarations) {
|
|
442
|
+
const prev = deduplicated.get(declaration.signature);
|
|
443
|
+
if (!prev || (!prev.comment && declaration.comment))
|
|
444
|
+
deduplicated.set(declaration.signature, declaration);
|
|
445
|
+
}
|
|
446
|
+
for (const declaration of deduplicated.values()) {
|
|
447
|
+
const comment = declaration.comment
|
|
448
|
+
? (function parseCComment(node) {
|
|
449
|
+
const result = { summary: '', params: [], authors: [], returns: undefined };
|
|
450
|
+
const text = (current) => (current.text ?? '') + (current.inner ?? []).map(text).join('');
|
|
451
|
+
for (const child of node.inner ?? []) {
|
|
452
|
+
if (child.kind === 'ParagraphComment')
|
|
453
|
+
result.summary += text(child);
|
|
454
|
+
if (child.kind === 'ParamCommandComment')
|
|
455
|
+
result.params.push({ name: child.param ?? '', description: text(child).trim() });
|
|
456
|
+
if (child.kind === 'BlockCommandComment') {
|
|
457
|
+
const value = text(child).trim();
|
|
458
|
+
if (/^brief$/i.test(child.name ?? ''))
|
|
459
|
+
result.summary += value;
|
|
460
|
+
if (/^returns?$/i.test(child.name ?? ''))
|
|
461
|
+
result.returns = value;
|
|
462
|
+
if (/^author$/i.test(child.name ?? ''))
|
|
463
|
+
result.authors.push(value);
|
|
464
|
+
}
|
|
465
|
+
}
|
|
466
|
+
return result;
|
|
467
|
+
})(declaration.comment)
|
|
468
|
+
: undefined;
|
|
469
|
+
const report = (name, kind, reason) => {
|
|
470
|
+
findings.push({ file: displayPath(cfg, file), line: declaration.line, column: 1, name, kind, reason, severity: 'error' });
|
|
471
|
+
};
|
|
472
|
+
if (!comment) {
|
|
473
|
+
missingTargets.set(`${displayPath(cfg, file)}|${declaration.line}|${declaration.name}`, declaration.signature);
|
|
474
|
+
report(declaration.name, 'function', `missing documentation block for ${declaration.name}`);
|
|
475
|
+
continue;
|
|
476
|
+
}
|
|
477
|
+
documentedSignatures.add(declaration.signature);
|
|
478
|
+
if (!comment.summary.trim())
|
|
479
|
+
report('<summary>', 'summary', 'add a meaningful documentation summary');
|
|
480
|
+
const documented = comment.params.map(({ name: n }) => n);
|
|
481
|
+
for (const name of declaration.params)
|
|
482
|
+
if (!documented.includes(name))
|
|
483
|
+
report(`@param ${name}`, 'param', `missing @param ${name}`);
|
|
484
|
+
for (const name of new Set(documented.filter(n => !declaration.params.includes(n))))
|
|
485
|
+
report(`@param ${name}`, 'param', `stale @param ${name}`);
|
|
486
|
+
if (declaration.params.some((n, i) => documented[i] !== n))
|
|
487
|
+
report('@param order', 'param', `@param tags must follow signature order: ${declaration.params.join(', ')}`);
|
|
488
|
+
for (const { name, description: desc } of comment.params)
|
|
489
|
+
if (declaration.params.includes(name) && !desc.trim())
|
|
490
|
+
report(`@param ${name}`, 'param', `missing description for @param ${name}`);
|
|
491
|
+
if (declaration.returnsValue && !comment.returns?.trim())
|
|
492
|
+
report('@return', 'return', 'missing @return description');
|
|
493
|
+
if (author && !comment.authors.includes(author))
|
|
494
|
+
report(`@author ${author}`, 'tag', `missing or incorrect @author ${author}`);
|
|
495
|
+
}
|
|
496
|
+
return findings;
|
|
497
|
+
}
|
|
498
|
+
/**
|
|
499
|
+
* Checks whether a node has a JSDoc or TSDoc block in its leading trivia.
|
|
500
|
+
*
|
|
501
|
+
* @param node Declaration node to inspect.
|
|
502
|
+
* @param src Source text containing the node.
|
|
503
|
+
*
|
|
504
|
+
* @return `true` when a documentation comment directly precedes the node.
|
|
505
|
+
*/
|
|
506
|
+
function documented(node, src) {
|
|
507
|
+
const target = documentationTarget(node);
|
|
508
|
+
const doc = [...src.slice(target.getFullStart(), target.getStart()).matchAll(S_S_G_REGEX())].at(-1);
|
|
509
|
+
if (!doc)
|
|
510
|
+
return false;
|
|
511
|
+
// The generated file header is source-level metadata, not documentation for
|
|
512
|
+
// the first declaration. Only exclude it when the block is the first
|
|
513
|
+
// path-bearing TSDoc in the file; a declaration's own later TSDoc remains
|
|
514
|
+
// valid even when the file also has a header.
|
|
515
|
+
let prefix = src.slice(0, target.getFullStart() + doc.index).replace(UFEFF_REGEX, '');
|
|
516
|
+
if (prefix.startsWith('#!'))
|
|
517
|
+
prefix = prefix.slice(prefix.indexOf('\n') + 1);
|
|
518
|
+
return !(prefix.trim() === '' &&
|
|
519
|
+
doc[0]
|
|
520
|
+
.slice(3, -2)
|
|
521
|
+
.split(R_N_REGEX)
|
|
522
|
+
.map(l => l.replace(S_CLASS_3, '').trim())
|
|
523
|
+
.some(l => C_M_JS_JSX_TS_TSX_REGEX.test(l)));
|
|
524
|
+
}
|
|
525
|
+
/**
|
|
526
|
+
* Checks whether a declaration carries an export modifier.
|
|
527
|
+
*
|
|
528
|
+
* @param node Declaration node to inspect.
|
|
529
|
+
*
|
|
530
|
+
* @return `true` when the node is explicitly exported.
|
|
531
|
+
*/
|
|
532
|
+
function exported(node) {
|
|
533
|
+
const target = documentationTarget(node);
|
|
534
|
+
return !!(ts.canHaveModifiers(target) && ts.getModifiers(target)?.some(m => m.kind === ts.SyntaxKind.ExportKeyword));
|
|
535
|
+
}
|
|
536
|
+
/**
|
|
537
|
+
* Extracts identifiers from a parameter's object or array binding pattern.
|
|
538
|
+
*
|
|
539
|
+
* @param name Parameter binding to inspect.
|
|
540
|
+
*
|
|
541
|
+
* @return Bound identifier names in source order.
|
|
542
|
+
*/
|
|
543
|
+
function bindingParamNames(name) {
|
|
544
|
+
if (ts.isIdentifier(name))
|
|
545
|
+
return [name.text];
|
|
546
|
+
return name.elements.flatMap(el => (ts.isOmittedExpression(el) ? [] : bindingParamNames(el.name)));
|
|
547
|
+
}
|
|
548
|
+
/**
|
|
549
|
+
* Chooses the TSDoc parameter-tag names for a declared function parameter.
|
|
550
|
+
*
|
|
551
|
+
* @param param Parameter declaration whose binding names should be documented.
|
|
552
|
+
* @param index Zero-based parameter position used when the binding has no identifiers.
|
|
553
|
+
*
|
|
554
|
+
* @return Bound identifier names, or a positional fallback for an empty pattern.
|
|
555
|
+
*/
|
|
556
|
+
function fnParamNames(param, index) {
|
|
557
|
+
if (ts.isIdentifier(param.name))
|
|
558
|
+
return [param.name.text];
|
|
559
|
+
const names = [...new Set(bindingParamNames(param.name))];
|
|
560
|
+
return names.length ? names : [`param${index + 1}`];
|
|
561
|
+
}
|
|
562
|
+
/**
|
|
563
|
+
* Gets the declared identifier used in a documentation diagnostic.
|
|
564
|
+
*
|
|
565
|
+
* @param node Declaration node whose name should be reported.
|
|
566
|
+
*
|
|
567
|
+
* @return Identifier text, or `<anonymous>` when the declaration has no identifier.
|
|
568
|
+
*/
|
|
569
|
+
function documentationNodeName(node) {
|
|
570
|
+
if (ts.isConstructorDeclaration(node))
|
|
571
|
+
return 'constructor';
|
|
572
|
+
const target = documentationTarget(node);
|
|
573
|
+
if (target !== node && ts.isVariableStatement(target)) {
|
|
574
|
+
const declaration = target.declarationList.declarations.find(c => containsNode(c, node));
|
|
575
|
+
if (declaration)
|
|
576
|
+
return declaration.name.getText();
|
|
577
|
+
}
|
|
578
|
+
const candidate = node.name ?? node;
|
|
579
|
+
return ts.isIdentifier(candidate) ? candidate.text : ts.isStringLiteral(candidate) || ts.isNumericLiteral(candidate) ? candidate.text : candidate === node ? '<anonymous>' : candidate.getText();
|
|
580
|
+
}
|
|
581
|
+
/**
|
|
582
|
+
* Finds the declaration that owns documentation for a named function value.
|
|
583
|
+
*
|
|
584
|
+
* @param node Function-like declaration or expression to resolve.
|
|
585
|
+
*
|
|
586
|
+
* @return Variable statement for a named function value, otherwise node itself.
|
|
587
|
+
*/
|
|
588
|
+
function documentationTarget(node) {
|
|
589
|
+
if (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) {
|
|
590
|
+
if (ts.isVariableDeclaration(node.parent) && node.parent.initializer === node) {
|
|
591
|
+
let target = node.parent;
|
|
592
|
+
while (target.parent && !ts.isVariableStatement(target))
|
|
593
|
+
target = target.parent;
|
|
594
|
+
return target;
|
|
595
|
+
}
|
|
596
|
+
}
|
|
597
|
+
return node;
|
|
598
|
+
}
|
|
599
|
+
/**
|
|
600
|
+
* Checks whether a function-like declaration has a stable name and needs its own documentation.
|
|
601
|
+
*
|
|
602
|
+
* @param node Syntax node to inspect.
|
|
603
|
+
*
|
|
604
|
+
* @return Whether node is a named function, method, constructor, or named function value.
|
|
605
|
+
*/
|
|
606
|
+
function isNamedDocumentationFn(node) {
|
|
607
|
+
if (!ts.isFunctionLike(node))
|
|
608
|
+
return false;
|
|
609
|
+
for (let parent = node.parent; parent; parent = parent.parent)
|
|
610
|
+
if (ts.isFunctionLike(parent))
|
|
611
|
+
return false;
|
|
612
|
+
if (ts.isFunctionDeclaration(node) ||
|
|
613
|
+
ts.isMethodDeclaration(node) ||
|
|
614
|
+
ts.isConstructorDeclaration(node) ||
|
|
615
|
+
ts.isGetAccessorDeclaration(node) ||
|
|
616
|
+
ts.isSetAccessorDeclaration(node) ||
|
|
617
|
+
ts.isMethodSignature(node))
|
|
618
|
+
return true;
|
|
619
|
+
if (ts.isFunctionExpression(node))
|
|
620
|
+
return Boolean(node.name) || documentationTarget(node) !== node;
|
|
621
|
+
if (ts.isArrowFunction(node))
|
|
622
|
+
return documentationTarget(node) !== node;
|
|
623
|
+
return false;
|
|
624
|
+
}
|
|
625
|
+
/**
|
|
626
|
+
* Tests whether an AST node is nested under a declaration.
|
|
627
|
+
*
|
|
628
|
+
* @param parent Candidate ancestor node.
|
|
629
|
+
* @param target Node whose ancestors should be searched.
|
|
630
|
+
*
|
|
631
|
+
* @return Whether target is parent or a descendant of parent.
|
|
632
|
+
*/
|
|
633
|
+
function containsNode(parent, target) {
|
|
634
|
+
for (let node = target; node; node = node.parent)
|
|
635
|
+
if (node === parent)
|
|
636
|
+
return true;
|
|
637
|
+
return false;
|
|
638
|
+
}
|
|
639
|
+
// hygiene-ignore single-use -- Keep the documented tsdocBlocks declaration so its parameter and return contract remains attached.
|
|
640
|
+
/**
|
|
641
|
+
* Scans source text for TSDoc blocks without treating comment-shaped text inside literals as documentation.
|
|
642
|
+
*
|
|
643
|
+
* @param src Source text to scan.
|
|
644
|
+
* @param parsed Parsed source file whose language variant should be respected.
|
|
645
|
+
*
|
|
646
|
+
* @return TSDoc blocks with their source offsets and original text.
|
|
647
|
+
*/
|
|
648
|
+
function tsdocBlocks(src, parsed) {
|
|
649
|
+
const blocks = new Map();
|
|
650
|
+
const add = (ranges) => {
|
|
651
|
+
for (const range of ranges ?? []) {
|
|
652
|
+
const text = src.slice(range.pos, range.end);
|
|
653
|
+
if (text.startsWith('/**'))
|
|
654
|
+
blocks.set(range.pos, { start: range.pos, end: range.end, text });
|
|
655
|
+
}
|
|
656
|
+
};
|
|
657
|
+
const visit = (node) => {
|
|
658
|
+
add(ts.getLeadingCommentRanges(src, node.getFullStart()));
|
|
659
|
+
add(ts.getTrailingCommentRanges(src, node.end));
|
|
660
|
+
ts.forEachChild(node, visit);
|
|
661
|
+
};
|
|
662
|
+
visit(parsed);
|
|
663
|
+
return [...blocks.values()].sort((l, r) => l.start - r.start);
|
|
664
|
+
}
|
|
665
|
+
/**
|
|
666
|
+
* Converts a TSDoc block into normalized content lines while retaining each line's source offset.
|
|
667
|
+
*
|
|
668
|
+
* @param block TSDoc block to split.
|
|
669
|
+
*
|
|
670
|
+
* @return TSDoc content lines with comment markers removed.
|
|
671
|
+
*/
|
|
672
|
+
function tsdocLines(block) {
|
|
673
|
+
const body = block.text.slice(3, -2);
|
|
674
|
+
const lineSize = body.includes('\r\n') ? 2 : 1;
|
|
675
|
+
let offset = block.start + 3;
|
|
676
|
+
return body.split(R_N_REGEX).map(l => {
|
|
677
|
+
// hygiene-ignore single-use -- Record this line's starting offset before advancing to the next line.
|
|
678
|
+
const result = { offset, text: l.replace(S_CLASS_3, '').trim() };
|
|
679
|
+
offset += l.length + lineSize;
|
|
680
|
+
return result;
|
|
681
|
+
});
|
|
682
|
+
}
|
|
683
|
+
// hygiene-ignore single-use -- Keep the documented fileHeaderBlock declaration so its parameter and return contract remains attached.
|
|
684
|
+
/**
|
|
685
|
+
* Finds the generated path-bearing mock-TSDoc block at the top of a source file, allowing a shebang and whitespace before it.
|
|
686
|
+
*
|
|
687
|
+
* @param src Source text to inspect.
|
|
688
|
+
* @param blocks TSDoc blocks found in the source.
|
|
689
|
+
*
|
|
690
|
+
* @return The top-level file-header block, or `undefined` when it is missing.
|
|
691
|
+
*/
|
|
692
|
+
function fileHeaderBlock(src, blocks) {
|
|
693
|
+
return blocks.find(b => {
|
|
694
|
+
let prefix = src.slice(0, b.start).replace(UFEFF_REGEX, '');
|
|
695
|
+
if (prefix.startsWith('#!'))
|
|
696
|
+
prefix = prefix.slice(prefix.indexOf('\n') + 1);
|
|
697
|
+
return prefix.trim() === '' && tsdocLines(b).some(l => C_M_JS_JSX_TS_TSX_REGEX.test(l.text));
|
|
698
|
+
});
|
|
699
|
+
}
|
|
700
|
+
/**
|
|
701
|
+
* Parses TSDoc tags and joins continuation lines with their leading tag line.
|
|
702
|
+
*
|
|
703
|
+
* @param lines Normalized TSDoc content lines.
|
|
704
|
+
*
|
|
705
|
+
* @return Parsed tag names, subjects, descriptions, and source offsets.
|
|
706
|
+
*/
|
|
707
|
+
function tsdocTagEntries(lines) {
|
|
708
|
+
const entries = [];
|
|
709
|
+
for (let idx = 0; idx < lines.length; idx += 1) {
|
|
710
|
+
const match = lines[idx].text.match(/^@(\S+)(?:\s+(.*))?$/);
|
|
711
|
+
if (!match)
|
|
712
|
+
continue;
|
|
713
|
+
const tag = match[1];
|
|
714
|
+
const content = [match[2] ?? ''];
|
|
715
|
+
let n = idx + 1;
|
|
716
|
+
while (n < lines.length && !lines[n].text.startsWith('@')) {
|
|
717
|
+
if (lines[n].text)
|
|
718
|
+
content.push(lines[n].text);
|
|
719
|
+
n += 1;
|
|
720
|
+
}
|
|
721
|
+
const rawContent = content.join(' ').trim();
|
|
722
|
+
const paramText = rawContent.replace(/^\{[^}]*\}\s*/, '').split(/\s+/)[0] ?? '';
|
|
723
|
+
entries.push({
|
|
724
|
+
tag,
|
|
725
|
+
subject: tag.toLowerCase() === 'param' ? paramText.replace(/^\[/, '').replace(/\]$/, '').split('=')[0] : tag.toLowerCase() === 'typeparam' ? paramText : '',
|
|
726
|
+
description: (function tagDesc(tag, content) {
|
|
727
|
+
let desc = content.trim().replace(S_CLASS_5, '');
|
|
728
|
+
if (tag.toLowerCase() === 'param' || tag.toLowerCase() === 'typeparam')
|
|
729
|
+
desc = desc.replace(/^\[[^\]]+\]\s*/, '').replace(/^\S+\s*/, '');
|
|
730
|
+
return desc.replace(/^[-:]\s*/, '').trim();
|
|
731
|
+
})(tag, rawContent),
|
|
732
|
+
offset: lines[idx].offset,
|
|
733
|
+
});
|
|
734
|
+
idx = n - 1;
|
|
735
|
+
}
|
|
736
|
+
return entries;
|
|
737
|
+
}
|
|
738
|
+
// hygiene-ignore single-use -- Keep the documented returnsVal declaration so its parameter and return contract remains attached.
|
|
739
|
+
/**
|
|
740
|
+
* Determines whether a function exposes a value through its return type or body.
|
|
741
|
+
*
|
|
742
|
+
* @param node Function declaration whose return contract is being checked.
|
|
743
|
+
*
|
|
744
|
+
* @return `true` when callers can receive a value rather than only completion.
|
|
745
|
+
*/
|
|
746
|
+
function returnsVal(node) {
|
|
747
|
+
if (ts.isConstructorDeclaration(node) || ts.isSetAccessorDeclaration(node))
|
|
748
|
+
return false;
|
|
749
|
+
if (ts.isArrowFunction(node) && !ts.isBlock(node.body))
|
|
750
|
+
return true;
|
|
751
|
+
const returnType = node.type?.getText().replace(/\s+/g, '') ?? '';
|
|
752
|
+
if (returnType === 'void' || returnType === 'Promise<void>')
|
|
753
|
+
return false;
|
|
754
|
+
if (node.type)
|
|
755
|
+
return true;
|
|
756
|
+
let valReturn = false;
|
|
757
|
+
const visit = (child) => {
|
|
758
|
+
if (valReturn)
|
|
759
|
+
return;
|
|
760
|
+
if (ts.isReturnStatement(child) && child.expression)
|
|
761
|
+
valReturn = true;
|
|
762
|
+
ts.forEachChild(child, visit);
|
|
763
|
+
};
|
|
764
|
+
if ('body' in node && node.body)
|
|
765
|
+
visit(node.body);
|
|
766
|
+
return valReturn;
|
|
767
|
+
}
|
|
768
|
+
// hygiene-ignore single-use -- Keep the documented documentationBlockFor declaration so its parameter and return contract remains attached.
|
|
769
|
+
/**
|
|
770
|
+
* Finds the TSDoc block directly attached to a declaration.
|
|
771
|
+
*
|
|
772
|
+
* @param src Source text containing the declaration and its comments.
|
|
773
|
+
* @param node Declaration whose leading documentation is required.
|
|
774
|
+
*
|
|
775
|
+
* @return The attached TSDoc block, or `undefined` when the declaration is undocumented.
|
|
776
|
+
*/
|
|
777
|
+
function documentationBlockFor(src, node) {
|
|
778
|
+
const range = (ts.getLeadingCommentRanges(src, documentationTarget(node).getFullStart()) ?? []).at(-1);
|
|
779
|
+
if (!range || range.kind !== ts.SyntaxKind.MultiLineCommentTrivia || !src.slice(range.pos, range.end).startsWith('/**'))
|
|
780
|
+
return undefined;
|
|
781
|
+
return { start: range.pos, end: range.end, text: src.slice(range.pos, range.end) };
|
|
782
|
+
}
|
|
783
|
+
// hygiene-ignore single-use -- Keep the documented descriptionFindingsForFile declaration so its parameter and return contract remains attached.
|
|
784
|
+
/**
|
|
785
|
+
* Audits existing TSDoc prose without inventing replacement text. Generated file
|
|
786
|
+
* path headers are source metadata and are intentionally excluded from this audit.
|
|
787
|
+
*
|
|
788
|
+
* @param cfg Quality configuration used to render repository-relative paths.
|
|
789
|
+
* @param file Absolute source path being inspected.
|
|
790
|
+
* @param src Source text containing the documentation blocks.
|
|
791
|
+
* @param parsed Parsed source file used for locations and comment scanning.
|
|
792
|
+
* @return Warning findings for missing file, summary, or tag descriptions.
|
|
793
|
+
*/
|
|
794
|
+
function descFindingsForFile(cfg, file, src, parsed) {
|
|
795
|
+
const blocks = tsdocBlocks(src, parsed);
|
|
796
|
+
const findings = [];
|
|
797
|
+
const header = fileHeaderBlock(src, blocks);
|
|
798
|
+
const attached = new Set();
|
|
799
|
+
const requiredAttached = new Set();
|
|
800
|
+
const requirements = { functions: true, ...cfg.documentation?.required };
|
|
801
|
+
const markAttached = (node) => {
|
|
802
|
+
const target = documentationTarget(node);
|
|
803
|
+
const requiresDocumentation = ((ts.isClassDeclaration(node) || ts.isEnumDeclaration(node) || ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node)) && requirements.types) ||
|
|
804
|
+
(isNamedDocumentationFn(node) && (requirements.functions || (requirements.exportedFunctions && exported(node)))) ||
|
|
805
|
+
((ts.isPropertySignature(node) || ts.isMethodSignature(node) || ts.isCallSignatureDeclaration(node) || ts.isConstructSignatureDeclaration(node) || ts.isIndexSignatureDeclaration(node)) &&
|
|
806
|
+
requirements.types);
|
|
807
|
+
if (ts.isDeclarationStatement(node) ||
|
|
808
|
+
ts.isFunctionLike(node) ||
|
|
809
|
+
ts.isClassLike(node) ||
|
|
810
|
+
ts.isEnumMember(node) ||
|
|
811
|
+
ts.isPropertySignature(node) ||
|
|
812
|
+
ts.isMethodSignature(node) ||
|
|
813
|
+
ts.isCallSignatureDeclaration(node) ||
|
|
814
|
+
ts.isConstructSignatureDeclaration(node) ||
|
|
815
|
+
ts.isIndexSignatureDeclaration(node) ||
|
|
816
|
+
ts.isTypeParameterDeclaration(node) ||
|
|
817
|
+
ts.isVariableStatement(node))
|
|
818
|
+
for (const range of ts.getLeadingCommentRanges(src, target.getFullStart()) ?? [])
|
|
819
|
+
if (src.slice(range.pos, range.end).startsWith('/**') && S_ONLY_REGEX.test(src.slice(range.end, target.getStart(parsed)))) {
|
|
820
|
+
attached.add(range.pos);
|
|
821
|
+
if (requiresDocumentation)
|
|
822
|
+
requiredAttached.add(range.pos);
|
|
823
|
+
}
|
|
824
|
+
ts.forEachChild(node, markAttached);
|
|
825
|
+
};
|
|
826
|
+
markAttached(parsed);
|
|
827
|
+
for (const block of blocks) {
|
|
828
|
+
if (!tsdocTagEntries(tsdocLines(block)).some(entry => entry.tag.toLowerCase() === 'typedef'))
|
|
829
|
+
continue;
|
|
830
|
+
attached.add(block.start);
|
|
831
|
+
if (requirements.types)
|
|
832
|
+
requiredAttached.add(block.start);
|
|
833
|
+
}
|
|
834
|
+
for (const block of blocks) {
|
|
835
|
+
if (block === header)
|
|
836
|
+
continue;
|
|
837
|
+
// JSDoc's parenthesized expression cast is part of the expression, not a detached declaration comment.
|
|
838
|
+
if (/@type\s*\{/u.test(block.text) && /^[ \t]*\(/u.test(src.slice(block.end)))
|
|
839
|
+
continue;
|
|
840
|
+
if (!attached.has(block.start)) {
|
|
841
|
+
findings.push(documentationCommentReport(file, parsed, block.start, '<detached TSDoc>', 'orphan', 'remove or attach this TSDoc to a declaration', cfg));
|
|
842
|
+
continue;
|
|
843
|
+
}
|
|
844
|
+
if (!requiredAttached.has(block.start))
|
|
845
|
+
continue;
|
|
846
|
+
const lines = tsdocLines(block);
|
|
847
|
+
const firstTag = lines.findIndex(l => l.text.startsWith('@'));
|
|
848
|
+
if (!lines
|
|
849
|
+
.slice(0, firstTag < 0 ? lines.length : firstTag)
|
|
850
|
+
.map(l => l.text)
|
|
851
|
+
.filter(Boolean).length)
|
|
852
|
+
findings.push(documentationCommentReport(file, parsed, block.start, '<TSDoc summary>', 'summary', 'add a meaningful description for this TSDoc block', cfg));
|
|
853
|
+
for (const entry of tsdocTagEntries(lines)) {
|
|
854
|
+
if (entry.tag.toLowerCase() === 'param' && entry.subject.toLowerCase() === 'props') {
|
|
855
|
+
findings.push(documentationCommentReport(file, parsed, entry.offset, `@${entry.tag} ${entry.subject}`, 'param', 'replace the aggregate props tag with an individual @param tag for each binding', cfg));
|
|
856
|
+
continue;
|
|
857
|
+
}
|
|
858
|
+
if (DESC_OPTIONAL_TAGS.has(entry.tag.toLowerCase()) || entry.description)
|
|
859
|
+
continue;
|
|
860
|
+
const name = `@${entry.tag}${entry.subject ? ` ${entry.subject}` : ''}`;
|
|
861
|
+
findings.push(documentationCommentReport(file, parsed, entry.offset, name, entry.tag.toLowerCase() === 'param' ? 'param' : entry.tag.toLowerCase() === 'return' || entry.tag.toLowerCase() === 'returns' ? 'return' : 'tag', `add a meaningful description for ${name}`, cfg));
|
|
862
|
+
}
|
|
863
|
+
}
|
|
864
|
+
return findings;
|
|
865
|
+
}
|
|
866
|
+
/**
|
|
867
|
+
* Creates an error finding anchored to a TSDoc comment offset.
|
|
868
|
+
*
|
|
869
|
+
* @param file Absolute source path containing the comment.
|
|
870
|
+
* @param parsed Parsed source file used to calculate the location.
|
|
871
|
+
* @param offset Zero-based source offset for the comment or tag.
|
|
872
|
+
* @param name Display name for the missing documentation.
|
|
873
|
+
* @param kind Documentation audit category.
|
|
874
|
+
* @param reason Human-readable remediation reason.
|
|
875
|
+
* @param cfg Quality configuration defining the repository root.
|
|
876
|
+
*
|
|
877
|
+
* @return Documentation error.
|
|
878
|
+
*/
|
|
879
|
+
function documentationCommentReport(file, parsed, offset, name, kind, reason, cfg) {
|
|
880
|
+
const pos = parsed.getLineAndCharacterOfPosition(offset);
|
|
881
|
+
return { file: displayPath(cfg, file), line: pos.line + 1, column: pos.character + 1, name, kind, reason, severity: 'error' };
|
|
882
|
+
}
|
|
883
|
+
/**
|
|
884
|
+
* Creates a documentation finding with a repository-relative source location.
|
|
885
|
+
*
|
|
886
|
+
* @param file Absolute path to the source file.
|
|
887
|
+
* @param parsed Parsed source file used to calculate the location.
|
|
888
|
+
* @param node Undocumented node that triggered the finding.
|
|
889
|
+
* @param name Display name for the node.
|
|
890
|
+
* @param kind Documentation category for the finding.
|
|
891
|
+
* @param reason Human-readable remediation reason.
|
|
892
|
+
* @param cfg Quality configuration defining the repository root.
|
|
893
|
+
*
|
|
894
|
+
* @return Structured documentation finding.
|
|
895
|
+
*/
|
|
896
|
+
function documentationReport(file, parsed, node, name, kind, reason, cfg) {
|
|
897
|
+
const pos = parsed.getLineAndCharacterOfPosition(node.getStart(parsed));
|
|
898
|
+
return { file: displayPath(cfg, file), line: pos.line + 1, column: pos.character + 1, name, kind, reason, severity: 'error' };
|
|
899
|
+
}
|
|
900
|
+
/**
|
|
901
|
+
* Evaluates documentation requirements for one source file.
|
|
902
|
+
*
|
|
903
|
+
* @param cfg Quality configuration used to render diagnostic paths.
|
|
904
|
+
* @param file Absolute source path to inspect.
|
|
905
|
+
* @param requirements Enabled documentation policies.
|
|
906
|
+
* @param analysis Optional shared program and source cache for the current run.
|
|
907
|
+
*
|
|
908
|
+
* @return Documentation findings for the file.
|
|
909
|
+
*/
|
|
910
|
+
function documentationFindingsForFile(cfg, file, requirements, analysis) {
|
|
911
|
+
if (!documentationSupported(file))
|
|
912
|
+
return [];
|
|
913
|
+
const src = analysis?.texts.get(file) ?? readFileSync(file, 'utf8');
|
|
914
|
+
// Regex-dedup registries are generated API plumbing marked as non-editable;
|
|
915
|
+
// their exported factories inherit documentation from the authored source use sites.
|
|
916
|
+
if (/^\/\/ Generated by @terra-symposium\/hygiene regex-dedup\. Do not edit\.$/mu.test(src))
|
|
917
|
+
return [];
|
|
918
|
+
const parsed = analysis?.sources.get(file) ?? ts.createSourceFile(file, src, ts.ScriptTarget.Latest, true, documentationScriptKind(file));
|
|
919
|
+
const findings = descFindingsForFile(cfg, file, src, parsed);
|
|
920
|
+
const visit = (node) => {
|
|
921
|
+
if (requirements.types && (ts.isClassDeclaration(node) || ts.isEnumDeclaration(node) || ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node)) && !documented(node, src))
|
|
922
|
+
findings.push(documentationReport(file, parsed, node, documentationNodeName(node), 'type', 'add TSDoc for this type', cfg));
|
|
923
|
+
if (isNamedDocumentationFn(node)) {
|
|
924
|
+
if (requirements.functions || (requirements.exportedFunctions && exported(node))) {
|
|
925
|
+
if (!documented(node, src)) {
|
|
926
|
+
findings.push(documentationReport(file, parsed, node, documentationNodeName(node), 'function', 'add TSDoc for this function', cfg));
|
|
927
|
+
}
|
|
928
|
+
else {
|
|
929
|
+
const block = documentationBlockFor(src, node);
|
|
930
|
+
if (block) {
|
|
931
|
+
const entries = tsdocTagEntries(tsdocLines(block));
|
|
932
|
+
const documentedParams = new Set(entries.filter(e => e.tag.toLowerCase() === 'param').map(e => e.subject));
|
|
933
|
+
const declaredParams = new Set(node.parameters.flatMap((param, i) => fnParamNames(param, i)));
|
|
934
|
+
for (const [idx, param] of node.parameters.entries()) {
|
|
935
|
+
for (const name of fnParamNames(param, idx))
|
|
936
|
+
if (!documentedParams.has(name))
|
|
937
|
+
findings.push(documentationReport(file, parsed, node, `@param ${name}`, 'param', `document the ${name} parameter`, cfg));
|
|
938
|
+
}
|
|
939
|
+
for (const entry of entries.filter(item => {
|
|
940
|
+
if (item.tag.toLowerCase() !== 'param' || !item.subject || declaredParams.has(item.subject))
|
|
941
|
+
return false;
|
|
942
|
+
return !declaredParams.has(item.subject.split('.')[0]);
|
|
943
|
+
})) {
|
|
944
|
+
if (!(entry.subject === 'props' && node.parameters.some(param => ts.isObjectBindingPattern(param.name))))
|
|
945
|
+
findings.push(documentationCommentReport(file, parsed, entry.offset, `@param ${entry.subject}`, 'param', `remove stale @param ${entry.subject}`, cfg));
|
|
946
|
+
}
|
|
947
|
+
if (returnsVal(node) && !entries.some(e => ['return', 'returns'].includes(e.tag.toLowerCase())))
|
|
948
|
+
findings.push(documentationReport(file, parsed, node, '@return', 'return', 'document the value returned by this function', cfg));
|
|
949
|
+
}
|
|
950
|
+
}
|
|
951
|
+
}
|
|
952
|
+
}
|
|
953
|
+
if (requirements.noInlineFunctions && (ts.isArrowFunction(node) || ts.isFunctionExpression(node)))
|
|
954
|
+
findings.push(documentationReport(file, parsed, node, documentationNodeName(node), 'inline', 'move this function to a named declaration', cfg));
|
|
955
|
+
ts.forEachChild(node, visit);
|
|
956
|
+
};
|
|
957
|
+
visit(parsed);
|
|
958
|
+
return findings;
|
|
959
|
+
}
|
|
960
|
+
/**
|
|
961
|
+
* Finds documentation-policy violations for the configured source scope.
|
|
962
|
+
*
|
|
963
|
+
* @param cfg Quality configuration containing required documentation policies.
|
|
964
|
+
* @param analysis Optional shared program and source cache for the current run.
|
|
965
|
+
*
|
|
966
|
+
* @return Documentation findings across the configured source scope.
|
|
967
|
+
*/
|
|
968
|
+
export function documentationFindings(cfg, analysis) {
|
|
969
|
+
const requirements = { functions: true, ...cfg.documentation?.required };
|
|
970
|
+
const sharedAnalysis = analysis;
|
|
971
|
+
const documentedSignatures = new Set();
|
|
972
|
+
const missingTargets = new Map();
|
|
973
|
+
// hygiene-ignore single-use -- Analyze C files first to populate documented signatures and missing targets before other findings.
|
|
974
|
+
const cFindings = srcFiles({ ...cfg, extensions: ['.c', '.h'] })
|
|
975
|
+
.filter(f => documentationSrcIncluded(cfg, f))
|
|
976
|
+
.flatMap(f => cDocumentationFindings(cfg, f, readFileSync(f, 'utf8'), documentedSignatures, missingTargets));
|
|
977
|
+
// hygiene-ignore single-use -- Complete the other source scan before selecting primary C declarations below.
|
|
978
|
+
const otherFindings = (sharedAnalysis?.files
|
|
979
|
+
? sharedAnalysis.files.filter(f => documentationSrcIncluded(cfg, f) && documentationSupported(f))
|
|
980
|
+
: srcFiles(cfg).filter(f => documentationSrcIncluded(cfg, f) && documentationSupported(f))).flatMap(f => documentationFindingsForFile(cfg, f, requirements, sharedAnalysis));
|
|
981
|
+
const primaryMissing = new Map();
|
|
982
|
+
for (const [target, signature] of missingTargets)
|
|
983
|
+
if (!primaryMissing.has(signature))
|
|
984
|
+
primaryMissing.set(signature, target);
|
|
985
|
+
return [...cFindings, ...otherFindings].filter(f => {
|
|
986
|
+
if (f.kind !== 'function' || !f.reason.startsWith('missing documentation block'))
|
|
987
|
+
return true;
|
|
988
|
+
const target = `${f.file}|${f.line}|${f.name}`;
|
|
989
|
+
const signature = missingTargets.get(target);
|
|
990
|
+
return !signature || (!documentedSignatures.has(signature) && primaryMissing.get(signature) === target);
|
|
991
|
+
});
|
|
992
|
+
}
|
|
993
|
+
/**
|
|
994
|
+
* Retains the historical API without generating placeholder documentation.
|
|
995
|
+
* Missing prose is reported for an author to write after reviewing the source.
|
|
996
|
+
*
|
|
997
|
+
* @param cfg Quality configuration containing documentation requirements.
|
|
998
|
+
* @param file Absolute source path to inspect.
|
|
999
|
+
*
|
|
1000
|
+
* @return Always `false`; the documentation workflow is read-only.
|
|
1001
|
+
*/
|
|
1002
|
+
export function documentSrcFile(cfg, file) {
|
|
1003
|
+
void cfg;
|
|
1004
|
+
void file;
|
|
1005
|
+
return false;
|
|
1006
|
+
}
|
|
1007
|
+
//# sourceMappingURL=documentation.js.map
|