@ankhorage/paradox 0.1.27 → 0.2.1

package/dist/analyze/documentation/validateDocumentationPolicyAsync.js

@@ -0,0 +1,150 @@
+import { access } from 'node:fs/promises';
+import { join } from 'node:path';
+import { DOCUMENTATION_POLICY } from '@ankhorage/policy/documentation';
+import { Node } from 'ts-morph';
+import { getParadoxComment } from '../utils/getParadoxComment.js';
+import { parseParadoxComment } from '../utils/parseParadoxComment.js';
+import { createDocumentationFinding } from './findings.js';
+import { validateReferencesAsync } from './validateReferencesAsync.js';
+/***
+ * Evaluates package documentation evidence against the canonical Ankhorage documentation policy.
+ */
+export async function validateDocumentationPolicyAsync(options) {
+    return [
+        ...validateCommentRules(options.comments),
+        ...validateUsageRules(options.comments),
+        ...(await validateConfigRulesAsync(options.root, options.project)),
+        ...validatePublicApiRules(options.exports),
+        ...(await validateReferencesAsync(options.root, options.project, options.comments, {
+            validateSeeUrlAsync: options.validateSeeUrlAsync,
+        })),
+    ];
+}
+/***
+ * Validates generic comment syntax rules shared by all documentation contexts.
+ */
+function validateCommentRules(comments) {
+    return comments.flatMap((comment) => {
+        const unsupported = comment.parsed.unsupportedTags.map((tag) => finding('documentation.comment.tag.unsupported', `Unsupported Paradox tag: @${tag}`, comment));
+        const code = comment.parsed.hasCodeBlock
+            ? [
+                finding('documentation.comment.code-block', 'Paradox comments must not contain code blocks.', comment),
+            ]
+            : [];
+        const configLocation = comment.parsed.isConfig && comment.sourcePath !== DOCUMENTATION_POLICY.config.path
+            ? [
+                finding('documentation.config.location', `@config is allowed only in ${DOCUMENTATION_POLICY.config.path}.`, comment),
+            ]
+            : [];
+        return [...unsupported, ...code, ...configLocation];
+    });
+}
+/***
+ * Validates canonical usage locations and the single README-promoted programmatic example.
+ */
+function validateUsageRules(comments) {
+    const usageComments = comments.filter((comment) => comment.parsed.isUsage);
+    const findings = usageComments.flatMap((comment) => validateUsageComment(comment));
+    const readmeExamples = usageComments.filter((comment) => isBelow(comment.sourcePath, DOCUMENTATION_POLICY.paths.examplesRoot) &&
+        comment.parsed.isReadme);
+    if (readmeExamples.length !== DOCUMENTATION_POLICY.readmeUsage.exactCount) {
+        findings.push(createDocumentationFinding('documentation.usage.readme.unique', `Expected exactly one @usage + @readme example; found ${readmeExamples.length}.`));
+    }
+    for (const comment of readmeExamples) {
+        if (!hasExactlyOneRequiredTag(comment, DOCUMENTATION_POLICY.readmeUsage.requiredTags) ||
+            comment.parsed.description === null) {
+            findings.push(finding('documentation.usage.readme.metadata', 'README usage requires non-empty @title and prose.', comment));
+        }
+    }
+    return findings;
+}
+/***
+ * Validates one usage comment location and forbidden CLI README promotion.
+ */
+function validateUsageComment(comment) {
+    const allowed = DOCUMENTATION_POLICY.paths.usageRoots.some((root) => isBelow(comment.sourcePath, root));
+    const location = allowed
+        ? []
+        : [
+            finding('documentation.usage.location', '@usage is allowed only below examples/** or src/cli/**.', comment),
+        ];
+    const cliReadme = isBelow(comment.sourcePath, DOCUMENTATION_POLICY.paths.cliRoot) && comment.parsed.isReadme
+        ? [
+            finding('documentation.usage.readme.cli', '@usage + @readme is not allowed below src/cli/**.', comment),
+        ]
+        : [];
+    return [...location, ...cliReadme];
+}
+/***
+ * Validates the canonical configuration file and its one README configuration root.
+ */
+async function validateConfigRulesAsync(root, project) {
+    const configPath = join(root, DOCUMENTATION_POLICY.config.path);
+    if (!(await fileExistsAsync(configPath))) {
+        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) => {
+        if (!Node.isInterfaceDeclaration(statement) && !Node.isTypeAliasDeclaration(statement)) {
+            return [];
+        }
+        const raw = getParadoxComment(statement);
+        if (raw === null)
+            return [];
+        const parsed = parseParadoxComment(raw);
+        return parsed.isConfig && parsed.isReadme ? [{ statement, parsed }] : [];
+    });
+    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));
+    }
+    for (const rootEntry of roots) {
+        if (!hasExactlyOneRequiredTag(rootEntry, DOCUMENTATION_POLICY.config.requiredTags) ||
+            rootEntry.parsed.description === null) {
+            findings.push(createDocumentationFinding('documentation.config.readme.metadata', 'README configuration requires non-empty @title and prose.', DOCUMENTATION_POLICY.config.path, rootEntry.statement.getStartLineNumber()));
+        }
+    }
+    return findings;
+}
+/***
+ * Warns when a public callable export has no Paradox description.
+ */
+function validatePublicApiRules(exports) {
+    return exports.flatMap((entry) => entry.signatures.length > 0 && entry.description === null
+        ? [
+            createDocumentationFinding('documentation.public-function.description', `Public function ${entry.name} has no Paradox description.`, entry.sourceLocation.filePath, entry.sourceLocation.line),
+        ]
+        : []);
+}
+/***
+ * Checks that each policy-required tag appears exactly once on one parsed documentation item.
+ */
+function hasExactlyOneRequiredTag(entry, requiredTags) {
+    return requiredTags.every((name) => entry.parsed.tags.filter((tag) => tag.name === name).length === 1);
+}
+/***
+ * Creates a finding at one collected comment location.
+ */
+function finding(ruleId, message, comment) {
+    return createDocumentationFinding(ruleId, message, comment.sourcePath, comment.line);
+}
+/***
+ * Checks whether a source path is contained in one canonical root.
+ */
+function isBelow(sourcePath, root) {
+    return sourcePath === root || sourcePath.startsWith(`${root}/`);
+}
+/***
+ * Checks whether a required canonical file exists.
+ */
+async function fileExistsAsync(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/analyze/documentation/validateReferencesAsync.d.ts

@@ -0,0 +1,11 @@
+import { type Project } from 'ts-morph';
+import type { AnalysisDocumentationFinding } from '../types.js';
+import type { CollectedDocumentationComment } from './collectDocumentationCommentsAsync.js';
+type SeeUrlValidator = (url: string) => Promise<unknown>;
+/***
+ * Validates external and executable references carried by documentation comments.
+ */
+export declare function validateReferencesAsync(root: string, project: Project, comments: readonly CollectedDocumentationComment[], options?: {
+    validateSeeUrlAsync?: SeeUrlValidator;
+}): Promise<AnalysisDocumentationFinding[]>;
+export {};

package/dist/analyze/documentation/validateReferencesAsync.js

@@ -0,0 +1,148 @@
+import { access } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { DOCUMENTATION_POLICY } from '@ankhorage/policy/documentation';
+import { validatePublicHttpsUrlAsync } from '@ankhorage/utility/node/http';
+import { Node } from 'ts-morph';
+import { createDocumentationFinding } from './findings.js';
+/***
+ * Validates external and executable references carried by documentation comments.
+ */
+export async function validateReferencesAsync(root, project, comments, options = {}) {
+    const validateSeeUrlAsync = options.validateSeeUrlAsync ?? validatePublicHttpsUrlAsync;
+    const findings = await Promise.all(comments.map(async (comment) => [
+        ...(await validateSeeReferencesAsync(comment, validateSeeUrlAsync)),
+        ...(await validateSecurityReferencesAsync(root, project, comment)),
+    ]));
+    return findings.flat();
+}
+/***
+ * Validates every @see value through syntax policy and the hardened public HTTPS utility.
+ */
+async function validateSeeReferencesAsync(comment, validateSeeUrlAsync) {
+    const seeTags = comment.parsed.tags.filter((tag) => tag.name === 'see');
+    const findings = await Promise.all(seeTags.map(async (tag) => {
+        const url = parseSeeUrl(tag.value);
+        if (url === null) {
+            return [
+                referenceFinding('documentation.see.value', '@see requires a public HTTPS URL without credentials.', comment),
+            ];
+        }
+        try {
+            await validateSeeUrlAsync(url);
+            return [];
+        }
+        catch (error) {
+            return [
+                referenceFinding('documentation.see.reachable', `@see target is not safely reachable: ${readErrorMessage(error)}`, comment),
+            ];
+        }
+    }));
+    return findings.flat();
+}
+/***
+ * Parses one @see value according to the policy-owned URL syntax contract.
+ */
+function parseSeeUrl(value) {
+    if (value === null)
+        return null;
+    try {
+        const url = new URL(value);
+        if (url.protocol !== DOCUMENTATION_POLICY.see.protocol)
+            return null;
+        if (url.username || url.password || url.hostname.length === 0)
+            return null;
+        return url.toString();
+    }
+    catch {
+        return null;
+    }
+}
+/***
+ * Validates every @security reference against one exact colocated executable test.
+ */
+async function validateSecurityReferencesAsync(root, project, comment) {
+    const securityTags = comment.parsed.tags.filter((tag) => tag.name === 'security');
+    return (await Promise.all(securityTags.map((tag) => validateSecurityReferenceAsync(root, project, comment, tag.value)))).flat();
+}
+/***
+ * Resolves one colocated security test reference and requires exactly one matching test declaration.
+ */
+async function validateSecurityReferenceAsync(root, project, comment, value) {
+    const reference = parseSecurityReference(value);
+    if (reference === null) {
+        return [securityFinding('Invalid @security test reference.', comment)];
+    }
+    const testPath = join(root, dirname(comment.sourcePath), reference.fileName);
+    if (!(await fileExistsAsync(testPath))) {
+        return [securityFinding(`Missing colocated security test: ${reference.fileName}`, comment)];
+    }
+    const sourceFile = project.getSourceFile(testPath) ?? project.addSourceFileAtPath(testPath);
+    const matches = sourceFile
+        .getDescendants()
+        .filter((node) => isNamedTestCall(node, reference.testName));
+    return matches.length === 1
+        ? []
+        : [
+            securityFinding(`Expected exactly one test named "${reference.testName}" in ${reference.fileName}; found ${matches.length}.`, comment),
+        ];
+}
+/***
+ * Parses a same-directory test filename and exact test name from an @security value.
+ */
+function parseSecurityReference(value) {
+    if (value === null)
+        return null;
+    const separator = value.indexOf('#');
+    if (separator <= 0 || separator === value.length - 1)
+        return null;
+    const fileName = value.slice(0, separator).trim();
+    const testName = value.slice(separator + 1).trim();
+    if (basename(fileName) !== fileName || !/\.(?:test|spec)\.[cm]?[jt]sx?$/.test(fileName)) {
+        return null;
+    }
+    return testName.length > 0 ? { fileName, testName } : null;
+}
+/***
+ * Checks whether a ts-morph node is test()/it() with the exact static string name.
+ */
+function isNamedTestCall(node, expectedName) {
+    if (!Node.isCallExpression(node))
+        return false;
+    const callee = node.getExpression().getText();
+    if (callee !== 'test' && callee !== 'it')
+        return false;
+    const [name] = node.getArguments();
+    if (!Node.isStringLiteral(name) && !Node.isNoSubstitutionTemplateLiteral(name))
+        return false;
+    return name.getLiteralText() === expectedName;
+}
+/***
+ * Creates the canonical security-reference finding at a comment location.
+ */
+function securityFinding(message, comment) {
+    return referenceFinding('documentation.security.reference', message, comment);
+}
+/***
+ * Creates a reference finding at the owning comment location.
+ */
+function referenceFinding(ruleId, message, comment) {
+    return createDocumentationFinding(ruleId, message, comment.sourcePath, comment.line);
+}
+/***
+ * Checks whether a referenced test file exists.
+ */
+async function fileExistsAsync(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/***
+ * Converts an unknown thrown value into a stable diagnostic string.
+ */
+function readErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/analyze/exports.d.ts

@@ -4,7 +4,11 @@ interface AnalyzeExportsResult {
     exports: AnalysisExport[];
     config: {
         exportName: string;
+        title: string | null;
+        description: string | null;
         isReadme: boolean;
+        see: string[];
+        security: string[];
     } | null;
 }
 /***

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';
@@ -16,16 +17,19 @@ export function analyzeExports(project, options) {
         for (const symbol of exported) {
             const resolved = resolveExportSymbol(symbol);
             const decl = getFirstDeclaration(resolved.getDeclarations());
-            if (decl === null) {
+            if (decl === null)
                 continue;
-            }
             const rawComment = getParadoxComment(decl);
             const parsed = rawComment ? parseParadoxComment(rawComment) : createEmptyMetadata();
             const name = resolved.getName();
             if (parsed.isConfig) {
                 config = {
                     exportName: name,
+                    title: parsed.title,
+                    description: parsed.description,
                     isReadme: parsed.isReadme,
+                    see: parsed.see,
+                    security: parsed.security,
                 };
             }
             const metadata = getExportMetadata({
@@ -39,11 +43,13 @@ export function analyzeExports(project, options) {
             exportsByName.set(name, existing
                 ? {
                     ...existing,
+                    title: existing.title ?? parsed.title,
                     description: existing.description ?? parsed.description,
                     isReadme: existing.isReadme || parsed.isReadme,
-                    examples: existing.examples.length > 0 ? existing.examples : parsed.examples,
-                    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,
                     ]),
@@ -56,9 +62,11 @@ export function analyzeExports(project, options) {
                 : {
                     name,
                     node: decl,
+                    title: parsed.title,
                     description: parsed.description,
                     isReadme: parsed.isReadme,
-                    examples: parsed.examples,
+                    see: parsed.see,
+                    security: parsed.security,
                     kind: inferKind(decl),
                     ...metadata,
                 });
@@ -99,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.
  */
@@ -117,10 +119,10 @@ function toPosixPath(path) {
 function createEmptyMetadata() {
     return {
         description: null,
+        title: null,
         isConfig: false,
         isReadme: false,
-        examples: [],
-        params: {},
-        returns: null,
+        see: [],
+        security: [],
     };
 }

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/readmeConfig.d.ts

@@ -1,12 +1,10 @@
 export interface AnalysisReadmeConfig {
-    description: string | null;
     language: string;
     code: string;
     sourcePath: string;
 }
 /***
- * Collects a README configuration example from the actual Paradox config file when its
- * leading Paradox comment is marked with both @config and @readme.
+ * Collects the concrete Paradox configuration instance as a README configuration example.
  */
 export declare function analyzeReadmeConfig(options: {
     root: string;

package/dist/analyze/readmeConfig.js

@@ -1,36 +1,22 @@
 import { readFile } from 'node:fs/promises';
 import { extname, relative } from 'node:path';
-import { getLeadingParadoxComment } from './utils/getLeadingParadoxComment.js';
 /***
- * Collects a README configuration example from the actual Paradox config file when its
- * leading Paradox comment is marked with both @config and @readme.
+ * Collects the concrete Paradox configuration instance as a README configuration example.
  */
 export async function analyzeReadmeConfig(options) {
     if (options.configFilePath === null)
         return null;
     const source = await readFile(options.configFilePath, 'utf-8');
-    const comment = getLeadingParadoxComment(source);
-    if (comment === null)
-        return null;
-    if (!comment.parsed.isConfig || !comment.parsed.isReadme)
-        return null;
     const sourcePath = toPosixPath(relative(options.root, options.configFilePath));
     return {
-        description: comment.parsed.description,
         language: getLanguage(sourcePath),
-        code: removeRange(source, comment.start, comment.end).trim(),
+        code: source.trim(),
         sourcePath,
     };
 }
-function removeRange(source, start, end) {
-    const before = source.slice(0, start).trimEnd();
-    const after = source.slice(end).trimStart();
-    if (before.length === 0)
-        return after;
-    if (after.length === 0)
-        return before;
-    return `${before}\n\n${after}`;
-}
+/***
+ * Returns the Markdown fence language for a configuration source path.
+ */
 function getLanguage(sourcePath) {
     const extension = extname(sourcePath).toLowerCase();
     if (extension === '.ts')
@@ -39,6 +25,9 @@ function getLanguage(sourcePath) {
         return 'js';
     return '';
 }
+/***
+ * Normalizes filesystem separators for stable documentation paths.
+ */
 function toPosixPath(path) {
     return path.replaceAll('\\', '/');
 }

package/dist/analyze/readmeUsage.d.ts

@@ -1,14 +1,11 @@
-export interface AnalysisReadmeUsage {
-    title: string | null;
-    description: string | null;
-    language: string;
-    code: string;
-    sourcePath: string;
-}
+import type { AnalysisUsageEntry } from './types.js';
 /***
- * Collects README usage examples from configured real source files.
+ * Collects every canonical usage declaration from examples and CLI source roots.
  */
 export declare function analyzeReadmeUsage(options: {
     root: string;
-    entrypoints: readonly string[];
-}): Promise<AnalysisReadmeUsage[]>;
+}): Promise<AnalysisUsageEntry[]>;
+/***
+ * Counts real example directories directly below the canonical examples root.
+ */
+export declare function countExampleDirectoriesAsync(root: string): Promise<number>;