@ankhorage/paradox 0.1.3 → 0.1.5

package/dist/analyze/utils/getExportMetadata.js

@@ -10,6 +10,7 @@ export function getExportMetadata(options) {
     const sourceLocation = getSourceLocation(options.node, options.root);
     const signatures = getSignatures(options.symbol, options.node);
     const members = getMembers(options.node);
+    const structuredRows = getStructuredRows(options.node, options.name);
     const relatedSymbols = collectRelatedSymbols(options.name, signatures.flatMap((signature) => [
         ...signature.parameters.map((parameter) => parameter.type),
         signature.returnType,
@@ -21,8 +22,12 @@ export function getExportMetadata(options) {
         relatedSymbols,
         signatures,
         members,
+        structuredRows,
     };
 }
+/***
+ * Resolves the source location for a declaration relative to the package root.
+ */
 function getSourceLocation(node, root) {
     const sourceFile = node.getSourceFile();
     const { column, line } = sourceFile.getLineAndColumnAtPos(node.getStart(false));
@@ -32,6 +37,9 @@ function getSourceLocation(node, root) {
         column,
     };
 }
+/***
+ * Extracts callable signatures for exported functions and callable values.
+ */
 function getSignatures(symbol, node) {
     const parsed = readParadoxMetadata(node);
     const signatures = getCallableDeclarations(symbol, node).map((declaration) => getSignature(declaration, parsed.params, parsed.returns));
@@ -39,6 +47,9 @@ function getSignatures(symbol, node) {
         signature.returnType !== null ||
         signature.returnDescription !== null), (signature) => signature.label);
 }
+/***
+ * Builds one normalized call signature from a callable declaration.
+ */
 function getSignature(declaration, params, returns) {
     const normalizedParameters = declaration.getParameters().map((parameter) => {
         const parameterDescription = params[parameter.getName()];
@@ -60,6 +71,9 @@ function getSignature(declaration, params, returns) {
         returnDescription: returns,
     };
 }
+/***
+ * Extracts members for interface and type literal exports.
+ */
 function getMembers(node) {
     if (getCallableNode(node) !== null)
         return [];
@@ -74,6 +88,9 @@ function getMembers(node) {
     }
     return [];
 }
+/***
+ * Converts TypeScript properties into documented member metadata.
+ */
 function getMembersFromProperties(properties) {
     return properties.flatMap((property) => {
         const declaration = getFirstDeclaration(property.getDeclarations());
@@ -83,7 +100,14 @@ function getMembersFromProperties(properties) {
         const rawComment = getParadoxComment(declaration);
         const parsed = rawComment
             ? parseParadoxComment(rawComment)
-            : { description: null, isConfig: false, params: {}, returns: null };
+            : {
+                description: null,
+                isConfig: false,
+                isReadme: false,
+                examples: [],
+                params: {},
+                returns: null,
+            };
         return [
             {
                 name: property.getName(),
@@ -95,10 +119,102 @@ function getMembersFromProperties(properties) {
         ];
     });
 }
+/***
+ * Extracts table-like rows from exported const arrays of object literals.
+ */
+function getStructuredRows(node, exportName) {
+    const declaration = getVariableDeclaration(node, exportName);
+    if (declaration === null)
+        return [];
+    const initializer = getStructuredArrayLiteral(declaration.getInitializer());
+    if (initializer === null)
+        return [];
+    return initializer.getElements().flatMap((element) => {
+        if (!Node.isObjectLiteralExpression(element))
+            return [];
+        const values = getObjectLiteralValues(element);
+        return Object.keys(values).length > 0 ? [{ values }] : [];
+    });
+}
+/***
+ * Resolves const assertions and returns the array literal used for structured docs.
+ */
+function getStructuredArrayLiteral(node) {
+    if (node === undefined)
+        return null;
+    if (Node.isArrayLiteralExpression(node))
+        return node;
+    if (Node.isAsExpression(node))
+        return getStructuredArrayLiteral(node.getExpression());
+    return null;
+}
+/***
+ * Resolves a variable declaration from declaration nodes used by export symbols.
+ */
+function getVariableDeclaration(node, exportName) {
+    if (Node.isVariableDeclaration(node))
+        return node;
+    if (Node.isVariableStatement(node)) {
+        return (node
+            .getDeclarationList()
+            .getDeclarations()
+            .find((declaration) => declaration.getName() === exportName) ?? null);
+    }
+    if (Node.isVariableDeclarationList(node)) {
+        return (node.getDeclarations().find((declaration) => declaration.getName() === exportName) ?? null);
+    }
+    return null;
+}
+/***
+ * Extracts primitive and string-array values from one object literal.
+ */
+function getObjectLiteralValues(node) {
+    const values = {};
+    for (const property of node.getProperties()) {
+        if (!Node.isPropertyAssignment(property))
+            continue;
+        const name = property.getName().replace(/^['"]|['"]$/g, '');
+        const value = getLiteralValue(property.getInitializer());
+        if (value !== null) {
+            values[name] = value;
+        }
+    }
+    return values;
+}
+/***
+ * Converts supported literal expressions into displayable string values.
+ */
+function getLiteralValue(node) {
+    if (node === undefined)
+        return null;
+    if (Node.isStringLiteral(node))
+        return node.getLiteralText();
+    if (Node.isNoSubstitutionTemplateLiteral(node))
+        return node.getLiteralText();
+    if (node.getKindName() === 'TrueKeyword')
+        return 'true';
+    if (node.getKindName() === 'FalseKeyword')
+        return 'false';
+    if (Node.isNumericLiteral(node))
+        return node.getText();
+    if (Node.isArrayLiteralExpression(node)) {
+        const values = node.getElements().map((element) => getLiteralValue(element));
+        if (values.some((value) => value === null))
+            return null;
+        return values.join(', ');
+    }
+    return null;
+}
+/***
+ * Returns the first declaration for a symbol, or null when none exists.
+ */
 function getFirstDeclaration(declarations) {
     const [declaration = null] = declarations;
     return declaration;
 }
+/***
+ * Finds callable declarations associated with an export symbol.
+ */
 function getCallableDeclarations(symbol, node) {
     const declarations = symbol
         .getDeclarations()
@@ -110,6 +226,9 @@ function getCallableDeclarations(symbol, node) {
     const callableNode = getCallableNode(node);
     return callableNode !== null ? [callableNode] : [];
 }
+/***
+ * Returns the callable node represented by a declaration when one exists.
+ */
 function getCallableNode(node) {
     if (Node.isFunctionDeclaration(node))
         return node;
@@ -130,15 +249,31 @@ function getCallableNode(node) {
     }
     return null;
 }
+/***
+ * Checks whether a node is a method declaration or method signature.
+ */
 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, params: {}, returns: null };
+        : {
+            description: null,
+            isConfig: false,
+            isReadme: false,
+            examples: [],
+            params: {},
+            returns: null,
+        };
 }
+/***
+ * Finds related exported symbols mentioned in signature and member type text.
+ */
 function collectRelatedSymbols(exportName, ...values) {
     const candidates = values.flatMap((entries) => entries).filter((entry) => entry !== null);
     const related = new Set();
@@ -152,9 +287,15 @@ function collectRelatedSymbols(exportName, ...values) {
     }
     return [...related].sort((left, right) => left.localeCompare(right));
 }
+/***
+ * Normalizes platform-specific path separators for generated documentation output.
+ */
 function toPosixPath(path) {
     return path.replaceAll('\\', '/');
 }
+/***
+ * Returns unique items by a caller-provided key while preserving first occurrence order.
+ */
 function uniqueBy(items, key) {
     const seen = new Set();
     return items.filter((item) => {

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

@@ -1,5 +1,5 @@
-import type { Node } from 'ts-morph';
+import { type Node as MorphNode } from 'ts-morph';
 /***
  * Reads the nearest Paradox doc comment attached to a declaration.
  */
-export declare function getParadoxComment(node: Node | undefined): string | null;
+export declare function getParadoxComment(node: MorphNode | undefined): string | null;

package/dist/analyze/utils/getParadoxComment.js

@@ -1,3 +1,4 @@
+import { Node } from 'ts-morph';
 /***
  * Reads the nearest Paradox doc comment attached to a declaration.
  */
@@ -6,7 +7,31 @@ export function getParadoxComment(node) {
         return null;
     const sourceFile = node.getSourceFile();
     const text = sourceFile.getFullText();
-    const nodeStart = node.getStart(false);
+    for (const nodeStart of getCommentTargetStarts(node)) {
+        const comment = readCommentBefore(text, nodeStart);
+        if (comment !== null)
+            return comment;
+    }
+    return null;
+}
+/***
+ * Returns declaration positions that may own a leading Paradox comment.
+ */
+function getCommentTargetStarts(node) {
+    const starts = [node.getStart(false)];
+    if (Node.isVariableDeclaration(node)) {
+        const parent = node.getParent();
+        const statement = Node.isVariableDeclarationList(parent) ? parent.getParent() : undefined;
+        if (statement !== undefined && Node.isVariableStatement(statement)) {
+            starts.unshift(statement.getStart(false));
+        }
+    }
+    return starts;
+}
+/***
+ * Reads a Paradox doc comment directly before a target position.
+ */
+function readCommentBefore(text, nodeStart) {
     const beforeNode = text.slice(0, nodeStart);
     const commentStart = beforeNode.lastIndexOf('/***');
     if (commentStart === -1)

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

@@ -0,0 +1,39 @@
+/***
+ * Supported Paradox documentation tags.
+ *
+ * Paradox supports doc tags inside triple-star documentation comments.
+ *
+ * @readme
+ */
+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 type or interface as part of the Paradox configuration model. @config alone does not imply README inclusion; use @config plus @readme for README output.";
+    readonly appliesTo: readonly ["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";
+}];
+export type ParadoxDocTagName = (typeof PARADOX_DOC_TAGS)[number]['name'];
+export type ParadoxDocTagHandlerId = (typeof PARADOX_DOC_TAGS)[number]['handler'];
+/***
+ * Looks up documentation tag metadata by tag name.
+ */
+export declare function getParadoxDocTag(name: string): (typeof PARADOX_DOC_TAGS)[number] | null;
+/***
+ * Checks whether a string is a supported Paradox documentation tag name.
+ */
+export declare function isParadoxDocTagName(name: string): name is ParadoxDocTagName;

package/dist/doc-tags/registry.js

@@ -0,0 +1,45 @@
+/***
+ * Supported Paradox documentation tags.
+ *
+ * Paradox supports doc tags inside triple-star documentation comments.
+ *
+ * @readme
+ */
+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 type or interface as part of the Paradox configuration model. @config alone does not imply README inclusion; use @config plus @readme for README output.',
+        appliesTo: ['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',
+    },
+];
+/***
+ * Looks up documentation tag metadata by tag name.
+ */
+export function getParadoxDocTag(name) {
+    return PARADOX_DOC_TAGS.find((tag) => tag.name === name) ?? null;
+}
+/***
+ * Checks whether a string is a supported Paradox documentation tag name.
+ */
+export function isParadoxDocTagName(name) {
+    return getParadoxDocTag(name) !== null;
+}

package/dist/index.d.ts

@@ -1,2 +1,4 @@
 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';

package/dist/index.js

@@ -1 +1,2 @@
 export { defineParadoxConfig } from './config/defineParadoxConfig.js';
+export { getParadoxDocTag, isParadoxDocTagName, PARADOX_DOC_TAGS } from './doc-tags/registry.js';

package/dist/model/buildModel.d.ts

@@ -59,6 +59,9 @@ interface BuildModelInput {
             returnDescription: string | null;
         }[];
         members: ExportMemberInput[];
+        structuredRows: {
+            values: Record<string, string>;
+        }[];
     }[];
     components: {
         name: string;
@@ -80,6 +83,15 @@ interface BuildModelInput {
             description: string | null;
         }[];
     }[];
+    sourceFunctions: {
+        name: string;
+        description: string | null;
+        sourceLocation: {
+            filePath: string;
+            line: number;
+            column: number;
+        };
+    }[];
     sequenceScenarios: {
         kind: 'bin' | 'export';
         name: string;

package/dist/model/buildModel.js

@@ -46,6 +46,15 @@ export function buildModel(analysis) {
             .sort((left, right) => left.path.localeCompare(right.path)),
         exports,
         components: sortByName(analysis.components.map((component) => mapComponent(component, exportsByName.get(component.name)))),
+        sourceFunctions: analysis.sourceFunctions.map((sourceFunction) => ({
+            name: sourceFunction.name,
+            description: sourceFunction.description,
+            sourceLocation: {
+                filePath: sourceFunction.sourceLocation.filePath,
+                line: sourceFunction.sourceLocation.line,
+                column: sourceFunction.sourceLocation.column,
+            },
+        })),
         sequenceScenarios: sortByName(analysis.sequenceScenarios.map((scenario) => ({
             kind: scenario.kind,
             name: scenario.name,
@@ -62,6 +71,9 @@ export function buildModel(analysis) {
         },
     };
 }
+/***
+ * Maps one analyzed export into the serializable documentation shape.
+ */
 function mapExport(item, exportNames) {
     return {
         name: item.name,
@@ -100,8 +112,12 @@ function mapExport(item, exportNames) {
             inheritedFrom: member.inheritedFrom,
             children: member.children,
         }))),
+        structuredRows: item.structuredRows.map((row) => ({ values: { ...row.values } })),
     };
 }
+/***
+ * Maps an analyzed component while preserving export metadata when available.
+ */
 function mapComponent(component, exportModel) {
     return {
         name: component.name,
@@ -124,6 +140,9 @@ function mapComponent(component, exportModel) {
         }))),
     };
 }
+/***
+ * Finds the conventional config factory export for a config type when present.
+ */
 function findConfigFactoryName(configExportName, exportNames) {
     const prefix = configExportName.endsWith('Config')
         ? configExportName.slice(0, -'Config'.length)
@@ -131,10 +150,16 @@ function findConfigFactoryName(configExportName, exportNames) {
     const expectedFactoryName = `define${prefix}Config`;
     return exportNames.includes(expectedFactoryName) ? expectedFactoryName : null;
 }
+/***
+ * Derives the default config file name from a package id.
+ */
 function getDefaultConfigFileName(packageId) {
     const packageBaseName = packageId.split('/').pop() ?? packageId;
     return `${packageBaseName}.config.ts`;
 }
+/***
+ * Returns a copy of items sorted by their `name` property.
+ */
 function sortByName(items) {
     return [...items].sort((a, b) => a.name.localeCompare(b.name));
 }

package/dist/model/types.d.ts

@@ -12,6 +12,7 @@ export interface DocumentationModel {
     modules: ModuleModel[];
     exports: ExportModel[];
     components: ComponentModel[];
+    sourceFunctions: SourceFunctionModel[];
     sequenceScenarios: SequenceScenarioModel[];
     graphs: GraphModel;
 }
@@ -48,8 +49,9 @@ export interface ExportModel {
     relatedSymbols: string[];
     signatures: SignatureModel[];
     members: MemberModel[];
+    structuredRows: StructuredRowModel[];
 }
-export type ExportKind = 'function' | 'type' | 'unknown';
+export type ExportKind = 'function' | 'type' | 'value' | 'unknown';
 export interface ComponentModel {
     name: string;
     description: string | null;
@@ -60,6 +62,11 @@ export interface ComponentModel {
     exportPaths: string[];
     props: PropModel[];
 }
+interface SourceFunctionModel {
+    name: string;
+    description: string | null;
+    sourceLocation: SourceLocationModel;
+}
 export interface SequenceScenarioModel {
     kind: 'bin' | 'export';
     name: string;
@@ -100,6 +107,9 @@ interface MemberModel {
     inheritedFrom?: string;
     children?: MemberModel[];
 }
+interface StructuredRowModel {
+    values: Record<string, string>;
+}
 export interface ModuleModel {
     path: string;
     isEntrypoint: boolean;

package/dist/paths/policy.d.ts

@@ -1,7 +1,19 @@
 import type { ParadoxConfig } from '../config/types.js';
+/***
+ * Searches upward from a start directory until it finds a supported Paradox config file.
+ */
 export declare function findParadoxConfigFile(startDir: string): Promise<string | null>;
+/***
+ * Loads a Paradox config module and returns its default export or an empty config.
+ */
 export declare function loadParadoxConfig(configFilePath: string): Promise<ParadoxConfig>;
+/***
+ * Resolves and validates the package root from config and config directory.
+ */
 export declare function resolvePackageRoot(config: ParadoxConfig, configDir: string): Promise<string>;
+/***
+ * Resolves the configured output directory and enforces that it stays inside the package root.
+ */
 export declare function resolveOutputRoot(config: ParadoxConfig, packageRoot: string): {
     outputDir: string;
     outputRoot: string;

package/dist/paths/policy.js

@@ -7,6 +7,9 @@ const CONFIG_FILENAMES = [
     'paradox.config.mjs',
     'paradox.config.cjs',
 ];
+/***
+ * Searches upward from a start directory until it finds a supported Paradox config file.
+ */
 export async function findParadoxConfigFile(startDir) {
     let current = resolve(startDir);
     let parent = dirname(current);
@@ -26,11 +29,17 @@ export async function findParadoxConfigFile(startDir) {
     }
     return null;
 }
+/***
+ * Loads a Paradox config module and returns its default export or an empty config.
+ */
 export async function loadParadoxConfig(configFilePath) {
     const url = pathToFileURL(configFilePath).href;
     const mod = (await import(url));
     return mod.default ?? {};
 }
+/***
+ * Resolves and validates the package root from config and config directory.
+ */
 export async function resolvePackageRoot(config, configDir) {
     const configuredRoot = config.package?.root;
     const resolvedRoot = configuredRoot
@@ -41,6 +50,9 @@ export async function resolvePackageRoot(config, configDir) {
     await assertPathExists(join(resolvedRoot, 'package.json'), `Unable to find package.json at resolved package root: ${resolvedRoot}`);
     return resolvedRoot;
 }
+/***
+ * Resolves the configured output directory and enforces that it stays inside the package root.
+ */
 export function resolveOutputRoot(config, packageRoot) {
     const outputDir = config.output?.dir ?? 'paradox';
     validateOutputDir(outputDir);
@@ -48,6 +60,9 @@ export function resolveOutputRoot(config, packageRoot) {
     assertWithinRoot(outputRoot, packageRoot, `Resolved output directory escapes package root: ${outputRoot}`);
     return { outputDir, outputRoot };
 }
+/***
+ * Checks whether a filesystem path can be accessed.
+ */
 async function pathExists(path) {
     try {
         await access(path);
@@ -57,11 +72,17 @@ async function pathExists(path) {
         return false;
     }
 }
+/***
+ * Throws a supplied error message when a required path does not exist.
+ */
 async function assertPathExists(path, message) {
     if (!(await pathExists(path))) {
         throw new Error(message);
     }
 }
+/***
+ * Validates an output directory string before resolving it against the package root.
+ */
 function validateOutputDir(outputDir) {
     const trimmed = outputDir.trim();
     if (trimmed.length === 0) {
@@ -74,18 +95,22 @@ function validateOutputDir(outputDir) {
     if (isAbsolute(normalized)) {
         throw new Error('Invalid output.dir: must be a relative path inside the package root (absolute paths are not allowed).');
     }
-    // Reject explicit parent traversal to keep writes deterministic and scoped.
     for (const segment of splitPathSegments(trimmed)) {
         if (segment === '..') {
             throw new Error('Invalid output.dir: must not contain ".." path segments.');
         }
     }
 }
+/***
+ * Splits a configured path into normalized non-empty path segments.
+ */
 function splitPathSegments(path) {
-    // Treat both separators as potential delimiters to stay robust across platforms/config styles.
     const normalized = path.replaceAll('\\', '/');
     return normalized.split('/').filter((segment) => segment.length > 0 && segment !== '.');
 }
+/***
+ * Throws when a resolved path is outside the expected package root.
+ */
 function assertWithinRoot(resolvedPath, root, message) {
     const rel = relative(root, resolvedPath);
     if (rel === '')