@ankhorage/paradox 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.2.2
+
+### Patch Changes
+
+- 336ea72: Respect capability-aware documentation policy so packages without programmatic usage or
+  configuration surfaces do not require fake README examples or config schemas.
+
+## 0.2.1
+
+### Patch Changes
+
+- f556df5: Update Ankhorage dependencies: `@ankhorage/policy`.
+
 ## 0.2.0
 
 ### Minor Changes

package/README.md

@@ -3,7 +3,7 @@
 
 # @ankhorage/paradox
 
-![license: MIT](./paradox/badges/license.svg) ![npm: v0.1.27](./paradox/badges/npm.svg) ![runtime: bun](./paradox/badges/runtime.svg) ![typescript: strict](./paradox/badges/typescript.svg) ![eslint: checked](./paradox/badges/eslint.svg) ![prettier: checked](./paradox/badges/prettier.svg) ![build: checked](./paradox/badges/build.svg) ![tests: checked](./paradox/badges/tests.svg) ![paradox: canonical](./paradox/badges/docs.svg)
+![license: MIT](./paradox/badges/license.svg) ![npm: v0.2.1](./paradox/badges/npm.svg) ![runtime: bun](./paradox/badges/runtime.svg) ![typescript: strict](./paradox/badges/typescript.svg) ![eslint: checked](./paradox/badges/eslint.svg) ![prettier: checked](./paradox/badges/prettier.svg) ![build: checked](./paradox/badges/build.svg) ![tests: checked](./paradox/badges/tests.svg) ![paradox: canonical](./paradox/badges/docs.svg)
 
 Deterministic documentation generator for TypeScript packages.
 

package/dist/analyze/documentation/validateDocumentationPolicyAsync.js

@@ -13,7 +13,7 @@ export async function validateDocumentationPolicyAsync(options) {
     return [
         ...validateCommentRules(options.comments),
         ...validateUsageRules(options.comments),
-        ...(await validateConfigRulesAsync(options.root, options.project)),
+        ...(await validateConfigRulesAsync(options.root, options.project, options.comments)),
         ...validatePublicApiRules(options.exports),
         ...(await validateReferencesAsync(options.root, options.project, options.comments, {
             validateSeeUrlAsync: options.validateSeeUrlAsync,
@@ -44,6 +44,8 @@ function validateCommentRules(comments) {
  */
 function validateUsageRules(comments) {
     const usageComments = comments.filter((comment) => comment.parsed.isUsage);
+    if (usageComments.length === 0)
+        return [];
     const findings = usageComments.flatMap((comment) => validateUsageComment(comment));
     const readmeExamples = usageComments.filter((comment) => isBelow(comment.sourcePath, DOCUMENTATION_POLICY.paths.examplesRoot) &&
         comment.parsed.isReadme);
@@ -76,17 +78,27 @@ function validateUsageComment(comment) {
     return [...location, ...cliReadme];
 }
 /***
- * Validates the canonical configuration file and its one README configuration root.
+ * Validates configuration only after the package opts into that documentation surface.
  */
-async function validateConfigRulesAsync(root, project) {
+async function validateConfigRulesAsync(root, project, comments) {
     const configPath = join(root, DOCUMENTATION_POLICY.config.path);
-    if (!(await fileExistsAsync(configPath))) {
+    const configExists = await fileExistsAsync(configPath);
+    const configTagged = comments.some((comment) => comment.parsed.isConfig);
+    if (!configExists && !configTagged)
+        return [];
+    if (!configExists) {
         return [
             createDocumentationFinding('documentation.config.file', `Missing canonical config schema: ${DOCUMENTATION_POLICY.config.path}`),
         ];
     }
     const sourceFile = project.getSourceFile(configPath) ?? project.addSourceFileAtPath(configPath);
-    const roots = sourceFile.getStatements().flatMap((statement) => {
+    return validateConfigRoots(collectConfigRoots(sourceFile));
+}
+/***
+ * Collects canonical @config + @readme type declarations from the config schema.
+ */
+function collectConfigRoots(sourceFile) {
+    return sourceFile.getStatements().flatMap((statement) => {
         if (!Node.isInterfaceDeclaration(statement) && !Node.isTypeAliasDeclaration(statement)) {
             return [];
         }
@@ -96,6 +108,11 @@ async function validateConfigRulesAsync(root, project) {
         const parsed = parseParadoxComment(raw);
         return parsed.isConfig && parsed.isReadme ? [{ statement, parsed }] : [];
     });
+}
+/***
+ * Validates cardinality and README metadata for canonical config roots.
+ */
+function validateConfigRoots(roots) {
     const findings = [];
     if (roots.length !== DOCUMENTATION_POLICY.config.exactCount) {
         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));

package/dist/analyze/exports.js

@@ -1,4 +1,5 @@
 import { isAbsolute, join, normalize, relative } from 'node:path';
+import { uniqueSortedStrings } from '@ankhorage/utility/array';
 import { Node } from 'ts-morph';
 import { getExportMetadata } from './utils/getExportMetadata.js';
 import { getParadoxComment } from './utils/getParadoxComment.js';
@@ -45,10 +46,10 @@ export function analyzeExports(project, options) {
                     title: existing.title ?? parsed.title,
                     description: existing.description ?? parsed.description,
                     isReadme: existing.isReadme || parsed.isReadme,
-                    see: uniqueSorted([...existing.see, ...parsed.see]),
-                    security: uniqueSorted([...existing.security, ...parsed.security]),
-                    exportPaths: uniqueSorted([...existing.exportPaths, ...metadata.exportPaths]),
-                    relatedSymbols: uniqueSorted([
+                    see: uniqueSortedStrings([...existing.see, ...parsed.see]),
+                    security: uniqueSortedStrings([...existing.security, ...parsed.security]),
+                    exportPaths: uniqueSortedStrings([...existing.exportPaths, ...metadata.exportPaths]),
+                    relatedSymbols: uniqueSortedStrings([
                         ...existing.relatedSymbols,
                         ...metadata.relatedSymbols,
                     ]),
@@ -106,12 +107,6 @@ function inferKind(node) {
         return 'value';
     return 'unknown';
 }
-/***
- * Returns unique string values sorted for deterministic generated output.
- */
-function uniqueSorted(values) {
-    return [...new Set(values)].sort((left, right) => left.localeCompare(right));
-}
 /***
  * Normalizes platform-specific path separators for generated documentation output.
  */

package/dist/analyze/modules.js

@@ -1,4 +1,5 @@
 import { isAbsolute, join, normalize, relative } from 'node:path';
+import { uniqueSortedStrings } from '@ankhorage/utility/array';
 /***
  * Builds a deterministic module relationship graph for documentation renderers.
  */
@@ -34,18 +35,12 @@ export function analyzeModules(project, options) {
         return {
             path,
             isEntrypoint: entrypointPaths.has(normalize(sourceFile.getFilePath())),
-            dependencies: uniqueSorted(dependencies),
-            exports: uniqueSorted(exports),
+            dependencies: uniqueSortedStrings(dependencies),
+            exports: uniqueSortedStrings(exports),
         };
     })
         .sort((left, right) => left.path.localeCompare(right.path));
 }
-/***
- * Returns unique string values sorted for deterministic generated output.
- */
-function uniqueSorted(values) {
-    return [...new Set(values)].sort((left, right) => left.localeCompare(right));
-}
 /***
  * Normalizes platform-specific path separators for generated documentation output.
  */

package/dist/analyze/semantic/exports.js

@@ -1,3 +1,4 @@
+import { uniqueSortedStrings } from '@ankhorage/utility/array';
 import { Node as MorphNode, TypeFormatFlags } from 'ts-morph';
 import { isReactComponent } from './isReactComponent.js';
 import { getParadoxComment, parseParadoxComment } from './paradoxComment.js';
@@ -21,7 +22,7 @@ export function collectExports(program) {
             const sourcePath = relativeToRoot(program.root, declaration.getSourceFile().getFilePath());
             const existing = exportsByName.get(name);
             const exportPaths = existing
-                ? uniqueSorted([...existing.exportPaths, entrypointPath])
+                ? uniqueSortedStrings([...existing.exportPaths, entrypointPath])
                 : [entrypointPath];
             const kind = existing?.kind ?? detectExportKind(declaration);
             exportsByName.set(name, {
@@ -378,9 +379,6 @@ function getCallableNode(node) {
     }
     return null;
 }
-function uniqueSorted(values) {
-    return [...new Set(values)].sort((left, right) => left.localeCompare(right));
-}
 const IGNORED_RELATED_SYMBOLS = new Set([
     'Array',
     'Boolean',

package/dist/analyze/sequenceScenarios.js

@@ -1,4 +1,5 @@
 import { isAbsolute, join, normalize } from 'node:path';
+import { uniqueSortedStrings } from '@ankhorage/utility/array';
 import { Node as MorphNode, } from 'ts-morph';
 import { relativeToRoot, toPosixPath } from './semantic/utils.js';
 import { getParadoxComment } from './utils/getParadoxComment.js';
@@ -85,7 +86,7 @@ function getBinSourceCandidates(targetPath) {
         candidates.push(normalized.replace(/\.jsx?$/, '.ts'));
         candidates.push(normalized.replace(/\.jsx?$/, '.tsx'));
     }
-    return uniqueSorted(candidates);
+    return uniqueSortedStrings(candidates);
 }
 function getSourceFileByRelativePath(project, root, relativePath) {
     const absolutePath = normalize(isAbsolute(relativePath) ? relativePath : join(root, relativePath));
@@ -169,6 +170,3 @@ function uniqueByFunctionName(declarations) {
         return true;
     });
 }
-function uniqueSorted(values) {
-    return [...new Set(values)].sort((left, right) => left.localeCompare(right));
-}

package/dist/render/renderers/diagrams.js

@@ -1,3 +1,4 @@
+import { uniqueSortedStrings } from '@ankhorage/utility/array';
 import { toFileStem } from '../toFileStem.js';
 const MAX_SEQUENCE_CALL_EDGES = 12;
 const MAX_SEQUENCE_PARTICIPANTS = 8;
@@ -174,7 +175,7 @@ function groupCallsBySource(callEdges) {
     return grouped;
 }
 function collectSequenceParticipants(callEdges) {
-    return uniqueSorted(callEdges.flatMap((edge) => [edge.fromSymbol, edge.toSymbol]));
+    return uniqueSortedStrings(callEdges.flatMap((edge) => [edge.fromSymbol, edge.toSymbol]));
 }
 function getCallEdgeKey(edge) {
     return `${edge.fromSymbol}->${edge.toSymbol}@${edge.sourcePath}:${edge.callExpression}`;
@@ -191,9 +192,6 @@ function renderFallbackEdge(modules, prefix) {
         return `  ${toMermaidId(`${prefix}-${previous.path}`)} -.-> ${toMermaidId(`${prefix}-${module.path}`)}`;
     });
 }
-function uniqueSorted(values) {
-    return [...new Set(values)].sort((left, right) => left.localeCompare(right));
-}
 function toMermaidId(value) {
     return value.replace(/[^A-Za-z0-9_]/g, '_');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/paradox",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Deterministic documentation generator for TypeScript packages.",
   "license": "MIT",
   "publishConfig": {
@@ -71,7 +71,7 @@
     "test:standalone": "bun test tests/cli.e2e.test.ts"
   },
   "dependencies": {
-    "@ankhorage/policy": "^0.1.0",
+    "@ankhorage/policy": "^0.2.0",
     "@ankhorage/utility": "^1.8.0",
     "ts-morph": "^28.0.0"
   },