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