redscript-mc 2.6.2 → 3.0.0

package/src/cli.ts

@@ -5,22 +5,27 @@
  * Usage:
  *   redscript compile <file> [-o <out>] [--namespace <ns>]
  *   redscript check <file>
+ *   redscript init [project-name]
  *   redscript repl
  *   redscript version
  */
 
-import { compile, checkWithWarnings } from './index'
-import { formatError } from './diagnostics'
-import { parseMcVersion, DEFAULT_MC_VERSION } from './types/mc-version'
+import { compile, checkDetailed } from './index'
+import { DiagnosticError, formatError } from './diagnostics'
+import { parseMcVersion, DEFAULT_MC_VERSION, McVersion } from './types/mc-version'
 import { startRepl } from './repl'
 import { generateDts } from './builtins/metadata'
 import { FileCache } from './cache/index'
 import { DependencyGraph } from './cache/deps'
 import { compileIncremental } from './cache/incremental'
+import { lintFile, formatLintWarning } from './lint/index'
 import * as fs from 'fs'
 import * as path from 'path'
 import * as https from 'https'
 import { execSync } from 'child_process'
+import archiver from 'archiver'
+import { loadProjectConfig, buildTomlTemplate } from './config/project-config'
+import { docsCommand } from './docs'
 
 // Parse command line arguments
 const args = process.argv.slice(2)
@@ -30,20 +35,30 @@ function printUsage(): void {
 RedScript Compiler v2
 
 Usage:
-  redscript compile <file> [-o <out>] [--namespace <ns>]
+  redscript compile <file> [-o <out>] [--namespace <ns>] [--incremental]
+  redscript publish <file> [-o <out.zip>] [--namespace <ns>] [--mc-version <ver>]
   redscript watch <dir> [-o <outdir>] [--namespace <ns>] [--hot-reload <url>]
+  redscript test <file> [--dry-run] [--mc-url <url>]
   redscript check <file>
+  redscript lint <file> [--max-function-lines <n>]
+  redscript init [project-name]
   redscript fmt <file.mcrs> [file2.mcrs ...]
   redscript generate-dts [-o <file>]
+  redscript docs [module] [--list]
   redscript repl
   redscript version
 
 Commands:
   compile       Compile a RedScript file to a Minecraft datapack
+  publish       Compile and package the datapack as a .zip (ready to install in Minecraft)
   watch         Watch a directory for .mcrs file changes, recompile, and hot reload
+  test          Compile and run @test-annotated functions as tests
   check         Check a RedScript file for errors without generating output
+  lint          Statically analyze a RedScript file for potential issues (warnings)
+  init          Scaffold a new RedScript datapack project
   fmt           Auto-format RedScript source files
   generate-dts  Generate builtin function declaration file (builtins.d.mcrs)
+  docs          Open the stdlib documentation website in your browser
   repl          Start an interactive RedScript REPL
   version       Print the RedScript version
   upgrade       Upgrade to the latest version (npm install -g redscript-mc@latest)
@@ -58,6 +73,9 @@ Options:
                          e.g. --mc-version 1.20.2, --mc-version 1.19
   --lenient              Treat type errors as warnings instead of blocking compilation
   --include <dir>        Add a directory to the import search path (repeatable)
+  --incremental          Enable file-level incremental compilation cache
+  --dry-run              (test) Verify compilation only — no MC server connection needed
+  --mc-url <url>         (test) MC server HTTP API URL for running tests live
   -h, --help             Show this help message
 `)
 }
@@ -163,6 +181,14 @@ function parseArgs(args: string[]): {
   mcVersionStr?: string
   lenient?: boolean
   includeDirs?: string[]
+  format?: 'human' | 'json'
+  fmtCheck?: boolean
+  incremental?: boolean
+  maxFunctionLines?: number
+  description?: string
+  dryRun?: boolean
+  mcUrl?: string
+  list?: boolean
 } {
   const result: ReturnType<typeof parseArgs> = {}
   let i = 0
@@ -195,6 +221,33 @@ function parseArgs(args: string[]): {
       if (!result.includeDirs) result.includeDirs = []
       result.includeDirs.push(args[++i])
       i++
+    } else if (arg === '--format') {
+      const format = args[++i]
+      if (format === 'json' || format === 'human') {
+        result.format = format
+      }
+      i++
+    } else if (arg === '--check') {
+      result.fmtCheck = true
+      i++
+    } else if (arg === '--incremental') {
+      result.incremental = true
+      i++
+    } else if (arg === '--max-function-lines') {
+      result.maxFunctionLines = parseInt(args[++i], 10)
+      i++
+    } else if (arg === '--description') {
+      result.description = args[++i]
+      i++
+    } else if (arg === '--dry-run') {
+      result.dryRun = true
+      i++
+    } else if (arg === '--list') {
+      result.list = true
+      i++
+    } else if (arg === '--mc-url') {
+      result.mcUrl = args[++i]
+      i++
     } else if (!result.command) {
       result.command = arg
       i++
@@ -215,6 +268,93 @@ function deriveNamespace(filePath: string): string {
   return basename.toLowerCase().replace(/[^a-z0-9]/g, '_')
 }
 
+function sanitizeProjectName(name: string): string {
+  return name.trim().toLowerCase().replace(/[^a-z0-9]/g, '_')
+}
+
+function buildInitFiles(namespace: string): Record<string, string> {
+  return {
+    'src/main.mcrs': `@load
+fn setup(): void {
+  say("Loaded ${namespace}");
+}
+
+@tick(rate=20)
+fn heartbeat(): void {
+  say("Tick from ${namespace}");
+}
+`,
+    'redscript.toml': buildTomlTemplate(namespace),
+    'redscript.config.json': `${JSON.stringify({
+      namespace,
+      entry: 'src/main.mcrs',
+      outDir: 'dist/',
+      mcVersion: '1.21.4',
+    }, null, 2)}
+`,
+    '.gitignore': `dist/
+.redscript-cache/
+`,
+    'README.md': `# ${namespace}
+
+Minimal RedScript datapack scaffold.
+
+## Quick Start
+
+\`\`\`bash
+redscript compile src/main.mcrs -o dist --namespace ${namespace}
+\`\`\`
+
+Then copy \`dist/\` into your world's datapacks folder and run \`/reload\`.
+
+## Files
+
+- \`src/main.mcrs\` contains \`@load\` and \`@tick\` examples.
+- \`redscript.toml\` stores the project configuration (replaces CLI flags).
+- \`redscript.config.json\` stores legacy project settings.
+`,
+  }
+}
+
+function initCommand(projectName?: string): void {
+  const explicitName = projectName?.trim()
+  const targetDir = explicitName
+    ? path.resolve(process.cwd(), explicitName)
+    : process.cwd()
+  const namespaceSource = explicitName ? path.basename(targetDir) : path.basename(targetDir)
+  const namespace = sanitizeProjectName(namespaceSource)
+
+  if (!namespace) {
+    console.error('Error: Project name must contain at least one letter or number')
+    process.exit(1)
+  }
+
+  if (fs.existsSync(targetDir)) {
+    const stat = fs.statSync(targetDir)
+    if (!stat.isDirectory()) {
+      console.error(`Error: Target path is not a directory: ${targetDir}`)
+      process.exit(1)
+    }
+    if (explicitName && fs.readdirSync(targetDir).length > 0) {
+      console.error(`Error: Target directory is not empty: ${targetDir}`)
+      process.exit(1)
+    }
+  } else {
+    fs.mkdirSync(targetDir, { recursive: true })
+  }
+
+  const files = buildInitFiles(namespace)
+  for (const [relativePath, content] of Object.entries(files)) {
+    const fullPath = path.join(targetDir, relativePath)
+    fs.mkdirSync(path.dirname(fullPath), { recursive: true })
+    fs.writeFileSync(fullPath, content, 'utf-8')
+  }
+
+  console.log(`✓ Initialized RedScript project in ${targetDir}`)
+  console.log(`  Namespace: ${namespace}`)
+  console.log('  Entry: src/main.mcrs')
+}
+
 function compileCommand(
   file: string,
   output: string,
@@ -223,6 +363,7 @@ function compileCommand(
   mcVersionStr?: string,
   lenient = false,
   includeDirs?: string[],
+  incremental = false,
 ): void {
   // Read source file
   if (!fs.existsSync(file)) {
@@ -240,6 +381,42 @@ function compileCommand(
     }
   }
 
+  if (incremental) {
+    const cacheDir = path.join(path.dirname(file), '.redscript-cache')
+    const cache = new FileCache(cacheDir)
+    cache.load()
+    const depGraph = new DependencyGraph()
+
+    const incResult = compileIncremental([file], cache, depGraph, {
+      namespace,
+      output,
+      generateSourceMap: sourceMap,
+      mcVersion,
+      lenient,
+      includeDirs,
+    })
+    if (incResult.errors.size > 0) {
+      const [failedFile, errorMessage] = incResult.errors.entries().next().value as [string, string]
+      const source = fs.existsSync(failedFile) ? fs.readFileSync(failedFile, 'utf-8') : ''
+      console.error(formatError(new Error(errorMessage), source, failedFile))
+      process.exit(1)
+    }
+
+    if (incResult.cached > 0) {
+      const entry = cache.get(path.resolve(file))
+      console.log(`✓ Reused cache for ${file}`)
+      console.log(`  Namespace: ${namespace}`)
+      console.log(`  Files: ${entry?.outputFiles?.length ?? 0}`)
+      return
+    }
+
+    const compiled = incResult.results.get(path.resolve(file))
+    console.log(`✓ Compiled ${file} to ${output}/`)
+    console.log(`  Namespace: ${namespace}`)
+    console.log(`  Files: ${compiled?.files.length ?? 0}`)
+    return
+  }
+
   const source = fs.readFileSync(file, 'utf-8')
 
   try {
@@ -269,7 +446,68 @@ function compileCommand(
   }
 }
 
-function checkCommand(file: string, namespace?: string): void {
+interface CliDiagnostic {
+  severity: 'warning' | 'error'
+  kind: string
+  message: string
+  file?: string
+  line?: number
+  col?: number
+}
+
+function warningToDiagnostic(warning: string, defaultFile?: string): CliDiagnostic {
+  const located = warning.match(/^\[([^\]]+)\]\s+(?:(.*?):)?line (\d+), col (\d+): (.+)$/)
+  if (located) {
+    return {
+      severity: 'warning',
+      kind: located[1],
+      file: located[2] || defaultFile,
+      line: Number(located[3]),
+      col: Number(located[4]),
+      message: located[5],
+    }
+  }
+
+  const simple = warning.match(/^\[([^\]]+)\]\s+(.+)$/)
+  if (simple) {
+    return {
+      severity: 'warning',
+      kind: simple[1],
+      message: simple[2],
+      file: defaultFile,
+    }
+  }
+
+  return {
+    severity: 'warning',
+    kind: 'Warning',
+    message: warning,
+    file: defaultFile,
+  }
+}
+
+function errorToDiagnostic(error: DiagnosticError): CliDiagnostic {
+  return {
+    severity: 'error',
+    kind: error.kind,
+    message: error.message,
+    file: error.location.file,
+    line: error.location.line,
+    col: error.location.col,
+  }
+}
+
+function formatWarningHuman(diagnostic: CliDiagnostic): string {
+  if (diagnostic.file && diagnostic.line && diagnostic.col) {
+    return `${diagnostic.file}:${diagnostic.line}:${diagnostic.col}: warning: [${diagnostic.kind}] ${diagnostic.message}`
+  }
+  if (diagnostic.file) {
+    return `${diagnostic.file}: warning: [${diagnostic.kind}] ${diagnostic.message}`
+  }
+  return `warning: [${diagnostic.kind}] ${diagnostic.message}`
+}
+
+function checkCommand(file: string, namespace?: string, outputFormat: 'human' | 'json' = 'human'): void {
   // Read source file
   if (!fs.existsSync(file)) {
     console.error(`Error: File not found: ${file}`)
@@ -279,18 +517,37 @@ function checkCommand(file: string, namespace?: string): void {
   const source = fs.readFileSync(file, 'utf-8')
 
   const ns = namespace ?? deriveNamespace(file)
-  const result = checkWithWarnings(source, ns, file)
+  const result = checkDetailed(source, ns, file)
+  const warnings = result.warnings.map(w => warningToDiagnostic(w, file))
+  const errors = result.errors.map(errorToDiagnostic)
+  const diagnostics = [...warnings, ...errors]
+  const exitCode = errors.length > 0 ? 2 : warnings.length > 0 ? 1 : 0
+
+  if (outputFormat === 'json') {
+    console.log(JSON.stringify({
+      file,
+      namespace: ns,
+      diagnostics,
+      summary: {
+        warnings: warnings.length,
+        errors: errors.length,
+      },
+    }, null, 2))
+  } else {
+    for (const warning of warnings) {
+      console.error(formatWarningHuman(warning))
+    }
 
-  for (const w of result.warnings) {
-    console.error(`Warning: ${w}`)
-  }
+    for (const error of result.errors) {
+      console.error(formatError(error, source, file))
+    }
 
-  if (result.error) {
-    console.error(formatError(result.error, source, file))
-    process.exit(1)
+    if (exitCode === 0) {
+      console.log('✓ No issues found')
+    }
   }
 
-  console.log(`✓ No errors found`)
+  process.exit(exitCode)
 }
 
 async function hotReload(url: string): Promise<void> {
@@ -345,6 +602,7 @@ function watchCommand(dir: string, output: string, namespace?: string, hotReload
     const incResult = compileIncremental(files, cache, depGraph, {
       namespace,
       output,
+      includeDirs: undefined,
     })
 
     const timestamp = new Date().toLocaleTimeString()
@@ -408,6 +666,123 @@ function watchCommand(dir: string, output: string, namespace?: string, hotReload
   })
 }
 
+/**
+ * Map a McVersion enum value to the corresponding pack_format integer.
+ * https://minecraft.wiki/w/Pack_format
+ */
+function mcVersionToPackFormat(version: McVersion): number {
+  // Use a threshold-based mapping (≥ version → pack_format)
+  if (version >= McVersion.v1_21_4) return 48
+  if (version >= McVersion.v1_21)   return 45
+  if (version >= McVersion.v1_20_4) return 26
+  if (version >= McVersion.v1_20_2) return 22
+  if (version >= McVersion.v1_20)   return 18
+  return 15 // 1.19 and below
+}
+
+/**
+ * Read redscript.config.json from the given directory (if it exists).
+ */
+function readConfig(dir: string): Record<string, string> {
+  const configPath = path.join(dir, 'redscript.config.json')
+  if (fs.existsSync(configPath)) {
+    try {
+      return JSON.parse(fs.readFileSync(configPath, 'utf-8'))
+    } catch {
+      // ignore parse errors
+    }
+  }
+  return {}
+}
+
+/**
+ * publish command — compile then zip as a Minecraft datapack.
+ */
+async function publishCommand(
+  file: string,
+  outputZip: string,
+  namespace: string,
+  description: string,
+  mcVersionStr: string | undefined,
+  lenient = false,
+  includeDirs?: string[],
+): Promise<void> {
+  if (!fs.existsSync(file)) {
+    console.error(`Error: File not found: ${file}`)
+    process.exit(1)
+  }
+
+  let mcVersion = DEFAULT_MC_VERSION
+  if (mcVersionStr) {
+    try {
+      mcVersion = parseMcVersion(mcVersionStr)
+    } catch (e) {
+      console.error(`Error: ${(e as Error).message}`)
+      process.exit(1)
+    }
+  }
+
+  const source = fs.readFileSync(file, 'utf-8')
+
+  let compileResult
+  try {
+    compileResult = compile(source, {
+      namespace,
+      filePath: file,
+      generateSourceMap: false,
+      mcVersion,
+      lenient,
+      includeDirs,
+    })
+  } catch (err) {
+    console.error(formatError(err as Error, source, file))
+    process.exit(1)
+  }
+
+  for (const w of compileResult.warnings) {
+    console.error(`Warning: ${w}`)
+  }
+
+  const packFormat = mcVersionToPackFormat(mcVersion)
+  const mcmeta = JSON.stringify({
+    pack: {
+      pack_format: packFormat,
+      description,
+    }
+  }, null, 2)
+
+  // Ensure output directory exists
+  fs.mkdirSync(path.dirname(path.resolve(outputZip)), { recursive: true })
+
+  await new Promise<void>((resolve, reject) => {
+    const output = fs.createWriteStream(outputZip)
+    const archive = archiver('zip', { zlib: { level: 9 } })
+
+    output.on('close', resolve)
+    archive.on('error', reject)
+    archive.pipe(output)
+
+    // Add pack.mcmeta at root
+    archive.append(mcmeta, { name: 'pack.mcmeta' })
+
+    // Add compiled files — skip pack.mcmeta from compile result (we generate our own)
+    // The compile result already produces correct datapack paths, e.g.:
+    //   data/<namespace>/function/setup.mcfunction
+    //   data/minecraft/tags/function/load.json
+    for (const dataFile of compileResult.files) {
+      if (dataFile.path === 'pack.mcmeta') continue
+      archive.append(dataFile.content, { name: dataFile.path })
+    }
+
+    void archive.finalize()
+  })
+
+  console.log(`✓ Published ${file} → ${outputZip}`)
+  console.log(`  Namespace:   ${namespace}`)
+  console.log(`  pack_format: ${packFormat}`)
+  console.log(`  Files:       ${compileResult.files.length}`)
+}
+
 // Main
 const parsed = parseArgs(args)
 
@@ -419,8 +794,8 @@ async function main(): Promise<void> {
 
   // Background update check — non-blocking, only shows notice if newer version exists
   // Skip for repl/upgrade/version to avoid double-printing
-  const noCheckCmds = new Set(['upgrade', 'update', 'version', 'repl'])
-  if (!noCheckCmds.has(parsed.command ?? '')) {
+  const noCheckCmds = new Set(['upgrade', 'update', 'version', 'repl', 'docs'])
+  if (!process.env.REDSCRIPT_NO_UPDATE_CHECK && !noCheckCmds.has(parsed.command ?? '')) {
     checkForUpdates().catch(() => { /* ignore */ })
   }
 
@@ -432,20 +807,77 @@ async function main(): Promise<void> {
         process.exit(1)
       }
       {
-        const namespace = parsed.namespace ?? deriveNamespace(parsed.file)
-        const output = parsed.output ?? './dist'
+        // Load redscript.toml (walk up from file's directory); CLI args take priority
+        const fileDir = path.dirname(path.resolve(parsed.file))
+        const tomlConfig = loadProjectConfig(fileDir)
+
+        const namespace = parsed.namespace
+          ?? tomlConfig?.project?.namespace
+          ?? deriveNamespace(parsed.file)
+        const output = parsed.output
+          ?? tomlConfig?.output?.dir
+          ?? './dist'
+        const mcVersionStr = parsed.mcVersionStr ?? tomlConfig?.project?.['mc-version']
+        const includeDirs = parsed.includeDirs
+          ?? tomlConfig?.compiler?.['include-dirs']
+
+        compileCommand(
+          parsed.file,
+          output,
+          namespace,
+          parsed.sourceMap,
+          mcVersionStr,
+          parsed.lenient,
+          includeDirs,
+          parsed.incremental,
+        )
+      }
+      break
 
-      compileCommand(
-        parsed.file,
-        output,
-        namespace,
-        parsed.sourceMap,
-        parsed.mcVersionStr,
-        parsed.lenient,
-        parsed.includeDirs,
-      )
+    case 'publish': {
+      if (!parsed.file) {
+        console.error('Error: No input file specified')
+        printUsage()
+        process.exit(1)
+      }
+      {
+        // Determine project directory
+        const fileDir = path.dirname(path.resolve(parsed.file))
+        // Load redscript.toml first, fall back to legacy redscript.config.json
+        const tomlConfig = loadProjectConfig(fileDir)
+        const legacyConfig = readConfig(fileDir)
+
+        const namespace = parsed.namespace
+          ?? tomlConfig?.project?.namespace
+          ?? legacyConfig.namespace
+          ?? deriveNamespace(parsed.file)
+        const description = parsed.description
+          ?? tomlConfig?.project?.description
+          ?? legacyConfig.description
+          ?? `${namespace} datapack`
+        const mcVersionStr = parsed.mcVersionStr
+          ?? tomlConfig?.project?.['mc-version']
+          ?? legacyConfig.mcVersion
+        const includeDirs = parsed.includeDirs
+          ?? tomlConfig?.compiler?.['include-dirs']
+
+        // Default output: <namespace>.zip in cwd
+        const defaultZip = path.join(process.cwd(), `${namespace}.zip`)
+        const outputZip = parsed.output
+          ?? (tomlConfig?.output?.dir ? path.join(tomlConfig.output.dir, `${namespace}.zip`) : defaultZip)
+
+        await publishCommand(
+          parsed.file,
+          outputZip,
+          namespace,
+          description,
+          mcVersionStr,
+          parsed.lenient,
+          includeDirs,
+        )
       }
       break
+    }
 
     case 'watch':
       if (!parsed.file) {
@@ -461,13 +893,65 @@ async function main(): Promise<void> {
       )
       break
 
+    case 'test': {
+      if (!parsed.file) {
+        console.error('Error: No input file specified\nUsage: redscript test <file> [--dry-run] [--mc-url <url>]')
+        process.exit(1)
+      }
+      {
+        const { runTests } = require('./testing/runner')
+        const namespace = parsed.namespace ?? deriveNamespace(parsed.file)
+        await runTests({
+          filePath: parsed.file,
+          outputDir: parsed.output,
+          dryRun: parsed.dryRun ?? !parsed.mcUrl,
+          mcUrl: parsed.mcUrl,
+          namespace,
+        })
+      }
+      break
+    }
+
     case 'check':
       if (!parsed.file) {
         console.error('Error: No input file specified')
         printUsage()
         process.exit(1)
       }
-      checkCommand(parsed.file, parsed.namespace)
+      {
+        const fileDir = path.dirname(path.resolve(parsed.file))
+        const tomlConfig = loadProjectConfig(fileDir)
+        const namespace = parsed.namespace ?? tomlConfig?.project?.namespace
+        checkCommand(parsed.file, namespace, parsed.format ?? 'human')
+      }
+      break
+
+    case 'lint':
+      if (!parsed.file) {
+        console.error('Error: No input file specified')
+        printUsage()
+        process.exit(1)
+      }
+      {
+        const namespace = parsed.namespace ?? deriveNamespace(parsed.file)
+        try {
+          const warnings = lintFile(parsed.file, namespace, {
+            maxFunctionLines: parsed.maxFunctionLines,
+          })
+          for (const w of warnings) {
+            console.log(formatLintWarning(w))
+          }
+          if (warnings.length === 0) {
+            console.log('✓ No lint issues found')
+          } else {
+            console.log(`\n${warnings.length} lint issue(s) found`)
+          }
+          process.exit(warnings.length > 0 ? 1 : 0)
+        } catch (err) {
+          console.error(`Error: ${(err as Error).message}`)
+          process.exit(2)
+        }
+      }
       break
 
     case 'fmt':
@@ -478,11 +962,27 @@ async function main(): Promise<void> {
         process.exit(1)
       }
       const { format } = require('./formatter')
+      let changed = 0
       for (const file of files) {
         const content = fs.readFileSync(file, 'utf8')
         const formatted = format(content)
-        fs.writeFileSync(file, formatted)
-        console.log(`Formatted: ${file}`)
+        if (content !== formatted) {
+          changed++
+          if (!parsed.fmtCheck) {
+            fs.writeFileSync(file, formatted)
+            console.log(`Formatted: ${file}`)
+          } else {
+            console.log(`Would format: ${file}`)
+          }
+        } else if (!parsed.fmtCheck) {
+          console.log(`Already formatted: ${file}`)
+        }
+      }
+      if (parsed.fmtCheck) {
+        if (changed > 0) {
+          process.exit(1)
+        }
+        console.log('All files are formatted')
       }
       break
     }
@@ -495,6 +995,10 @@ async function main(): Promise<void> {
       break
     }
 
+    case 'init':
+      initCommand(parsed.file)
+      break
+
     case 'repl':
       await startRepl(parsed.namespace ?? 'repl')
       break
@@ -509,6 +1013,11 @@ async function main(): Promise<void> {
       upgradeCommand()
       break
 
+    case 'docs':
+      // parsed.file holds the positional argument after the command (module name)
+      docsCommand(parsed.file, parsed.list ?? false)
+      break
+
     default:
       console.error(`Error: Unknown command '${parsed.command}'`)
       printUsage()