@shiva-fw/cli 1.0.0

package/src/utils/lua-annotations.js

@@ -0,0 +1,319 @@
+'use strict';
+
+/**
+ * LuaLS annotation parser for shiva-cli.
+ *
+ * Parses the following LuaLS annotation tags from Lua source files:
+ *   ---@class  ClassName [: ParentClass]
+ *   ---@field  name type [description]
+ *   ---@param  name type [description]
+ *   ---@return type [name] [description]
+ *   ---@alias  name type
+ *   ---@type   type
+ *
+ * Usage:
+ *   const { parseAnnotations, scanModuleAnnotations } = require('./lua-annotations');
+ *   const api = scanModuleAnnotations('/path/to/module');
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+// ─── Regex patterns ────────────────────────────────────────────────────────────
+
+const RE_CLASS  = /^---@class\s+(\w+)(?:\s*:\s*(\w+))?\s*(?:--\s*(.*))?$/;
+const RE_FIELD  = /^---@field\s+(\w+)\s+(\S+)(?:\s+(.*))?$/;
+const RE_PARAM  = /^---@param\s+(\w+)\s+(\S+)(?:\s+(.*))?$/;
+const RE_RETURN = /^---@return\s+(\S+)(?:\s+(\w+))?(?:\s+(.*))?$/;
+const RE_ALIAS  = /^---@alias\s+(\w+)\s+(\S+)(?:\s+(.*))?$/;
+const RE_FN_DEF = /^(?:local\s+)?function\s+([\w.]+)\s*\(([^)]*)\)/;
+const RE_FN_ASSIGN = /^(?:local\s+)?([\w.]+)\s*=\s*function\s*\(([^)]*)\)/;
+const RE_COMMENT = /^---\s*(.*)/;
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+/**
+ * @typedef {Object} LuaParam
+ * @property {string} name
+ * @property {string} type
+ * @property {string|null} description
+ */
+
+/**
+ * @typedef {Object} LuaReturn
+ * @property {string} type
+ * @property {string|null} name
+ * @property {string|null} description
+ */
+
+/**
+ * @typedef {Object} LuaFunction
+ * @property {string} name
+ * @property {string|null} description
+ * @property {LuaParam[]} params
+ * @property {LuaReturn[]} returns
+ * @property {string} file
+ * @property {number} line
+ */
+
+/**
+ * @typedef {Object} LuaClass
+ * @property {string} name
+ * @property {string|null} parent
+ * @property {string|null} description
+ * @property {Array<{name:string,type:string,description:string|null}>} fields
+ * @property {string} file
+ * @property {number} line
+ */
+
+/**
+ * @typedef {Object} LuaAlias
+ * @property {string} name
+ * @property {string} type
+ * @property {string|null} description
+ */
+
+/**
+ * @typedef {Object} ParseResult
+ * @property {LuaClass[]}    classes
+ * @property {LuaFunction[]} functions
+ * @property {LuaAlias[]}    aliases
+ */
+
+// ─── Core parser ──────────────────────────────────────────────────────────────
+
+/**
+ * Parse LuaLS annotations from a single Lua source string.
+ * @param {string} source      Lua source code
+ * @param {string} [filePath]  Path for source attribution
+ * @returns {ParseResult}
+ */
+function parseAnnotations(source, filePath = '<unknown>') {
+  const lines     = source.split('\n');
+  const classes   = [];
+  const functions = [];
+  const aliases   = [];
+
+  let pendingParams  = /** @type {LuaParam[]} */ ([]);
+  let pendingReturns = /** @type {LuaReturn[]} */ ([]);
+  let pendingDesc    = /** @type {string[]} */    ([]);
+  let currentClass   = /** @type {LuaClass|null} */ (null);
+
+  const flushPending = () => {
+    pendingParams  = [];
+    pendingReturns = [];
+    pendingDesc    = [];
+  };
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+
+    // ── @class ────────────────────────────────────────────────
+    const classMatch = line.match(RE_CLASS);
+    if (classMatch) {
+      const [, name, parent, desc] = classMatch;
+      currentClass = { name, parent: parent || null, description: desc || null, fields: [], file: filePath, line: i + 1 };
+      classes.push(currentClass);
+      flushPending();
+      continue;
+    }
+
+    // ── @field (attached to the last @class) ─────────────────
+    const fieldMatch = line.match(RE_FIELD);
+    if (fieldMatch && currentClass) {
+      const [, name, type, desc] = fieldMatch;
+      currentClass.fields.push({ name, type, description: desc || null });
+      continue;
+    }
+
+    // ── @alias ────────────────────────────────────────────────
+    const aliasMatch = line.match(RE_ALIAS);
+    if (aliasMatch) {
+      const [, name, type, desc] = aliasMatch;
+      aliases.push({ name, type, description: desc || null });
+      flushPending();
+      continue;
+    }
+
+    // ── @param ────────────────────────────────────────────────
+    const paramMatch = line.match(RE_PARAM);
+    if (paramMatch) {
+      const [, name, type, desc] = paramMatch;
+      pendingParams.push({ name, type, description: desc || null });
+      currentClass = null;
+      continue;
+    }
+
+    // ── @return ───────────────────────────────────────────────
+    const returnMatch = line.match(RE_RETURN);
+    if (returnMatch) {
+      const [, type, name, desc] = returnMatch;
+      pendingReturns.push({ type, name: name || null, description: desc || null });
+      currentClass = null;
+      continue;
+    }
+
+    // ── Free-standing doc comment ─────────────────────────────
+    const commentMatch = line.match(RE_COMMENT);
+    if (commentMatch && !line.startsWith('---@')) {
+      pendingDesc.push(commentMatch[1].trim());
+      continue;
+    }
+
+    // ── Function definitions ──────────────────────────────────
+    const fnDef    = line.match(RE_FN_DEF);
+    const fnAssign = line.match(RE_FN_ASSIGN);
+    const fnMatch  = fnDef || fnAssign;
+
+    if (fnMatch) {
+      const name    = fnMatch[1];
+      const rawArgs = fnMatch[2] || '';
+      const args    = rawArgs.split(',').map(s => s.trim()).filter(Boolean);
+      const desc    = pendingDesc.length > 0 ? pendingDesc.join(' ') : null;
+
+      // Merge @param annotations; fill in un-annotated args as unknown
+      const params = args.map(argName => {
+        const annotated = pendingParams.find(p => p.name === argName);
+        return annotated || { name: argName, type: 'any', description: null };
+      });
+
+      // Add any extra @params not matched to positional args (e.g. varargs)
+      for (const p of pendingParams) {
+        if (!params.find(ep => ep.name === p.name)) {
+          params.push(p);
+        }
+      }
+
+      functions.push({
+        name,
+        description: desc,
+        params,
+        returns: [...pendingReturns],
+        file:    filePath,
+        line:    i + 1,
+      });
+
+      flushPending();
+      currentClass = null;
+      continue;
+    }
+
+    // ── Non-annotation, non-function line: reset if not blank ─
+    if (line !== '' && !line.startsWith('---')) {
+      flushPending();
+      if (!line.startsWith('--')) currentClass = null;
+    }
+  }
+
+  return { classes, functions, aliases };
+}
+
+// ─── Scanner ──────────────────────────────────────────────────────────────────
+
+/**
+ * Recursively collect all .lua files in a directory.
+ * @param {string} dir
+ * @param {string[]} [results]
+ * @returns {string[]}
+ */
+function collectLuaFiles(dir, results = []) {
+  if (!fs.existsSync(dir)) return results;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      collectLuaFiles(full, results);
+    } else if (entry.isFile() && entry.name.endsWith('.lua')) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+/**
+ * Scan all Lua files in a module directory and return combined annotations.
+ * @param {string} modulePath  Root path of a Shiva module
+ * @returns {ParseResult}
+ */
+function scanModuleAnnotations(modulePath) {
+  const luaFiles = collectLuaFiles(modulePath);
+  const combined = /** @type {ParseResult} */ ({ classes: [], functions: [], aliases: [] });
+
+  for (const file of luaFiles) {
+    const source = fs.readFileSync(file, 'utf-8');
+    const result = parseAnnotations(source, file);
+    combined.classes.push(...result.classes);
+    combined.functions.push(...result.functions);
+    combined.aliases.push(...result.aliases);
+  }
+
+  return combined;
+}
+
+/**
+ * Generate a Markdown API reference from parsed annotations.
+ * @param {string} moduleName
+ * @param {ParseResult} api
+ * @returns {string}
+ */
+function toMarkdown(moduleName, api) {
+  const lines = [`# ${moduleName} API Reference\n`];
+
+  if (api.classes.length > 0) {
+    lines.push('## Classes\n');
+    for (const cls of api.classes) {
+      const heading = cls.parent ? `### \`${cls.name}\` *(extends ${cls.parent})*` : `### \`${cls.name}\``;
+      lines.push(heading);
+      if (cls.description) lines.push(`\n${cls.description}\n`);
+      if (cls.fields.length > 0) {
+        lines.push('\n**Fields:**\n');
+        lines.push('| Name | Type | Description |');
+        lines.push('|------|------|-------------|');
+        for (const f of cls.fields) {
+          lines.push(`| \`${f.name}\` | \`${f.type}\` | ${f.description || ''} |`);
+        }
+      }
+      lines.push('');
+    }
+  }
+
+  if (api.aliases.length > 0) {
+    lines.push('## Aliases\n');
+    for (const a of api.aliases) {
+      lines.push(`- **\`${a.name}\`** = \`${a.type}\`${a.description ? ' — ' + a.description : ''}`);
+    }
+    lines.push('');
+  }
+
+  if (api.functions.length > 0) {
+    lines.push('## Functions\n');
+    for (const fn of api.functions) {
+      const paramStr = fn.params.map(p => p.name).join(', ');
+      lines.push(`### \`${fn.name}(${paramStr})\``);
+      if (fn.description) lines.push(`\n${fn.description}\n`);
+
+      if (fn.params.length > 0) {
+        lines.push('\n**Parameters:**\n');
+        lines.push('| Name | Type | Description |');
+        lines.push('|------|------|-------------|');
+        for (const p of fn.params) {
+          lines.push(`| \`${p.name}\` | \`${p.type}\` | ${p.description || ''} |`);
+        }
+      }
+
+      if (fn.returns.length > 0) {
+        lines.push('\n**Returns:**\n');
+        for (const r of fn.returns) {
+          const label = r.name ? `\`${r.name}\`` : '';
+          const desc  = r.description || '';
+          lines.push(`- \`${r.type}\`${label ? ' ' + label : ''}${desc ? ' — ' + desc : ''}`);
+        }
+      }
+
+      lines.push(`\n*Defined in: \`${path.basename(fn.file)}\` line ${fn.line}*\n`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = { parseAnnotations, scanModuleAnnotations, collectLuaFiles, toMarkdown };

package/src/utils/lua-parser.js

@@ -0,0 +1,119 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Parse a module.lua manifest file.
+ * Extracts name, version, dependencies etc. using simple regex patterns.
+ * @param {string} filePath
+ * @returns {object}
+ */
+function parseModuleManifest(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+
+  const content = fs.readFileSync(filePath, 'utf-8');
+
+  const result = {
+    name: extractLuaString(content, 'name'),
+    version: extractLuaString(content, 'version'),
+    description: extractLuaString(content, 'description'),
+    author: extractLuaString(content, 'author'),
+    dependencies: extractLuaArray(content, 'dependencies'),
+    events: extractLuaArray(content, 'events'),
+  };
+
+  return result;
+}
+
+/**
+ * Parse an fxmanifest.lua file.
+ * @param {string} filePath
+ * @returns {object}
+ */
+function parseFxManifest(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+
+  const content = fs.readFileSync(filePath, 'utf-8');
+
+  return {
+    fxVersion: extractManifestValue(content, 'fx_version'),
+    game: extractManifestValue(content, 'game'),
+    name: extractManifestValue(content, 'name') || extractManifestValue(content, 'resource'),
+    version: extractManifestValue(content, 'version'),
+    description: extractManifestValue(content, 'description'),
+  };
+}
+
+function extractLuaString(content, key) {
+  const re = new RegExp(`${key}\\s*=\\s*['"]([^'"]+)['"]`);
+  const match = content.match(re);
+  return match ? match[1] : null;
+}
+
+function extractManifestValue(content, key) {
+  const re = new RegExp(`^${key}\\s+['"]([^'"]+)['"]`, 'm');
+  const match = content.match(re);
+  return match ? match[1] : null;
+}
+
+function extractLuaArray(content, key) {
+  const re = new RegExp(`${key}\\s*=\\s*\\{([^}]*)\\}`, 's');
+  const match = content.match(re);
+  if (!match) return [];
+
+  const items = match[1].match(/['"]([^'"]+)['"]/g);
+  if (!items) return [];
+  return items.map(s => s.replace(/['"]/g, ''));
+}
+
+/**
+ * Scan a resources directory for Shiva modules.
+ * Looks for module.lua files under resources/[shiva]/ directories.
+ * @param {string} resourcesDir
+ * @returns {Array<{name: string, path: string, manifest: object}>}
+ */
+function scanModules(resourcesDir) {
+  if (!fs.existsSync(resourcesDir)) return [];
+
+  const modules = [];
+  const shivaDir = path.join(resourcesDir, '[shiva]');
+
+  if (fs.existsSync(shivaDir)) {
+    scanCategoryDir(shivaDir, modules);
+  }
+
+  // Also scan other [category] dirs for compatibility
+  const entries = fs.readdirSync(resourcesDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory() && entry.name.startsWith('[') && entry.name !== '[shiva]') {
+      scanCategoryDir(path.join(resourcesDir, entry.name), modules);
+    }
+  }
+
+  return modules;
+}
+
+function scanCategoryDir(categoryDir, modules) {
+  if (!fs.existsSync(categoryDir)) return;
+  const entries = fs.readdirSync(categoryDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const modulePath = path.join(categoryDir, entry.name);
+    const manifestPath = path.join(modulePath, 'module.lua');
+    const manifest = parseModuleManifest(manifestPath);
+    if (manifest) {
+      modules.push({
+        name: manifest.name || entry.name,
+        path: modulePath,
+        manifest,
+      });
+    }
+  }
+}
+
+module.exports = { parseModuleManifest, parseFxManifest, scanModules };

package/src/utils/server-root.js

@@ -0,0 +1,66 @@
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+
+/**
+ * Walk up directory tree looking for a Shiva server root.
+ * Identifies root by presence of shiva.json or server.cfg.
+ * @param {string} startDir
+ * @returns {string|null}
+ */
+function findServerRoot(startDir = process.cwd()) {
+  let dir = path.resolve(startDir);
+  const { root } = path.parse(dir);
+
+  while (dir !== root) {
+    if (fs.existsSync(path.join(dir, 'shiva.json'))) {
+      return dir;
+    }
+    if (fs.existsSync(path.join(dir, 'server.cfg'))) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  return null;
+}
+
+/**
+ * Get the resources directory for the server root.
+ * @param {string} serverRoot
+ * @returns {string}
+ */
+function getResourcesDir(serverRoot) {
+  return path.join(serverRoot, 'resources');
+}
+
+/**
+ * Get the [shiva] category directory within resources.
+ * Follows FiveM's [category] folder convention.
+ * @param {string} serverRoot
+ * @returns {string}
+ */
+function getShivaModulesDir(serverRoot) {
+  return path.join(serverRoot, 'resources', '[shiva]');
+}
+
+/**
+ * Require a server root or throw a helpful error.
+ * @param {string} [startDir]
+ * @returns {string}
+ */
+function requireServerRoot(startDir = process.cwd()) {
+  const root = findServerRoot(startDir);
+  if (!root) {
+    const chalk = require('chalk');
+    console.error(chalk.red('✖ Could not find a Shiva server root.'));
+    console.error(chalk.yellow('  Run this command from within a Shiva project, or run `shiva init` first.'));
+    process.exit(1);
+  }
+  return root;
+}
+
+module.exports = { findServerRoot, getResourcesDir, getShivaModulesDir, requireServerRoot };