@ankhorage/paradox 0.1.27 → 0.2.0

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

@@ -226,9 +226,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)

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/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`,
     };
 }
 /***

package/dist/analyze/utils/getExportMetadata.js

@@ -42,8 +42,7 @@ function getSourceLocation(node, root) {
  * Extracts callable signatures for exported functions and callable values.
  */
 function getSignatures(symbol, node, root) {
-    const parsed = readParadoxMetadata(node);
-    const signatures = getCallableDeclarations(symbol, node).map((declaration) => getSignature(declaration, parsed.params, parsed.returns, root));
+    const signatures = getCallableDeclarations(symbol, node).map((declaration) => getSignature(declaration, root));
     return uniqueBy(signatures.filter((signature) => signature.parameters.length > 0 ||
         signature.returnType !== null ||
         signature.returnDescription !== null), (signature) => signature.label);
@@ -51,16 +50,13 @@ function getSignatures(symbol, node, root) {
 /***
  * Builds one normalized call signature from a callable declaration.
  */
-function getSignature(declaration, params, returns, root) {
-    const normalizedParameters = declaration.getParameters().map((parameter) => {
-        const parameterDescription = params[parameter.getName()];
-        return {
-            name: parameter.getName(),
-            type: normalizeTypeText(parameter.getType().getText(parameter), root),
-            required: !parameter.isOptional(),
-            description: parameterDescription ? parameterDescription.trim() : null,
-        };
-    });
+function getSignature(declaration, root) {
+    const normalizedParameters = declaration.getParameters().map((parameter) => ({
+        name: parameter.getName(),
+        type: normalizeTypeText(parameter.getType().getText(parameter), root),
+        required: !parameter.isOptional(),
+        description: null,
+    }));
     const returnType = normalizeTypeText(declaration.getReturnType().getText(declaration), root);
     const parameterLabel = normalizedParameters
         .map((parameter) => `${parameter.name}${parameter.required ? '' : '?'}: ${parameter.type}`)
@@ -69,7 +65,7 @@ function getSignature(declaration, params, returns, root) {
         label: `(${parameterLabel})${returnType === 'void' ? '' : ` => ${returnType}`}`,
         parameters: normalizedParameters,
         returnType,
-        returnDescription: returns,
+        returnDescription: null,
     };
 }
 /***
@@ -99,23 +95,14 @@ function getMembersFromProperties(properties, root) {
             return [];
         }
         const rawComment = getParadoxComment(declaration);
-        const parsed = rawComment
-            ? parseParadoxComment(rawComment)
-            : {
-                description: null,
-                isConfig: false,
-                isReadme: false,
-                examples: [],
-                params: {},
-                returns: null,
-            };
+        const parsed = rawComment === null ? null : parseParadoxComment(rawComment);
         return [
             {
                 name: property.getName(),
                 kind: isMemberMethodDeclaration(declaration) ? 'method' : 'property',
                 type: normalizeTypeText(property.getTypeAtLocation(declaration).getText(declaration), root),
                 required: !property.isOptional(),
-                description: parsed.description,
+                description: parsed?.description ?? null,
             },
         ];
     });
@@ -256,22 +243,6 @@ function getCallableNode(node) {
 function isMemberMethodDeclaration(node) {
     return Node.isMethodDeclaration(node) || Node.isMethodSignature(node);
 }
-/***
- * Reads Paradox comment metadata from a declaration.
- */
-function readParadoxMetadata(node) {
-    const rawComment = getParadoxComment(node);
-    return rawComment
-        ? parseParadoxComment(rawComment)
-        : {
-            description: null,
-            isConfig: false,
-            isReadme: false,
-            examples: [],
-            params: {},
-            returns: null,
-        };
-}
 /***
  * Finds related exported symbols mentioned in signature and member type text.
  */

package/dist/analyze/utils/parseParadoxComment.d.ts

@@ -1,22 +1,25 @@
+import { type ParadoxDocTagName } from '../../doc-tags/registry.js';
+interface ParsedParadoxTag {
+    readonly name: ParadoxDocTagName;
+    readonly value: string | null;
+}
 /***
- * Parsed representation of a Paradox doc comment.
+ * Parsed representation of a Paradox documentation comment.
  */
 export interface ParsedParadoxComment {
     description: string | null;
     isConfig: boolean;
     isReadme: boolean;
     isUsage: boolean;
-    examples: ParsedExample[];
-    params: Record<string, string>;
-    returns: string | null;
-}
-interface ParsedExample {
     title: string | null;
-    language: string | null;
-    code: string;
+    see: string[];
+    security: string[];
+    tags: ParsedParadoxTag[];
+    unsupportedTags: string[];
+    hasCodeBlock: boolean;
 }
 /***
- * Parses a Paradox doc comment into structured metadata.
+ * Parses a Paradox comment into prose, supported tags, and validation evidence.
  */
 export declare function parseParadoxComment(rawComment: string): ParsedParadoxComment;
 export {};

package/dist/analyze/utils/parseParadoxComment.js

@@ -1,97 +1,85 @@
-const USAGE_TAG = `${String.fromCharCode(64)}usage`;
+import { isParadoxDocTagName } from '../../doc-tags/registry.js';
 /***
- * Parses a Paradox doc comment into structured metadata.
+ * Parses a Paradox comment into prose, supported tags, and validation evidence.
  */
 export function parseParadoxComment(rawComment) {
     const lines = normalizeCommentLines(rawComment);
-    const descriptionLines = [];
-    const examples = [];
-    let isConfig = false;
-    let isReadme = false;
-    let isUsage = false;
-    const params = {};
-    let returns = null;
-    for (let index = 0; index < lines.length; index += 1) {
-        const line = lines[index] ?? '';
-        const trimmed = line.trimStart();
-        if (trimmed.startsWith('@config')) {
-            isConfig = true;
-            continue;
-        }
-        if (trimmed.startsWith('@readme')) {
-            isReadme = true;
-            continue;
-        }
-        if (trimmed.startsWith(USAGE_TAG)) {
-            isUsage = true;
-            continue;
-        }
-        if (trimmed.startsWith('@example')) {
-            const parsed = parseExample(lines, index);
-            examples.push(parsed.example);
-            index = parsed.nextIndex;
-            continue;
-        }
-        if (trimmed.startsWith('@param ')) {
-            const paramBody = trimmed.slice('@param '.length).trim();
-            const [name, ...descriptionParts] = paramBody.split(/\s+/);
-            if (name) {
-                params[name] = descriptionParts.join(' ').trim();
-            }
-            continue;
-        }
-        if (trimmed.startsWith('@returns') || trimmed.startsWith('@return')) {
-            const returnBody = trimmed.replace(/^@returns?/, '').trim();
-            returns = returnBody.length > 0 ? returnBody : null;
-            continue;
-        }
-        descriptionLines.push(line);
-    }
-    const description = descriptionLines.join('\n').trim();
+    const parsedLines = lines.map(parseCommentLine);
+    const tags = parsedLines.flatMap((line) => line.tag ?? []);
+    const unsupportedTags = parsedLines.flatMap((line) => line.unsupportedTag ?? []);
+    const description = parsedLines
+        .filter((line) => line.tag === undefined && line.unsupportedTag === undefined)
+        .map((line) => line.text)
+        .join('\n')
+        .trim();
     return {
         description: description.length > 0 ? description : null,
-        isConfig,
-        isReadme,
-        isUsage,
-        examples,
-        params,
-        returns,
+        isConfig: hasTag(tags, 'config'),
+        isReadme: hasTag(tags, 'readme'),
+        isUsage: hasTag(tags, 'usage'),
+        title: getSingleTagValue(tags, 'title'),
+        see: getTagValues(tags, 'see'),
+        security: getTagValues(tags, 'security'),
+        tags,
+        unsupportedTags,
+        hasCodeBlock: hasCodeBlock(lines),
     };
 }
-function parseExample(lines, startIndex) {
-    const header = lines[startIndex]?.trimStart() ?? '';
-    const title = header.slice('@example'.length).trim();
-    let language = null;
-    const codeLines = [];
-    let index = startIndex + 1;
-    while (index < lines.length && (lines[index] ?? '').trim() === '') {
-        index += 1;
-    }
-    const firstCodeLine = lines[index]?.trim() ?? '';
-    if (firstCodeLine.startsWith('```')) {
-        language = firstCodeLine.slice('```'.length).trim() || null;
-        index += 1;
-        while (index < lines.length) {
-            const current = lines[index] ?? '';
-            if (current.trim() === '```')
-                break;
-            codeLines.push(current);
-            index += 1;
-        }
+/***
+ * Parses one normalized comment line when it has explicit tag-line syntax.
+ */
+function parseCommentLine(text) {
+    const trimmed = text.trim();
+    const match = /^@([A-Za-z][A-Za-z0-9-]*)(?:\s+(.*))?$/.exec(trimmed);
+    if (match === null)
+        return { text };
+    const [, name] = match;
+    const value = match.slice(2).join('').trim();
+    if (!isParadoxDocTagName(name)) {
+        return { text, unsupportedTag: name };
     }
     return {
-        example: {
-            title: title.length > 0 ? title : null,
-            language,
-            code: codeLines.join('\n').trimEnd(),
+        text,
+        tag: {
+            name,
+            value: value.length > 0 ? value : null,
         },
-        nextIndex: index,
     };
 }
+/***
+ * Returns whether a parsed tag set contains the requested tag.
+ */
+function hasTag(tags, name) {
+    return tags.some((tag) => tag.name === name);
+}
+/***
+ * Returns all non-empty values for a repeatable tag.
+ */
+function getTagValues(tags, name) {
+    return tags.flatMap((tag) => (tag.name === name && tag.value !== null ? [tag.value] : []));
+}
+/***
+ * Returns the first non-empty value for a singular tag.
+ */
+function getSingleTagValue(tags, name) {
+    return getTagValues(tags, name)[0] ?? null;
+}
+/***
+ * Detects fenced or Markdown-indented code blocks while leaving inline code spans untouched.
+ */
+function hasCodeBlock(lines) {
+    return lines.some((line) => {
+        const trimmed = line.trimStart();
+        return trimmed.startsWith('```') || trimmed.startsWith('~~~') || /^(?: {4}|\t)\S/.test(line);
+    });
+}
+/***
+ * Removes Paradox comment syntax while preserving prose indentation for code-block validation.
+ */
 function normalizeCommentLines(rawComment) {
     return rawComment
         .replace(/^\/\*\*\*/, '')
         .replace(/\*\/$/, '')
         .split('\n')
-        .map((line) => line.replace(/^\s*\*\s?/, '').trimEnd());
+        .map((line) => line.replace(/^\s*\* ?/, '').replace(/\s+$/, ''));
 }