@ankhorage/paradox 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.1.5
+
+### Patch Changes
+
+- fd606af: Move documentation tag metadata into a typed registry, stop rendering Paradox tag docs by default in consumer READMEs, and add structured table rendering for documented const array exports.
+
+## 0.1.4
+
+### Patch Changes
+
+- 0255235: Full documentation of repo
+
 ## 0.1.3
 
 ### Patch Changes

package/README.md

@@ -3,7 +3,7 @@
 
 # @ankhorage/paradox
 
-![license: MIT](./paradox/badges/license.svg) ![npm: v0.1.2](./paradox/badges/npm.svg) ![runtime: bun](./paradox/badges/runtime.svg) ![typescript: strict](./paradox/badges/typescript.svg) ![eslint: checked](./paradox/badges/eslint.svg) ![prettier: checked](./paradox/badges/prettier.svg) ![build: checked](./paradox/badges/build.svg) ![tests: checked](./paradox/badges/tests.svg) ![docs: paradox](./paradox/badges/docs.svg)
+![license: MIT](./paradox/badges/license.svg) ![npm: v0.1.4](./paradox/badges/npm.svg) ![runtime: bun](./paradox/badges/runtime.svg) ![typescript: strict](./paradox/badges/typescript.svg) ![eslint: checked](./paradox/badges/eslint.svg) ![prettier: checked](./paradox/badges/prettier.svg) ![build: checked](./paradox/badges/build.svg) ![tests: checked](./paradox/badges/tests.svg) ![docs: paradox](./paradox/badges/docs.svg)
 
 Deterministic documentation generator for TypeScript packages.
 
@@ -64,29 +64,6 @@ sequenceDiagram
 
 </details>
 
-## Documentation Tags
-
-<details>
-<summary>@readme</summary>
-
-Includes a documentation block or exported symbol in README output.
-
-</details>
-
-<details>
-<summary>@config</summary>
-
-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.
-
-</details>
-
-<details>
-<summary>@example</summary>
-
-Adds a titled fenced code example to the generated documentation for a symbol.
-
-</details>
-
 ## Configuration
 
 Create a `paradox.config.ts` file:
@@ -119,6 +96,7 @@ export default defineParadoxConfig({
 - [Architecture overview](./paradox/diagrams/architecture-overview.mmd)
 - [Module relationships](./paradox/diagrams/module-relationships.mmd)
 - [Export graph](./paradox/diagrams/export-graph.mmd)
+- [isParadoxDocTagName sequence](./paradox/diagrams/sequences/is-paradox-doc-tag-name.mmd)
 - [paradox sequence](./paradox/diagrams/sequences/paradox.mmd)
 
 ## Architecture preview
@@ -142,6 +120,7 @@ graph TD
   module_src_analyze_analyze_ts --> module_src_analyze_semantic_exports_ts
   module_src_analyze_analyze_ts --> module_src_analyze_semantic_graphs_ts
   module_src_analyze_analyze_ts --> module_src_analyze_sequenceScenarios_ts
+  module_src_analyze_analyze_ts --> module_src_analyze_sourceFunctions_ts
   module_src_analyze_analyze_ts --> module_src_analyze_types_ts
   module_src_analyze_analyze_ts --> module_src_analyze_usage_ts
   module_src_analyze_analyze_ts --> module_src_config_types_ts
@@ -224,6 +203,11 @@ graph TD
   module_src_analyze_sequenceScenarios_ts --> module_src_analyze_usage_ts
   module_src_analyze_sequenceScenarios_ts --> module_src_analyze_utils_getParadoxComment_ts
   module_src_analyze_sequenceScenarios_ts --> module_src_analyze_utils_parseParadoxComment_ts
+  module_src_analyze_sourceFunctions_ts["src/analyze/sourceFunctions.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_sourceFunctions_ts
+  module_src_analyze_sourceFunctions_ts --> module_src_analyze_types_ts
+  module_src_analyze_sourceFunctions_ts --> module_src_analyze_utils_getParadoxComment_ts
+  module_src_analyze_sourceFunctions_ts --> module_src_analyze_utils_parseParadoxComment_ts
   module_src_analyze_types_ts["src/analyze/types.ts"]
   package__ankhorage_paradox -.-> module_src_analyze_types_ts
   module_src_analyze_usage_ts["src/analyze/usage.ts"]
@@ -261,6 +245,8 @@ graph TD
   module_src_config_defineParadoxConfig_ts --> module_src_config_types_ts
   module_src_config_types_ts["src/config/types.ts"]
   package__ankhorage_paradox -.-> module_src_config_types_ts
+  module_src_doc_tags_registry_ts["src/doc-tags/registry.ts"]
+  package__ankhorage_paradox -.-> module_src_doc_tags_registry_ts
   module_src_index_ts["src/index.ts"]
   module_src_model_buildModel_ts["src/model/buildModel.ts"]
   package__ankhorage_paradox -.-> module_src_model_buildModel_ts
@@ -316,7 +302,7 @@ graph TD
 
 ## Public API
 
-### Configuration
+### Config
 
 <details>
 <summary>defineParadoxConfig</summary>
@@ -342,3 +328,23 @@ Module: `src/config/types.ts`
 Source: `src/config/types.ts:7:1`
 
 </details>
+
+### Documentation
+
+<details>
+<summary>PARADOX_DOC_TAGS</summary>
+
+Supported Paradox documentation tags.
+
+Paradox supports doc tags inside triple-star documentation comments.
+
+| name      | syntax     | description                                                                                                                                                      | applies to      | repeatable | handler        |
+| --------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | ---------- | -------------- |
+| `readme`  | `@readme`  | Includes a documentation block or exported symbol in README output.                                                                                              | block, symbol   | no         | `markReadme`   |
+| `config`  | `@config`  | 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. | interface, type | no         | `markConfig`   |
+| `example` | `@example` | Adds a titled fenced code example to the generated documentation for a symbol.                                                                                   | symbol          | yes        | `parseExample` |
+
+Module: `src/doc-tags/registry.ts`
+Source: `src/doc-tags/registry.ts:8:14`
+
+</details>

package/dist/analyze/analyze.d.ts

@@ -1,5 +1,8 @@
 import type { ParadoxConfig } from '../config/types.js';
 import type { AnalysisResult } from './types.js';
+/***
+ * Analyzes a package and returns the complete documentation input model.
+ */
 export declare function analyze(config: ParadoxConfig, runtime: {
     packageRoot: string;
 }): Promise<AnalysisResult>;

package/dist/analyze/analyze.js

@@ -9,7 +9,11 @@ import { createTypeScriptProgram } from './semantic/createTypeScriptProgram.js';
 import { collectTypeMembers, resolveTypeReference } from './semantic/exports.js';
 import { collectCallGraph, collectComponentCompositionGraph, collectImportGraph, } from './semantic/graphs.js';
 import { analyzeSequenceScenarios } from './sequenceScenarios.js';
+import { analyzeSourceFunctions } from './sourceFunctions.js';
 import { createUsageFromPackageJson } from './usage.js';
+/***
+ * Analyzes a package and returns the complete documentation input model.
+ */
 export async function analyze(config, runtime) {
     const root = runtime.packageRoot;
     const pkg = await readPackageJson(root);
@@ -21,6 +25,7 @@ export async function analyze(config, runtime) {
     const { config: configMetadata, exports } = analyzeExports(project, { root, entrypoints });
     const components = analyzeComponents(exports, { program });
     const modules = analyzeModules(project, { root, entrypoints });
+    const sourceFunctions = analyzeSourceFunctions(project, root);
     const sequenceScenarios = analyzeSequenceScenarios({ project, root, pkg, exports });
     const configExport = configMetadata
         ? (exports.find((entry) => entry.name === configMetadata.exportName) ?? null)
@@ -49,6 +54,7 @@ export async function analyze(config, runtime) {
         description: config.docs?.description ?? pkg.description ?? null,
         exports,
         components,
+        sourceFunctions,
         entrypoints: entrypoints.map((entrypoint) => entrypoint.replaceAll('\\', '/')).sort(),
         modules,
         badges,
@@ -64,6 +70,9 @@ export async function analyze(config, runtime) {
         graphs,
     };
 }
+/***
+ * Converts semantic type members into serializable analysis output.
+ */
 function mapTypeMembers(members) {
     return members.map((member) => ({
         name: member.name,
@@ -75,6 +84,9 @@ function mapTypeMembers(members) {
         ...(member.children ? { children: mapTypeMembers(member.children) } : {}),
     }));
 }
+/***
+ * Reads package metadata from the analyzed package root.
+ */
 async function readPackageJson(root) {
     const raw = await readFile(join(root, 'package.json'), 'utf-8');
     return JSON.parse(raw);

package/dist/analyze/badges.js

@@ -132,6 +132,9 @@ export async function analyzeBadges(root, pkg) {
     });
     return sortBadges(badges);
 }
+/***
+ * Checks whether any candidate file exists under the repository root.
+ */
 async function hasAnyFile(root, paths) {
     for (const relativePath of paths) {
         if (await fileExists(join(root, relativePath))) {
@@ -140,18 +143,30 @@ async function hasAnyFile(root, paths) {
     }
     return false;
 }
+/***
+ * Reads tsconfig metadata and detects strict TypeScript mode.
+ */
 async function hasTypeScriptStrictMode(root) {
     const tsconfig = await readJsonFile(join(root, 'tsconfig.json'));
     return tsconfig?.compilerOptions?.strict === true;
 }
+/***
+ * Reads the line coverage percentage from a coverage summary file when present.
+ */
 async function readCoveragePercent(root) {
     const coverage = await readJsonFile(join(root, 'coverage', 'coverage-summary.json'));
     const value = coverage?.total?.lines?.pct;
     return typeof value === 'number' && Number.isFinite(value) ? value : null;
 }
+/***
+ * Formats integer and fractional percentages for badge labels.
+ */
 function formatPercent(value) {
     return Number.isInteger(value) ? `${value}` : value.toFixed(1);
 }
+/***
+ * Selects the coverage badge color from the coverage percentage.
+ */
 function getCoverageColor(value) {
     if (value >= 90)
         return '0a7f3f';
@@ -161,12 +176,21 @@ function getCoverageColor(value) {
         return 'ca8a04';
     return 'dc2626';
 }
+/***
+ * Checks whether a named package script is configured.
+ */
 function hasScript(pkg, name) {
     return typeof pkg.scripts?.[name] === 'string' && pkg.scripts[name].length > 0;
 }
+/***
+ * Checks whether a package script contains a specific command fragment.
+ */
 function scriptContains(pkg, name, command) {
     return pkg.scripts?.[name]?.includes(command) ?? false;
 }
+/***
+ * Detects whether package metadata or workflows indicate Bun support.
+ */
 function supportsBun(pkg, workflowFiles) {
     if (pkg.packageManager?.startsWith('bun@') ?? false) {
         return true;
@@ -178,6 +202,9 @@ function supportsBun(pkg, workflowFiles) {
         workflow.includes('bun install') ||
         /\bbun(?:x)?\b/.test(workflow));
 }
+/***
+ * Checks whether any workflow file invokes a named package script.
+ */
 function workflowRunsScript(workflowFiles, scriptName) {
     const escaped = escapeRegExp(scriptName);
     const patterns = [
@@ -188,9 +215,15 @@ function workflowRunsScript(workflowFiles, scriptName) {
     ];
     return workflowFiles.some((workflow) => patterns.some((pattern) => pattern.test(workflow)));
 }
+/***
+ * Escapes regular expression syntax in a script name.
+ */
 function escapeRegExp(value) {
     return value.replaceAll(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
+/***
+ * Reads all GitHub Actions workflow files from the repository.
+ */
 async function readWorkflowFiles(root) {
     const workflowsPath = join(root, '.github', 'workflows');
     const entries = await readDirectory(workflowsPath);
@@ -200,6 +233,9 @@ async function readWorkflowFiles(root) {
         .map((entry) => readFile(join(workflowsPath, entry), 'utf-8')));
     return contents;
 }
+/***
+ * Reads a directory and treats a missing path as an empty directory.
+ */
 async function readDirectory(path) {
     try {
         return await readdir(path);
@@ -211,9 +247,15 @@ async function readDirectory(path) {
         throw new Error(`Unable to read workflow directory: ${path}`, { cause: error });
     }
 }
+/***
+ * Checks whether an unknown error is a file-not-found filesystem error.
+ */
 function isNotFoundError(error) {
     return typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT';
 }
+/***
+ * Reads and parses a JSON file, returning null when the file does not exist.
+ */
 async function readJsonFile(path) {
     let content;
     try {
@@ -232,6 +274,9 @@ async function readJsonFile(path) {
         throw new Error(`Unable to parse JSON metadata file: ${path}`, { cause: error });
     }
 }
+/***
+ * Checks whether a filesystem path exists.
+ */
 async function fileExists(path) {
     try {
         await access(path);
@@ -244,12 +289,18 @@ async function fileExists(path) {
         throw error;
     }
 }
+/***
+ * Sorts badges into the stable preferred display order.
+ */
 function sortBadges(badges) {
     return [...badges].sort((left, right) => {
         const order = getBadgeOrder(left.id) - getBadgeOrder(right.id);
         return order !== 0 ? order : left.id.localeCompare(right.id);
     });
 }
+/***
+ * Returns the configured display order index for a badge id.
+ */
 function getBadgeOrder(id) {
     const index = BADGE_ORDER.indexOf(id);
     return index === -1 ? BADGE_ORDER.length : index;

package/dist/analyze/exports.d.ts

@@ -1,4 +1,4 @@
-import type { Project } from 'ts-morph';
+import { type Project } from 'ts-morph';
 import type { AnalysisExport } from './types.js';
 interface AnalyzeExportsResult {
     exports: AnalysisExport[];

package/dist/analyze/exports.js

@@ -1,4 +1,5 @@
 import { isAbsolute, join, normalize, relative } from 'node:path';
+import { Node } from 'ts-morph';
 import { getExportMetadata } from './utils/getExportMetadata.js';
 import { getParadoxComment } from './utils/getParadoxComment.js';
 import { parseParadoxComment } from './utils/parseParadoxComment.js';
@@ -48,6 +49,9 @@ export function analyzeExports(project, options) {
                     ]),
                     signatures: existing.signatures.length > 0 ? existing.signatures : metadata.signatures,
                     members: existing.members.length > 0 ? existing.members : metadata.members,
+                    structuredRows: existing.structuredRows.length > 0
+                        ? existing.structuredRows
+                        : metadata.structuredRows,
                 }
                 : {
                     name,
@@ -65,6 +69,9 @@ export function analyzeExports(project, options) {
         config,
     };
 }
+/***
+ * Resolves configured entrypoint paths to source files in the TypeScript project.
+ */
 function getEntryPointSourceFiles(project, options) {
     return options.entrypoints
         .map((entrypoint) => {
@@ -73,23 +80,40 @@ function getEntryPointSourceFiles(project, options) {
     })
         .filter((sourceFile) => sourceFile != null);
 }
+/***
+ * Returns the first declaration for a symbol, or null when none exists.
+ */
 function getFirstDeclaration(declarations) {
     const [declaration = null] = declarations;
     return declaration;
 }
+/***
+ * Infers the public export kind from the declaration shape.
+ */
 function inferKind(node) {
     if ('getParameters' in node)
         return 'function';
     if ('getProperties' in node || 'getMembers' in node)
         return 'type';
+    if (Node.isVariableDeclaration(node))
+        return 'value';
     return 'unknown';
 }
+/***
+ * Returns unique string values sorted for deterministic generated output.
+ */
 function uniqueSorted(values) {
     return [...new Set(values)].sort((left, right) => left.localeCompare(right));
 }
+/***
+ * Normalizes platform-specific path separators for generated documentation output.
+ */
 function toPosixPath(path) {
     return path.replaceAll('\\', '/');
 }
+/***
+ * Creates empty documentation metadata for exports without Paradox comments.
+ */
 function createEmptyMetadata() {
     return {
         description: null,

package/dist/analyze/modules.js

@@ -36,9 +36,15 @@ export function analyzeModules(project, options) {
     })
         .sort((left, right) => left.path.localeCompare(right.path));
 }
+/***
+ * Returns unique string values sorted for deterministic generated output.
+ */
 function uniqueSorted(values) {
     return [...new Set(values)].sort((left, right) => left.localeCompare(right));
 }
+/***
+ * Normalizes platform-specific path separators for generated documentation output.
+ */
 function toPosixPath(path) {
     return path.replaceAll('\\', '/');
 }

package/dist/analyze/sourceFunctions.d.ts

@@ -0,0 +1,6 @@
+import { type Project } from 'ts-morph';
+import type { AnalysisSourceFunction } from './types.js';
+/***
+ * Collects callable declarations from analyzed source files for source-area documentation.
+ */
+export declare function analyzeSourceFunctions(project: Project, root: string): AnalysisSourceFunction[];

package/dist/analyze/sourceFunctions.js

@@ -0,0 +1,64 @@
+import { relative } from 'node:path';
+import { Node } from 'ts-morph';
+import { getParadoxComment } from './utils/getParadoxComment.js';
+import { parseParadoxComment } from './utils/parseParadoxComment.js';
+/***
+ * Collects callable declarations from analyzed source files for source-area documentation.
+ */
+export function analyzeSourceFunctions(project, root) {
+    return project
+        .getSourceFiles()
+        .flatMap((sourceFile) => {
+        if (sourceFile.isDeclarationFile())
+            return [];
+        const filePath = toPosixPath(relative(root, sourceFile.getFilePath()));
+        if (!filePath.startsWith('src/'))
+            return [];
+        return sourceFile.getDescendants().flatMap((node) => {
+            if (Node.isFunctionDeclaration(node)) {
+                const name = node.getName();
+                if (name === undefined)
+                    return [];
+                return [createSourceFunction(name, node, root)];
+            }
+            if (Node.isVariableDeclaration(node)) {
+                const initializer = node.getInitializer();
+                if (initializer === undefined ||
+                    (!Node.isArrowFunction(initializer) && !Node.isFunctionExpression(initializer))) {
+                    return [];
+                }
+                return [createSourceFunction(node.getName(), node, root)];
+            }
+            return [];
+        });
+    })
+        .sort((left, right) => left.sourceLocation.filePath === right.sourceLocation.filePath
+        ? left.sourceLocation.line - right.sourceLocation.line
+        : left.sourceLocation.filePath.localeCompare(right.sourceLocation.filePath));
+}
+/***
+ * Converts a callable declaration into source documentation metadata.
+ */
+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 };
+    return {
+        name,
+        description: parsedComment.description,
+        sourceLocation: {
+            filePath: toPosixPath(relative(root, sourceFile.getFilePath())),
+            line,
+            column,
+        },
+    };
+}
+/***
+ * Normalizes platform-specific path separators for generated documentation output.
+ */
+function toPosixPath(path) {
+    return path.replaceAll('\\', '/');
+}

package/dist/analyze/types.d.ts

@@ -34,19 +34,23 @@ export interface AnalysisMember {
     inheritedFrom?: string;
     children?: AnalysisMember[];
 }
+export interface AnalysisStructuredRow {
+    values: Record<string, string>;
+}
 export interface AnalysisExport {
     name: string;
     node: Node;
     description: string | null;
     isReadme: boolean;
     examples: AnalysisExample[];
-    kind: 'function' | 'type' | 'unknown';
+    kind: 'function' | 'type' | 'value' | 'unknown';
     modulePath: string;
     sourceLocation: AnalysisSourceLocation;
     exportPaths: string[];
     relatedSymbols: string[];
     signatures: AnalysisSignature[];
     members: AnalysisMember[];
+    structuredRows: AnalysisStructuredRow[];
 }
 /***
  * Describes one React component and its extracted props.
@@ -95,6 +99,11 @@ export interface AnalysisSequenceScenario {
     description: string | null;
     isReadme: boolean;
 }
+export interface AnalysisSourceFunction {
+    name: string;
+    description: string | null;
+    sourceLocation: AnalysisSourceLocation;
+}
 interface AnalysisTypeMember {
     name: string;
     type: string;
@@ -141,6 +150,7 @@ export interface AnalysisResult {
     description: string | null;
     exports: AnalysisExport[];
     components: AnalysisComponent[];
+    sourceFunctions: AnalysisSourceFunction[];
     entrypoints: string[];
     modules: AnalysisModule[];
     badges: AnalysisBadge[];

package/dist/analyze/usage.d.ts

@@ -10,4 +10,7 @@ export interface PackageJsonModel {
     eslintConfig?: unknown;
     prettier?: unknown;
 }
+/***
+ * Builds installation and executable usage commands from package metadata.
+ */
 export declare function createUsageFromPackageJson(pkg: PackageJsonModel): AnalysisUsage | null;

package/dist/analyze/usage.js

@@ -1,3 +1,6 @@
+/***
+ * Builds installation and executable usage commands from package metadata.
+ */
 export function createUsageFromPackageJson(pkg) {
     if (pkg.bin == null)
         return null;
@@ -35,6 +38,9 @@ export function createUsageFromPackageJson(pkg) {
         })),
     };
 }
+/***
+ * Extracts the unscoped package name from a package id.
+ */
 function getPackageBaseName(packageName) {
     return packageName.split('/').pop() ?? packageName;
 }

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

@@ -9,4 +9,4 @@ export declare function getExportMetadata(options: {
     root: string;
     entrypointPath: string;
     symbol: MorphSymbol;
-}): Pick<AnalysisExport, 'exportPaths' | 'members' | 'modulePath' | 'relatedSymbols' | 'signatures' | 'sourceLocation'>;
+}): Pick<AnalysisExport, 'exportPaths' | 'members' | 'modulePath' | 'relatedSymbols' | 'signatures' | 'sourceLocation' | 'structuredRows'>;