Feature: Lua language analyzer plugin

[marco0560]

Title

Feature: Lua language analyzer plugin

Status

• Type: feature / analyzer plugin
• Priority: high (especially for LuaTeX / TeX ecosystem)

Summary

Add a dedicated Lua language analyzer plugin to Codira to provide first-class support for Lua codebases.

Lua is widely used as an embedded and extension language, and in ecosystems such as LuaTeX / TeXLive it acts as a core development language, not just a scripting layer. Without Lua support, a significant portion of repository logic remains invisible to Codira.

Motivation

In many modern systems, Lua is used for:

• runtime logic
• extension mechanisms
• configuration and orchestration
• domain-specific implementations

In particular, in LuaTeX-based environments:

• Lua drives core processing behavior
• TeX ↔ Lua interaction defines execution flow
• critical features (fonts, callbacks, processing pipelines) are implemented in Lua

Without a Lua analyzer, Codira:

• cannot index or retrieve Lua-defined logic
• cannot answer questions involving Lua execution paths
• produces incomplete repository understanding

Problem

Currently, Codira has no Lua analyzer.

This leads to:

• missing symbols for .lua files
• no module/dependency graph for Lua code
• inability to integrate Lua logic into retrieval and explanation flows

Goal

Introduce a Lua analyzer plugin that:

• parses Lua source files
• extracts deterministic structural information
• integrates with the analyzer/plugin architecture
• aligns with the canonical ontology and capability model

Non-goals

• Full runtime interpretation of Lua
• Execution simulation
• Dynamic analysis (e.g. runtime values, environment-dependent behavior)
• Heuristic guessing of dynamic constructs

Proposed Design

Plugin identity

• name: lua
• version: 1.x
• source: plugin (external package)
• parser: tree-sitter-lua (or equivalent deterministic parser)

File coverage

Initial glob set:

*.lua

Sub-objectives

1. Initial scope (V1 — structural indexing)

Focus on deterministic, high-value structural extraction:

• module-level structure (files as modules)
• function definitions (local and global)
• table-based namespaces (common Lua pattern)
• top-level assignments
• require(...) dependencies (module graph)

Expected output:

• symbols aligned with ontology:
  • module
  • callable
  • namespace (via tables)
  • import (via require)

Constraints:

• no inference of dynamic behavior
• no resolution of runtime-dependent constructs
• degrade deterministically when constructs cannot be resolved

2. Deferred scope (V2+ — semantic enrichment)

Extend the analyzer with deeper Lua semantics:

• improved namespace modeling:
  • table mutation tracking (limited, deterministic cases only)
• detection of method-style definitions (function t:f())
• improved module resolution heuristics (without guessing)
• recognition of common patterns:
  • factory modules
  • returned tables as public API

Ecosystem-specific extensions (optional, if deterministic):

• LuaTeX callback registration patterns
• TeX ↔ Lua interaction points (if stable and modelable)

Explicitly out of scope unless proven deterministic:

• dynamic require resolution
• metatable-driven behavior inference
• runtime state reconstruction

Architecture Notes

• Must be a separate analyzer plugin
• Must not introduce Lua-specific assumptions into core logic
• Must comply with analyzer declaration contract (Issue Deterministic Capability Contract, Canonical Ontology, and Analyzer Declarations #7)
• Must declare:
  • supported ontology types
  • explicitly unsupported types

Testing

• fixture-based tests covering:
  • simple modules
  • function definitions
  • table-based namespaces
  • require dependencies
• regression tests ensuring:
  • deterministic output
  • no interference with other analyzers

Acceptance Criteria

• .lua files are correctly discovered and indexed
• module, function, and dependency structures are extracted
• analyzer integrates with plugin registry
• deterministic output across runs
• no regression in existing analyzers
• capability declaration is complete and explicit

Notes

Lua should be treated as a first-class language, not merely as a scripting add-on.

This plugin is particularly important for:

• LuaTeX / TeXLive ecosystems
• embedded scripting systems
• configuration-driven architectures

It complements other analyzers (e.g. TeX, build systems) to provide a complete view of repository behavior.