From a1eff753927f2788bab0a96c70bbac9d7b34797f Mon Sep 17 00:00:00 2001
From: Hakim Cassimally <hakim.cassimally@couchbase.com>
Date: Thu, 1 Feb 2024 11:34:28 +0000
Subject: [PATCH 1/2] fixes #10 by checking for clean:true in scan

---
 packages/collector-extension/lib/index.js     |  6 ++++-
 .../test/collector-extension-test.js          | 27 +++++++++++++++++--
 2 files changed, 30 insertions(+), 3 deletions(-)

diff --git a/packages/collector-extension/lib/index.js b/packages/collector-extension/lib/index.js
index 883522c..8000f17 100644
--- a/packages/collector-extension/lib/index.js
+++ b/packages/collector-extension/lib/index.js
@@ -34,6 +34,7 @@ module.exports.register = function () {
         const worktreeDir = worktree || ospath.join(cacheDir, generateWorktreeFolderName({ url, gitdir, worktree }))
         const expandPathContext = { base: worktreeDir, cwd: worktreeDir, dot: ospath.join(worktreeDir, startPath) }
         const scanDirs = new Set()
+        const cleanDirs = new Set()
         const collectors = (Array.isArray(collectorConfig) ? collectorConfig : [collectorConfig]).map((collector) => {
           const { run: runConfig = {}, scan: scanConfig = [] } = collector
           return {
@@ -45,6 +46,9 @@ module.exports.register = function () {
               if (typeof scan.dir === 'string') {
                 const dir = expandPath(scan.dir, expandPathContext)
                 scanDirs.add(dir)
+                if (scan.clean) {
+                  cleanDirs.add(dir)
+                }
                 accum.push({ ...scan, dir })
               }
               return accum
@@ -52,7 +56,7 @@ module.exports.register = function () {
           }
         })
         if (worktree) {
-          for (const scanDir of scanDirs) await fsp.rm(scanDir, { recursive: true, force: true })
+          for (const cleanDir of cleanDirs) await fsp.rm(cleanDir, { recursive: true, force: true })
         } else {
           const cache = gitCache[gitdir] || (gitCache[gitdir] = {})
           const ref = `refs/${reftype === 'branch' ? 'head' : reftype}s/${refname}`
diff --git a/packages/collector-extension/test/collector-extension-test.js b/packages/collector-extension/test/collector-extension-test.js
index 295da43..433d63c 100644
--- a/packages/collector-extension/test/collector-extension-test.js
+++ b/packages/collector-extension/test/collector-extension-test.js
@@ -742,10 +742,10 @@ describe('collector extension', () => {
       })
     })
 
-    it('should clean scan dir in worktree before running command(s)', async () => {
+    it('should clean scan dir in worktree before running command(s) when clean key is set in scan', async () => {
       const collectorConfig = {
         run: { command: 'node .gen-start-page.js' },
-        scan: { dir: 'build' },
+        scan: { dir: 'build', clean: true },
       }
       await runScenario({
         repoName: 'test-at-root',
@@ -765,6 +765,29 @@ describe('collector extension', () => {
       })
     })
 
+    it('should not clean scan dir in worktree before running command(s) by default', async () => {
+      const collectorConfig = {
+        run: { command: 'node .gen-start-page.js' },
+        scan: { dir: 'build' },
+      }
+      await runScenario({
+        repoName: 'test-at-root',
+        local: true,
+        collectorConfig,
+        before: async (contentAggregate) => {
+          expect(contentAggregate).to.have.lengthOf(1)
+          expect(contentAggregate[0].files).to.be.empty()
+          const worktree = contentAggregate[0].origins[0].worktree
+          const residualPagePath = ospath.join(worktree, 'build/modules/ROOT/pages/residual-page.adoc')
+          await fsp.mkdir(ospath.dirname(residualPagePath), { recursive: true })
+          await fsp.writeFile(residualPagePath, '= Residual Page', 'utf8')
+        },
+        after: (contentAggregate) => {
+          expect(contentAggregate[0].files.map((it) => it.path)).to.include('modules/ROOT/pages/residual-page.adoc')
+        },
+      })
+    })
+
     it('should run specified command in temporary worktree if repository is local and reference is not worktree', async () => {
       const collectorConfig = {
         run: { command: 'node .gen-start-page.js' },
-- 
GitLab


From a9a008c6c8b9cb8053b06d1ce5b4ac98fa5b2546 Mon Sep 17 00:00:00 2001
From: Hakim Cassimally <hakim.cassimally@couchbase.com>
Date: Thu, 1 Feb 2024 14:15:07 +0000
Subject: [PATCH 2/2] Update README

---
 packages/collector-extension/README.adoc | 40 ++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/packages/collector-extension/README.adoc b/packages/collector-extension/README.adoc
index 9f68831..5267b7c 100644
--- a/packages/collector-extension/README.adoc
+++ b/packages/collector-extension/README.adoc
@@ -47,6 +47,46 @@ ext:
       dir: build/generated-files
 ----
 
+You may define multiple collectors as a list.
+
+.antora.yml
+[,yaml]
+----
+name: my-project
+version: true
+# ...
+ext:
+  collector:
+    # (1)
+    - run:
+        command: node generate-ephemeral-files.js
+      scan:
+        dir: build/generated-files
+        clean: true
+
+    # (2)
+    - run:
+        command: node update-existing-module.js
+      scan:
+        dir: .
+
+    # (3)
+    - run:
+        dir: .
+        command: ./command-run-from-location-of-start-path
+----
+
+The example above demonstrates:
+
+. the optional `clean` flag to the scan operation.
+When this is true and you are running in worktree mode, the extension first deletes the contents of the scanned directory before running the command.
+This defaults to `false`.
+
+. if your command updates the *existing* worktree, by modifying or adding new files, then you need to explicitly re-scan the directory.
+
+. The `dir` key to the run operation sets the working directory.
+This defaults to the root of the repo, with `.` set to the `start_path` of the component.
+
 == Copyright and License
 
 Copyright (C) 2022-present by OpenDevise Inc. and the individual contributors of this project.
-- 
GitLab