quackage 1.0.65 → 1.0.67

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "quackage",
-    "version": "1.0.65",
+    "version": "1.0.67",
     "description": "Building.  Testing.  Quacking.  Reloading.",
     "main": "source/Quackage-CLIProgram.js",
     "scripts": {
@@ -60,14 +60,14 @@
         "gulp-env": "^0.4.0",
         "gulp-sourcemaps": "^3.0.0",
         "gulp-terser": "^2.1.0",
-        "indoctrinate": "^1.0.8",
+        "indoctrinate": "^1.0.10",
         "jsdoc": "^4.0.5",
         "mocha": "10.4.0",
         "npm-check-updates": "^18.0.1",
         "nyc": "^15.1.0",
         "pict-docuserve": "^0.0.32",
         "pict-service-commandlineutility": "^1.0.19",
-        "retold-harness": "^1.1.2",
+        "retold-harness": "^1.1.6",
         "vinyl-buffer": "^1.0.1",
         "vinyl-source-stream": "^2.0.0"
     },

package/source/commands/Quackage-Command-PrepareDocs.js

@@ -1,6 +1,7 @@
 const libCommandLineCommand = require('pict-service-commandlineutility').ServiceCommandLineCommand;
 const libFS = require('fs');
 const libPath = require('path');
+const libChildProcess = require('child_process');
 
 class QuackageCommandPrepareDocs extends libCommandLineCommand
 {
@@ -16,6 +17,7 @@ class QuackageCommandPrepareDocs extends libCommandLineCommand
 		this.options.CommandOptions.push({ Name: '-d, --directory_root [directory_root]', Description: 'Root directory to scan for modules (defaults to CWD).', Default: '' });
 		this.options.CommandOptions.push({ Name: '-b, --branch [branch]', Description: 'Git branch for GitHub raw URLs (defaults to master).', Default: 'master' });
 		this.options.CommandOptions.push({ Name: '-g, --github_org [github_org]', Description: 'GitHub organization for raw URLs (defaults to stevenvelozo).', Default: 'stevenvelozo' });
+		this.options.CommandOptions.push({ Name: '-x, --excluded_modules [excluded_modules]', Description: 'Comma-separated list of module names to exclude from the catalog and keyword index.  Merged with any ExcludedModules list in indoctrinate\'s loaded config file (e.g. .indoctrinate.config.json).', Default: '' });
 
 		this.options.Aliases.push('docs');
 		this.options.Aliases.push('prep-docs');
@@ -30,6 +32,15 @@ class QuackageCommandPrepareDocs extends libCommandLineCommand
 		let tmpBranch = this.CommandOptions.branch || 'master';
 		let tmpGitHubOrg = this.CommandOptions.github_org || 'stevenvelozo';
 
+		// Exclusion list passthrough. When set, both indoctrinate sub-commands
+		// get -x <list>.  Comma-separated; indoctrinate will merge this with
+		// any ExcludedModules entries in its loaded config file.
+		let tmpExcludedModulesArgs = [];
+		if (this.CommandOptions.excluded_modules && this.CommandOptions.excluded_modules.length > 0)
+		{
+			tmpExcludedModulesArgs = ['-x', this.CommandOptions.excluded_modules];
+		}
+
 		this.log.info(`Preparing documentation in [${tmpDocsFolder}]...`);
 
 		// Ensure the output folder exists
@@ -81,7 +92,7 @@ class QuackageCommandPrepareDocs extends libCommandLineCommand
 						'-o', tmpCatalogFile,
 						'-b', tmpBranch,
 						'-g', tmpGitHubOrg
-					],
+					].concat(tmpExcludedModulesArgs),
 					{ cwd: this.fable.AppData.CWD },
 					fNext
 				);
@@ -98,17 +109,65 @@ class QuackageCommandPrepareDocs extends libCommandLineCommand
 						'generate_keyword_index',
 						'-d', tmpDirectoryRoot,
 						'-o', tmpKeywordIndexFile
-					].concat(tmpExtraScanArgs),
+					].concat(tmpExtraScanArgs).concat(tmpExcludedModulesArgs),
 					{ cwd: this.fable.AppData.CWD },
 					fNext
 				);
 			}.bind(this));
 
-		// Step 3: Inject pict-docuserve assets
+		// Step 3: Write _version.json version placard sidecar
+		tmpAnticipate.anticipate(
+			function (fNext)
+			{
+				this.log.info(`###############################[ STEP 3: VERSION PLACARD ]###############################`);
+				try
+				{
+					let tmpPackageJsonPath = libPath.join(tmpDirectoryRoot, 'package.json');
+					if (!libFS.existsSync(tmpPackageJsonPath))
+					{
+						this.log.warn(`No package.json at [${tmpPackageJsonPath}]; skipping _version.json generation.`);
+						return fNext();
+					}
+					let tmpPackage = JSON.parse(libFS.readFileSync(tmpPackageJsonPath, 'utf8'));
+
+					let tmpGitCommit = null;
+					try
+					{
+						tmpGitCommit = libChildProcess.execSync('git rev-parse --short HEAD',
+							{ cwd: tmpDirectoryRoot, stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+					}
+					catch (pGitErr)
+					{
+						// Non-git repo or no commits yet — omit GitCommit.
+					}
+
+					let tmpVersionPayload = {
+						Name: tmpPackage.name || '',
+						Version: tmpPackage.version || '',
+						Description: tmpPackage.description || '',
+						GeneratedAt: new Date().toISOString()
+					};
+					if (tmpGitCommit)
+					{
+						tmpVersionPayload.GitCommit = tmpGitCommit;
+					}
+
+					let tmpVersionFile = libPath.join(tmpDocsFolder, '_version.json');
+					libFS.writeFileSync(tmpVersionFile, JSON.stringify(tmpVersionPayload, null, '\t'));
+					this.log.info(`Wrote version placard: ${tmpVersionFile} (${tmpVersionPayload.Name} v${tmpVersionPayload.Version}${tmpGitCommit ? ' @ ' + tmpGitCommit : ''})`);
+				}
+				catch (pError)
+				{
+					this.log.warn(`Failed to write _version.json: ${pError.message}`);
+				}
+				return fNext();
+			}.bind(this));
+
+		// Step 4: Inject pict-docuserve assets
 		tmpAnticipate.anticipate(
 			function (fNext)
 			{
-				this.log.info(`###############################[ STEP 3: DOCUSERVE INJECT ]###############################`);
+				this.log.info(`###############################[ STEP 4: DOCUSERVE INJECT ]###############################`);
 				this.fable.QuackageProcess.execute(
 					tmpDocuserveLocation,
 					[