@itentialopensource/adapter-bluecat_ipam 0.1.1

package/utils/adapterInfo.js

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+/* @copyright Itential, LLC 2025 */
+
+/* eslint global-require:warn */
+/* eslint import/no-dynamic-require:warn */
+/* eslint prefer-destructuring:warn */
+
+/**
+ * This script will determine the information about the adapter and store
+ * it into a file in the adapter. This is self contained and only depends on
+ * finding files within the adapter to gather information.
+ *
+ * This utility is used when adapters are committed and pushed. It is not used by
+ * any customers nor is it references in any scripts.
+ */
+
+const path = require('path');
+const fs = require('fs-extra');
+
+/**
+ * @summary Count the number of lines in a file
+ * @param {string} filePath - The path to the file
+ * @returns {number} The total number of lines in the file
+ */
+function countLinesInFile(filePath) {
+  if (fs.existsSync(filePath)) {
+    const cFile = fs.readFileSync(filePath, 'utf8');
+    return cFile.split('\n').length;
+  }
+  console.log(`Missing - ${path.basename(filePath)}`);
+  return 0;
+}
+
+/**
+ * @summary Count the number of lines across multiple files
+ * @param {array} filePaths - An array of file paths
+ * @returns {number} The total number of lines across all files
+ */
+function countLinesInFiles(filePaths) {
+  return filePaths.reduce((total, filePath) => total + countLinesInFile(filePath), 0);
+}
+
+/**
+ * @summary Count the number of lines in all json files within an entity directory
+ * @param {string} entityDir - The entity directory
+ * @returns {number} The total number of lines across all JSON files in the entity directory
+ */
+function countEntityLines(entityDir) {
+  let totalLines = 0;
+
+  if (!fs.existsSync(entityDir)) {
+    console.log('Could not find the entities directory');
+    return totalLines;
+  }
+  const entities = fs.readdirSync(entityDir);
+  for (let e = 0; e < entities.length; e += 1) {
+    const entityPath = path.join(entityDir, entities[e]);
+    if (fs.statSync(entityPath).isDirectory()) {
+      const jsonFiles = fs.readdirSync(entityPath).filter((f) => f.endsWith('.json'));
+      for (let j = 0; j < jsonFiles.length; j += 1) {
+        totalLines += countLinesInFile(path.join(entityPath, jsonFiles[j]));
+      }
+    }
+  }
+  return totalLines;
+}
+
+/**
+ * @summary Count the number of test cases in a file
+ * @param {string} filePath - The path to the test file
+ * @returns {number} The total number of test cases in the file
+ */
+function countTestsInFile(filePath) {
+  if (fs.existsSync(filePath)) {
+    const tFile = fs.readFileSync(filePath, 'utf8');
+    const ttestCount = tFile.split('it(\'').length;
+    return ttestCount;
+  }
+  console.log(`Missing - ${path.basename(filePath)}`);
+  return 0;
+}
+
+/**
+ * @summary Count the number of test cases across multiple files
+ * @param {array} filePaths - An array of test file paths
+ * @returns {number} The total number of test cases across all files
+ */
+function countTestsInFiles(filePaths) {
+  return filePaths.reduce((total, filePath) => total + countTestsInFile(filePath), 0);
+}
+
+function adapterInfo() {
+  // set the base pase of the adapter - tool shoud be one level up in utils
+  let adaptdir = __dirname;
+  const infoRes = {};
+
+  if (adaptdir.endsWith('/utils')) {
+    adaptdir = adaptdir.substring(0, adaptdir.length - 6);
+  }
+
+  // if no package.json then not in right place - end with error
+  if (!fs.existsSync(`${adaptdir}/package.json`)) {
+    throw new Error('Missing - package.json');
+  }
+  const pack = require(`${adaptdir}/package.json`);
+  infoRes.version = pack.version;
+
+  let configCount = 0;
+  const configFiles = ['pronghorn.json', 'propertiesSchema.json', 'error.json'].map((f) => path.join(adaptdir, f));
+  configCount = countLinesInFiles(configFiles);
+
+  const entityDir = path.join(adaptdir, '/entities');
+  configCount += countEntityLines(entityDir);
+
+  infoRes.configLines = configCount;
+
+  const utilFiles = ['argParser', 'checkMigrate.js', 'entitiesToDB.js', 'findPath.js', 'logger.js', 'methodDocumentor.js', 'modify.js', 'mongoDbConnection.js',
+    'mongoUtils.js', 'setup.js', 'taskMover.js', 'tbScript.js', 'tbUtils.js', 'testRunner.js', 'troubleshootingAdapter.js', 'updateAdapterConfig.js'
+  ].map((f) => path.join(adaptdir, 'utils', f));
+
+  infoRes.scriptLines = countLinesInFiles(utilFiles);
+
+  const adapterFiles = ['adapter.js', 'adapterBase.js'].map((f) => path.join(adaptdir, f));
+  infoRes.codeLines = countLinesInFiles(adapterFiles);
+
+  const testFiles = [
+    'test/integration/adapterTestBasicGet.js',
+    'test/integration/adapterTestConnectivity.js',
+    'test/integration/adapterTestIntegration.js',
+    'test/unit/adapterBaseTestUnit.js',
+    'test/unit/adapterTestUnit.js'
+  ].map((f) => path.join(adaptdir, f));
+  infoRes.testLines = countLinesInFiles(testFiles);
+  infoRes.testCases = countTestsInFiles(testFiles);
+
+  infoRes.totalCodeLines = infoRes.scriptLines + infoRes.codeLines + infoRes.testLines;
+
+  if (fs.existsSync(`${adaptdir}/pronghorn.json`)) {
+    // Read the entity schema from the file system
+    const phFile = path.join(adaptdir, '/pronghorn.json');
+    const prong = require(phFile);
+    infoRes.wfTasks = prong.methods.length;
+  } else {
+    console.log('Missing - pronghorn.json');
+  }
+
+  console.log(JSON.stringify(infoRes));
+  fs.writeFileSync(`${adaptdir}/report/adapterInfo.json`, JSON.stringify(infoRes, null, 2));
+}
+
+try {
+  adapterInfo();
+} catch (err) {
+  console.error(err.message);
+  process.exit();
+}

package/utils/argParser.js

@@ -0,0 +1,44 @@
+const customLevels = {
+  spam: 6,
+  trace: 5,
+  debug: 4,
+  info: 3,
+  warn: 2,
+  error: 1,
+  none: 0
+};
+
+function parseArgs(argv = process.argv) {
+  let properties = null;
+  let logLevel = 'none';
+  let maxCalls = 5;
+  let host = null;
+
+  argv.forEach((val) => {
+    if (val.startsWith('--PROPS=')) {
+      // get the properties
+      const inputVal = val.split('=')[1];
+      properties = JSON.parse(inputVal);
+    } else if (val.startsWith('--LOG=')) {
+      // get the desired log level
+      const level = val.split('=')[1];
+      // validate the log level is supported, if so set it
+      if (Object.hasOwnProperty.call(customLevels, level)) {
+        logLevel = level;
+      }
+    } else if (val.startsWith('--MAXCALLS=')) {
+      const override = parseInt(val.split('=')[1], 10);
+      if (!Number.isNaN(override) && override > 0) {
+        maxCalls = override;
+      }
+    } else if (val.startsWith('--HOST=')) {
+      [, host] = val.split('=');
+    }
+  });
+
+  return {
+    properties, logLevel, maxCalls, host
+  };
+}
+
+module.exports = { parseArgs };

package/utils/checkMigrate.js

@@ -0,0 +1,102 @@
+/* @copyright Itential, LLC 2025 */
+
+/**
+ * This script will determine if the adapter needs to be upgraded, a migration is needed or
+ * a remediation is needed. This is self contained and depends on accessing GitLab repos as well as
+ * finding files within the adapter to gather and compare information.
+ *
+ * This utility is executed from a script in the package.json by `npm run adapter:checkMigrate`. As a result,
+ * this utility is exposed and available to customers but exclusively through the CLI.
+ */
+
+const { execSync } = require('child_process');
+const semver = require('semver');
+const packageJson = require('../package.json');
+const { get } = require('./tbUtils');
+
+const localAdaptVer = packageJson.version;
+const localEngineVer = packageJson.engineVersion;
+const localUtils = execSync('npm list @itentialopensource/adapter-utils', { encoding: 'utf-8' });
+const localUtilsVer = localUtils.split('@').pop().replace(/(\r\n|\n|\r| )/gm, '');
+
+/**
+ * @summary Checks if adapter is the latest version
+ *
+ * @function updateNeeded
+ */
+async function updateNeeded() {
+  const adapterUrl = `https://registry.npmjs.org/${packageJson.name}`;
+  const latestAdapterVer = (await get(adapterUrl)).data['dist-tags'].latest;
+  console.log('\n[Upgrade Check]');
+  console.log(`Local Adapter Version : ${localAdaptVer}`);
+  console.log(`Latest Adapter Version: ${latestAdapterVer}`);
+  return semver.lt(localAdaptVer, latestAdapterVer);
+}
+
+/**
+ * @summary Checks if adapter is up-to-date or if migration is needed
+ *
+ * @function migrateNeeded
+ */
+async function migrateNeeded() {
+  const engineUrl = 'https://adapters.itential.io/engineVersion';
+  const latestEngineVer = (await get(engineUrl)).data;
+  console.log('\n[Migration Check]');
+  console.log(`Local Engine Version : ${localEngineVer}`);
+  console.log(`Latest Engine Version: ${latestEngineVer}`);
+  return semver.lt(localEngineVer, latestEngineVer);
+}
+
+/**
+ * @summary Checks if adapter is up-to-date or if remediation is needed
+ *
+ * @function remediationNeeded
+ */
+async function remediationNeeded() {
+  const utilsUrl = 'https://registry.npmjs.org/@itentialopensource/adapter-utils';
+  const latestUtilsVer = (await get(utilsUrl)).data['dist-tags'].latest;
+  console.log('\n[Remediation Check]');
+  console.log(`Local Utils Version : ${localUtilsVer}`);
+  console.log(`Latest Utils Version: ${latestUtilsVer}`);
+  return semver.lt(localUtilsVer, latestUtilsVer);
+}
+
+/**
+ * @summary Main Script (rest of file)
+ *
+ * Input - None
+ * Process - gets the adapter version from the package.json and compares it to the latest version of the adapter,
+ *      then get the engine version from the package.json and compare it to the adapter engine version in the repo.
+ *      then get the local adapter-utils version and compare that to the latest version of adapter-utils.
+ * Output - console logs providing state and path forward
+ *
+ */
+updateNeeded().then((needed) => {
+  if (needed) {
+    console.log('You should update the adapter to the latest available version -- git pull');
+  } else {
+    console.log('Update is not needed at the current time.');
+  }
+}).catch((error) => {
+  console.log('Could not get latest adapter version. Confirm the adapter is an open source adapter.', error.message);
+});
+
+migrateNeeded().then((needed) => {
+  if (needed) {
+    console.log('Migration is needed -- if open source, request Itential migrate the adapter');
+  } else {
+    console.log('Migration is not needed at the current time.');
+  }
+}).catch((error) => {
+  console.log('Could not get latest engine version. Confirm the adapter was built by the Itential Adapter Builder.', error.message);
+});
+
+remediationNeeded().then((needed) => {
+  if (needed) {
+    console.log('Remediation is needed -- update the version of adapter-utils in the package.json, remove node modules and package-lock and run npm install');
+  } else {
+    console.log('Remediation is not needed at the current time.');
+  }
+}).catch((error) => {
+  console.log('Could not get latest utils version. Confirm the adapter utilizes the Itential adapter foundation.', error.message);
+});

package/utils/entitiesToDB.js

@@ -0,0 +1,190 @@
+/* @copyright Itential, LLC 2021 */
+
+// Set globals
+/* global log */
+
+/* eslint import/no-dynamic-require: warn */
+/* eslint global-require: warn */
+/* eslint no-unused-vars: warn */
+/* eslint import/no-unresolved: warn */
+/* eslint no-promise-executor-return: warn */
+
+/**
+ *  This script is used to read through an adapter's entities files
+ *  and then creates documents and enters them into the IAP mongodb
+ */
+
+const fs = require('fs');
+const path = require('path');
+const tbUtils = require('./tbUtils');
+const mongoUtils = require('./mongoUtils');
+
+/**
+ * Function to load sample properties from the file system
+ */
+const loadSampleProperties = async () => {
+  const samplePath = path.join(__dirname, '../sampleProperties.json');
+  if (fs.existsSync(samplePath)) {
+    const fullProps = JSON.parse(fs.readFileSync(samplePath, 'utf-8'));
+    return fullProps.properties.mongo;
+  }
+  throw new Error('sampleProperties.json not found');
+};
+
+/**
+ *  Function used to take a file path to a entity directory and build
+ *  a document that corresponds to the entity files.
+ */
+const buildDoc = (pathstring) => {
+  let files = fs.readdirSync(pathstring);
+
+  // load the mockdatafiles
+  const mockdatafiles = {};
+  if (files.includes('mockdatafiles') && fs.lstatSync(`${pathstring}/mockdatafiles`).isDirectory()) {
+    fs.readdirSync(`${pathstring}/mockdatafiles`).forEach((file) => {
+      if (file.split('.').pop() === 'json') {
+        const mockpath = `${pathstring}/mockdatafiles/${file}`;
+        const data = JSON.parse(fs.readFileSync(mockpath));
+        mockdatafiles[mockpath.split('/').pop()] = data;
+      }
+    });
+  }
+
+  // load the action data
+  let actions;
+  if (files.includes('action.json')) {
+    actions = JSON.parse(fs.readFileSync(`${pathstring}/action.json`));
+  }
+
+  // Load schema.json and other schemas in remaining json files
+  files = files.filter((f) => (f !== 'action.json') && f.endsWith('.json'));
+  const schema = [];
+  files.forEach((file) => {
+    const data = JSON.parse(fs.readFileSync(`${pathstring}/${file}`));
+    schema.push({
+      name: file,
+      schema: data
+    });
+  });
+
+  // return the data
+  return {
+    actions: actions.actions,
+    schema,
+    mockdatafiles
+  };
+};
+
+/**
+ *  Function used to get the database from the options or a provided directory
+ */
+const optionsHandler = async (options) => {
+  try {
+    // Try mongo properties from service config first
+    const mongoPronghornProps = options?.pronghornProps?.mongo;
+    const validatedPronghornProps = mongoPronghornProps ? mongoUtils.getAndValidateMongoProps(mongoPronghornProps) : undefined;
+    if (validatedPronghornProps) return validatedPronghornProps;
+
+    // Fallback to sample properties
+    const sampleProps = await loadSampleProperties();
+    const validatedSampleProps = mongoUtils.getAndValidateMongoProps(sampleProps);
+    if (validatedSampleProps) return validatedSampleProps;
+
+    throw new Error('No mongo properties provided! Need either a complete URL or both host and database');
+  } catch (error) {
+    log.error('Error in optionsHandler:', error.message);
+    throw error;
+  }
+};
+
+/**
+ *  Function used to put the adapter configuration into the provided database
+ */
+const moveEntitiesToDB = async (targetPath, options) => {
+  // set local variables
+  let myOpts = options;
+  let myPath = targetPath;
+  let mongoConnection = null;
+
+  // if we got a string parse into a JSON object
+  if (typeof myOpts === 'string') {
+    myOpts = JSON.parse(myOpts);
+  }
+
+  // if there is no target collection - set the collection to the default
+  if (!myOpts.targetCollection) {
+    myOpts.targetCollection = 'adapter_configs';
+  }
+
+  // if there is no id error since we need an id for the entities
+  if (!myOpts.id) {
+    throw new Error('Adapter ID required!');
+  }
+
+  // Check valid filepath provided
+  if (!myPath) {
+    // if no path use the current directory without the utils
+    myPath = path.join(__dirname, '../');
+  } else if (myPath.slice(-1) === '/') {
+    myPath = myPath.slice(0, -1);
+  }
+
+  try {
+    // get the database properties from adapter service instance configs
+    const currentProps = await optionsHandler(options);
+
+    // verify set the entity path
+    const entitiesPath = `${myPath}/entities`;
+    if (!fs.existsSync(entitiesPath)) {
+      throw new Error(`Entities path does not exist in filesystem: ${entitiesPath}`);
+    } else {
+      log.trace('Target found on filesystem');
+    }
+
+    // Get adapter details
+    if (!fs.existsSync(`${myPath}/pronghorn.json`)) {
+      throw new Error(`pronghorn.json does not exist in path: ${myPath}`);
+    } else {
+      log.trace('pronghorn.json found on filesystem');
+    }
+    const adapterData = JSON.parse(fs.readFileSync(`${myPath}/pronghorn.json`));
+
+    // Load files from the filesystem
+    const docs = [];
+    const entities = fs.readdirSync(entitiesPath);
+    entities.forEach((entity) => {
+      const entityPath = `${entitiesPath}/${entity}`;
+      const isDir = fs.lstatSync(entitiesPath).isDirectory();
+
+      // Build doc for entity
+      if (isDir) {
+        let doc = buildDoc(entityPath);
+        doc = {
+          id: myOpts.id,
+          type: adapterData.id,
+          entity,
+          ...doc
+        };
+        docs.push(doc);
+      }
+    });
+
+    // Upload documents to db collection
+    mongoConnection = await tbUtils.connect(currentProps).catch((err) => { log.error(err); throw err; });
+    if (!mongoConnection) {
+      log.error('Error occurred when connecting to database', currentProps);
+      throw new Error('Database not found');
+    }
+
+    const collection = mongoConnection.db.collection(myOpts.targetCollection);
+    const res = await collection.insertMany(docs, { checkKeys: false }).catch((err) => { log.error(err); throw err; });
+    return res;
+  } finally {
+    // Ensure connection is closed even if an error occurs
+    if (mongoConnection) {
+      await tbUtils.closeConnection(mongoConnection);
+    }
+  }
+};
+
+module.exports = { moveEntitiesToDB };

package/utils/findPath.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+/* @copyright Itential, LLC 2019 */
+/* eslint global-require:warn */
+/* eslint import/no-dynamic-require:warn */
+/* eslint prefer-destructuring:warn */
+
+const path = require('path');
+const fs = require('fs-extra');
+const rls = require('readline-sync');
+
+/**
+ * This script will determine the type of integration test to run
+ * based on input. If other information is needed, it will solicit
+ * that input and then edit the integration test accordingly.
+ */
+
+/**
+ * Updates the action files
+ */
+function checkActionFiles(apath) {
+  // verify the path
+  if (!apath) {
+    console.log('  NO PATH PROVIDED!');
+    return 'Done';
+  }
+
+  // make sure the entities directory exists
+  const entitydir = path.join(__dirname, '../entities');
+  if (!fs.statSync(entitydir).isDirectory()) {
+    console.log('Could not find the entities directory');
+    return 'error';
+  }
+
+  const entities = fs.readdirSync(entitydir);
+  let found = false;
+
+  // need to go through each entity in the entities directory
+  for (let e = 0; e < entities.length; e += 1) {
+    // make sure the entity is a directory - do not care about extra files
+    // only entities (dir)
+    if (fs.statSync(`${entitydir}/${entities[e]}`).isDirectory()) {
+      // see if the action file exists in the entity
+      if (fs.existsSync(`${entitydir}/${entities[e]}/action.json`)) {
+        // Read the entity actions from the file system
+        const actions = require(`${entitydir}/${entities[e]}/action.json`);
+
+        // go through all of the actions set the appropriate info in the newActions
+        for (let a = 0; a < actions.actions.length; a += 1) {
+          if (actions.actions[a].entitypath.indexOf(apath) >= 0) {
+            found = true;
+            console.log(`  Found - entity: ${entities[e]} action: ${actions.actions[a].name}`);
+            console.log(`          method: ${actions.actions[a].method} path: ${actions.actions[a].entitypath}`);
+            console.log(' ');
+          }
+        }
+      } else {
+        console.log(`Could not find entities ${entities[e]} action.json file`);
+        return 'error';
+      }
+    } else {
+      console.log(`Could not find entities ${entities[e]} directory`);
+      return 'error';
+    }
+  }
+
+  if (!found) {
+    console.log('  PATH NOT FOUND!');
+  }
+  return 'Done';
+}
+
+const findPath = rls.question('Enter the path/partial path you are looking for: ');
+console.log(`PATH: ${findPath}`);
+checkActionFiles(findPath);

package/utils/logger.js

@@ -0,0 +1,26 @@
+// utils/logger.js
+const winston = require('winston');
+const { parseArgs } = require('./argParser');
+
+const customLevels = {
+  spam: 6,
+  trace: 5,
+  debug: 4,
+  info: 3,
+  warn: 2,
+  error: 1,
+  none: 0
+};
+
+// Only set global logger if it doesn't already exist (i.e., not provided by app)
+if (!global.log) {
+  const { logLevel = 'info' } = parseArgs();
+
+  global.log = winston.createLogger({
+    level: logLevel,
+    levels: customLevels,
+    transports: [new winston.transports.Console()]
+  });
+}
+
+module.exports = global.log;