feat: exclude contracts in docs, multiple outputs

.changeset/hot-cycles-attend.md

@@ -0,0 +1,18 @@
+---
+"clarigen-deno": patch
+---
+
+You can now output multiple Clarigen generated type files. To do so,
+use `outputs` with an array of paths, instead of `output`. Example:
+
+```toml
+[esm]
+outputs = ["src/clarigen.ts", "other/types.ts"]
+```
+
+You can also exclude specific contracts from having documentation generated. To do so, use the `exclude` (array) in your `Clarigen.toml`. Each entry in `exclude` should be the contract name - without file extensions or paths. Example:
+
+```toml
+[docs]
+exclude = ["ft-trait"]
+```

Clarigen.toml

@@ -5,14 +5,14 @@ clarinet = "./Clarinet.toml"
 # Comment or remove section to skip Deno types
 [deno]
 # `output` can be a directory or a folder.
-output = "artifacts/clarigen"
+output = "artifacts/clarigen/index.ts"
 helper = "tests/helper.ts"
 
 # Set where you'd like ESM types output.
 # Comment or remove section to skip ESM types
 [esm]
 # `output` can be a directory or a folder.
-output = "esm"
+outputs = ["esm/index.ts", "esm/2.ts"]
 include_accounts = true
 
 # `esm.after` - script to run after ESM types are generated.
@@ -25,4 +25,5 @@ after = "deno fmt ./esm/index.ts"
 # Generate docs by running `clarigen docs`
 [docs]
 # `output` should be a folder
-output = "docs"
+output = "docs"
+exclude = ["ft-trait"]

deno.lock

@@ -142,6 +142,7 @@
     "https://deno.land/x/kia@0.4.1b/mod.ts": "727b60e707c46429e40a2159ab73381245ef08a8e1e59e1e5a705745b99f4aec",
     "https://deno.land/x/kia@0.4.1b/spinners.ts": "26b63f964c745d6cc46e547d98352a4f64ae6d28400d35d9b77be7a5141db860",
     "https://deno.land/x/kia@0.4.1b/util.ts": "b7ac0962b5a39f666bad41c8b93efe1ea599fbac05ea9f65c0409926e8092618",
+    "https://deno.land/x/typebox@0.25.20/src/typebox.ts": "9b20b62c0bf31f1a9128b6dc6dfd470a5d956a48f0b0ef0a1ccc4d794fb55dcc",
     "https://denoporter.sirjosh.workers.dev/v1/deno.land/x/computed_types/src/DateType.ts": "2608ef17bb31d573f4564a7a36b6348af7eab0cb7b26d332d7008512c13ab4e1",
     "https://denoporter.sirjosh.workers.dev/v1/deno.land/x/computed_types/src/Schema.ts": "c984b56e12f0df38708659cdd94ad16fea7cfaba1c5360a0960d81cc4a81a6fd",
     "https://denoporter.sirjosh.workers.dev/v1/deno.land/x/computed_types/src/Validator.ts": "5bf584120e3c9e9419366aeb89b598e0f939b086e31432dc553c13e3c50c0a01",

docs/counter.md

@@ -39,7 +39,7 @@ Get the current counter
 
 ### increment
 
-[View in file](../contracts/counter.clar#L18)
+[View in file](../contracts/counter.clar#L22)
 
 `(define-public (increment ((step uint)) (response uint none))`
 
@@ -72,7 +72,7 @@ Increment the counter.
 
 ### decrement
 
-[View in file](../contracts/counter.clar#L31)
+[View in file](../contracts/counter.clar#L35)
 
 `(define-public (decrement ((step uint)) (response uint none))`
 

src/cli/config.ts

@@ -1,4 +1,5 @@
 import {
+  array,
   boolean,
   dirname,
   join,
@@ -25,15 +26,19 @@ const ConfigFileSchema = Schema({
   clarinet: string,
   [OutputType.ESM]: Schema({
     output: string.optional(),
-    include_accounts: boolean.optional(),
+    outputs: array.of(string).optional(),
+    include_accounts: boolean.optional(false),
     after: string.optional(),
   }).optional(),
   [OutputType.Deno]: Schema({
     output: string.optional(),
+    outputs: array.of(string).optional(),
     helper: string.optional(),
   }).optional(),
   [OutputType.Docs]: Schema({
     output: string.optional(),
+    outputs: array.of(string).optional(),
+    exclude: array.of(string).optional(),
   }).optional(),
 });
 
@@ -58,28 +63,33 @@ export class Config {
     return new this(config, clarinet);
   }
 
-  outputResolve(type: OutputType, filePath?: string) {
-    const path = this.configFile[type]?.output;
-    if (typeof path === 'undefined') return null;
-    const base = cwdResolve(path, filePath || '');
-    if (typeof filePath === 'undefined') {
-      if (base.endsWith('.ts')) return base;
-      return join(base, './index.ts');
-    } else {
-      return base;
-    }
+  getOutputs(type: OutputType): string[] {
+    const singlePath = this.configFile[type]?.output;
+    const multiPath = this.configFile[type]?.outputs || [];
+    if (singlePath !== undefined) return [singlePath];
+    return multiPath;
+  }
+
+  outputResolve(type: OutputType, filePath?: string): string[] | null {
+    const outputs = this.getOutputs(type);
+    if (!this.supports(type)) return null;
+    return outputs.map((path) => {
+      return cwdResolve(path, filePath || '');
+    });
   }
 
   async writeOutput(type: OutputType, contents: string, filePath?: string) {
-    const path = this.outputResolve(type, filePath);
-    if (path === null) return null;
-    await writeFile(path, contents);
-    log.debug(`Generated ${type} file at ${cwdRelative(path)}`);
-    return path;
+    const paths = this.outputResolve(type, filePath);
+    if (paths === null) return null;
+    await Promise.all(paths.map(async (path) => {
+      await writeFile(path, contents);
+      log.debug(`Generated ${type} file at ${cwdRelative(path)}`);
+    }));
+    return paths;
   }
 
   supports(type: OutputType) {
-    return !!this.configFile[type]?.output;
+    return this.getOutputs(type).length > 0;
   }
 
   type(type: OutputType) {

src/cli/files/docs.ts

@@ -9,7 +9,8 @@ import { runDenoFmt } from '../format.ts';
 export async function generateDocs(
   { session, config }: { session: Session; config: Config },
 ) {
-  const docsBase = config.configFile[OutputType.Docs]?.output;
+  const docs = config.configFile[OutputType.Docs];
+  const docsBase = docs?.output;
   if (!docsBase) {
     warnNoDocs();
     return;
@@ -19,10 +20,16 @@ export async function generateDocs(
       `Docs output path ('${docsBase}') looks like a file - it needs to be a directory.`,
     );
   }
+  const excluded: Record<string, boolean> = Object.fromEntries(
+    (docs.exclude || []).map((e) => {
+      return [e, true];
+    }),
+  );
   log.debug(`Generating docs at path \`${docsBase}\``);
-  const docsBaseFolder = config.outputResolve(OutputType.Docs, './')!;
+  const docsBaseFolder = (config.outputResolve(OutputType.Docs, './')!)[0];
   const paths = await Promise.all(session.contracts.map(async (contract) => {
     const name = getContractName(contract.contract_id, false);
+    if (excluded[name]) return null;
     const docFile = `${name}.md`;
     // location of
     const contractPathDef = config.clarinet.contracts?.[name]?.path;
@@ -42,14 +49,16 @@ export async function generateDocs(
 
     // log.debug(`Writing docs markdown file at ${cwdRelative(docPathFull)}`);
     const path = (await config.writeOutput(OutputType.Docs, md, docFile))!;
-    return path;
+    return path[0];
   }));
 
   const readme = generateReadme(session);
 
-  paths.push((await config.writeOutput(OutputType.Docs, readme, 'README.md'))!);
+  paths.push(
+    (await config.writeOutput(OutputType.Docs, readme, 'README.md'))![0],
+  );
 
-  await runDenoFmt(paths);
+  await runDenoFmt((paths.filter((s) => s !== null)) as string[]);
 }
 
 function warnNoDocs() {

src/cli/format.ts

@@ -18,9 +18,9 @@ export async function runDenoFmt(files: string[]) {
 }
 
 export async function denoFmt(config: Config) {
-  const file = config.outputResolve(OutputType.Deno);
-  if (file === null) return;
-  await runDenoFmt([file]);
+  const files = config.outputResolve(OutputType.Deno);
+  if (files === null) return;
+  await runDenoFmt(files);
 }
 
 export async function afterESM(config: Config) {

src/cli/generate.ts

@@ -17,7 +17,7 @@ export async function generate() {
     await config.writeOutput(OutputType.Deno, denoFile);
     await denoFmt(config);
     if (config.deno?.helper) {
-      const denoBase = config.outputResolve(OutputType.Deno)!;
+      const denoBase = (config.outputResolve(OutputType.Deno)!)[0];
       const helperPath = cwdResolve(config.deno.helper);
       const helperFile = makeHelper(session.contracts, denoBase, helperPath);
       await writeFile(helperPath, helperFile);

test_pkg/config_test.ts

@@ -9,7 +9,7 @@ Deno.test({
 
     await t.step('Resolving output files', () => {
       config.configFile.docs = { output: 'docs' };
-      const output = config.outputResolve(OutputType.Docs, 'file.md')!;
+      const output = (config.outputResolve(OutputType.Docs, 'file.md')!)[0];
       assert(output.endsWith('docs/file.md'));
       assertEquals(cwdRelative(output), 'docs/file.md');
     });