@ankhorage/paradox 0.1.27 → 0.2.1

package/dist/analyze/readmeUsage.js

@@ -1,60 +1,108 @@
-import { readFile } from 'node:fs/promises';
-import { extname, isAbsolute, join, relative } from 'node:path';
+import { readdir } from 'node:fs/promises';
+import { extname, join, relative } from 'node:path';
+import { DOCUMENTATION_POLICY } from '@ankhorage/policy/documentation';
+import { Project } from 'ts-morph';
+import { getParadoxComment } from './utils/getParadoxComment.js';
 import { parseParadoxComment } from './utils/parseParadoxComment.js';
-const USAGE_TAG = `${String.fromCharCode(64)}usage`;
+const SOURCE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs']);
 /***
- * Collects README usage examples from configured real source files.
+ * Collects every canonical usage declaration from examples and CLI source roots.
  */
 export async function analyzeReadmeUsage(options) {
-    const entries = await Promise.all(options.entrypoints.map(async (entrypoint) => analyzeUsageEntrypoint(options.root, entrypoint)));
-    return entries.flat().sort((left, right) => left.sourcePath.localeCompare(right.sourcePath));
+    const project = new Project({ skipAddingFilesFromTsConfig: true });
+    const files = (await Promise.all(DOCUMENTATION_POLICY.paths.usageRoots.map((usageRoot) => collectSourceFilesAsync(join(options.root, usageRoot)))))
+        .flat()
+        .sort((left, right) => left.localeCompare(right));
+    return files.flatMap((filePath) => analyzeUsageFile(options.root, project, filePath));
 }
-async function analyzeUsageEntrypoint(root, entrypoint) {
-    const absolutePath = isAbsolute(entrypoint) ? entrypoint : join(root, entrypoint);
-    const source = await readFile(absolutePath, 'utf-8');
-    const sourcePath = toPosixPath(relative(root, absolutePath));
-    const matches = findUsageComments(source);
-    return matches.map((match) => {
-        const parsed = parseParadoxComment(match.comment);
-        return {
-            title: getUsageTitle(parsed.description, sourcePath),
-            description: parsed.description,
-            language: getLanguage(sourcePath),
-            code: removeRange(source, match.start, match.end).trim(),
-            sourcePath,
-        };
+/***
+ * Collects supported source files recursively below one canonical usage root.
+ */
+async function collectSourceFilesAsync(root) {
+    let entries;
+    try {
+        entries = await readdir(root, { withFileTypes: true });
+    }
+    catch (error) {
+        if (isMissingPathError(error))
+            return [];
+        throw error;
+    }
+    const nested = await Promise.all(entries.map(async (entry) => {
+        const path = join(root, entry.name);
+        if (entry.isDirectory())
+            return collectSourceFilesAsync(path);
+        return entry.isFile() && SOURCE_EXTENSIONS.has(extname(entry.name)) ? [path] : [];
+    }));
+    return nested.flat();
+}
+/***
+ * Extracts usage-marked top-level statements from one real source file.
+ */
+function analyzeUsageFile(root, project, filePath) {
+    const sourceFile = project.getSourceFile(filePath) ?? project.addSourceFileAtPath(filePath);
+    const sourcePath = toPosixPath(relative(root, filePath));
+    return sourceFile.getStatements().flatMap((statement) => {
+        const comment = getParadoxComment(statement);
+        if (comment === null)
+            return [];
+        const parsed = parseParadoxComment(comment);
+        if (!parsed.isUsage)
+            return [];
+        return [
+            {
+                area: sourcePath.startsWith(`${DOCUMENTATION_POLICY.paths.examplesRoot}/`)
+                    ? 'examples'
+                    : 'cli',
+                title: parsed.title ?? deriveUsageTitle(sourcePath),
+                description: parsed.description,
+                language: getLanguage(sourcePath),
+                code: getStatementCode(statement),
+                sourcePath,
+                isReadme: parsed.isReadme,
+                see: parsed.see,
+                security: parsed.security,
+            },
+        ];
     });
 }
-function findUsageComments(source) {
-    const matches = [];
-    const pattern = /\/\*\*\*[\s\S]*?\*\//g;
-    for (const match of source.matchAll(pattern)) {
-        const [comment] = match;
-        if (!comment.includes(USAGE_TAG))
-            continue;
-        matches.push({
-            comment,
-            start: match.index,
-            end: match.index + comment.length,
-        });
-    }
-    return matches;
+/***
+ * Returns the exact source statement owned by a usage comment.
+ */
+function getStatementCode(statement) {
+    return statement.getText().trim();
 }
-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}`;
+/***
+ * Derives a deterministic title from the canonical example or CLI structure.
+ */
+function deriveUsageTitle(sourcePath) {
+    const parts = sourcePath.split('/');
+    if (parts[0] === DOCUMENTATION_POLICY.paths.examplesRoot) {
+        return titleCase(parts[1] ?? 'usage');
+    }
+    if (sourcePath === `${DOCUMENTATION_POLICY.paths.cliRoot}/index.ts`) {
+        return 'CLI';
+    }
+    const commandsIndex = parts.indexOf('commands');
+    const commandParts = commandsIndex === -1 ? [parts.at(-1) ?? 'cli'] : parts.slice(commandsIndex + 1);
+    return commandParts
+        .map((part) => part.replace(/\.[^.]+$/, ''))
+        .map(titleCase)
+        .join(' ');
 }
-function getUsageTitle(description, sourcePath) {
-    if (description === null)
-        return sourcePath;
-    const [firstLine = sourcePath] = description.split('\n');
-    return firstLine.trim() || sourcePath;
+/***
+ * Converts a kebab-case structural segment into presentation words.
+ */
+function titleCase(value) {
+    return value
+        .split('-')
+        .filter((word) => word.length > 0)
+        .map((word) => `${word.charAt(0).toUpperCase()}${word.slice(1)}`)
+        .join(' ');
 }
+/***
+ * Returns the Markdown fence language for a usage source path.
+ */
 function getLanguage(sourcePath) {
     const extension = extname(sourcePath).toLowerCase();
     if (extension === '.tsx')
@@ -63,10 +111,38 @@ function getLanguage(sourcePath) {
         return 'ts';
     if (extension === '.jsx')
         return 'jsx';
-    if (extension === '.js')
+    if (extension === '.js' || extension === '.mjs' || extension === '.cjs')
         return 'js';
     return '';
 }
+/***
+ * Counts real example directories directly below the canonical examples root.
+ */
+export async function countExampleDirectoriesAsync(root) {
+    try {
+        const entries = await readdir(join(root, DOCUMENTATION_POLICY.paths.examplesRoot), {
+            withFileTypes: true,
+        });
+        return entries.filter((entry) => entry.isDirectory()).length;
+    }
+    catch (error) {
+        if (isMissingPathError(error))
+            return 0;
+        throw error;
+    }
+}
+/***
+ * Checks whether a filesystem error reports a missing path.
+ */
+function isMissingPathError(error) {
+    return (error instanceof Error &&
+        'code' in error &&
+        typeof error.code === 'string' &&
+        error.code === 'ENOENT');
+}
+/***
+ * Normalizes filesystem separators for stable documentation paths.
+ */
 function toPosixPath(path) {
     return path.replaceAll('\\', '/');
 }

package/dist/analyze/semantic/docBlocks.js

@@ -16,9 +16,8 @@ export function collectDocBlocks(sourceFile, options) {
         const end = start + raw.length;
         const { line, column } = sourceFile.getLineAndColumnAtPos(start);
         const parsed = parseDocBlock(raw, tagRegistry);
-        const id = `${sourcePath}:${line}:${column}`;
         blocks.push({
-            id,
+            id: `${sourcePath}:${line}:${column}`,
             sourcePath,
             start,
             end,
@@ -26,8 +25,6 @@ export function collectDocBlocks(sourceFile, options) {
             column,
             raw,
             description: parsed.description,
-            params: parsed.params,
-            returns: parsed.returns,
             tags: parsed.tags,
         });
     }
@@ -37,62 +34,35 @@ export function collectDocBlocks(sourceFile, options) {
  * Extracts registered tags from a doc block.
  */
 function collectTags(raw, tagRegistry = defaultTagRegistry) {
-    const tags = [];
-    const lines = normalizeDocBlock(raw);
-    for (const line of lines) {
-        const trimmed = line.trim();
-        if (!trimmed.startsWith('@'))
-            continue;
-        const [tagName, ...rest] = trimmed.slice(1).split(/\s+/);
-        if (!tagName || !tagRegistry.has(tagName))
-            continue;
-        const value = rest.join(' ').trim();
-        tags.push({
-            name: tagName,
-            value: value.length > 0 ? value : null,
-        });
-    }
-    return tags;
+    return normalizeDocBlock(raw).flatMap((line) => {
+        const match = /^@([A-Za-z][A-Za-z0-9-]*)(?:\s+(.*))?$/.exec(line.trim());
+        if (match === null)
+            return [];
+        const [, name] = match;
+        if (!tagRegistry.has(name))
+            return [];
+        const value = match.slice(2).join('').trim();
+        return [{ name, value: value.length > 0 ? value : null }];
+    });
 }
+/***
+ * Parses semantic description and supported tags without interpreting unsupported tag syntax.
+ */
 function parseDocBlock(raw, tagRegistry) {
     const lines = normalizeDocBlock(raw);
     const tags = collectTags(raw, tagRegistry);
-    const params = {};
-    let returns = null;
     const description = lines
-        .filter((line) => {
-        const trimmed = line.trim();
-        if (!trimmed.startsWith('@'))
-            return true;
-        const [tagName, ...rest] = trimmed.slice(1).split(/\s+/);
-        if (!tagName)
-            return false;
-        if (tagName === 'param') {
-            const [name, ...descParts] = rest;
-            if (name) {
-                params[name] = descParts.join(' ').trim();
-            }
-            return false;
-        }
-        if (tagName === 'returns' || tagName === 'return') {
-            const returnBody = rest.join(' ').trim();
-            returns = returnBody.length > 0 ? returnBody : null;
-            return false;
-        }
-        if (tagRegistry.has(tagName)) {
-            return false;
-        }
-        return true;
-    })
+        .filter((line) => !/^@[A-Za-z][A-Za-z0-9-]*(?:\s|$)/.test(line.trim()))
         .join('\n')
         .trim();
     return {
         description: description.length > 0 ? description : null,
         tags,
-        params,
-        returns,
     };
 }
+/***
+ * Removes Paradox comment delimiters while preserving prose content.
+ */
 function normalizeDocBlock(raw) {
     return raw
         .replace(/^\/\*\*\*/, '')

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, {
@@ -226,9 +227,7 @@ function collectMembersFromType(program, reference, inheritedFrom, depth) {
             return [];
         const propertyType = property.getTypeAtLocation(declaration);
         const rawComment = getParadoxComment(declaration);
-        const parsed = rawComment
-            ? parseParadoxComment(rawComment)
-            : { description: null, isConfig: false, params: {}, returns: null };
+        const parsed = rawComment ? parseParadoxComment(rawComment) : { description: null };
         const required = !property.isOptional() && !isUndefinedUnion(propertyType);
         const childReference = shouldExpandType(program, propertyType)
             ? resolveTypeReference(program, propertyType)
@@ -380,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/semantic/model.d.ts

@@ -20,8 +20,6 @@ export interface AnalyzedDocBlock {
     column: number;
     raw: string;
     description: string | null;
-    params: Record<string, string>;
-    returns: string | null;
     tags: AnalyzedTag[];
 }
 export interface AnalyzedTag {

package/dist/analyze/semantic/paradoxComment.d.ts

@@ -1,16 +1,6 @@
 import type { Node } from 'ts-morph';
+export { parseParadoxComment } from '../utils/parseParadoxComment.js';
 /***
  * Reads the nearest Paradox doc comment attached to a declaration.
  */
 export declare function getParadoxComment(node: Node | undefined): string | null;
-interface ParsedParadoxComment {
-    description: string | null;
-    isConfig: boolean;
-    params: Record<string, string>;
-    returns: string | null;
-}
-/***
- * Parses a Paradox doc comment into structured metadata.
- */
-export declare function parseParadoxComment(rawComment: string): ParsedParadoxComment;
-export {};

package/dist/analyze/semantic/paradoxComment.js

@@ -1,3 +1,4 @@
+export { parseParadoxComment } from '../utils/parseParadoxComment.js';
 /***
  * Reads the nearest Paradox doc comment attached to a declaration.
  */
@@ -19,46 +20,3 @@ export function getParadoxComment(node) {
         return null;
     return text.slice(commentStart, commentEnd + 2);
 }
-/***
- * Parses a Paradox doc comment into structured metadata.
- */
-export function parseParadoxComment(rawComment) {
-    const lines = rawComment
-        .replace(/^\/\*\*\*/, '')
-        .replace(/\*\/$/, '')
-        .split('\n')
-        .map((line) => line.replace(/^\s*\*\s?/, '').trimEnd());
-    let isConfig = false;
-    const params = {};
-    let returns = null;
-    const description = lines
-        .filter((line) => {
-        const trimmed = line.trimStart();
-        if (trimmed.startsWith('@config')) {
-            isConfig = true;
-            return false;
-        }
-        if (trimmed.startsWith('@param ')) {
-            const paramBody = trimmed.slice('@param '.length).trim();
-            const [name, ...descriptionParts] = paramBody.split(/\s+/);
-            if (name) {
-                params[name] = descriptionParts.join(' ').trim();
-            }
-            return false;
-        }
-        if (trimmed.startsWith('@returns') || trimmed.startsWith('@return')) {
-            const returnBody = trimmed.replace(/^@returns?/, '').trim();
-            returns = returnBody.length > 0 ? returnBody : null;
-            return false;
-        }
-        return true;
-    })
-        .join('\n')
-        .trim();
-    return {
-        description: description.length > 0 ? description : null,
-        isConfig,
-        params,
-        returns,
-    };
-}

package/dist/analyze/semantic/tagRegistry.js

@@ -1 +1,2 @@
-export const defaultTagRegistry = new Set(['readme', 'config']);
+import { DOCUMENTATION_POLICY } from '@ankhorage/policy/documentation';
+export const defaultTagRegistry = new Set(DOCUMENTATION_POLICY.tags.map((tag) => tag.name));

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/analyze/sourceFunctions.js

@@ -43,12 +43,12 @@ function createSourceFunction(name, node, root) {
     const sourceFile = node.getSourceFile();
     const { column, line } = sourceFile.getLineAndColumnAtPos(node.getStart(false));
     const rawComment = getParadoxComment(node);
-    const parsedComment = rawComment
-        ? parseParadoxComment(rawComment)
-        : { description: null, isReadme: false };
+    const parsedComment = rawComment === null ? null : parseParadoxComment(rawComment);
     return {
         name,
-        description: parsedComment.description,
+        description: parsedComment?.description ?? null,
+        see: parsedComment?.see ?? [],
+        security: parsedComment?.security ?? [],
         sourceLocation: {
             filePath: toPosixPath(relative(root, sourceFile.getFilePath())),
             line,

package/dist/analyze/types.d.ts

@@ -1,9 +1,5 @@
+import type { PolicySeverity } from '@ankhorage/policy/status';
 import type { Node } from 'ts-morph';
-interface AnalysisExample {
-    title: string | null;
-    language: string | null;
-    code: string;
-}
 /***
  * Describes one exported declaration discovered in a package.
  */
@@ -40,9 +36,11 @@ export interface AnalysisStructuredRow {
 export interface AnalysisExport {
     name: string;
     node: Node;
+    title: string | null;
     description: string | null;
     isReadme: boolean;
-    examples: AnalysisExample[];
+    see: string[];
+    security: string[];
     kind: 'function' | 'type' | 'value' | 'unknown';
     modulePath: string;
     sourceLocation: AnalysisSourceLocation;
@@ -53,13 +51,14 @@ export interface AnalysisExport {
     structuredRows: AnalysisStructuredRow[];
 }
 /***
- * Describes one React component and its extracted props.
+ * Describes one React component and its props.
  */
 export interface AnalysisComponent {
     name: string;
     description: string | null;
     isReadme: boolean;
-    examples: AnalysisExample[];
+    see: string[];
+    security: string[];
     modulePath: string;
     sourceLocation: AnalysisSourceLocation;
     exportPaths: string[];
@@ -73,28 +72,30 @@ export interface AnalysisComponent {
 }
 export interface AnalysisUsage {
     packageName: string;
-    commands: AnalysisUsageCommand[];
-}
-interface AnalysisDonation {
-    account: string;
-}
-interface AnalysisUsageCommand {
-    name: string;
     command: string;
 }
-interface AnalysisReadmeUsage {
+export interface AnalysisUsageEntry {
+    area: 'cli' | 'examples';
     title: string | null;
     description: string | null;
     language: string;
     code: string;
     sourcePath: string;
+    isReadme: boolean;
+    see: string[];
+    security: string[];
 }
-interface AnalysisReadmeCli {
-    description: string | null;
-    sourcePath: string;
+export interface AnalysisDocumentationFinding {
+    ruleId: string;
+    severity: PolicySeverity;
+    message: string;
+    sourcePath: string | null;
+    line: number | null;
+}
+interface AnalysisDonation {
+    account: string;
 }
 interface AnalysisReadmeConfig {
-    description: string | null;
     language: string;
     code: string;
     sourcePath: string;
@@ -122,6 +123,8 @@ export interface AnalysisSequenceScenario {
 export interface AnalysisSourceFunction {
     name: string;
     description: string | null;
+    see: string[];
+    security: string[];
     sourceLocation: AnalysisSourceLocation;
 }
 interface AnalysisTypeMember {
@@ -177,14 +180,18 @@ export interface AnalysisResult {
     modules: AnalysisModule[];
     badges: AnalysisBadge[];
     sequenceScenarios: AnalysisSequenceScenario[];
-    usage: AnalysisUsage | null;
-    readmeUsageDescription: string | null;
-    readmeUsage: AnalysisReadmeUsage[];
-    readmeCli: AnalysisReadmeCli | null;
+    usage: AnalysisUsage;
+    usageEntries: AnalysisUsageEntry[];
+    exampleCount: number;
+    findings: AnalysisDocumentationFinding[];
     readmeConfig: AnalysisReadmeConfig | null;
     config: {
         exportName: string;
+        title: string | null;
+        description: string | null;
         isReadme: boolean;
+        see: string[];
+        security: string[];
         members: AnalysisTypeMember[];
     } | null;
     graphs: AnalysisGraphs;

package/dist/analyze/usage.d.ts

@@ -11,6 +11,6 @@ export interface PackageJsonModel {
     prettier?: unknown;
 }
 /***
- * Builds executable CLI commands from package metadata.
+ * Builds the canonical Ankh package help command from package metadata.
  */
-export declare function createUsageFromPackageJson(pkg: PackageJsonModel): AnalysisUsage | null;
+export declare function createUsageFromPackageJson(pkg: PackageJsonModel): AnalysisUsage;

package/dist/analyze/usage.js

@@ -1,41 +1,11 @@
 /***
- * Builds executable CLI commands from package metadata.
+ * Builds the canonical Ankh package help command from package metadata.
  */
 export function createUsageFromPackageJson(pkg) {
-    if (pkg.bin == null)
-        return null;
-    if (typeof pkg.bin === 'string') {
-        return {
-            packageName: pkg.name,
-            commands: [
-                {
-                    name: getPackageBaseName(pkg.name),
-                    command: `bunx ${pkg.name}`,
-                },
-            ],
-        };
-    }
-    const entries = Object.keys(pkg.bin).sort((a, b) => a.localeCompare(b));
-    if (entries.length === 0)
-        return null;
-    if (entries.length === 1) {
-        const [name] = entries;
-        return {
-            packageName: pkg.name,
-            commands: [
-                {
-                    name,
-                    command: `bunx ${pkg.name}`,
-                },
-            ],
-        };
-    }
+    const packageName = getPackageBaseName(pkg.name);
     return {
         packageName: pkg.name,
-        commands: entries.map((name) => ({
-            name,
-            command: `bunx ${pkg.name} ${name}`,
-        })),
+        command: `ankh ${packageName} --help`,
     };
 }
 /***