@ankhorage/paradox 0.1.27 → 0.2.1

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+$/, ''));
 }

package/dist/cli/index.d.ts

@@ -1,6 +1,7 @@
 /***
- * Generates deterministic documentation for a package through the Paradox CLI.
+ * Exposes the Paradox command provider through the canonical Ankhorage CLI surface.
  *
- * @readme
+ * @title CLI
+ * @usage
  */
 export { default } from '../docsSurface.js';

package/dist/cli/index.js

@@ -1,6 +1,7 @@
 /***
- * Generates deterministic documentation for a package through the Paradox CLI.
+ * Exposes the Paradox command provider through the canonical Ankhorage CLI surface.
  *
- * @readme
+ * @title CLI
+ * @usage
  */
 export { default } from '../docsSurface.js';

package/dist/cli/standalone.js

@@ -23,10 +23,21 @@ async function main() {
     const packageRoot = await resolvePackageRoot(config, configDir);
     const { outputDir, outputRoot } = resolveOutputRoot(config, packageRoot);
     const analysis = await analyze(config, { packageRoot, configFilePath });
+    assertNoDocumentationErrors(analysis.findings);
     const model = buildModel(analysis);
     const result = render(model, { outputDir });
     await write(result, config, { packageRoot, outputRoot });
 }
+/***
+ * Refuses to write generated artifacts when canonical documentation policy contains errors.
+ */
+function assertNoDocumentationErrors(findings) {
+    const errors = findings.filter((finding) => finding.severity === 'error');
+    if (errors.length === 0)
+        return;
+    const details = errors.map((finding) => `- [${finding.ruleId}] ${finding.message}`).join('\n');
+    throw new Error(`Paradox documentation policy is invalid:\n${details}`);
+}
 main().catch((error) => {
     console.error(error);
     process.exit(1);

package/dist/config/defineParadoxConfig.d.ts

@@ -1,4 +1,4 @@
-import type { ParadoxConfig } from './types.js';
+import type { ParadoxConfig } from '../types/config.js';
 /***
  * Defines a Paradox configuration object without changing its shape.
  *

package/dist/doc-tags/registry.d.ts

@@ -1,39 +1,35 @@
-export declare const PARADOX_DOC_TAGS: readonly [{
-    readonly name: "readme";
-    readonly syntax: "@readme";
-    readonly description: "Includes a documentation block or exported symbol in README output.";
-    readonly appliesTo: readonly ["block", "symbol"];
-    readonly repeatable: false;
-    readonly handler: "markReadme";
-}, {
-    readonly name: "config";
-    readonly syntax: "@config";
-    readonly description: "Marks a configuration type, interface, or source block. Pair with @readme to include the schema or actual config source in README Configuration output.";
-    readonly appliesTo: readonly ["block", "interface", "type"];
-    readonly repeatable: false;
-    readonly handler: "markConfig";
-}, {
-    readonly name: "example";
-    readonly syntax: "@example";
-    readonly description: "Adds a titled fenced code example to the generated documentation for a symbol.";
-    readonly appliesTo: readonly ["symbol"];
-    readonly repeatable: true;
-    readonly handler: "parseExample";
-}, {
-    readonly name: "usage";
-    readonly syntax: "@usage";
-    readonly description: "Promotes a real source example into the generated README Usage section.";
-    readonly appliesTo: readonly ["block", "symbol"];
-    readonly repeatable: false;
-    readonly handler: "markUsage";
-}];
-export type ParadoxDocTagName = (typeof PARADOX_DOC_TAGS)[number]['name'];
-export type ParadoxDocTagHandlerId = (typeof PARADOX_DOC_TAGS)[number]['handler'];
+import { type DocumentationTagName, type DocumentationTagTarget, type DocumentationTagValueKind } from '@ankhorage/policy/documentation';
+declare const HANDLERS: {
+    readonly readme: "markReadme";
+    readonly usage: "markUsage";
+    readonly config: "markConfig";
+    readonly title: "setTitle";
+    readonly see: "addSee";
+    readonly security: "addSecurity";
+};
+interface ParadoxDocTag {
+    name: DocumentationTagName;
+    syntax: string;
+    description: string;
+    appliesTo: readonly DocumentationTagTarget[];
+    repeatable: boolean;
+    valueKind: DocumentationTagValueKind;
+    handler: (typeof HANDLERS)[DocumentationTagName];
+}
+/***
+ * Supported Paradox documentation tags projected from the canonical Ankhorage documentation policy.
+ *
+ * @readme
+ */
+export declare const PARADOX_DOC_TAGS: readonly ParadoxDocTag[];
+export type ParadoxDocTagName = DocumentationTagName;
+export type ParadoxDocTagHandlerId = (typeof HANDLERS)[DocumentationTagName];
 /***
  * Looks up documentation tag metadata by tag name.
  */
-export declare function getParadoxDocTag(name: string): (typeof PARADOX_DOC_TAGS)[number] | null;
+export declare function getParadoxDocTag(name: string): ParadoxDocTag | null;
 /***
  * Checks whether a string is a supported Paradox documentation tag name.
  */
 export declare function isParadoxDocTagName(name: string): name is ParadoxDocTagName;
+export {};

package/dist/doc-tags/registry.js

@@ -1,46 +1,23 @@
+import { DOCUMENTATION_POLICY, } from '@ankhorage/policy/documentation';
+const HANDLERS = {
+    readme: 'markReadme',
+    usage: 'markUsage',
+    config: 'markConfig',
+    title: 'setTitle',
+    see: 'addSee',
+    security: 'addSecurity',
+};
 /***
- * Supported Paradox documentation tags.
- *
- * Paradox supports doc tags inside triple-star documentation comments.
+ * Supported Paradox documentation tags projected from the canonical Ankhorage documentation policy.
  *
  * @readme
  */
-const DOC_TAG_PREFIX = '\u0040';
-const USAGE_DOC_TAG = `${DOC_TAG_PREFIX}usage`;
-export const PARADOX_DOC_TAGS = [
-    {
-        name: 'readme',
-        syntax: '@readme',
-        description: 'Includes a documentation block or exported symbol in README output.',
-        appliesTo: ['block', 'symbol'],
-        repeatable: false,
-        handler: 'markReadme',
-    },
-    {
-        name: 'config',
-        syntax: '@config',
-        description: 'Marks a configuration type, interface, or source block. Pair with @readme to include the schema or actual config source in README Configuration output.',
-        appliesTo: ['block', 'interface', 'type'],
-        repeatable: false,
-        handler: 'markConfig',
-    },
-    {
-        name: 'example',
-        syntax: '@example',
-        description: 'Adds a titled fenced code example to the generated documentation for a symbol.',
-        appliesTo: ['symbol'],
-        repeatable: true,
-        handler: 'parseExample',
-    },
-    {
-        name: 'usage',
-        syntax: USAGE_DOC_TAG,
-        description: 'Promotes a real source example into the generated README Usage section.',
-        appliesTo: ['block', 'symbol'],
-        repeatable: false,
-        handler: 'markUsage',
-    },
-];
+export const PARADOX_DOC_TAGS = DOCUMENTATION_POLICY.tags.map((tag) => ({
+    ...tag,
+    syntax: `@${tag.name}`,
+    description: describeTag(tag.name),
+    handler: HANDLERS[tag.name],
+}));
 /***
  * Looks up documentation tag metadata by tag name.
  */
@@ -53,3 +30,22 @@ export function getParadoxDocTag(name) {
 export function isParadoxDocTagName(name) {
     return getParadoxDocTag(name) !== null;
 }
+/***
+ * Describes the rendering meaning of one policy-owned documentation tag.
+ */
+function describeTag(name) {
+    switch (name) {
+        case 'readme':
+            return 'Promotes the documented item into generated README output.';
+        case 'usage':
+            return 'Marks real source as package usage documentation.';
+        case 'config':
+            return 'Marks the canonical package configuration schema root.';
+        case 'title':
+            return 'Provides an explicit presentation title for a documented item.';
+        case 'see':
+            return 'Adds a validated external documentation reference.';
+        case 'security':
+            return 'Links security-sensitive behavior to an exact colocated executable test.';
+    }
+}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { defineParadoxConfig } from './config/defineParadoxConfig.js';
-export type { ParadoxConfig } from './config/types.js';
 export type { ParadoxDocTagHandlerId, ParadoxDocTagName } from './doc-tags/registry.js';
 export { getParadoxDocTag, isParadoxDocTagName, PARADOX_DOC_TAGS } from './doc-tags/registry.js';
 export { packageMetadata as paradoxPackageMetadata } from './packageMetadata.js';
+export type { ParadoxConfig } from './types/config.js';

package/dist/model/buildModel.d.ts

@@ -1,9 +1,4 @@
 import type { DocumentationModel, ExportKind } from './types.js';
-interface ExampleInput {
-    title: string | null;
-    language: string | null;
-    code: string;
-}
 interface ExportMemberInput {
     name: string;
     kind: 'property' | 'method';
@@ -39,9 +34,11 @@ interface BuildModelInput {
     }[];
     exports: {
         name: string;
+        title: string | null;
         description: string | null;
         isReadme: boolean;
-        examples: ExampleInput[];
+        see: string[];
+        security: string[];
         kind: ExportKind;
         modulePath: string;
         sourceLocation: {
@@ -71,7 +68,8 @@ interface BuildModelInput {
         name: string;
         description: string | null;
         isReadme: boolean;
-        examples: ExampleInput[];
+        see: string[];
+        security: string[];
         modulePath: string;
         sourceLocation: {
             filePath: string;
@@ -90,6 +88,8 @@ interface BuildModelInput {
     sourceFunctions: {
         name: string;
         description: string | null;
+        see: string[];
+        security: string[];
         sourceLocation: {
             filePath: string;
             line: number;
@@ -106,32 +106,39 @@ interface BuildModelInput {
     }[];
     usage: {
         packageName: string;
-        commands: {
-            name: string;
-            command: string;
-        }[];
-    } | null;
-    readmeUsageDescription: string | null;
-    readmeUsage: {
+        command: string;
+    };
+    usageEntries: {
+        area: 'cli' | 'examples';
         title: string | null;
         description: string | null;
         language: string;
         code: string;
         sourcePath: string;
+        isReadme: boolean;
+        see: string[];
+        security: string[];
+    }[];
+    exampleCount: number;
+    findings: {
+        ruleId: string;
+        severity: 'warning' | 'error';
+        message: string;
+        sourcePath: string | null;
+        line: number | null;
     }[];
-    readmeCli: {
-        description: string | null;
-        sourcePath: string;
-    } | null;
     readmeConfig: {
-        description: string | null;
         language: string;
         code: string;
         sourcePath: string;
     } | null;
     config: {
         exportName: string;
+        title: string | null;
+        description: string | null;
         isReadme: boolean;
+        see: string[];
+        security: string[];
         members: ConfigMemberInput[];
     } | null;
     entrypoints: string[];