@erinjs/core 1.0.0 → 1.2.4

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

@@ -1,262 +0,0 @@
-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

@@ -1,24 +0,0 @@
-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

@@ -1,103 +0,0 @@
-#!/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

@@ -1,100 +0,0 @@
-/**
- * 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

@@ -1,147 +0,0 @@
-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

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

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

@@ -1,9 +0,0 @@
-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

@@ -1,26 +0,0 @@
-# @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`.