@erinjs/core 1.0.0

package/core/packages/docgen/src/extract.ts

@@ -0,0 +1,262 @@
+import * as ts from 'typescript';
+import doctrine from 'doctrine';
+import {
+  DocParam,
+  DocConstructor,
+  DocProperty,
+  DocMethod,
+  DocSource,
+  DocInterfaceProperty,
+  DocEnumMember,
+} from './schema.js';
+import { formatTypeNode, formatTypeFromType } from './formatType.js';
+
+function getJSDoc(node: ts.Node): string {
+  const sourceFile = node.getSourceFile();
+  const text = sourceFile.getFullText();
+  const commentRanges = ts.getLeadingCommentRanges(text, node.getFullStart());
+  if (!commentRanges?.length) return '';
+  const range = commentRanges[commentRanges.length - 1];
+  return text.slice(range.pos, range.end);
+}
+
+function parseJSDoc(comment: string): doctrine.Annotation | null {
+  try {
+    return doctrine.parse(comment, { unwrap: true });
+  } catch {
+    return null;
+  }
+}
+
+function cleanDescription(s: string): string {
+  return s
+    .replace(/\s*\/\s*$/, '')
+    .replace(/\n\s*\n\s*\n/g, '\n\n')
+    .trim();
+}
+
+function getDescriptionFromJSDoc(comment: string): string {
+  const parsed = parseJSDoc(comment);
+  if (!parsed) return '';
+  return cleanDescription(parsed.description ?? '');
+}
+
+function getParamDescriptions(comment: string): Map<string, string> {
+  const parsed = parseJSDoc(comment);
+  const map = new Map<string, string>();
+  if (!parsed?.tags) return map;
+  for (const tag of parsed.tags) {
+    if (tag.title === 'param' && 'name' in tag) {
+      const name = (tag as doctrine.type.ParameterTag).name;
+      const desc = (tag as doctrine.type.ParameterTag).description ?? '';
+      if (name) map.set(name.replace(/^\[|\]$/g, ''), cleanDescription(desc));
+    }
+  }
+  return map;
+}
+
+function _getReturnsFromJSDoc(comment: string): string | undefined {
+  const parsed = parseJSDoc(comment);
+  if (!parsed?.tags) return undefined;
+  const tag = parsed.tags.find((t) => t.title === 'returns');
+  if (tag && tag.type === 'ReturnTag') {
+    return ((tag as doctrine.type.ReturnTag).description ?? '').trim();
+  }
+  return undefined;
+}
+
+function getExamplesFromJSDoc(comment: string): string[] {
+  const parsed = parseJSDoc(comment);
+  if (!parsed?.tags) return [];
+  return parsed.tags
+    .filter((t) => t.title === 'example')
+    .map((t) => ((t as doctrine.type.Tag).description ?? '').trim())
+    .filter(Boolean);
+}
+
+export function getDeprecatedFromJSDoc(comment: string): boolean | string | undefined {
+  const parsed = parseJSDoc(comment);
+  if (!parsed?.tags) return undefined;
+  const tag = parsed.tags.find((t) => t.title === 'deprecated');
+  if (!tag) return undefined;
+  const desc = (tag as doctrine.type.Tag).description?.trim();
+  return desc || true;
+}
+
+/** @discordJsCompat or @discordJsCompat https://discord.js.org/... — string = URL, true = no link */
+export function getDiscordJsCompatFromJSDoc(comment: string): boolean | string | undefined {
+  const parsed = parseJSDoc(comment);
+  if (!parsed?.tags) return undefined;
+  const tag = parsed.tags.find(
+    (t) => t.title === 'discordJsCompat' || t.title === 'discordjscompat',
+  );
+  if (!tag) return undefined;
+  const desc = (tag as doctrine.type.Tag).description?.trim();
+  return desc || true;
+}
+
+export function getDescriptionFromJSDocComment(comment: string): string {
+  return getDescriptionFromJSDoc(comment);
+}
+
+function getSource(node: ts.Node): DocSource | undefined {
+  const sourceFile = node.getSourceFile();
+  const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+  const fileName = sourceFile.fileName.split(/[/\\]/).pop() ?? '';
+  return { file: fileName, line: line + 1 };
+}
+
+export function extractConstructor(
+  checker: ts.TypeChecker,
+  node: ts.ConstructorDeclaration,
+): DocConstructor | undefined {
+  const comment = getJSDoc(node);
+  const paramDescs = getParamDescriptions(comment);
+
+  const params: DocParam[] = node.parameters.map((p) => {
+    const name = (p.name as ts.Identifier).getText();
+    const type = p.type
+      ? formatTypeNode(checker, p.type)
+      : formatTypeFromType(checker, checker.getTypeAtLocation(p));
+    const optional = !!p.questionToken;
+    const description = paramDescs.get(name);
+    return { name, type, optional, description };
+  });
+
+  const examples = getExamplesFromJSDoc(comment);
+
+  return {
+    params,
+    description: getDescriptionFromJSDoc(comment) || undefined,
+    examples: examples.length ? examples : undefined,
+  };
+}
+
+export function extractProperty(
+  checker: ts.TypeChecker,
+  node: ts.PropertyDeclaration | ts.PropertySignature,
+): DocProperty | null {
+  const name = (node.name as ts.Identifier)?.getText();
+  if (!name || name.startsWith('_')) return null;
+
+  const comment = getJSDoc(node);
+  const type = node.type
+    ? formatTypeNode(checker, node.type)
+    : formatTypeFromType(checker, checker.getTypeAtLocation(node));
+  const readonly = !!(node as ts.PropertyDeclaration).modifiers?.some(
+    (m) => m.kind === ts.SyntaxKind.ReadonlyKeyword,
+  );
+  const optional = !!(node as ts.PropertySignature).questionToken;
+  const description = getDescriptionFromJSDoc(comment) || undefined;
+  const discordJsCompat = getDiscordJsCompatFromJSDoc(comment);
+  const examples = getExamplesFromJSDoc(comment);
+
+  return {
+    name,
+    type,
+    readonly,
+    optional,
+    description,
+    discordJsCompat,
+    examples: examples.length ? examples : undefined,
+  };
+}
+
+export function extractMethod(
+  checker: ts.TypeChecker,
+  node: ts.MethodDeclaration | ts.MethodSignature,
+): DocMethod | null {
+  const name = (node.name as ts.Identifier)?.getText();
+  if (!name || name.startsWith('_')) return null;
+
+  const comment = getJSDoc(node);
+  const paramDescs = getParamDescriptions(comment);
+
+  const params: DocParam[] = (node.parameters ?? []).map((p) => {
+    const pname = (p.name as ts.Identifier).getText();
+    const type = p.type
+      ? formatTypeNode(checker, p.type)
+      : formatTypeFromType(checker, checker.getTypeAtLocation(p));
+    const optional = !!p.questionToken;
+    const description = paramDescs.get(pname);
+    return { name: pname, type, optional, description };
+  });
+
+  const returnType = node.type
+    ? formatTypeNode(checker, node.type)
+    : (node as ts.MethodDeclaration).body
+      ? formatTypeFromType(
+          checker,
+          checker.getReturnTypeOfSignature(checker.getSignatureFromDeclaration(node)!),
+        )
+      : 'void';
+
+  const async = !!(node as ts.MethodDeclaration).modifiers?.some(
+    (m) => m.kind === ts.SyntaxKind.AsyncKeyword,
+  );
+
+  const deprecated = getDeprecatedFromJSDoc(comment);
+  const discordJsCompat = getDiscordJsCompatFromJSDoc(comment);
+  const examples = getExamplesFromJSDoc(comment);
+
+  return {
+    name,
+    params,
+    returns: returnType,
+    description: getDescriptionFromJSDoc(comment) || undefined,
+    examples: examples.length ? examples : undefined,
+    async,
+    deprecated,
+    discordJsCompat,
+    source: getSource(node),
+  };
+}
+
+export function extractGetterProperty(
+  checker: ts.TypeChecker,
+  node: ts.GetAccessorDeclaration,
+): DocProperty | null {
+  const name = (node.name as ts.Identifier)?.getText();
+  if (!name || name.startsWith('_')) return null;
+
+  const comment = getJSDoc(node);
+  const returnType = node.type
+    ? formatTypeNode(checker, node.type)
+    : formatTypeFromType(
+        checker,
+        checker.getReturnTypeOfSignature(checker.getSignatureFromDeclaration(node)!),
+      );
+  const description = getDescriptionFromJSDoc(comment) || undefined;
+  const discordJsCompat = getDiscordJsCompatFromJSDoc(comment);
+  const examples = getExamplesFromJSDoc(comment);
+
+  return {
+    name,
+    type: returnType,
+    readonly: true,
+    optional: false,
+    description,
+    discordJsCompat,
+    examples: examples.length ? examples : undefined,
+  };
+}
+
+export function extractInterfaceProperty(
+  checker: ts.TypeChecker,
+  node: ts.PropertySignature,
+): DocInterfaceProperty | null {
+  return extractProperty(checker, node) as DocInterfaceProperty | null;
+}
+
+export function extractEnumMember(node: ts.EnumMember): DocEnumMember {
+  const name = (node.name as ts.Identifier).getText();
+  let value: string | number = name;
+  if (node.initializer) {
+    if (ts.isNumericLiteral(node.initializer)) {
+      value = parseInt(node.initializer.getText(), 10);
+    } else if (ts.isStringLiteral(node.initializer)) {
+      value = node.initializer.getText().slice(1, -1);
+    }
+  }
+  return { name, value };
+}

package/core/packages/docgen/src/formatType.ts

@@ -0,0 +1,24 @@
+import * as ts from 'typescript';
+
+/**
+ * Strip import("..."). prefixes from type strings.
+ * TS checker emits these for types from other modules - we want just the type name.
+ */
+function sanitizeTypeString(s: string): string {
+  return s.replace(/\bimport\s*\(["']([^"']*)["']\)\s*\./g, '');
+}
+
+/**
+ * Convert a TypeScript type to a readable string for documentation.
+ */
+export function formatTypeNode(checker: ts.TypeChecker, typeNode: ts.TypeNode | undefined): string {
+  if (!typeNode) return 'void';
+  const type = checker.getTypeFromTypeNode(typeNode);
+  const raw = checker.typeToString(type, typeNode, ts.TypeFormatFlags.None);
+  return sanitizeTypeString(raw);
+}
+
+export function formatTypeFromType(checker: ts.TypeChecker, type: ts.Type): string {
+  const raw = checker.typeToString(type, undefined, ts.TypeFormatFlags.None);
+  return sanitizeTypeString(raw);
+}

package/core/packages/docgen/src/index.ts

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+/**
+ * Custom doc generator using TypeScript Compiler API.
+ * Outputs clean JSON schema for the docs website.
+ */
+
+import * as ts from 'typescript';
+import { resolve, dirname } from 'path';
+import { mkdirSync, writeFileSync } from 'fs';
+import { DocOutput } from './schema.js';
+
+export type { DocOutput, DocClass, DocInterface, DocEnum } from './schema.js';
+import { visitSourceFile } from './visitor.js';
+
+export interface DocgenOptions {
+  entryPoints: string[];
+  tsconfigPath: string;
+  packageName: string;
+  outFile: string;
+  /** Repo root for source link paths */
+  repoRoot?: string;
+}
+
+export function generateDocs(options: DocgenOptions): DocOutput {
+  const { entryPoints, tsconfigPath, packageName, outFile, repoRoot } = options;
+
+  const configPath = resolve(tsconfigPath);
+  const configFile = ts.readConfigFile(configPath, ts.sys.readFile);
+  if (configFile.error) {
+    throw new Error(`Failed to read tsconfig: ${configFile.error.messageText}`);
+  }
+
+  const parsedConfig = ts.parseJsonConfigFileContent(
+    configFile.config,
+    ts.sys,
+    dirname(configPath),
+  );
+
+  const rootPath = dirname(configPath);
+  const program = ts.createProgram(
+    parsedConfig.fileNames.length
+      ? parsedConfig.fileNames
+      : entryPoints.map((e) => resolve(rootPath, e)),
+    parsedConfig.options,
+  );
+
+  const checker = program.getTypeChecker();
+  const allClasses: DocOutput['classes'] = [];
+  const allInterfaces: DocOutput['interfaces'] = [];
+  const allEnums: DocOutput['enums'] = [];
+
+  const seenClasses = new Set<string>();
+  const seenInterfaces = new Set<string>();
+  const seenEnums = new Set<string>();
+
+  const visitOptions = repoRoot ? { repoRoot } : undefined;
+
+  for (const sourceFile of program.getSourceFiles()) {
+    const filePath = sourceFile.fileName;
+    if (filePath.includes('node_modules')) continue;
+    if (!filePath.includes(rootPath)) continue;
+
+    const result = visitSourceFile(checker, sourceFile, visitOptions);
+    for (const c of result.classes) {
+      if (!seenClasses.has(c.name)) {
+        seenClasses.add(c.name);
+        allClasses.push(c);
+      }
+    }
+    for (const i of result.interfaces) {
+      if (!seenInterfaces.has(i.name)) {
+        seenInterfaces.add(i.name);
+        allInterfaces.push(i);
+      }
+    }
+    for (const e of result.enums) {
+      if (!seenEnums.has(e.name)) {
+        seenEnums.add(e.name);
+        allEnums.push(e);
+      }
+    }
+  }
+
+  allClasses.sort((a, b) => a.name.localeCompare(b.name));
+  allInterfaces.sort((a, b) => a.name.localeCompare(b.name));
+  allEnums.sort((a, b) => a.name.localeCompare(b.name));
+
+  const output: DocOutput = {
+    meta: {
+      generator: 'fluxer-docgen',
+      version: '1',
+      date: Date.now(),
+    },
+    package: packageName,
+    classes: allClasses,
+    interfaces: allInterfaces,
+    enums: allEnums,
+  };
+
+  mkdirSync(dirname(outFile), { recursive: true });
+  writeFileSync(outFile, JSON.stringify(output, null, 2), 'utf-8');
+  return output;
+}

package/core/packages/docgen/src/schema.ts

@@ -0,0 +1,100 @@
+/**
+ * Output schema for the custom doc generator.
+ */
+
+export interface DocMeta {
+  generator: string;
+  version: string;
+  date: number;
+}
+
+export interface DocParam {
+  name: string;
+  type: string;
+  optional?: boolean;
+  description?: string;
+}
+
+export interface DocConstructor {
+  params: DocParam[];
+  description?: string;
+  examples?: string[];
+}
+
+export interface DocProperty {
+  name: string;
+  type: string;
+  readonly?: boolean;
+  description?: string;
+  examples?: string[];
+  optional?: boolean;
+  /** Discord.js compatible: string = link to d.js docs, true = no link */
+  discordJsCompat?: boolean | string;
+}
+
+export interface DocMethod {
+  name: string;
+  params: DocParam[];
+  returns: string;
+  description?: string;
+  examples?: string[];
+  async?: boolean;
+  deprecated?: boolean | string;
+  /** Discord.js compatible: string = link to d.js docs, true = no link */
+  discordJsCompat?: boolean | string;
+  source?: DocSource;
+}
+
+export interface DocSource {
+  file: string;
+  line: number;
+  /** Path relative to repo root, e.g. packages/fluxer-core/src/Client.ts */
+  path?: string;
+}
+
+export interface DocClass {
+  name: string;
+  description?: string;
+  extends?: string;
+  constructor?: DocConstructor;
+  properties: DocProperty[];
+  methods: DocMethod[];
+  source?: DocSource;
+  deprecated?: boolean | string;
+  /** Discord.js compatible: string = link to d.js docs, true = no link */
+  discordJsCompat?: boolean | string;
+}
+
+export interface DocInterfaceProperty {
+  name: string;
+  type: string;
+  optional?: boolean;
+  description?: string;
+}
+
+export interface DocInterface {
+  name: string;
+  description?: string;
+  properties: DocInterfaceProperty[];
+  source?: DocSource;
+}
+
+export interface DocEnumMember {
+  name: string;
+  value: string | number;
+}
+
+export interface DocEnum {
+  name: string;
+  description?: string;
+  members: DocEnumMember[];
+  source?: DocSource;
+}
+
+export interface DocOutput {
+  meta: DocMeta;
+  package: string;
+  classes: DocClass[];
+  interfaces: DocInterface[];
+  enums: DocEnum[];
+}

package/core/packages/docgen/src/visitor.ts

@@ -0,0 +1,147 @@
+import * as ts from 'typescript';
+import { relative } from 'path';
+import { DocClass, DocInterface, DocEnum, DocSource } from './schema.js';
+import {
+  extractConstructor,
+  extractProperty,
+  extractMethod,
+  extractGetterProperty,
+  extractInterfaceProperty,
+  extractEnumMember,
+  getDescriptionFromJSDocComment,
+  getDeprecatedFromJSDoc,
+  getDiscordJsCompatFromJSDoc,
+} from './extract.js';
+
+function getJSDoc(node: ts.Node): string {
+  const sourceFile = node.getSourceFile();
+  const text = sourceFile.getFullText();
+  const commentRanges = ts.getLeadingCommentRanges(text, node.getFullStart());
+  if (!commentRanges?.length) return '';
+  const range = commentRanges[commentRanges.length - 1];
+  return text.slice(range.pos, range.end);
+}
+
+function getSource(node: ts.Node, repoRoot?: string): DocSource {
+  const sourceFile = node.getSourceFile();
+  const { line } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+  const fileName = sourceFile.fileName.split(/[/\\]/).pop() ?? '';
+  const result: DocSource = { file: fileName, line: line + 1 };
+  if (repoRoot) {
+    const rel = relative(repoRoot, sourceFile.fileName);
+    result.path = rel.replace(/\\/g, '/');
+  }
+  return result;
+}
+
+function isExported(node: ts.Node): boolean {
+  return !!(
+    ts.getCombinedModifierFlags(node as ts.Declaration) & ts.ModifierFlags.Export ||
+    (node.parent &&
+      ts.isSourceFile(node.parent) &&
+      (node as ts.Declaration).modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword))
+  );
+}
+
+export function visitSourceFile(
+  checker: ts.TypeChecker,
+  sourceFile: ts.SourceFile,
+  options?: { repoRoot: string },
+): { classes: DocClass[]; interfaces: DocInterface[]; enums: DocEnum[] } {
+  const classes: DocClass[] = [];
+  const interfaces: DocInterface[] = [];
+  const enums: DocEnum[] = [];
+
+  function visit(node: ts.Node) {
+    if (ts.isClassDeclaration(node)) {
+      const name = node.name?.getText();
+      if (name && isExported(node)) {
+        const comment = getJSDoc(node);
+        const docClass: DocClass = {
+          name,
+          description: getDescriptionFromJSDocComment(comment) || undefined,
+          extends: node.heritageClauses
+            ?.find((c) => c.token === ts.SyntaxKind.ExtendsKeyword)
+            ?.types?.[0]?.expression?.getText(),
+          constructor: undefined,
+          properties: [],
+          methods: [],
+          source: getSource(node, options?.repoRoot),
+          deprecated: getDeprecatedFromJSDoc(comment),
+          discordJsCompat: getDiscordJsCompatFromJSDoc(comment),
+        };
+
+        for (const member of node.members) {
+          if (ts.isConstructorDeclaration(member)) {
+            docClass.constructor = extractConstructor(checker, member);
+          } else if (ts.isPropertyDeclaration(member)) {
+            const prop = extractProperty(checker, member);
+            if (prop) docClass.properties.push(prop);
+          } else if (ts.isGetAccessor(member)) {
+            const prop = extractGetterProperty(checker, member);
+            if (prop) docClass.properties.push(prop);
+          } else if (ts.isSetAccessor(member)) {
+            // Setters are not documented as separate properties
+          } else if (ts.isMethodDeclaration(member)) {
+            const method = extractMethod(checker, member);
+            if (method) docClass.methods.push(method);
+          }
+        }
+
+        docClass.properties.sort((a, b) => a.name.localeCompare(b.name));
+        docClass.methods.sort((a, b) => a.name.localeCompare(b.name));
+        classes.push(docClass);
+      }
+    } else if (ts.isInterfaceDeclaration(node)) {
+      const name = node.name.getText();
+      if (isExported(node)) {
+        const comment = getJSDoc(node);
+        const docInterface: DocInterface = {
+          name,
+          description: getDescriptionFromJSDocComment(comment) || undefined,
+          properties: [],
+          source: getSource(node, options?.repoRoot),
+        };
+
+        for (const member of node.members) {
+          if (ts.isPropertySignature(member)) {
+            const prop = extractInterfaceProperty(checker, member);
+            if (prop) docInterface.properties.push(prop);
+          }
+        }
+
+        docInterface.properties.sort((a, b) => a.name.localeCompare(b.name));
+        interfaces.push(docInterface);
+      }
+    } else if (ts.isEnumDeclaration(node)) {
+      const name = node.name.getText();
+      if (isExported(node)) {
+        const comment = getJSDoc(node);
+        const docEnum: DocEnum = {
+          name,
+          description: getDescriptionFromJSDocComment(comment) || undefined,
+          members: node.members.map(extractEnumMember),
+          source: getSource(node, options?.repoRoot),
+        };
+        enums.push(docEnum);
+      }
+    } else if (ts.isTypeAliasDeclaration(node)) {
+      const name = node.name.getText();
+      if (isExported(node)) {
+        const comment = getJSDoc(node);
+        const docInterface: DocInterface = {
+          name,
+          description: getDescriptionFromJSDocComment(comment) || undefined,
+          properties: [],
+          source: getSource(node, options?.repoRoot),
+        };
+        interfaces.push(docInterface);
+      }
+    }
+
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sourceFile);
+  return { classes, interfaces, enums };
+}

package/core/packages/docgen/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "noEmit": false
+  },
+  "include": ["src/**/*"]
+}

package/core/packages/docgen/tsup.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['cjs', 'esm'],
+  dts: true,
+  splitting: false,
+  clean: true,
+});

package/core/packages/fluxer-core/README.md

@@ -0,0 +1,26 @@
+# @erinjs/core
+
+Main client for the Fluxer bot SDK.
+
+## Install
+
+```bash
+npm install @erinjs/core
+```
+
+## Usage
+
+```javascript
+import { Client, Events } from '@erinjs/core';
+
+const client = new Client({ intents: 0 });
+
+client.on(Events.Ready, () => console.log('Ready'));
+client.on(Events.MessageCreate, async (m) => {
+  if (m.content === '!ping') await m.reply('Pong');
+});
+
+await client.login(process.env.FLUXER_BOT_TOKEN);
+```
+
+For voice, add `@erinjs/voice`. For embeds, use `EmbedBuilder`.