@ankhorage/paradox 0.0.2 → 0.0.4

package/dist/model/types.d.ts

@@ -0,0 +1,42 @@
+/***
+ * Serializable model consumed by renderers and writers.
+ */
+export interface DocumentationModel {
+    packageName: string;
+    packageId: string;
+    description: string | null;
+    usage: UsageModel | null;
+    config: ConfigModel | null;
+    exports: ExportModel[];
+    components: ComponentModel[];
+}
+export interface UsageModel {
+    packageName: string;
+    commands: UsageCommandModel[];
+}
+export interface UsageCommandModel {
+    name: string;
+    command: string;
+}
+export interface ConfigModel {
+    exportName: string;
+    configFile: string;
+    factoryName: string | null;
+}
+export interface ExportModel {
+    name: string;
+    description: string | null;
+    kind: ExportKind;
+}
+export type ExportKind = 'function' | 'type' | 'unknown';
+export interface ComponentModel {
+    name: string;
+    description: string | null;
+    props: PropModel[];
+}
+export interface PropModel {
+    name: string;
+    type: string;
+    required: boolean;
+    description: string | null;
+}

package/dist/model/types.js

@@ -0,0 +1 @@
+export {};

package/dist/paths/policy.d.ts

@@ -0,0 +1,23 @@
+import type { ParadoxConfig } from '../config/types.js';
+export interface ResolvedRuntimePaths {
+    cwd: string;
+    configFilePath: string;
+    configDir: string;
+    packageRoot: string;
+    outputDir: string;
+    outputRoot: string;
+}
+export declare function findParadoxConfigFile(startDir: string): Promise<string | null>;
+export declare function loadParadoxConfig(configFilePath: string): Promise<ParadoxConfig>;
+export declare function resolvePackageRoot(config: ParadoxConfig, configDir: string): Promise<string>;
+export declare function resolveOutputRoot(config: ParadoxConfig, packageRoot: string): {
+    outputDir: string;
+    outputRoot: string;
+};
+export declare function resolveWriteTargets(packageRoot: string, outputRoot: string): {
+    exportsMarkdown: string;
+    componentsMarkdown: string;
+    exportsJson: string;
+    paradoxJson: string;
+    readme: string;
+};

package/dist/paths/policy.js

@@ -0,0 +1,105 @@
+import { access } from 'node:fs/promises';
+import { dirname, isAbsolute, join, normalize, relative, resolve, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+const CONFIG_FILENAMES = [
+    'paradox.config.ts',
+    'paradox.config.js',
+    'paradox.config.mjs',
+    'paradox.config.cjs',
+];
+export async function findParadoxConfigFile(startDir) {
+    let current = resolve(startDir);
+    let parent = dirname(current);
+    while (parent !== current) {
+        for (const filename of CONFIG_FILENAMES) {
+            const candidate = join(current, filename);
+            if (await pathExists(candidate))
+                return candidate;
+        }
+        current = parent;
+        parent = dirname(current);
+    }
+    for (const filename of CONFIG_FILENAMES) {
+        const candidate = join(current, filename);
+        if (await pathExists(candidate))
+            return candidate;
+    }
+    return null;
+}
+export async function loadParadoxConfig(configFilePath) {
+    const url = pathToFileURL(configFilePath).href;
+    const mod = (await import(url));
+    return mod.default ?? {};
+}
+export async function resolvePackageRoot(config, configDir) {
+    const configuredRoot = config.package?.root;
+    const resolvedRoot = configuredRoot
+        ? isAbsolute(configuredRoot)
+            ? configuredRoot
+            : resolve(configDir, configuredRoot)
+        : resolve(configDir);
+    await assertPathExists(join(resolvedRoot, 'package.json'), `Unable to find package.json at resolved package root: ${resolvedRoot}`);
+    return resolvedRoot;
+}
+export function resolveOutputRoot(config, packageRoot) {
+    const outputDir = config.output?.dir ?? 'paradox';
+    validateOutputDir(outputDir);
+    const outputRoot = resolve(packageRoot, outputDir);
+    assertWithinRoot(outputRoot, packageRoot, `Resolved output directory escapes package root: ${outputRoot}`);
+    return { outputDir, outputRoot };
+}
+export function resolveWriteTargets(packageRoot, outputRoot) {
+    return {
+        exportsMarkdown: join(outputRoot, 'exports.md'),
+        componentsMarkdown: join(outputRoot, 'components.md'),
+        exportsJson: join(outputRoot, 'exports.json'),
+        paradoxJson: join(outputRoot, 'paradox.json'),
+        readme: join(packageRoot, 'README.md'),
+    };
+}
+async function pathExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function assertPathExists(path, message) {
+    if (!(await pathExists(path))) {
+        throw new Error(message);
+    }
+}
+function validateOutputDir(outputDir) {
+    const trimmed = outputDir.trim();
+    if (trimmed.length === 0) {
+        throw new Error('Invalid output.dir: must be a non-empty string.');
+    }
+    const normalized = normalize(trimmed);
+    if (normalized === '.' || normalized === '') {
+        throw new Error('Invalid output.dir: must not be ".".');
+    }
+    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.');
+        }
+    }
+}
+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 !== '.');
+}
+function assertWithinRoot(resolvedPath, root, message) {
+    const rel = relative(root, resolvedPath);
+    if (rel === '')
+        return;
+    if (rel === '..' || rel.startsWith(`..${sep}`)) {
+        throw new Error(message);
+    }
+}

package/dist/render/render.d.ts

@@ -0,0 +1,6 @@
+import type { DocumentationModel } from '../model/types.js';
+import type { RenderResult } from './types.js';
+/***
+ * Renders the documentation model into README and artifact files.
+ */
+export declare function render(model: DocumentationModel): RenderResult;

package/dist/render/render.js

@@ -0,0 +1,95 @@
+/***
+ * Renders the documentation model into README and artifact files.
+ */
+export function render(model) {
+    return {
+        readme: renderReadme(model),
+        exportsMarkdown: renderExports(model),
+        components: renderComponents(model),
+        exportsJson: `${JSON.stringify(model.exports, null, 2)}\n`,
+        paradoxJson: `${JSON.stringify(model, null, 2)}\n`,
+    };
+}
+function renderReadme(model) {
+    const lines = [`# ${model.packageName}`, ''];
+    if (model.description) {
+        lines.push(model.description, '');
+    }
+    if (model.usage !== null) {
+        lines.push('## Usage', '');
+        lines.push('```bash');
+        for (const command of model.usage.commands) {
+            lines.push(command.command);
+        }
+        lines.push('```', '');
+    }
+    if (model.config !== null) {
+        lines.push('## Configuration', '');
+        lines.push(`Create a \`${model.config.configFile}\` file:`, '');
+        lines.push('```ts');
+        if (model.config.factoryName !== null) {
+            lines.push(`import { ${model.config.factoryName} } from '${model.packageId}';`);
+            lines.push('');
+            lines.push(`export default ${model.config.factoryName}({`);
+            lines.push('  // ...');
+            lines.push('});');
+        }
+        else {
+            lines.push(`import type { ${model.config.exportName} } from '${model.packageId}';`);
+            lines.push('');
+            lines.push('const config = {');
+            lines.push('  // ...');
+            lines.push(`} satisfies ${model.config.exportName};`);
+            lines.push('');
+            lines.push('export default config;');
+        }
+        lines.push('```', '');
+    }
+    lines.push('## Path resolution', '');
+    lines.push('- Config discovery: searches upward from `process.cwd()` for `paradox.config.ts/js/mjs/cjs` (required; no fallback).');
+    lines.push('- Package root: defaults to the directory containing `paradox.config.*`; `package.root` (when relative) resolves relative to that directory.');
+    lines.push('- Output directory: defaults to `paradox/`; `output.dir` (when relative) resolves relative to the resolved package root and must stay inside it.');
+    lines.push('- Modes:');
+    lines.push('  - `safe`: writes generated artifacts only under the output directory');
+    lines.push('  - `write`: additionally updates `<packageRoot>/README.md`', '');
+    if (model.exports.length > 0) {
+        lines.push('## Public API', '');
+        for (const item of model.exports) {
+            lines.push(`### ${item.name}`, '');
+            lines.push(item.description ?? `\`${item.kind}\` export.`, '');
+        }
+    }
+    return `${lines.join('\n').trimEnd()}\n`;
+}
+function renderExports(model) {
+    const lines = ['# Public API', ''];
+    for (const item of model.exports) {
+        lines.push(`## ${item.name}`, '');
+        lines.push(`Kind: \`${item.kind}\``, '');
+        if (item.description) {
+            lines.push(item.description, '');
+        }
+    }
+    return `${lines.join('\n').trimEnd()}\n`;
+}
+function renderComponents(model) {
+    const lines = ['# Components', ''];
+    for (const component of model.components) {
+        lines.push(`## ${component.name}`, '');
+        if (component.description) {
+            lines.push(component.description, '');
+        }
+        if (component.props.length > 0) {
+            lines.push('| Prop | Type | Required | Description |');
+            lines.push('| --- | --- | --- | --- |');
+            for (const prop of component.props) {
+                lines.push(`| ${escapeTableCell(prop.name)} | \`${escapeTableCell(prop.type)}\` | ${prop.required ? 'yes' : 'no'} | ${escapeTableCell(prop.description ?? '')} |`);
+            }
+            lines.push('');
+        }
+    }
+    return `${lines.join('\n').trimEnd()}\n`;
+}
+function escapeTableCell(value) {
+    return value.replaceAll('|', '\\|');
+}

package/dist/render/types.d.ts

@@ -0,0 +1,10 @@
+/***
+ * Rendered documentation files ready to be written to disk.
+ */
+export interface RenderResult {
+    readme: string;
+    exportsMarkdown: string;
+    components: string;
+    exportsJson: string;
+    paradoxJson: string;
+}

package/dist/render/types.js

@@ -0,0 +1 @@
+export {};

package/dist/write/write.d.ts

@@ -0,0 +1,9 @@
+import type { ParadoxConfig } from '../config/types.js';
+import type { RenderResult } from '../render/types.js';
+/***
+ * Writes generated documentation artifacts to the configured output paths.
+ */
+export declare function write(result: RenderResult, config: ParadoxConfig, runtime: {
+    packageRoot: string;
+    outputRoot: string;
+}): Promise<void>;

package/dist/write/write.js

@@ -0,0 +1,18 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/***
+ * Writes generated documentation artifacts to the configured output paths.
+ */
+export async function write(result, config, runtime) {
+    const root = runtime.packageRoot;
+    const { outputRoot } = runtime;
+    const mode = config.mode ?? 'safe';
+    await mkdir(outputRoot, { recursive: true });
+    await writeFile(join(outputRoot, 'exports.md'), result.exportsMarkdown);
+    await writeFile(join(outputRoot, 'components.md'), result.components);
+    await writeFile(join(outputRoot, 'exports.json'), result.exportsJson);
+    await writeFile(join(outputRoot, 'paradox.json'), result.paradoxJson);
+    if (mode === 'write') {
+        await writeFile(join(root, 'README.md'), result.readme);
+    }
+}

package/package.json

@@ -1,17 +1,40 @@
 {
   "name": "@ankhorage/paradox",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Deterministic documentation generator for TypeScript packages.",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
+  "homepage": "https://github.com/ankhorage/paradox#readme",
+  "bugs": {
+    "url": "https://github.com/ankhorage/paradox/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ankhorage/paradox.git"
+  },
   "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
   "bin": {
-    "paradox": "./src/cli.ts"
+    "paradox": "./dist/cli.js"
   },
   "scripts": {
-    "build": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json",
     "changeset": "changeset",
     "changeset:status": "changeset status --since=origin/main",
     "docs": "bun src/cli.ts",
@@ -20,6 +43,7 @@
     "format:check": "prettier --check .",
     "lint": "eslint . --max-warnings=0",
     "lint:fix": "eslint . --fix --max-warnings=0",
+    "prepack": "bun run build",
     "test": "bun test",
     "typecheck": "bun x tsc --noEmit -p tsconfig.json",
     "version-packages": "changeset version"

package/.changeset/README.md

@@ -1,5 +0,0 @@
-# Changesets
-
-This directory stores release notes consumed by Changesets.
-
-Run `bun run changeset` to create a new changeset before publishing a package change.

package/.changeset/config.json

@@ -1,11 +0,0 @@
-{
-  "$schema": "https://unpkg.com/@changesets/config@3.1.3/schema.json",
-  "changelog": "@changesets/cli/changelog",
-  "commit": false,
-  "fixed": [],
-  "linked": [],
-  "access": "public",
-  "baseBranch": "main",
-  "updateInternalDependencies": "patch",
-  "ignore": []
-}

package/.changeset/stable-usage-model.md

@@ -1,5 +0,0 @@
----
-'@ankhorage/paradox': patch
----
-
-Stabilize usage metadata, documentation model serialization, and deterministic output ordering.

package/.github/workflows/docs.yml

@@ -1,45 +0,0 @@
-name: CI
-
-on:
-  pull_request:
-  push:
-    branches:
-      - main
-
-jobs:
-  validate:
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: '1.3.11'
-
-      - name: Install dependencies
-        run: bun install --frozen-lockfile
-
-      - name: Run lint
-        run: bun run lint
-
-      - name: Check formatting
-        run: bun run format:check
-
-      - name: Run typecheck
-        run: bun run typecheck
-
-      - name: Run tests
-        run: bun run test
-
-      - name: Check changesets
-        if: github.event_name == 'pull_request'
-        run: bun run changeset:status
-
-      - name: Generate docs
-        run: bun run docs
-
-      - name: Check generated docs
-        run: git diff --exit-code

package/.prettierignore

@@ -1 +0,0 @@
-tests/__snapshots__/*.md

package/.prettierrc.js

@@ -1,5 +0,0 @@
-import { createRequire } from 'node:module';
-
-const require = createRequire(import.meta.url);
-
-export default require('@ankhorage/devtools/prettier');