1.1.29

npmextra.json

@@ -9,22 +9,18 @@
       "npmPackagename": "@git.zone/tsdoc",
       "license": "MIT",
       "projectDomain": "git.zone",
-      "description": "An advanced TypeScript documentation tool leveraging AI for enhanced insights and automated documentation generation, with capabilities for automated and enhanced documentation creation tailor-made for TypeScript projects.",
+      "description": "An advanced TypeScript documentation tool using AI to generate and enhance documentation for TypeScript projects.",
       "keywords": [
         "TypeScript",
-        "documentation",
+        "documentation generation",
         "AI-enhanced documentation",
-        "automated documentation generation",
+        "CLI tool",
         "code analysis",
-        "development tool",
+        "automated documentation",
-        "CLI utility",
+        "developer tools",
         "API documentation",
-        "developer productivity",
+        "technical writing",
-        "code insights",
+        "code quality improvement"
-        "integrated development environment tooling",
-        "code quality enhancement",
-        "project documentation",
-        "documentation automation"
       ]
     }
   },

package.json

@@ -1,8 +1,8 @@
 {
   "name": "@git.zone/tsdoc",
-  "version": "1.1.17",
+  "version": "1.1.29",
   "private": false,
-  "description": "An advanced TypeScript documentation tool leveraging AI for enhanced insights and automated documentation generation, with capabilities for automated and enhanced documentation creation tailor-made for TypeScript projects.",
+  "description": "An advanced TypeScript documentation tool using AI to generate and enhance documentation for TypeScript projects.",
   "main": "dist_ts/index.js",
   "typings": "dist_ts/index.d.ts",
   "type": "module",
@@ -12,29 +12,30 @@
     "tsdoc": "cli.js"
   },
   "scripts": {
-    "test": "(tstest test/) && (node ./cli.ts.js)",
+    "test": "(tstest test/) && npm run testCli",
+    "testCli": "(node ./cli.ts.js) && (node ./cli.ts.js aidocs)",
     "build": "(tsbuild --web --allowimplicitany)"
   },
   "devDependencies": {
-    "@git.zone/tsbuild": "^2.1.65",
+    "@git.zone/tsbuild": "^2.1.76",
     "@git.zone/tsrun": "^1.2.46",
-    "@git.zone/tstest": "^1.0.73",
+    "@git.zone/tstest": "^1.0.90",
-    "@push.rocks/tapbundle": "^5.0.4",
+    "@push.rocks/tapbundle": "^5.0.23",
-    "@types/node": "^20.12.7"
+    "@types/node": "^20.12.12"
   },
   "dependencies": {
     "@push.rocks/early": "^4.0.3",
-    "@push.rocks/npmextra": "^5.0.10",
+    "@push.rocks/npmextra": "^5.0.13",
     "@push.rocks/qenv": "^6.0.5",
-    "@push.rocks/smartai": "^0.0.8",
+    "@push.rocks/smartai": "^0.0.17",
-    "@push.rocks/smartcli": "^4.0.6",
+    "@push.rocks/smartcli": "^4.0.10",
     "@push.rocks/smartdelay": "^3.0.5",
-    "@push.rocks/smartfile": "^11.0.13",
+    "@push.rocks/smartfile": "^11.0.14",
     "@push.rocks/smartinteract": "^2.0.15",
     "@push.rocks/smartlog": "^3.0.1",
-    "@push.rocks/smartlog-destination-local": "^9.0.1",
+    "@push.rocks/smartlog-destination-local": "^9.0.2",
-    "@push.rocks/smartpath": "^5.0.13",
+    "@push.rocks/smartpath": "^5.0.18",
-    "@push.rocks/smartshell": "^3.0.4",
+    "@push.rocks/smartshell": "^3.0.5",
     "typedoc": "^0.25.13",
     "typescript": "^5.4.5"
   },
@@ -55,18 +56,14 @@
   ],
   "keywords": [
     "TypeScript",
-    "documentation",
+    "documentation generation",
     "AI-enhanced documentation",
-    "automated documentation generation",
+    "CLI tool",
     "code analysis",
-    "development tool",
+    "automated documentation",
-    "CLI utility",
+    "developer tools",
     "API documentation",
-    "developer productivity",
+    "technical writing",
-    "code insights",
+    "code quality improvement"
-    "integrated development environment tooling",
-    "code quality enhancement",
-    "project documentation",
-    "documentation automation"
   ]
 }

readme.md

@@ -1,92 +1,311 @@
 # @git.zone/tsdoc
-An advanced TypeScript documentation tool that leverages AI for enhanced insights and automated documentation generation.
+An advanced TypeScript documentation tool using AI to generate and enhance documentation for TypeScript projects.
 
 ## Install
-To install `@git.zone/tsdoc`, you have two options depending on your usage preference: globally for CLI use or locally within your project for use through NPX. To install globally, run:
 
-```sh
+To install `@git.zone/tsdoc`, you can either install it globally or use it with `npx`.
+
+### Global Installation
+
+You can install `@git.zone/tsdoc` globally on your system using npm:
+
+```bash
 npm install -g @git.zone/tsdoc
 ```
 
-For local installation within your project, use:
+### Usage with npx
 
-```sh
+If you prefer not to install it globally, you can use it with `npx`:
-npm install --save @git.zone/tsdoc
-```
 
-You can then use the tool through NPX if installed locally:
+```bash
-
+npx @git.zone/tsdoc <command>
-```sh
-npx tsdoc
 ```
 
 ## Usage
-`@git.zone/tsdoc` is a tool designed to improve the process of generating documentation for TypeScript projects. It combines the capabilities of Typedoc with AI-powered features to automatically generate insights and enhance the quality of your API documentation without manual intervention.
 
-To get started, after installation, navigate to the root directory of your TypeScript project where your `tsconfig.json` is located and run:
+`@git.zone/tsdoc` provides a comprehensive CLI tool and advanced AI-enhanced features to generate and enhance documentation for your TypeScript projects.
 
-```typescript
+### Using the CLI
-import { runCli } from '@git.zone/tsdoc';
 
-// Initialize and run the CLI
+The primary interface for `@git.zone/tsdoc` is through its command-line tool. Below, we'll explore the different commands available and provide examples of how to use them.
-runCli().then(() => {
-  console.log('Documentation generation complete!');
-}).catch((error) => {
-  console.error('Failed to generate documentation:', error);
-});
-```
 
-### Generating Documentation
+### Commands
-`@git.zone/tsdoc` provides a command-line interface to generate documentation directly from your TypeScript source files. The CLI uses information from your TypeScript configuration and the source files to create comprehensive documentation.
 
-Once `tsdoc` is installed globally, you can run the following command in the root of your TypeScript project:
+#### `tsdoc` - Auto-detect Documentation Format
 
-```sh
+The standard command will automatically detect the documentation format of your project and generate the appropriate documentation.
+
+```bash
 tsdoc
 ```
 
-This command analyzes your TypeScript project, extracts type information, and generates documentation pages as HTML or Markdown. You can customize the output format and specify additional options via command line parameters or by editing `tsdoc` configuration files.
+### Example
 
-### Command Line Parameters
+```typescript
-The CLI tool reads options from `./ts/cli.ts`. Command line parameters allow you to customize the behavior of `tsdoc`. For more detailed usage, run:
+// In a TypeScript project, run the above command.
-
-```sh
-tsdoc --help
 ```
 
-This will display a list of available commands and options, such as specifying the output directory for the generated documentation or enabling/disabling certain features of the documentation generator.
+#### `tsdoc typedoc` - Generate Documentation using TypeDoc
 
-### Examples
+The `typedoc` command will generate documentation compliant with the TypeDoc format.
-Below is an example of how to use `tsdoc` to generate documentation with custom options:
 
-```sh
+```bash
-tsdoc --output docs/api --format html
+tsdoc typedoc --publicSubdir docs 
-```
-This command generates HTML documentation for your project and places it in the `docs/api` directory.
-
-### Additional Features
-Beyond basic documentation generation, `tsdoc` integrates AI-powered analysis to enrich the documentation automatically. This feature helps by providing insights into complex types, documenting patterns used within your codebase, and suggesting improvements for better maintainability and readability of your documentation.
-
-**Note:** `tsdoc` is designed for use with projects adhering to modern TypeScript conventions. Ensure your project structure and TypeScript configuration are compatible for optimal results.
-
-### Integration with CI/CD
-`@git.zone/tsdoc` can be integrated into your CI/CD pipelines to automatically generate and update documentation as part of your build process. This ensures that your API documentation is always up-to-date with your codebase.
-
-Here's an example configuration snippet for a CI workflow:
-
-```yml
-steps:
-  - name: Install tsdoc
-    run: npm install -g @git.zone/tsdoc
-  
-  - name: Generate Documentation
-    run: tsdoc
 ```
 
-Remember to replace placeholders and adjust paths as necessary depending on your CI provider and project configuration.
+### Example
 
-### Conclusion
+```typescript
-`@git.zone/tsdoc` is a powerful tool that leverages the best of Typedoc and AI to streamline the documentation process for TypeScript projects. By automating the generation of insightful and comprehensive documentation, it enhances developer productivity and improves the quality of project documentation.
+import * as plugins from '@push.rocks/smartfile';
+
+const tsconfigPath = plugins.path.join(__dirname, 'tsconfig.json');
+const outputPath = plugins.path.join(__dirname, 'docs');
+
+await plugins.smartshellInstance.exec(
+  `typedoc --tsconfig ${tsconfigPath} --out ${outputPath} index.ts`
+);
+```
+
+#### `tsdoc aidoc` - Generate AI-Enhanced Documentation
+
+The `aidoc` command will use AI to generate an enhanced README and update your project description.
+
+```bash
+tsdoc aidoc
+```
+
+### Example
+
+```typescript
+import { AiDoc } from '@git.zone/tsdoc';
+
+(async () => {
+  const aidoc = new AiDoc();
+  await aidoc.start();
+  await aidoc.buildReadme('./');
+  await aidoc.buildDescription('./');
+})();
+```
+
+#### `tsdoc test` - Test Your Documentation Setup
+
+The `test` command will test your current documentation setup, ensuring everything is configured correctly.
+
+```bash
+tsdoc test
+```
+
+### Example
+
+```typescript
+import * as plugins from '@git.zone/tsdoc';
+
+await plugins.runCli().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});
+```
+
+## Features in Depth
+
+### Using Plugins
+
+`@git.zone/tsdoc` extensively uses plugins to extend its capabilities.
+
+### Available Plugins
+
+- **npmextra**: Manage npm project-related configurations.
+- **qenv**: Environment variable management.
+- **smartai**: AI integration.
+- **smartcli**: CLI helper.
+- **smartdelay**: Simple delay utility.
+- **smartfile**: File system utilities.
+- **smartinteract**: Interaction helper.
+- **smartlog**: Logging utility.
+- **smartlogDestinationLocal**: Local file destination for logging.
+- **smartpath**: Path utilities.
+- **smartshell**: Shell command execution.
+- **typedoc**: Documentation generation.
+
+### Example Usage of Plugins
+
+#### Path Management
+
+```typescript
+import * as path from 'path';
+
+const packageDir = path.join(__dirname, '../');
+const cwd = process.cwd();
+const binDir = path.join(packageDir, './node_modules/.bin');
+const assetsDir = path.join(packageDir, './assets');
+const publicDir = path.join(cwd, './public');
+const tsDir = path.join(cwd, './ts');
+const tsconfigFile = path.join(assetsDir, './tsconfig.json');
+const typedocOptionsFile = path.join(assetsDir, './typedoc.json');
+```
+
+#### Logging
+
+```typescript
+import * as plugins from './plugins';
+
+const logger = new plugins.smartlog.Smartlog({
+  logContext: {
+    company: 'Some Company',
+    companyunit: 'Some CompanyUnit',
+    containerName: 'Some Containername',
+    environment: 'local',
+    runtime: 'node',
+    zone: 'gitzone',
+  },
+  minimumLogLevel: 'silly',
+});
+
+logger.addLogDestination(new plugins.smartlogDestinationLocal.DestinationLocal());
+```
+
+## Advanced Usage
+
+### Using `TypeDoc` Class
+
+The `TypeDoc` class provides utility methods to compile TypeScript documentation.
+
+```typescript
+import { TypeDoc } from '@git.zone/tsdoc/classes.typedoc';
+
+const typeDocInstance = new TypeDoc(paths.cwd);
+
+await typeDocInstance.compile({
+  publicSubdir: 'docs',
+});
+```
+
+### Using `AiDoc` Class
+
+The `AiDoc` class integrates with AI services to enhance your documentation.
+
+#### Initializing and Using AI
+
+```typescript
+import { AiDoc } from '@git.zone/tsdoc';
+
+const aiDoc = new AiDoc({ OPENAI_TOKEN: 'your-openai-token' });
+
+await aiDoc.start();
+await aiDoc.buildReadme('./');
+await aiDoc.buildDescription('./');
+```
+
+#### Retrieving AI Tokens
+
+```typescript
+import * as plugins from '@git.zone/tsdoc/plugins';
+
+const qenv = new plugins.qenv.Qenv();
+const openaiToken = await qenv.getEnvVarOnDemand('OPENAI_TOKEN');
+```
+
+### Testing
+
+The provided tests demonstrate how to verify the functionality of the `@git.zone/tsdoc` tool.
+
+#### Example Test Script
+
+```typescript
+import { expect, tap } from '@push.rocks/tapbundle';
+import * as tsdoc from '../ts/index';
+
+tap.test('should create AiDoc instance', async () => {
+  const aidoc = new tsdoc.AiDoc({ OPENAI_TOKEN: 'dummy-token' });
+  expect(aidoc).toBeInstanceOf(tsdoc.AiDoc);
+});
+
+tap.test('should start AiDoc', async () => {
+  const aidoc = new tsdoc.AiDoc({ OPENAI_TOKEN: 'dummy-token' });
+  await aidoc.start();
+  await aidoc.buildReadme('./');
+  await aidoc.buildDescription('./');
+});
+
+tap.start();
+```
+
+### Internals
+
+The `@git.zone/tsdoc` consists of several internal classes and utilities that streamline its functionality.
+
+#### File Paths Management
+
+Located in `ts/paths.ts`, the file defines various directories and file paths used by the tool.
+
+```typescript
+import * as plugins from './plugins';
+
+export const packageDir = plugins.path.join(
+  plugins.smartpath.get.dirnameFromImportMetaUrl(import.meta.url),
+  '../'
+);
+export const cwd = process.cwd();
+export const binDir = plugins.path.join(packageDir, './node_modules/.bin');
+export const assetsDir = plugins.path.join(packageDir, './assets');
+export const publicDir = plugins.path.join(cwd, './public');
+export const tsDir = plugins.path.join(cwd, './ts');
+export const tsconfigFile = plugins.path.join(assetsDir, './tsconfig.json');
+export const typedocOptionsFile = plugins.path.join(assetsDir, './typedoc.json');
+```
+
+#### Utility Commands
+
+Define utility commands that streamline various processes.
+
+##### Example: SmartCLI Usage
+
+```typescript
+// Import required modules and plugins
+import * as plugins from './plugins';
+import * as paths from './paths';
+
+// TypeDoc and AiDoc classes
+import { TypeDoc } from './classes.typedoc';
+import { AiDoc } from './classes.aidoc';
+
+// Export a run function
+export const run = async () => {
+  const tsdocCli = new plugins.smartcli.Smartcli();
+
+  tsdocCli.standardCommand().subscribe(async argvArg => {
+    switch (true) {
+      case await TypeDoc.isTypeDocDir(paths.cwd):
+        tsdocCli.triggerCommand('typedoc', argvArg);
+        break;
+      default:
+        console.error(`Cannot determine docs format at ${paths.cwd}`);
+    }
+  });
+
+  tsdocCli.addCommand('typedoc').subscribe(async argvArg => {
+    const typeDocInstance = new TypeDoc(paths.cwd);
+    await typeDocInstance.compile({
+      publicSubdir: argvArg.publicSubdir
+    });
+  });
+
+  tsdocCli.addCommand('aidoc').subscribe(async argvArg => {
+    const aidocInstance = new AiDoc(argvArg);
+    await aidocInstance.start();
+    await aidocInstance.buildReadme(paths.cwd);
+    await aidocInstance.buildDescription(paths.cwd);
+  });
+
+  tsdocCli.startParse();
+};
+```
+
+By leveraging these functionalities, you can configure and extend `@git.zone/tsdoc` to fit your specific documentation generation needs.
+
+### Further Enhancements
+
+The `@git.zone/tsdoc` tool is designed to be extensible. Explore the source files and plugins to add more functionality or integrate with other tools as needed. This README provides an extensive overview of the commands and features but it's always beneficial to dive into the source code to understand the intricacies and potential customizations. Happy documenting!
 
 ## License and Legal Information
 

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@git.zone/tsdoc',
-  version: '1.1.17',
+  version: '1.1.29',
-  description: 'An advanced TypeScript documentation tool leveraging AI for enhanced insights and automated documentation generation, with capabilities for automated and enhanced documentation creation tailor-made for TypeScript projects.'
+  description: 'An advanced TypeScript documentation tool using AI to generate and enhance documentation for TypeScript projects.'
 }

ts/aidocs_classes/description.ts

@@ -8,7 +8,6 @@ interface IDescriptionInterface {
 }
 
 export class Description {
-
   // INSTANCE
   private aiDocsRef: AiDoc;
   private projectDir: string;
@@ -23,29 +22,31 @@ export class Description {
     const projectContext = new ProjectContext(this.projectDir);
     const contextString = await projectContext.update();
 
-    let result = await this.aiDocsRef.openaiInstance.chat(
+    let result = await this.aiDocsRef.openaiInstance.chat({
-      `
+      systemMessage: `
-        You create a json adhering the following interface:
+You create a json adhering the following interface:
-        {
+{
   description: string; // a sensible short, one sentence description of the project
   keywords: string[]; // an array of tags that describe the project
-        }
+}
 
-        The description should be based on what you understand from the project's files.
+The description should be based on what you understand from the project's files.
-        The keywords should be based on use cases you see from the files.
+The keywords should be based on use cases you see from the files.
-        Don't be cheap about the way you think.
+Don't be cheap about the way you think.
 
-        Important: Answer only in valid JSON.
+Important: Answer only in valid JSON.
-        You answer should be parseable with JSON.parse() without modifying anything.
+You answer should be parseable with JSON.parse() without modifying anything.
 
-        Don't wrap the JSON in three ticks json!!!
+Don't wrap the JSON in three ticks json!!!
     `,
-      contextString,
+      messageHistory: [],
-      []
+      userMessage: contextString,
-    );
+    });
 
-    console.log(result.message.content);
+    console.log(result.message);
-    const resultObject: IDescriptionInterface = JSON.parse(result.message.content.replace('```json', '').replace('```', ''));
+    const resultObject: IDescriptionInterface = JSON.parse(
+      result.message.replace('```json', '').replace('```', '')
+    );
 
     const npmextraJson = (await projectContext.gatherFiles()).smartfilesNpmextraJSON;
     const npmextraJsonContent = JSON.parse(npmextraJson.contents.toString());
@@ -64,10 +65,9 @@ export class Description {
     packageJson.contents = Buffer.from(JSON.stringify(packageJsonContent, null, 2));
     await packageJson.write();
 
-
     console.log(`\n======================\n`);
     console.log(JSON.stringify(resultObject, null, 2));
     console.log(`\n======================\n`);
-    return result.message.content;
+    return result.message;
   }
 }

ts/aidocs_classes/projectcontext.ts

@@ -30,7 +30,7 @@ export class ProjectContext {
     );
     const smartfilesMod = await plugins.smartfile.fs.fileTreeToObject(
       this.projectDir,
-      'ts/**/*.ts'
+      'ts*/**/*.ts'
     );
     const smartfilesTest = await plugins.smartfile.fs.fileTreeToObject(
       this.projectDir,
@@ -47,6 +47,10 @@ export class ProjectContext {
   }
 
   public async convertFilesToContext(filesArg: plugins.smartfile.SmartFile[]) {
+    console.log(`Using the following files for the documentation:`)
+    filesArg.map(fileArg => {
+      console.log(`  -> ${fileArg.relative}`);
+    })
     return filesArg
       .map((smartfile) => {
         return `
@@ -70,6 +74,7 @@ ${smartfile.contents.toString()}
       ...files.smartfilesMod,
       ...files.smartfilesTest,
     ]);
+    // console.log(context);
     return context;
   }
 

ts/aidocs_classes/readme.ts

@@ -28,8 +28,8 @@ export class Readme {
       console.log(error);
     }
 
-    let result = await this.aiDocsRef.openaiInstance.chat(
+    let result = await this.aiDocsRef.openaiInstance.chat({
-      `
+      systemMessage: `
 You create markdown readmes for npm projects. You only output the markdown readme.
 
 The Readme should follow the following template:
@@ -64,23 +64,23 @@ The Readme should follow the following template:
   * readme.hints.md provides valuable hints about module ideas.
 ]
             `,
-      contextString,
+      messageHistory: [],
-      []
+      userMessage: contextString,
-    );
+    });
     
 
-    finalReadmeString += result.message.content + '\n' + legalInfo;
+    finalReadmeString += result.message + '\n' + legalInfo;
 
     
 
     console.log(`\n======================\n`);
-    console.log(result.message.content);
+    console.log(result.message);
     console.log(`\n======================\n`);
 
     const readme = (await projectContext.gatherFiles()).smartfilesReadme;
     readme.contents = Buffer.from(finalReadmeString);
     await readme.write();
 
-    return result.message.content;
+    return result.message;
   }
 }

ts/classes.aidoc.ts

@@ -42,13 +42,15 @@ export class AiDoc {
         mandatoryKeys: ['OPENAI_TOKEN'],
       });
 
-      const missingKeys = this.npmextraKV.getMissingMandatoryKeys();
+      const missingKeys = await this.npmextraKV.getMissingMandatoryKeys();
       if (missingKeys.length > 0) {
         // lets try argv
         if (this.argvArg?.OPENAI_TOKEN) {
           this.openaiToken = this.argvArg.OPENAI_TOKEN;
         } else {
           // lets try smartinteract
+          // wait for a second until OpenAI fixes punycode problem...
+          await plugins.smartdelay.delayFor(1000);
           const answerObject = await this.smartinteractInstance.askQuestion({
             type: 'input',
             message: `Please provide your OpenAI token`,
@@ -59,12 +61,17 @@ export class AiDoc {
         }
 
         this.printSanitizedToken();
-        // await this.npmextraKV.writeKey('OPENAI_TOKEN', this.openaiToken);
+        await this.npmextraKV.writeKey('OPENAI_TOKEN', this.openaiToken);
       }
     }
+    if (!this.openaiToken) {
+      this.openaiToken = await this.npmextraKV.readKey('OPENAI_TOKEN');
+    }
 
     // lets assume we have an OPENAI_Token now
-    this.openaiInstance = new plugins.smartai.OpenAiProvider(this.openaiToken);
+    this.openaiInstance = new plugins.smartai.OpenAiProvider({
+      openaiToken: this.openaiToken,
+    });
     await this.openaiInstance.start();
   }
 

ts/cli.ts

@@ -27,8 +27,15 @@ export const run = async () => {
     });
   });
 
-  tsdocCli.addCommand('aidocs').subscribe(async (argvArg) => {
+  tsdocCli.addCommand('aidoc').subscribe(async (argvArg) => {
-    const aidocs = new AiDoc();
+    logger.log('info', `Generating new readme...`);
+    logger.log('info', `This may take some time...`);
+    const aidocInstance = new AiDoc();
+    await aidocInstance.start();
+    aidocInstance.buildReadme(paths.cwd);
+    logger.log('info', `Generating new keywords...`);
+    logger.log('info', `This may take some time...`);
+    aidocInstance.buildDescription(paths.cwd);
   })
 
   tsdocCli.addCommand('test').subscribe((argvArg) => {