@ankhorage/paradox 0.0.3 → 0.0.5

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.0.5
+
+### Patch Changes
+
+- 859c537: Standardize CI/release workflow files and update the Bun tooling baseline.
+
+## 0.0.4
+
+### Patch Changes
+
+- f5b89ce: Stabilize Paradox config discovery and output path resolution so generated artifacts are written under the resolved package output directory.
+
 ## 0.0.3
 
 ### Patch Changes

package/README.md

@@ -20,6 +20,15 @@ export default defineParadoxConfig({
 });
 ```
 
+## Path resolution
+
+- Config discovery: searches upward from `process.cwd()` for `paradox.config.ts/js/mjs/cjs` (required; no fallback).
+- Package root: defaults to the directory containing `paradox.config.*`; `package.root` (when relative) resolves relative to that directory.
+- Output directory: defaults to `paradox/`; `output.dir` (when relative) resolves relative to the resolved package root and must stay inside it.
+- Modes:
+  - `safe`: writes generated artifacts only under the output directory
+  - `write`: additionally updates `<packageRoot>/README.md`
+
 ## Public API
 
 ### defineParadoxConfig

package/dist/analyze/analyze.d.ts

@@ -3,4 +3,6 @@ import type { AnalysisResult } from './types.js';
 /***
  * Runs the source analysis pipeline for a configured package.
  */
-export declare function analyze(config: ParadoxConfig): Promise<AnalysisResult>;
+export declare function analyze(config: ParadoxConfig, runtime: {
+    packageRoot: string;
+}): Promise<AnalysisResult>;

package/dist/analyze/analyze.js

@@ -7,8 +7,8 @@ import { createUsageFromPackageJson } from './usage.js';
 /***
  * Runs the source analysis pipeline for a configured package.
  */
-export async function analyze(config) {
-    const root = config.package?.root ?? process.cwd();
+export async function analyze(config, runtime) {
+    const root = runtime.packageRoot;
     const pkg = await readPackageJson(root);
     const usage = createUsageFromPackageJson(pkg);
     const project = createProject(root);

package/dist/cli.js

@@ -1,21 +1,24 @@
 #!/usr/bin/env bun
-import { join } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { dirname } from 'node:path';
 import { analyze } from './analyze/analyze.js';
 import { buildModel } from './model/buildModel.js';
+import { findParadoxConfigFile, loadParadoxConfig, resolveOutputRoot, resolvePackageRoot, } from './paths/policy.js';
 import { render } from './render/render.js';
 import { write } from './write/write.js';
 async function main() {
-    const config = await loadConfig(process.cwd());
-    const analysis = await analyze(config);
+    const cwd = process.cwd();
+    const configFilePath = await findParadoxConfigFile(cwd);
+    if (!configFilePath) {
+        throw new Error(`Unable to find Paradox config. Looked for paradox.config.{ts,js,mjs,cjs} by searching upward from: ${cwd}`);
+    }
+    const configDir = dirname(configFilePath);
+    const config = await loadParadoxConfig(configFilePath);
+    const packageRoot = await resolvePackageRoot(config, configDir);
+    const { outputRoot } = resolveOutputRoot(config, packageRoot);
+    const analysis = await analyze(config, { packageRoot });
     const model = buildModel(analysis);
     const result = render(model);
-    await write(result, config);
-}
-async function loadConfig(root) {
-    const configUrl = pathToFileURL(join(root, 'paradox.config.ts')).href;
-    const mod = (await import(configUrl));
-    return mod.default ?? {};
+    await write(result, config, { packageRoot, outputRoot });
 }
 main().catch((error) => {
     console.error(error);

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.js

@@ -45,6 +45,13 @@ function renderReadme(model) {
         }
         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) {

package/dist/write/write.d.ts

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

package/dist/write/write.js

@@ -3,15 +3,15 @@ import { join } from 'node:path';
 /***
  * Writes generated documentation artifacts to the configured output paths.
  */
-export async function write(result, config) {
-    const root = config.package?.root ?? process.cwd();
-    const outputDir = config.output?.dir ?? 'paradox';
+export async function write(result, config, runtime) {
+    const root = runtime.packageRoot;
+    const { outputRoot } = runtime;
     const mode = config.mode ?? 'safe';
-    await mkdir(join(root, outputDir), { recursive: true });
-    await writeFile(join(root, outputDir, 'exports.md'), result.exportsMarkdown);
-    await writeFile(join(root, outputDir, 'components.md'), result.components);
-    await writeFile(join(root, outputDir, 'exports.json'), result.exportsJson);
-    await writeFile(join(root, outputDir, 'paradox.json'), result.paradoxJson);
+    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,6 +1,6 @@
 {
   "name": "@ankhorage/paradox",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "Deterministic documentation generator for TypeScript packages.",
   "license": "MIT",
   "publishConfig": {
@@ -54,7 +54,8 @@
   "devDependencies": {
     "@ankhorage/devtools": "^1.0.0",
     "@changesets/cli": "^2.31.0",
-    "@types/bun": "^1.1.14",
+    "@types/bun": "^1.3.13",
     "typescript": "^5.6.3"
-  }
+  },
+  "packageManager": "bun@1.3.13"
 }