@ankhorage/paradox 0.1.23 → 0.1.25

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.1.25
+
+### Patch Changes
+
+- e377b70: Update docs & add changeset
+
+## 0.1.24
+
+### Patch Changes
+
+- 95b08c8: Add opt-in Collaborators README and managed workflow generation through the root-level `collaborators` configuration.
+
 ## 0.1.23
 
 ### Patch Changes

package/README.md

@@ -3,7 +3,7 @@
 
 # @ankhorage/paradox
 
-![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)
+![license: MIT](./paradox/badges/license.svg) ![npm: v0.1.24](./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,8 @@ import { defineParadoxConfig } from './src/config/defineParadoxConfig.js';
 export default defineParadoxConfig({
   mode: 'write',
 
+  collaborators: true,
+
   donation: {
     account: 'ankhorage',
   },
@@ -92,13 +94,14 @@ export default defineParadoxConfig({
 <details>
 <summary>Configuration options</summary>
 
-| 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       | —       |             |
+| Field         | Type                                                                                                                | Required | Default | Description |
+| ------------- | ------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ----------- |
+| mode          | `'safe' \| 'write' \| undefined`                                                                                    | no       | —       |             |
+| collaborators | `true \| 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>
 
@@ -142,6 +145,11 @@ Source: `src/config/types.ts:7:1`
 
 </details>
 
+## Collaborators
+
+<!-- readme: collaborators -start -->
+<!-- readme: collaborators -end -->
+
 ## Donation
 
 If this project is useful to you, you can support its continued development.

package/dist/analyze/analyze.js

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

package/dist/analyze/types.d.ts

@@ -168,6 +168,7 @@ export interface AnalysisResult {
     packageName: string;
     packageId: string;
     description: string | null;
+    collaborators: true | null;
     donation: AnalysisDonation | null;
     exports: AnalysisExport[];
     components: AnalysisComponent[];

package/dist/config/types.d.ts

@@ -6,6 +6,8 @@
  */
 export interface ParadoxConfig {
     mode?: 'safe' | 'write';
+    /** Enables canonical direct-collaborator documentation and workflow integration. */
+    collaborators?: true;
     /** Enables canonical GitHub Sponsors integration for generated repository documentation. */
     donation?: {
         /** GitHub Sponsors account login used for the Sponsor button and Donation chapter. */

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

@@ -0,0 +1 @@
+export declare function validateCollaborators(value: unknown): true | null;

package/dist/config/utils/validateCollaborators.js

@@ -0,0 +1,7 @@
+export function validateCollaborators(value) {
+    if (value === undefined)
+        return null;
+    if (value === true)
+        return true;
+    throw new Error('Invalid collaborators config. Expected literal true or omission.');
+}

package/dist/model/buildModel.d.ts

@@ -27,6 +27,7 @@ interface BuildModelInput {
     packageName: string;
     packageId: string;
     description: string | null;
+    collaborators: true | null;
     donation: {
         account: string;
     } | null;

package/dist/model/buildModel.js

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

package/dist/model/types.d.ts

@@ -5,6 +5,7 @@ export interface DocumentationModel {
     packageName: string;
     packageId: string;
     description: string | null;
+    collaborators: true | null;
     donation: DonationModel | null;
     badges: GeneratedBadge[];
     usage: UsageModel | null;

package/dist/render/render.js

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

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

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

package/dist/render/renderers/collaborators.js

@@ -0,0 +1,51 @@
+export function renderCollaborators(context) {
+    if (context.model.collaborators === null) {
+        return {
+            collaboratorsWorkflowYaml: null,
+            readme: context.result.readme,
+        };
+    }
+    return {
+        collaboratorsWorkflowYaml: renderCollaboratorsWorkflowYaml(),
+        readme: renderCollaboratorsReadme(context.result.readme),
+    };
+}
+// Upgrade both values together only after verifying the Marketplace release and immutable tag SHA.
+const actionCommit = '83ea0b4f1ac928fbfe88b9e8460a932a528eb79f';
+const actionVersion = 'v2.3.11';
+const collaboratorsMarkers = [
+    '<!-- readme: collaborators -start -->',
+    '<!-- readme: collaborators -end -->',
+].join('\n');
+function renderCollaboratorsReadme(readme) {
+    return `${readme.trimEnd()}\n\n## Collaborators\n\n${collaboratorsMarkers}\n`;
+}
+function renderCollaboratorsWorkflowYaml() {
+    return [
+        '# Generated by Paradox. Do not edit manually.',
+        'name: Update collaborators',
+        '',
+        'on:',
+        '  schedule:',
+        "    - cron: '17 3 * * 1'",
+        '  workflow_dispatch:',
+        '',
+        'permissions:',
+        '  contents: write',
+        '  pull-requests: write',
+        '',
+        'jobs:',
+        '  collaborators:',
+        '    name: Update collaborators',
+        '    runs-on: ubuntu-latest',
+        '    steps:',
+        '      - name: Update collaborators',
+        `        uses: akhilmhdh/contributors-readme-action@${actionCommit} # ${actionVersion}`,
+        '        with:',
+        '          readme_path: README.md',
+        '          collaborators: direct',
+        '        env:',
+        '          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}',
+        '',
+    ].join('\n');
+}

package/dist/render/types.d.ts

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

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

@@ -0,0 +1,3 @@
+export declare function syncCollaboratorsWorkflowAsync(packageRoot: string, workflowYaml: string | null, options?: {
+    mode?: 'check' | 'write';
+}): Promise<void>;

package/dist/write/utils/syncCollaboratorsWorkflowAsync.js

@@ -0,0 +1,34 @@
+import { mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+export async function syncCollaboratorsWorkflowAsync(packageRoot, workflowYaml, options = {}) {
+    const workflowPath = join(packageRoot, '.github', 'workflows', 'collaborators.yml');
+    const existing = await readCollaboratorsWorkflowAsync(workflowPath);
+    const mode = options.mode ?? 'write';
+    if (workflowYaml === null) {
+        if (mode === 'write' && existing !== null && isParadoxOwnedCollaboratorsWorkflow(existing)) {
+            await unlink(workflowPath);
+        }
+        return;
+    }
+    if (existing !== null && !isParadoxOwnedCollaboratorsWorkflow(existing)) {
+        throw new Error('Refusing to overwrite existing non-Paradox .github/workflows/collaborators.yml.');
+    }
+    if (mode === 'check')
+        return;
+    await mkdir(dirname(workflowPath), { recursive: true });
+    await writeFile(workflowPath, workflowYaml);
+}
+const generatedWorkflowMarker = '# Generated by Paradox. Do not edit manually.';
+function isParadoxOwnedCollaboratorsWorkflow(content) {
+    return content.split(/\r?\n/, 1)[0] === generatedWorkflowMarker;
+}
+async function readCollaboratorsWorkflowAsync(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 { syncCollaboratorsWorkflowAsync } from './utils/syncCollaboratorsWorkflowAsync.js';
 import { syncFundingFileAsync } from './utils/syncFundingFileAsync.js';
 /***
  * Writes generated documentation artifacts to the configured output paths.
@@ -8,6 +9,11 @@ export async function write(result, config, runtime) {
     const root = runtime.packageRoot;
     const { outputRoot } = runtime;
     const mode = config.mode ?? 'safe';
+    if (mode === 'write') {
+        await syncCollaboratorsWorkflowAsync(root, result.collaboratorsWorkflowYaml, {
+            mode: 'check',
+        });
+    }
     await mkdir(outputRoot, { recursive: true });
     await writeFile(join(outputRoot, 'exports.md'), result.exportsMarkdown);
     await writeFile(join(outputRoot, 'components.md'), result.components);
@@ -26,6 +32,7 @@ export async function write(result, config, runtime) {
     }
     if (mode === 'write') {
         await writeFile(join(root, 'README.md'), result.readme);
+        await syncCollaboratorsWorkflowAsync(root, result.collaboratorsWorkflowYaml);
         await syncFundingFileAsync(root, result.fundingYaml);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/paradox",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "description": "Deterministic documentation generator for TypeScript packages.",
   "license": "MIT",
   "publishConfig": {
@@ -54,29 +54,28 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
-    "changeset": "changeset",
-    "changeset:status": "changeset status --since=origin/main",
+    "changeset": "ankhorage-changeset",
+    "changeset:status": "ankhorage-changeset status --since=origin/main",
     "docs": "bun src/cli/standalone.ts",
     "docs:bunx": "bunx @ankhorage/paradox",
     "format": "ankhorage-prettier --write .",
     "format:check": "ankhorage-prettier --check .",
-    "knip": "ankhorage-knip",
     "lint": "ankhorage-eslint . --max-warnings=0",
     "lint:fix": "ankhorage-eslint . --fix --max-warnings=0",
     "prepack": "bun run build",
     "test": "bun test",
     "typecheck": "bun x tsc --noEmit -p tsconfig.json",
-    "version-packages": "changeset version"
+    "version-packages": "ankhorage-changeset version",
+    "knip:check": "ankhorage-knip"
   },
   "dependencies": {
     "ts-morph": "^28.0.0"
   },
   "devDependencies": {
-    "@ankhorage/devtools": "^1.6.0",
-    "@changesets/cli": "^2.31.0",
-    "@types/bun": "^1.3.14",
+    "@ankhorage/devtools": "^1.14.0",
+    "@types/bun": "^1.4.1",
     "@types/node": "^24.13.3",
     "typescript": "^5.9.3"
   },
-  "packageManager": "bun@1.3.14"
+  "packageManager": "bun@1.4.2"
 }