@ankhorage/paradox 0.2.23 → 0.2.25

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.2.25
+
+### Patch Changes
+
+- 70d72a8: Stop rendering paradox.config.ts as the documented package's README configuration example; configuration docs now come only from the package-owned @config schema.
+
+## 0.2.24
+
+### Patch Changes
+
+- 9c1050d: Update Ankhorage dependencies: `@ankhorage/utility`.
+
 ## 0.2.23
 
 ### Patch Changes

package/README.md

@@ -3,7 +3,7 @@
 
 # @ankhorage/paradox
 
-![license: MIT](./paradox/badges/license.svg) ![npm: v0.2.23](./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) ![paradox: canonical](./paradox/badges/docs.svg)
+![license: MIT](./paradox/badges/license.svg) ![npm: v0.2.25](./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) ![paradox: canonical](./paradox/badges/docs.svg)
 
 Deterministic documentation generator for TypeScript packages.
 
@@ -40,30 +40,6 @@ export const basicConfig = defineParadoxConfig({
 
 Configures Paradox documentation generation for a package.
 
-### Example
-
-```ts
-import { defineParadoxConfig } from './src/config/defineParadoxConfig.js';
-
-export default defineParadoxConfig({
-  mode: 'write',
-
-  collaborators: true,
-
-  donation: {
-    account: 'ankhorage',
-  },
-
-  package: {
-    entrypoints: ['src/index.ts'],
-  },
-
-  output: {
-    dir: 'paradox',
-  },
-});
-```
-
 <details>
 <summary>Configuration options</summary>
 

package/dist/analyze/analyze.d.ts

@@ -5,5 +5,4 @@ import type { AnalysisResult } from './types.js';
  */
 export declare function analyze(config: ParadoxConfig, runtime: {
     packageRoot: string;
-    configFilePath?: string;
 }): Promise<AnalysisResult>;

package/dist/analyze/analyze.js

@@ -11,7 +11,6 @@ import { validateDocumentationPolicyAsync } from './documentation/validateDocume
 import { analyzeExports } from './exports.js';
 import { analyzeModules } from './modules.js';
 import { createProject } from './project.js';
-import { analyzeReadmeConfig } from './readmeConfig.js';
 import { analyzeReadmeUsage, countExampleDirectoriesAsync } from './readmeUsage.js';
 import { createTypeScriptProgram } from './semantic/createTypeScriptProgram.js';
 import { collectTypeMembers, resolveTypeReference } from './semantic/exports.js';
@@ -41,9 +40,6 @@ export async function analyze(config, runtime) {
     const usageEntries = await analyzeReadmeUsage({ root });
     const exampleCount = await countExampleDirectoriesAsync(root);
     const comments = await collectDocumentationCommentsAsync(root);
-    const readmeConfig = configMetadata?.isReadme === true
-        ? await analyzeReadmeConfig({ root, configFilePath: runtime.configFilePath ?? null })
-        : null;
     const configMembers = collectConfigMembers(program, exports, configMetadata);
     const graphs = {
         imports: collectImportGraph(program),
@@ -80,7 +76,6 @@ export async function analyze(config, runtime) {
         usageEntries,
         exampleCount,
         findings,
-        readmeConfig,
         config: configMetadata === null
             ? null
             : {

package/dist/analyze/types.d.ts

@@ -95,11 +95,6 @@ export interface AnalysisDocumentationFinding {
 interface AnalysisDonation {
     account: string;
 }
-interface AnalysisReadmeConfig {
-    language: string;
-    code: string;
-    sourcePath: string;
-}
 export interface AnalysisBadge {
     id: string;
     label: string;
@@ -184,7 +179,6 @@ export interface AnalysisResult {
     usageEntries: AnalysisUsageEntry[];
     exampleCount: number;
     findings: AnalysisDocumentationFinding[];
-    readmeConfig: AnalysisReadmeConfig | null;
     config: {
         exportName: string;
         title: string | null;

package/dist/cli/standalone.js

@@ -22,7 +22,7 @@ async function main() {
     const config = await loadParadoxConfig(configFilePath);
     const packageRoot = await resolvePackageRoot(config, configDir);
     const { outputDir, outputRoot } = resolveOutputRoot(config, packageRoot);
-    const analysis = await analyze(config, { packageRoot, configFilePath });
+    const analysis = await analyze(config, { packageRoot });
     assertNoDocumentationErrors(analysis.findings);
     const model = buildModel(analysis);
     const result = render(model, { outputDir });

package/dist/model/buildModel.d.ts

@@ -127,11 +127,6 @@ interface BuildModelInput {
         sourcePath: string | null;
         line: number | null;
     }[];
-    readmeConfig: {
-        language: string;
-        code: string;
-        sourcePath: string;
-    } | null;
     config: {
         exportName: string;
         title: string | null;

package/dist/model/buildModel.js

@@ -17,7 +17,6 @@ export function buildModel(analysis) {
             .sort((left, right) => left.sourcePath.localeCompare(right.sourcePath)),
         exampleCount: analysis.exampleCount,
         findings: analysis.findings.map((finding) => ({ ...finding })),
-        readmeConfig: analysis.readmeConfig === null ? null : { ...analysis.readmeConfig },
         config: analysis.config === null
             ? null
             : {

package/dist/model/types.d.ts

@@ -13,7 +13,6 @@ export interface DocumentationModel {
     usageEntries: UsageEntryModel[];
     exampleCount: number;
     findings: DocumentationFindingModel[];
-    readmeConfig: ReadmeConfigModel | null;
     config: ConfigModel | null;
     entrypoints: string[];
     modules: ModuleModel[];
@@ -54,11 +53,6 @@ interface DocumentationFindingModel {
     sourcePath: string | null;
     line: number | null;
 }
-interface ReadmeConfigModel {
-    language: string;
-    code: string;
-    sourcePath: string;
-}
 interface ConfigModel {
     exportName: string;
     title: string | null;

package/dist/render/renderers/markdown.js

@@ -85,29 +85,20 @@ function getPackageDisplayName(packageId) {
     return packageId.split('/').pop() ?? packageId;
 }
 /***
- * Renders the canonical Configuration chapter from the tagged schema plus concrete config instance.
+ * Renders the package-owned Configuration chapter from the canonical tagged schema.
  */
 function renderConfiguration(lines, model) {
     const config = model.config?.isReadme ? model.config : null;
-    const example = model.readmeConfig;
-    if (config === null && example === null)
+    if (config === null)
         return;
     lines.push('## Configuration', '');
-    if (config !== null) {
-        if (config.title !== null && config.title !== 'Configuration') {
-            lines.push(`### ${config.title}`, '');
-        }
-        if (config.description !== null)
-            lines.push(config.description, '');
-        renderReferences(lines, config);
-    }
-    if (example !== null) {
-        lines.push('### Example', '');
-        lines.push('```' + example.language);
-        lines.push(example.code);
-        lines.push('```', '');
+    if (config.title !== null && config.title !== 'Configuration') {
+        lines.push(`### ${config.title}`, '');
     }
-    if (config === null || config.members.length === 0)
+    if (config.description !== null)
+        lines.push(config.description, '');
+    renderReferences(lines, config);
+    if (config.members.length === 0)
         return;
     lines.push('<details>');
     lines.push('<summary>Configuration options</summary>', '');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/paradox",
-  "version": "0.2.23",
+  "version": "0.2.25",
   "description": "Deterministic documentation generator for TypeScript packages.",
   "license": "MIT",
   "publishConfig": {
@@ -72,7 +72,7 @@
   },
   "dependencies": {
     "@ankhorage/policy": "^0.6.0",
-    "@ankhorage/utility": "^1.9.54",
+    "@ankhorage/utility": "^1.9.61",
     "ts-morph": "^28.0.0"
   },
   "devDependencies": {

package/dist/analyze/readmeConfig.d.ts

@@ -1,12 +0,0 @@
-export interface AnalysisReadmeConfig {
-    language: string;
-    code: string;
-    sourcePath: string;
-}
-/***
- * Collects the concrete Paradox configuration instance as a README configuration example.
- */
-export declare function analyzeReadmeConfig(options: {
-    root: string;
-    configFilePath: string | null;
-}): Promise<AnalysisReadmeConfig | null>;

package/dist/analyze/readmeConfig.js

@@ -1,28 +0,0 @@
-import { readFile } from 'node:fs/promises';
-import { extname, relative } from 'node:path';
-import { toPortablePath } from '@ankhorage/utility/node/path';
-/***
- * Collects the concrete Paradox configuration instance as a README configuration example.
- */
-export async function analyzeReadmeConfig(options) {
-    if (options.configFilePath === null)
-        return null;
-    const source = await readFile(options.configFilePath, 'utf-8');
-    const sourcePath = toPortablePath(relative(options.root, options.configFilePath));
-    return {
-        language: getLanguage(sourcePath),
-        code: source.trim(),
-        sourcePath,
-    };
-}
-/***
- * Returns the Markdown fence language for a configuration source path.
- */
-function getLanguage(sourcePath) {
-    const extension = extname(sourcePath).toLowerCase();
-    if (extension === '.ts')
-        return 'ts';
-    if (extension === '.js' || extension === '.mjs' || extension === '.cjs')
-        return 'js';
-    return '';
-}