Skip to main content

runec/
sources.rs

1//! Source discovery and visibility independent of developer-chosen folders.
2use crate::parallel::parallel_map;
3use crate::parser::Expr;
4use crate::symbol::{SymbolKind, SymbolRegistry};
5use crate::symloader::{Comments, collect_all_files};
6use crate::types::Type;
7use std::collections::HashMap;
8use std::fs;
9use std::io;
10use std::io::BufRead;
11use std::path::{Path, PathBuf};
12
13#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
14pub enum Scope {
15    Rune = 1,
16    Client = 2,
17    Global = 4,
18    Lobby = 8,
19}
20
21impl Scope {
22    pub fn folder(self) -> &'static str {
23        match self {
24            Self::Rune => "runescript",
25            Self::Client => "clientscript",
26            Self::Global => "globalscript",
27            Self::Lobby => "lobbyscript",
28        }
29    }
30
31    pub fn extension(self) -> &'static str {
32        match self {
33            Self::Rune => "rs2",
34            Self::Client => "cs2",
35            Self::Global => "gs2",
36            Self::Lobby => "ls2",
37        }
38    }
39
40    pub fn from_path(path: &Path) -> Option<Self> {
41        match path.extension()?.to_str()? {
42            "rs2" => Some(Self::Rune),
43            "cs2" => Some(Self::Client),
44            "gs2" => Some(Self::Global),
45            "ls2" => Some(Self::Lobby),
46            _ => None,
47        }
48    }
49
50    /// Scripts use their extension. Configs and constants default to shared;
51    /// a leading `// @scope(server|client|lobby|shared)` comment can restrict them.
52    pub fn for_file(path: &Path, text: &str) -> io::Result<Self> {
53        if let Some(scope) = Self::from_path(path) {
54            return Ok(scope);
55        }
56        let mut scope = None;
57        for line in text.lines() {
58            let line = line.trim().trim_start_matches('\u{feff}');
59            if line.is_empty() {
60                continue;
61            }
62            let Some(comment) = line.strip_prefix("//") else {
63                break;
64            };
65            let Some(value) = comment.trim().strip_prefix("@scope") else {
66                continue;
67            };
68            let value = value
69                .trim()
70                .strip_prefix('(')
71                .and_then(|v| v.strip_suffix(')'));
72            let declared = match value.map(str::trim) {
73                Some("server") => Self::Rune,
74                Some("client") => Self::Client,
75                Some("lobby") => Self::Lobby,
76                Some("shared") => Self::Global,
77                _ => {
78                    return Err(io::Error::new(
79                        io::ErrorKind::InvalidData,
80                        format!(
81                            "{}: expected // @scope(server|client|lobby|shared)",
82                            path.display()
83                        ),
84                    ));
85                }
86            };
87            if scope.replace(declared).is_some() {
88                return Err(io::Error::new(
89                    io::ErrorKind::InvalidData,
90                    format!("{}: duplicate @scope declaration", path.display()),
91                ));
92            }
93        }
94        Ok(scope.unwrap_or(Self::Global))
95    }
96}
97
98/// A revision's scripts tree, including when a caller supplies an old target
99/// subdirectory. Standalone projects can use any explicitly supplied root.
100pub fn source_root(dir: &Path) -> PathBuf {
101    dir.ancestors()
102        .find(|path| path.file_name().is_some_and(|name| name == "scripts"))
103        .unwrap_or(dir)
104        .to_path_buf()
105}
106
107pub(crate) fn target_dir(dir: &Path, _scope: Scope) -> PathBuf {
108    source_root(dir)
109}
110
111/// All targets share the same root; extensions select their script sources.
112pub fn roots(dir: &Path) -> Vec<PathBuf> {
113    vec![source_root(dir)]
114}
115
116pub fn config_files(dir: &Path) -> Vec<PathBuf> {
117    let mut files = Vec::new();
118    for root in roots(dir) {
119        collect_all_files(&root, &mut files);
120    }
121    files.sort();
122    files
123}
124
125fn file_scope(path: &Path) -> io::Result<Scope> {
126    if let Some(scope) = Scope::from_path(path) {
127        return Ok(scope);
128    }
129    let mut header = String::new();
130    for line in io::BufReader::new(fs::File::open(path)?).lines() {
131        let line = line?;
132        let trimmed = line.trim().trim_start_matches('\u{feff}');
133        if !trimmed.is_empty() && !trimmed.starts_with("//") {
134            break;
135        }
136        header.push_str(&line);
137        header.push('\n');
138    }
139    Scope::for_file(path, &header)
140}
141
142/// Read only the configs a target can use. Ownership indexing still sees all
143/// declarations, so opposite-target references receive visibility errors.
144pub fn target_config_files(dir: &Path, target: Scope) -> io::Result<Vec<PathBuf>> {
145    let mut files = Vec::new();
146    for path in config_files(dir) {
147        if crate::filesystem::config_kind(&path).is_none() {
148            continue;
149        }
150        let scope = file_scope(&path)?;
151        if scope == Scope::Global || scope == target {
152            files.push(path);
153        }
154    }
155    Ok(files)
156}
157
158pub fn script_files(dir: &Path, extension: &str) -> io::Result<Vec<PathBuf>> {
159    let root = source_root(dir);
160    // Report a missing source root instead of silently compiling nothing.
161    fs::read_dir(&root)?;
162    let mut files = config_files(&root);
163    files.retain(|path| {
164        path.extension()
165            .and_then(|ext| ext.to_str())
166            .is_some_and(|ext| ext == extension || (ext == "gs2" && extension != "ls2"))
167    });
168    Ok(files)
169}
170
171/// Locate an engine declaration by its filename, wherever it is organized.
172pub fn engine_file(dir: &Path, scope: Scope) -> io::Result<Option<PathBuf>> {
173    let name = format!("engine.{}", scope.extension());
174    let mut matches = config_files(dir)
175        .into_iter()
176        .filter(|path| path.file_name().is_some_and(|file| file == name.as_str()));
177    let first = matches.next();
178    if let Some(second) = matches.next() {
179        return Err(io::Error::new(
180            io::ErrorKind::InvalidData,
181            format!(
182                "Multiple {name} files: {} and {}",
183                first.as_ref().unwrap().display(),
184                second.display(),
185            ),
186        ));
187    }
188    Ok(first)
189}
190
191/// Pack registries assign IDs; source declarations grant visibility. Keeping
192/// this separate prevents stale or opposite-target pack entries granting access.
193#[derive(Debug, Clone, Default)]
194pub struct Visibility {
195    active: bool,
196    documents: HashMap<PathBuf, Scope>,
197    owners: HashMap<String, HashMap<String, u8>>,
198    ids: HashMap<(Type, i32), String>,
199}
200
201/// The `(kind, name)` pairs a source or config file declares.
202fn declarations(file: &Path) -> Vec<(String, String)> {
203    let mut declared = Vec::new();
204    let Some(ext) = file.extension().and_then(|ext| ext.to_str()) else {
205        return declared;
206    };
207    let is_script = matches!(ext, "rs2" | "cs2" | "gs2" | "ls2");
208    if !is_script
209        && ext != "constant"
210        && !Type::from_name(ext).is_some_and(|ty| config_kind(ty).is_some())
211    {
212        return declared;
213    }
214    let Ok(input) = fs::File::open(file) else {
215        return declared;
216    };
217    let mut declare = |kind: &str, name: &str| declared.push((kind.to_owned(), name.to_owned()));
218    let mut input = io::BufReader::new(input);
219    let mut buffer = String::new();
220    let mut comments = Comments::default();
221    loop {
222        buffer.clear();
223        if !input.read_line(&mut buffer).is_ok_and(|count| count > 0) {
224            break;
225        }
226        let Some(line) = comments.line(&buffer) else {
227            continue;
228        };
229        if is_script {
230            if let Some(header) = line.strip_prefix('[').and_then(|line| line.split_once(']'))
231                && let Some((trigger, name)) = header.0.split_once(',')
232                && trigger.trim() != "command"
233            {
234                declare(trigger.trim(), name.trim());
235            }
236        } else if ext == "constant" {
237            if let Some((name, _)) = line.split_once('=') {
238                declare("constant", name.trim().trim_start_matches('^'));
239            }
240        } else if let Some(name) = line
241            .strip_prefix('[')
242            .and_then(|line| line.strip_suffix(']'))
243        {
244            if ext == "varc" {
245                declare("varc", name);
246                declare("varcstr", name);
247            } else if ext == "varclan" {
248                for kind in ["varclan", "varclan_bit", "varclan_long", "varclan_string"] {
249                    declare(kind, name);
250                }
251            } else if ext == "varclansetting" {
252                for kind in [
253                    "varclansetting",
254                    "clansetting_int",
255                    "clansetting_varbit",
256                    "clansetting_long",
257                    "clansetting_string",
258                ] {
259                    declare(kind, name);
260                }
261            } else {
262                declare(ext, name);
263            }
264        }
265    }
266    declared
267}
268
269/// Script declarations, as opposed to configs, constants and game vars.
270fn script_kind(kind: &str) -> bool {
271    (crate::trigger_table::is_valid_trigger(kind)
272        || crate::clientscript::triggers::lookup(kind).is_some())
273        && !Type::from_name(kind).is_some_and(|ty| config_kind(ty).is_some())
274}
275
276fn config_kind(ty: Type) -> Option<&'static str> {
277    match ty {
278        Type::NamedObj | Type::Obj => Some("obj"),
279        Type::IdKit => Some("idk"),
280        Type::MapElement => Some("mel"),
281        Type::DbColumn => Some("dbtable"),
282        Type::Npc
283        | Type::Loc
284        | Type::Seq
285        | Type::Spotanim
286        | Type::MesAnim
287        | Type::Inv
288        | Type::Enum
289        | Type::Struct
290        | Type::Param
291        | Type::DbTable
292        | Type::DbRow
293        | Type::Varp
294        | Type::Varn
295        | Type::Vars
296        | Type::VarpBit
297        | Type::Hunt
298        | Type::Controller
299        | Type::Hitmark
300        | Type::Area
301        | Type::Bas
302        | Type::Billboard
303        | Type::ParticleEffector
304        | Type::ParticleEmitter
305        | Type::Cursor
306        | Type::Flo
307        | Type::Flu
308        | Type::ItemCode
309        | Type::Light
310        | Type::Msi
311        | Type::Quest
312        | Type::Varc
313        | Type::VarClan
314        | Type::VarClanSetting
315        | Type::VarCon
316        | Type::VarConBit
317        | Type::VarnBit
318        | Type::VarObj => Some(ty.name()),
319        _ => None,
320    }
321}
322
323impl Visibility {
324    /// Explicit ownership for memory documents and caller-defined namespaces.
325    pub fn new() -> Self {
326        Self {
327            active: true,
328            ..Self::default()
329        }
330    }
331
332    /// Labels are opaque identifiers. No path lookup or filesystem access occurs.
333    pub fn bind(&mut self, label: impl Into<PathBuf>, scope: Scope) {
334        self.active = true;
335        self.documents.insert(label.into(), scope);
336    }
337
338    pub fn unbind(&mut self, label: &Path) {
339        self.documents.remove(label);
340    }
341
342    pub(crate) fn scope(&self, label: &Path) -> Option<Scope> {
343        self.documents
344            .get(label)
345            .copied()
346            .or_else(|| Scope::from_path(label))
347    }
348
349    pub(crate) fn undeclare(&mut self, kind: &str, name: &str, scope: Scope) {
350        if let Some(names) = self.owners.get_mut(kind)
351            && let Some(owners) = names.get_mut(name)
352        {
353            *owners &= !(scope as u8);
354            if *owners == 0 {
355                names.remove(name);
356            }
357        }
358    }
359
360    pub(crate) fn load(dir: &Path, registry: &SymbolRegistry) -> Self {
361        let mut result = Self::scan(dir);
362        result.index_registry(registry);
363        result
364    }
365
366    /// What the sources and configs around `dir` declare, before
367    /// [`index_registry`](Self::index_registry). The files are read in
368    /// parallel and declared in their order.
369    pub(crate) fn scan(dir: &Path) -> Self {
370        let files: Vec<_> = config_files(dir)
371            .into_iter()
372            .filter(|path| {
373                Scope::from_path(path).is_some() || crate::filesystem::config_kind(path).is_some()
374            })
375            .collect();
376        let mut result = Self {
377            active: true,
378            ..Self::default()
379        };
380        for (file, scope, declared) in parallel_map(&files, |file| {
381            (
382                file.clone(),
383                file_scope(file).unwrap_or(Scope::Global),
384                declarations(file),
385            )
386        }) {
387            result.bind(file, scope);
388            for (kind, name) in declared {
389                result.declare(&kind, &name, scope);
390            }
391        }
392        result
393    }
394
395    /// Index typed numeric references after the caller has supplied config IDs.
396    pub fn index_registry(&mut self, registry: &SymbolRegistry) {
397        self.ids.clear();
398        for (name, entry) in &registry.entity_ids {
399            for &(ty, id) in &entry.variants {
400                if config_kind(ty).is_some() || ty == Type::Graphic {
401                    self.ids.insert((ty, id), name.clone());
402                }
403                // Certificate configs are generated by the object packer from
404                // the base object. They inherit its namespace when there is no
405                // explicit certificate definition.
406                if ty == Type::Obj
407                    && let Some(base) = name.strip_prefix("cert_")
408                    && let Some(objects) = self.owners.get_mut("obj")
409                    && let Some(&owner) = objects.get(base)
410                {
411                    objects.entry(name.clone()).or_insert(owner);
412                }
413            }
414        }
415        for (name, symbol) in &registry.game_vars {
416            if let SymbolKind::GameVar {
417                var_id, category, ..
418            } = &symbol.kind
419                && let Some(ty) = Type::from_name(category)
420            {
421                self.ids.insert((ty, *var_id), name.clone());
422            }
423        }
424    }
425
426    pub(crate) fn declare_source(&mut self, path: &Path, file: &crate::parser::ScriptFile) {
427        for script in &file.scripts {
428            self.declare_script(path, &script.trigger, &script.name);
429        }
430    }
431
432    pub(crate) fn declare_script(&mut self, path: &Path, trigger: &str, name: &str) {
433        if let Some(scope) = self.scope(path) {
434            self.declare(trigger, name, scope);
435        }
436    }
437
438    pub(crate) fn declaration(&self, path: &Path, trigger: &str, name: &str) -> Option<String> {
439        self.check(path, trigger, name, false)
440    }
441
442    pub fn declare(&mut self, kind: &str, name: &str, scope: Scope) {
443        let normalized;
444        let name = if Type::from_name(kind).is_some_and(|ty| config_kind(ty).is_some())
445            && !matches!(kind, "varp" | "varpbit" | "varn" | "vars")
446        {
447            normalized = crate::symbol::normalize_entity_name(name);
448            normalized.as_ref()
449        } else {
450            name
451        };
452        *self
453            .owners
454            .entry(kind.to_owned())
455            .or_default()
456            .entry(name.to_owned())
457            .or_default() |= scope as u8;
458    }
459
460    pub(crate) fn check(
461        &self,
462        path: &Path,
463        kind: &str,
464        name: &str,
465        required: bool,
466    ) -> Option<String> {
467        if !self.active {
468            return None;
469        }
470        let scope = self.scope(path)?;
471        let name = if matches!(
472            kind,
473            "varp"
474                | "varpbit"
475                | "varn"
476                | "vars"
477                | "varc"
478                | "varcstr"
479                | "varclan"
480                | "varclan_bit"
481                | "varclan_long"
482                | "varclan_string"
483                | "varobj"
484                | "varnbit"
485                | "varcon"
486                | "varconbit"
487        ) {
488            name.trim_start_matches('.')
489        } else {
490            name
491        };
492        let name = if kind == "dbtable" {
493            name.split(':').next().unwrap_or(name)
494        } else {
495            name
496        };
497        let owners = self
498            .owners
499            .get(kind)
500            .and_then(|names| names.get(name))
501            .copied()
502            .unwrap_or(0);
503        // Lobbyscript shares configs with every target but compiles no .gs2.
504        let script = scope == Scope::Lobby && script_kind(kind);
505        let private = match scope {
506            Scope::Lobby if script => 0,
507            Scope::Lobby => Scope::Lobby as u8,
508            _ => Scope::Rune as u8 | Scope::Client as u8,
509        };
510        if (kind == "constant" || kind == "proc")
511            && owners & Scope::Global as u8 != 0
512            && owners & private != 0
513        {
514            return Some(format!(
515                "{kind} '{name}' is declared in both shared and private scopes; keep one shared declaration"
516            ));
517        }
518        if owners == 0 && !required {
519            return None;
520        }
521        let shared = if script { 0 } else { Scope::Global as u8 };
522        if owners & (scope as u8 | shared) != 0 {
523            return None;
524        }
525        let allowed = if scope == Scope::Global {
526            "a .gs2 source or shared config".to_owned()
527        } else if scope == Scope::Lobby {
528            if script {
529                "a .ls2 source".to_owned()
530            } else {
531                "a .ls2 source, or a shared or @scope(lobby) config".to_owned()
532            }
533        } else {
534            format!(
535                "a .{} or .gs2 source, or a visible config",
536                scope.extension()
537            )
538        };
539        Some(format!(
540            "{kind} '{name}' is not visible to {}; define it in {allowed}",
541            scope.folder()
542        ))
543    }
544
545    pub(crate) fn typed(
546        &self,
547        path: &Path,
548        name: &str,
549        ty: Type,
550        registry: &SymbolRegistry,
551    ) -> Option<String> {
552        if let Some(kind) = config_kind(ty) {
553            let normalized;
554            let name = if !matches!(ty, Type::Varp | Type::VarpBit | Type::Varn | Type::Vars) {
555                normalized = crate::symbol::normalize_entity_name(name);
556                normalized.as_ref()
557            } else {
558                name
559            };
560            return self.check(path, kind, name, true);
561        }
562        match ty {
563            Type::Proc
564            | Type::Label
565            | Type::Queue
566            | Type::Timer
567            | Type::SoftTimer
568            | Type::Walktrigger
569            | Type::ControllerQueue
570            | Type::NpcQueue => self.check(path, ty.name(), name, true),
571            Type::ClientScript => self.check(
572                path,
573                if registry
574                    .lookup_script_by_trigger("clientscript", name)
575                    .is_some()
576                {
577                    "clientscript"
578                } else {
579                    "proc"
580                },
581                name,
582                true,
583            ),
584            _ => None,
585        }
586    }
587
588    pub(crate) fn config_name(&self, ty: Type, id: i32) -> Option<&str> {
589        self.ids.get(&(ty, id)).map(String::as_str)
590    }
591
592    fn numeric(&self, path: &Path, id: i32, ty: Type) -> Option<String> {
593        // Negative sentinels and event placeholders are values, not config IDs.
594        if id < 0 {
595            return None;
596        }
597        let kind = config_kind(ty)?;
598        self.check(
599            path,
600            kind,
601            self.ids
602                .get(&(ty, id))
603                .map(String::as_str)
604                .unwrap_or(&id.to_string()),
605            true,
606        )
607    }
608
609    pub(crate) fn reference(
610        &self,
611        path: &Path,
612        expr: &Expr,
613        hint: Option<Type>,
614        registry: &SymbolRegistry,
615    ) -> Option<String> {
616        if !self.active {
617            return None;
618        }
619        match expr {
620            Expr::GameVar(name, _) => {
621                let kind = match registry.lookup_game_var(name).map(|s| &s.kind) {
622                    Some(SymbolKind::GameVar { category, .. }) => category.as_str(),
623                    _ => return None,
624                };
625                self.check(path, kind, name, true)
626            }
627            Expr::ConstantVar(name, _) => self.check(path, "constant", name, false).or_else(|| {
628                if let Some(SymbolKind::Constant {
629                    int_value: Some(id),
630                    ..
631                }) = registry.lookup_constant(name).map(|s| &s.kind)
632                {
633                    self.numeric(path, *id, hint?)
634                } else {
635                    None
636                }
637            }),
638            Expr::IntLiteral(id) => self.numeric(path, *id, hint?),
639            Expr::StringLiteral(name) => self.typed(path, name, hint?, registry),
640            Expr::Identifier(name) => {
641                if let Some(ty) = hint
642                    && registry.lookup_reference(name, ty).is_some()
643                {
644                    return self.typed(path, name, ty, registry);
645                }
646                if registry.lookup_constant(name).is_some() {
647                    self.reference(path, &Expr::ConstantVar(name.clone(), 0), hint, registry)
648                } else if let Some(entity) = registry.lookup_entity_id(name)
649                    && (entity.const_type != Type::Param
650                        || hint == Some(Type::Param)
651                        || !registry.type_chars.contains_key(name))
652                {
653                    self.typed(path, name, entity.const_type, registry)
654                } else if registry
655                    .lookup_command(name.trim_start_matches('.'))
656                    .is_some()
657                    || registry.type_chars.contains_key(name)
658                {
659                    None
660                } else {
661                    self.typed(path, name, hint?, registry)
662                }
663            }
664            Expr::ProcCall { name, .. } => self.check(
665                path,
666                if registry.lookup_script_by_trigger("proc", name).is_none()
667                    && registry
668                        .lookup_script_by_trigger("clientscript", name)
669                        .is_some()
670                {
671                    "clientscript"
672                } else {
673                    "proc"
674                },
675                name,
676                true,
677            ),
678            Expr::JumpCall { name, .. } => self.check(path, "label", name, true),
679            Expr::BinaryOp {
680                op: crate::parser::BinOp::Add,
681                lhs,
682                rhs,
683            } => {
684                if let (Expr::Identifier(left), Expr::Identifier(right)) =
685                    (lhs.as_ref(), rhs.as_ref())
686                {
687                    let name = format!("{left}+{right}");
688                    if let Some(entity) = registry.lookup_entity_id(&name) {
689                        return self.typed(
690                            path,
691                            &name,
692                            hint.unwrap_or(entity.const_type),
693                            registry,
694                        );
695                    }
696                }
697                None
698            }
699            _ => None,
700        }
701    }
702}