Create demo renderer (#807)

Author: lorisleiva

.changeset/nice-nights-battle.md

@@ -0,0 +1,5 @@
+---
+'@codama/renderers-core': patch
+---
+
+Add `fragmentToRenderMap` helper

.changeset/rude-spoons-fall.md

@@ -0,0 +1,5 @@
+---
+'@codama/renderers-demo': patch
+---
+
+Add new demo renderer that generates Markdown files for a given program.

packages/renderers-core/src/renderMap.ts

@@ -12,6 +12,12 @@ export function renderMap(): RenderMap {
     return new Map<Path, string>();
 }
 
+export function fragmentToRenderMap(fragment: BaseFragment, path: Path): RenderMap {
+    const newMap = new Map<Path, string>();
+    newMap.set(path, fragment.content);
+    return newMap;
+}
+
 export function addToRenderMap(renderMap: RenderMap, path: Path, content: BaseFragment | string): RenderMap {
     const newMap = new Map(renderMap);
     newMap.set(path, typeof content === 'string' ? content : content.content);

packages/renderers-demo/.gitignore

@@ -0,0 +1 @@
+dist/

packages/renderers-demo/.prettierignore

@@ -0,0 +1,5 @@
+dist/
+test/e2e/
+test-ledger/
+target/
+CHANGELOG.md

packages/renderers-demo/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Codama
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

packages/renderers-demo/README.md

@@ -0,0 +1,32 @@
+# Codama ➤ Renderers ➤ Demo
+
+[![npm][npm-image]][npm-url]
+[![npm-downloads][npm-downloads-image]][npm-url]
+
+[npm-downloads-image]: https://img.shields.io/npm/dm/@codama/renderers-demo.svg?style=flat
+[npm-image]: https://img.shields.io/npm/v/@codama/renderers-demo.svg?style=flat&label=%40codama%2Frenderers-demo
+[npm-url]: https://www.npmjs.com/package/@codama/renderers-demo
+
+This package provides a demo implementation of a Codama renderer to help developers create their own.
+
+## Installation
+
+```sh
+pnpm install @codama/renderers-demo
+```
+
+## Usage
+
+Add the following script to your Codama configuration file.
+
+```json
+{
+    // ...
+    "scripts": {
+        "demo": {
+            "from": "@codama/renderers-demo",
+            "args": ["docs"]
+        }
+    }
+}
+```

packages/renderers-demo/package.json

@@ -0,0 +1,64 @@
+{
+    "name": "@codama/renderers-demo",
+    "version": "1.0.0",
+    "description": "Demo renderer to help creating new ones",
+    "exports": {
+        "types": "./dist/types/index.d.ts",
+        "node": {
+            "import": "./dist/index.node.mjs",
+            "require": "./dist/index.node.cjs"
+        }
+    },
+    "main": "./dist/index.node.cjs",
+    "module": "./dist/index.node.mjs",
+    "types": "./dist/types/index.d.ts",
+    "type": "commonjs",
+    "files": [
+        "./dist/types",
+        "./dist/index.*"
+    ],
+    "sideEffects": false,
+    "keywords": [
+        "solana",
+        "framework",
+        "standard",
+        "renderers",
+        "demo"
+    ],
+    "scripts": {
+        "build": "rimraf dist && pnpm build:src && pnpm build:types",
+        "build:src": "zx ../../node_modules/@codama/internals/scripts/build-src.mjs node",
+        "build:types": "zx ../../node_modules/@codama/internals/scripts/build-types.mjs",
+        "dev": "zx ../../node_modules/@codama/internals/scripts/test-unit.mjs node --watch",
+        "lint": "zx ../../node_modules/@codama/internals/scripts/lint.mjs",
+        "lint:fix": "zx ../../node_modules/@codama/internals/scripts/lint.mjs --fix",
+        "test": "pnpm test:types && pnpm test:treeshakability && pnpm test:node && pnpm test:e2e && pnpm test:exports",
+        "test:e2e": "./test/e2e/test.sh",
+        "test:exports": "node ./test/exports/module.mjs && node ./test/exports/commonjs.cjs",
+        "test:node": "zx ../../node_modules/@codama/internals/scripts/test-unit.mjs node",
+        "test:treeshakability": "zx ../../node_modules/@codama/internals/scripts/test-treeshakability.mjs",
+        "test:types": "zx ../../node_modules/@codama/internals/scripts/test-types.mjs"
+    },
+    "dependencies": {
+        "@codama/errors": "workspace:*",
+        "@codama/nodes": "workspace:*",
+        "@codama/renderers-core": "workspace:*",
+        "@codama/visitors-core": "workspace:*",
+        "@solana/codecs": "^3.0.0"
+    },
+    "devDependencies": {
+        "@codama/cli": "workspace:*"
+    },
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/codama-idl/codama"
+    },
+    "bugs": {
+        "url": "http://github.com/codama-idl/codama/issues"
+    },
+    "browserslist": [
+        "supports bigint and not dead",
+        "maintained node versions"
+    ]
+}

packages/renderers-demo/src/fragments/accountPage.ts

@@ -0,0 +1,36 @@
+import { AccountNode, PdaNode, titleCase } from '@codama/nodes';
+import { visit } from '@codama/visitors-core';
+
+import {
+    Fragment,
+    fragment,
+    getCodeBlockFragment,
+    getFrontmatterFragment,
+    getPageFragment,
+    getTitleAndDescriptionFragment,
+} from '../utils';
+import { TypeVisitor } from '../visitors/getTypeVisitor';
+import { getPdaFunctionUsageFragment } from './pdaFunctionUsage';
+
+export function getAccountPageFragment(
+    node: AccountNode,
+    typeVisitor: TypeVisitor,
+    size?: number,
+    pda?: PdaNode,
+): Fragment {
+    const title = titleCase(node.name);
+    const type = visit(node, typeVisitor);
+
+    return getPageFragment(
+        [
+            getFrontmatterFragment(title, `Overview of the ${title} account`),
+            getTitleAndDescriptionFragment(title, node.docs),
+            fragment('## Account data'),
+            getCodeBlockFragment(type, 'ts'),
+            ...(size ? [fragment(`This account has a fixed size of ${size} bytes.`)] : []),
+            ...(pda ? [fragment('## PDA'), getCodeBlockFragment(getPdaFunctionUsageFragment(pda), 'ts')] : []),
+        ],
+        // Generated accounts are within the same directory.
+        { generatedAccounts: '.' },
+    );
+}

packages/renderers-demo/src/fragments/definedTypePage.ts

@@ -0,0 +1,28 @@
+import { DefinedTypeNode, titleCase } from '@codama/nodes';
+import { visit } from '@codama/visitors-core';
+
+import {
+    Fragment,
+    fragment,
+    getCodeBlockFragment,
+    getFrontmatterFragment,
+    getPageFragment,
+    getTitleAndDescriptionFragment,
+} from '../utils';
+import { TypeVisitor } from '../visitors/getTypeVisitor';
+
+export function getDefinedTypePageFragment(node: DefinedTypeNode, typeVisitor: TypeVisitor): Fragment {
+    const title = titleCase(node.name);
+    const type = visit(node, typeVisitor);
+
+    return getPageFragment(
+        [
+            getFrontmatterFragment(title, `Overview of the ${title} type`),
+            getTitleAndDescriptionFragment(title, node.docs),
+            fragment('## Type definition'),
+            getCodeBlockFragment(type, 'ts'),
+        ],
+        // Generated types are within the same directory.
+        { generatedTypes: '.' },
+    );
+}