From ac6519b17df3b396cf9e5a3677cdd03a5e6f4b92 Mon Sep 17 00:00:00 2001 From: Dan Allen Date: Thu, 7 Aug 2025 20:24:40 -0600 Subject: [PATCH] resolves #51 add private key on scan entry to set private property on scanned file --- CHANGELOG.adoc | 4 ++ .../modules/ROOT/pages/configure-scan.adoc | 23 ++++++++++ packages/collector-extension/lib/index.js | 3 +- .../test/extension-test.js | 42 +++++++++++++++++++ .../modules/ROOT/pages/_bar.adoc | 3 ++ .../modules/ROOT/pages/foo.adoc | 3 ++ 6 files changed, 77 insertions(+), 1 deletion(-) create mode 100644 packages/collector-extension/test/fixtures/extension-test/at-start-path/with-underscore-files/modules/ROOT/pages/_bar.adoc create mode 100644 packages/collector-extension/test/fixtures/extension-test/at-start-path/with-underscore-files/modules/ROOT/pages/foo.adoc diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index b92963c..3e08ef8 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -6,6 +6,10 @@ For a detailed view of what's changed, refer to the {url-repo}/commits[commit hi == Unreleased +=== Added + +* add private key on scan entry to set private property on scanned file (#51) + === Fixed * apply camelCase transformation to keys in scanned component version descriptor (antora.yml) (#49) diff --git a/docs/collector-extension/modules/ROOT/pages/configure-scan.adoc b/docs/collector-extension/modules/ROOT/pages/configure-scan.adoc index bc8b1a1..ffe6c5c 100644 --- a/docs/collector-extension/modules/ROOT/pages/configure-scan.adoc +++ b/docs/collector-extension/modules/ROOT/pages/configure-scan.adoc @@ -100,6 +100,11 @@ Acceptable keys for the map value are listed in the table below. |false |Boolean |Whether to clean the scan directory before running commands. + +|<> +|undefined +|Boolean +|Sets the value of the private property on all files scanned by this action. |=== {empty}* required @@ -246,3 +251,21 @@ In this case, the Collector instance will be recycling a worktree it has used on If Collector creates a new worktree in which to run the Collector instance, there's usually no need to clean. However, if the Collector instance has multiple steps, and those steps generate files into the same scan directory, it may be necessary to clean the scan directory at the start of each step. You'll need to put some thought into when you want the scan directory to be cleaned. + +== private key + +NOTE: Use of this key requires Antora 3.2.0 or better. + +By default, Antora will import underscore files (i.e., files that either start with an underscore or are found inside a directory that starts with an underscore), but will not publish those files. +This behavior can be overridden using the `private` key. + +If the `private` key is set on the entry, the value of that key will be propagated to the `private` property on the scanned (or updated) file. +This property, in turn, controls whether the file is published, assuming the file is in a publishable family. +If this property is not set, the default behavior in Antora takes effect. + +By setting the `private` key to `true`, you can force Antora to publish an underscore file. +Conversely, by setting the `private` key to `false`, you force Antora to not publish the file, even if it's in a publishable family. + +Note that all such files are still imported into the content catalog by Antora. +This key is merely controlling which publishable files actually get published to the site. +An unpublishable file can still be used in an include directive. diff --git a/packages/collector-extension/lib/index.js b/packages/collector-extension/lib/index.js index 7280a21..1485bc0 100644 --- a/packages/collector-extension/lib/index.js +++ b/packages/collector-extension/lib/index.js @@ -154,7 +154,7 @@ module.exports.register = function ({ config: { createWorktrees = 'auto', keepWo } } } - for (const { dir, files, into } of scans) { + for (const { dir, files, into, private: private_ } of scans) { let componentVersionDesc const scannedFiles = await srcFs(dir, files, into.dir).then((result) => result.filter((file) => (file.path === 'antora.yml' ? !(componentVersionDesc = file) : true)) @@ -190,6 +190,7 @@ module.exports.register = function ({ config: { createWorktrees = 'auto', keepWo for (const file of scannedFiles) { const relpath = file.path const existingFile = targetFiles.find((it) => it.path === relpath) + if (private_ != null) Object.assign(existingFile || file, { private: private_ }) if (existingFile) { Object.assign(existingFile, { contents: file.contents, stat: file.stat }) } else { diff --git a/packages/collector-extension/test/extension-test.js b/packages/collector-extension/test/extension-test.js index 56ead32..0ad97d5 100644 --- a/packages/collector-extension/test/extension-test.js +++ b/packages/collector-extension/test/extension-test.js @@ -1011,6 +1011,48 @@ describe(localPackageName, () => { }) }) + it('should label files as private if private key is true on scan entry', async () => { + const collectorConfig = { + scan: { dir: 'other-docs', private: true }, + } + await runScenario({ + repoName: 'at-start-path', + startPath: 'docs', + collectorConfig, + pre: (contentAggregate) => { + assert.equal(contentAggregate.length, 1) + assertx.empty(contentAggregate[0].files) + }, + post: (contentAggregate) => { + assert.equal(contentAggregate[0].files.length, 1) + assert.equal(contentAggregate[0].files[0].private, true) + }, + }) + }) + + it('should label files as not private if private key is false on scan entry', async () => { + const collectorConfig = { + scan: { dir: 'with-underscore-files', private: false }, + } + await runScenario({ + repoName: 'at-start-path', + startPath: 'docs', + collectorConfig, + pre: (contentAggregate) => { + assert.equal(contentAggregate.length, 1) + assertx.empty(contentAggregate[0].files) + }, + post: (contentAggregate) => { + assert.equal(contentAggregate[0].files.length, 2) + assert.equal(contentAggregate[0].files[0].private, false) + assert.equal(contentAggregate[0].files[1].private, false) + const underscoreFile = contentAggregate[0].files.find((it) => it.src.basename.charAt() === '_') + assert(underscoreFile != null) + assert.equal(underscoreFile.src.basename, '_bar.adoc') + }, + }) + }) + it('should not fail if scan dir does not exist', async () => { const collectorConfig = { scan: { dir: 'does-not-exist' }, diff --git a/packages/collector-extension/test/fixtures/extension-test/at-start-path/with-underscore-files/modules/ROOT/pages/_bar.adoc b/packages/collector-extension/test/fixtures/extension-test/at-start-path/with-underscore-files/modules/ROOT/pages/_bar.adoc new file mode 100644 index 0000000..6e5fa2e --- /dev/null +++ b/packages/collector-extension/test/fixtures/extension-test/at-start-path/with-underscore-files/modules/ROOT/pages/_bar.adoc @@ -0,0 +1,3 @@ += Bar + +bar content diff --git a/packages/collector-extension/test/fixtures/extension-test/at-start-path/with-underscore-files/modules/ROOT/pages/foo.adoc b/packages/collector-extension/test/fixtures/extension-test/at-start-path/with-underscore-files/modules/ROOT/pages/foo.adoc new file mode 100644 index 0000000..41381f2 --- /dev/null +++ b/packages/collector-extension/test/fixtures/extension-test/at-start-path/with-underscore-files/modules/ROOT/pages/foo.adoc @@ -0,0 +1,3 @@ += Foo + +include::_bar.adoc[lines=3..] -- GitLab