@ankhorage/paradox 0.2.1 → 0.2.2
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/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,12 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.2.2
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- 336ea72: Respect capability-aware documentation policy so packages without programmatic usage or
|
|
8
|
+
configuration surfaces do not require fake README examples or config schemas.
|
|
9
|
+
|
|
3
10
|
## 0.2.1
|
|
4
11
|
|
|
5
12
|
### Patch Changes
|
package/README.md
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
|
|
4
4
|
# @ankhorage/paradox
|
|
5
5
|
|
|
6
|
-
         
|
|
7
7
|
|
|
8
8
|
Deterministic documentation generator for TypeScript packages.
|
|
9
9
|
|
|
@@ -13,7 +13,7 @@ export async function validateDocumentationPolicyAsync(options) {
|
|
|
13
13
|
return [
|
|
14
14
|
...validateCommentRules(options.comments),
|
|
15
15
|
...validateUsageRules(options.comments),
|
|
16
|
-
...(await validateConfigRulesAsync(options.root, options.project)),
|
|
16
|
+
...(await validateConfigRulesAsync(options.root, options.project, options.comments)),
|
|
17
17
|
...validatePublicApiRules(options.exports),
|
|
18
18
|
...(await validateReferencesAsync(options.root, options.project, options.comments, {
|
|
19
19
|
validateSeeUrlAsync: options.validateSeeUrlAsync,
|
|
@@ -44,6 +44,8 @@ function validateCommentRules(comments) {
|
|
|
44
44
|
*/
|
|
45
45
|
function validateUsageRules(comments) {
|
|
46
46
|
const usageComments = comments.filter((comment) => comment.parsed.isUsage);
|
|
47
|
+
if (usageComments.length === 0)
|
|
48
|
+
return [];
|
|
47
49
|
const findings = usageComments.flatMap((comment) => validateUsageComment(comment));
|
|
48
50
|
const readmeExamples = usageComments.filter((comment) => isBelow(comment.sourcePath, DOCUMENTATION_POLICY.paths.examplesRoot) &&
|
|
49
51
|
comment.parsed.isReadme);
|
|
@@ -76,17 +78,27 @@ function validateUsageComment(comment) {
|
|
|
76
78
|
return [...location, ...cliReadme];
|
|
77
79
|
}
|
|
78
80
|
/***
|
|
79
|
-
* Validates
|
|
81
|
+
* Validates configuration only after the package opts into that documentation surface.
|
|
80
82
|
*/
|
|
81
|
-
async function validateConfigRulesAsync(root, project) {
|
|
83
|
+
async function validateConfigRulesAsync(root, project, comments) {
|
|
82
84
|
const configPath = join(root, DOCUMENTATION_POLICY.config.path);
|
|
83
|
-
|
|
85
|
+
const configExists = await fileExistsAsync(configPath);
|
|
86
|
+
const configTagged = comments.some((comment) => comment.parsed.isConfig);
|
|
87
|
+
if (!configExists && !configTagged)
|
|
88
|
+
return [];
|
|
89
|
+
if (!configExists) {
|
|
84
90
|
return [
|
|
85
91
|
createDocumentationFinding('documentation.config.file', `Missing canonical config schema: ${DOCUMENTATION_POLICY.config.path}`),
|
|
86
92
|
];
|
|
87
93
|
}
|
|
88
94
|
const sourceFile = project.getSourceFile(configPath) ?? project.addSourceFileAtPath(configPath);
|
|
89
|
-
|
|
95
|
+
return validateConfigRoots(collectConfigRoots(sourceFile));
|
|
96
|
+
}
|
|
97
|
+
/***
|
|
98
|
+
* Collects canonical @config + @readme type declarations from the config schema.
|
|
99
|
+
*/
|
|
100
|
+
function collectConfigRoots(sourceFile) {
|
|
101
|
+
return sourceFile.getStatements().flatMap((statement) => {
|
|
90
102
|
if (!Node.isInterfaceDeclaration(statement) && !Node.isTypeAliasDeclaration(statement)) {
|
|
91
103
|
return [];
|
|
92
104
|
}
|
|
@@ -96,6 +108,11 @@ async function validateConfigRulesAsync(root, project) {
|
|
|
96
108
|
const parsed = parseParadoxComment(raw);
|
|
97
109
|
return parsed.isConfig && parsed.isReadme ? [{ statement, parsed }] : [];
|
|
98
110
|
});
|
|
111
|
+
}
|
|
112
|
+
/***
|
|
113
|
+
* Validates cardinality and README metadata for canonical config roots.
|
|
114
|
+
*/
|
|
115
|
+
function validateConfigRoots(roots) {
|
|
99
116
|
const findings = [];
|
|
100
117
|
if (roots.length !== DOCUMENTATION_POLICY.config.exactCount) {
|
|
101
118
|
findings.push(createDocumentationFinding('documentation.config.readme.unique', `Expected exactly one @config + @readme root in ${DOCUMENTATION_POLICY.config.path}; found ${roots.length}.`, DOCUMENTATION_POLICY.config.path));
|