@ankhorage/paradox 0.1.21 → 0.1.22

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.1.22
+
+### Patch Changes
+
+- 125eac9: Add opt-in GitHub Sponsors support from a single root-level `donation.account` config, including generated Donation documentation and `.github/FUNDING.yml` handling.
+
 ## 0.1.21
 
 ### Patch Changes

package/README.md

@@ -3,7 +3,7 @@
 
 # @ankhorage/paradox
 
-![license: MIT](./paradox/badges/license.svg) ![npm: v0.1.21](./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.22](./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.
 
@@ -70,6 +70,10 @@ import { defineParadoxConfig } from './src/config/defineParadoxConfig.js';
 export default defineParadoxConfig({
   mode: 'write',
 
+  donation: {
+    account: 'ankhorage',
+  },
+
   docs: {
     title: '@ankhorage/paradox',
     description: 'Deterministic documentation generator for TypeScript packages.',
@@ -88,12 +92,13 @@ export default defineParadoxConfig({
 <details>
 <summary>Configuration options</summary>
 
-| Field   | Type                                                                                                                | Required | Default | Description |
-| ------- | ------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ----------- |
-| mode    | `'safe' \| 'write' \| undefined`                                                                                    | no       | —       |             |
-| docs    | `{ title?: string; description?: string; usage?: { description?: string; entrypoints?: string[]; }; } \| undefined` | no       | —       |             |
-| package | `{ root?: string; entrypoints?: string[]; } \| undefined`                                                           | no       | —       |             |
-| output  | `{ dir?: string; } \| undefined`                                                                                    | no       | —       |             |
+| Field    | Type                                                                                                                | Required | Default | Description |
+| -------- | ------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ----------- |
+| mode     | `'safe' \| 'write' \| undefined`                                                                                    | no       | —       |             |
+| donation | `{ account: string; } \| undefined`                                                                                 | no       | —       |             |
+| docs     | `{ title?: string; description?: string; usage?: { description?: string; entrypoints?: string[]; }; } \| undefined` | no       | —       |             |
+| package  | `{ root?: string; entrypoints?: string[]; } \| undefined`                                                           | no       | —       |             |
+| output   | `{ dir?: string; } \| undefined`                                                                                    | no       | —       |             |
 
 </details>
 
@@ -136,3 +141,9 @@ Module: `src/config/types.ts`
 Source: `src/config/types.ts:7:1`
 
 </details>
+
+## Donation
+
+If this project is useful to you, you can support its continued development.
+
+[Support @ankhorage](https://github.com/sponsors/ankhorage)

package/dist/analyze/analyze.js

@@ -1,5 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { validateDonationAccount } from '../config/utils/validateDonationAccount.js';
 import { analyzeBadges } from './badges.js';
 import { analyzeComponents } from './components.js';
 import { analyzeExports } from './exports.js';
@@ -20,6 +21,9 @@ import { createUsageFromPackageJson } from './usage.js';
 export async function analyze(config, runtime) {
     const root = runtime.packageRoot;
     const pkg = await readPackageJson(root);
+    const donation = config.donation === undefined
+        ? null
+        : { account: validateDonationAccount(config.donation.account) };
     const usage = createUsageFromPackageJson(pkg);
     const badges = await analyzeBadges(root, pkg);
     const project = createProject(root);
@@ -67,6 +71,7 @@ export async function analyze(config, runtime) {
         packageName: config.docs?.title ?? pkg.name,
         packageId: pkg.name,
         description: config.docs?.description ?? pkg.description ?? null,
+        donation,
         exports,
         components,
         sourceFunctions,

package/dist/analyze/types.d.ts

@@ -75,6 +75,9 @@ export interface AnalysisUsage {
     packageName: string;
     commands: AnalysisUsageCommand[];
 }
+interface AnalysisDonation {
+    account: string;
+}
 interface AnalysisUsageCommand {
     name: string;
     command: string;
@@ -165,6 +168,7 @@ export interface AnalysisResult {
     packageName: string;
     packageId: string;
     description: string | null;
+    donation: AnalysisDonation | null;
     exports: AnalysisExport[];
     components: AnalysisComponent[];
     sourceFunctions: AnalysisSourceFunction[];

package/dist/config/types.d.ts

@@ -6,6 +6,11 @@
  */
 export interface ParadoxConfig {
     mode?: 'safe' | 'write';
+    /** Enables canonical GitHub Sponsors integration for generated repository documentation. */
+    donation?: {
+        /** GitHub Sponsors account login used for the Sponsor button and Donation chapter. */
+        account: string;
+    };
     docs?: {
         title?: string;
         description?: string;

package/dist/config/utils/validateDonationAccount.d.ts

@@ -0,0 +1 @@
+export declare function validateDonationAccount(account: string): string;

package/dist/config/utils/validateDonationAccount.js

@@ -0,0 +1,7 @@
+export function validateDonationAccount(account) {
+    if (!githubAccountPattern.test(account)) {
+        throw new Error(`Invalid donation account "${account}". Expected a GitHub account login containing only alphanumeric characters or single hyphens.`);
+    }
+    return account;
+}
+const githubAccountPattern = /^(?!-)(?!.*--)[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?$/;

package/dist/model/buildModel.d.ts

@@ -27,6 +27,9 @@ interface BuildModelInput {
     packageName: string;
     packageId: string;
     description: string | null;
+    donation: {
+        account: string;
+    } | null;
     badges: {
         id: string;
         label: string;

package/dist/model/buildModel.js

@@ -9,6 +9,7 @@ export function buildModel(analysis) {
         packageName: analysis.packageName,
         packageId: analysis.packageId,
         description: analysis.description,
+        donation: analysis.donation === null ? null : { account: analysis.donation.account },
         badges: analysis.badges.map((badge) => ({
             id: badge.id,
             label: badge.label,

package/dist/model/types.d.ts

@@ -5,6 +5,7 @@ export interface DocumentationModel {
     packageName: string;
     packageId: string;
     description: string | null;
+    donation: DonationModel | null;
     badges: GeneratedBadge[];
     usage: UsageModel | null;
     readmeUsageDescription: string | null;
@@ -20,6 +21,9 @@ export interface DocumentationModel {
     sequenceScenarios: SequenceScenarioModel[];
     graphs: GraphModel;
 }
+interface DonationModel {
+    account: string;
+}
 export interface GeneratedBadge {
     id: string;
     label: string;

package/dist/render/render.js

@@ -1,5 +1,7 @@
 import { renderBadgeArtifacts } from './renderers/badges.js';
 import { renderDiagramArtifacts } from './renderers/diagrams.js';
+import { renderDonation } from './renderers/donation.js';
+import { renderFundingYaml } from './renderers/funding.js';
 import { renderHtml } from './renderers/html.js';
 import { renderMarkdown } from './renderers/markdown.js';
 /***
@@ -16,6 +18,7 @@ export function render(model, options = {}) {
         exportsJson: `${JSON.stringify(model.exports, null, 2)}\n`,
         paradoxJson: `${JSON.stringify(model, null, 2)}\n`,
         indexHtml: '',
+        fundingYaml: renderFundingYaml(model),
         badges,
         diagrams,
     };
@@ -29,5 +32,6 @@ export function render(model, options = {}) {
     for (const renderer of [renderMarkdown, renderHtml]) {
         Object.assign(result, renderer(context));
     }
+    Object.assign(result, renderDonation(context));
     return result;
 }

package/dist/render/renderers/donation.d.ts

@@ -0,0 +1,2 @@
+import type { RenderContext } from '../types.js';
+export declare function renderDonation(context: RenderContext): Pick<RenderContext['result'], 'indexHtml' | 'readme'>;

package/dist/render/renderers/donation.js

@@ -0,0 +1,30 @@
+export function renderDonation(context) {
+    const { donation } = context.model;
+    if (donation === null) {
+        return { indexHtml: context.result.indexHtml, readme: context.result.readme };
+    }
+    const { account } = donation;
+    return {
+        readme: renderDonationReadme(context.result.readme, account),
+        indexHtml: renderDonationHtml(context.result.indexHtml, account),
+    };
+}
+function renderDonationHtml(indexHtml, account) {
+    const mainEnd = indexHtml.indexOf('\n      </main>');
+    const homeStart = indexHtml.indexOf('<section id="view-home"');
+    const homeEnd = indexHtml.lastIndexOf('\n        </section>', mainEnd);
+    if (mainEnd < 0 || homeStart < 0 || homeEnd < homeStart) {
+        throw new Error('Unable to locate Paradox HTML home view for Donation rendering.');
+    }
+    const panel = [
+        '          <section class="panel" data-search="donation sponsor support">',
+        '            <h2>Donation</h2>',
+        '            <p>If this project is useful to you, you can support its continued development.</p>',
+        `            <p><a href="https://github.com/sponsors/${account}">Support @${account}</a></p>`,
+        '          </section>',
+    ].join('\n');
+    return `${indexHtml.slice(0, homeEnd)}\n${panel}${indexHtml.slice(homeEnd)}`;
+}
+function renderDonationReadme(readme, account) {
+    return `${readme.trimEnd()}\n\n## Donation\n\nIf this project is useful to you, you can support its continued development.\n\n[Support @${account}](https://github.com/sponsors/${account})\n`;
+}

package/dist/render/renderers/funding.d.ts

@@ -0,0 +1,2 @@
+import type { DocumentationModel } from '../../model/types.js';
+export declare function renderFundingYaml(model: DocumentationModel): string | null;

package/dist/render/renderers/funding.js

@@ -0,0 +1,9 @@
+export function renderFundingYaml(model) {
+    if (model.donation === null)
+        return null;
+    return [
+        '# Generated by Paradox. Do not edit manually.',
+        `github: ${model.donation.account}`,
+        '',
+    ].join('\n');
+}

package/dist/render/types.d.ts

@@ -18,6 +18,7 @@ export interface RenderResult {
     exportsJson: string;
     paradoxJson: string;
     indexHtml: string;
+    fundingYaml: string | null;
     diagrams: DiagramArtifact[];
     badges: BadgeArtifact[];
 }

package/dist/write/utils/syncFundingFileAsync.d.ts

@@ -0,0 +1 @@
+export declare function syncFundingFileAsync(packageRoot: string, fundingYaml: string | null): Promise<void>;

package/dist/write/utils/syncFundingFileAsync.js

@@ -0,0 +1,30 @@
+import { mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+export async function syncFundingFileAsync(packageRoot, fundingYaml) {
+    const fundingPath = join(packageRoot, '.github', 'FUNDING.yml');
+    const existing = await readFundingFileAsync(fundingPath);
+    if (fundingYaml === null) {
+        if (existing !== null && isParadoxOwnedFunding(existing))
+            await unlink(fundingPath);
+        return;
+    }
+    if (existing !== null && !isParadoxOwnedFunding(existing)) {
+        throw new Error('Refusing to overwrite existing non-Paradox .github/FUNDING.yml.');
+    }
+    await mkdir(dirname(fundingPath), { recursive: true });
+    await writeFile(fundingPath, fundingYaml);
+}
+const generatedFundingMarker = '# Generated by Paradox. Do not edit manually.';
+function isParadoxOwnedFunding(content) {
+    return content.startsWith(`${generatedFundingMarker}\n`);
+}
+async function readFundingFileAsync(path) {
+    try {
+        return await readFile(path, 'utf-8');
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}

package/dist/write/write.js

@@ -1,5 +1,6 @@
 import { mkdir, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
+import { syncFundingFileAsync } from './utils/syncFundingFileAsync.js';
 /***
  * Writes generated documentation artifacts to the configured output paths.
  */
@@ -25,5 +26,6 @@ export async function write(result, config, runtime) {
     }
     if (mode === 'write') {
         await writeFile(join(root, 'README.md'), result.readme);
+        await syncFundingFileAsync(root, result.fundingYaml);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/paradox",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "description": "Deterministic documentation generator for TypeScript packages.",
   "license": "MIT",
   "publishConfig": {