Skip to main content

appstruct_codegen/web/
symbols.rs

1use appstruct_ir::{AppIr, Diagnostic, SourceSpan};
2use oxc_allocator::Allocator;
3use oxc_ast::ast::{
4    BindingPattern, Declaration, Expression, ObjectPropertyKind, PropertyKey, Statement,
5};
6use oxc_parser::Parser;
7use oxc_span::{GetSpan, SourceType, Span};
8use std::collections::BTreeSet;
9use std::fs;
10use std::path::{Path, PathBuf};
11
12const REGISTRY_CANDIDATES: &[&str] = &[
13    "app/web/registry.ts",
14    "app/web/registry.tsx",
15    "app/web/registry/index.ts",
16    "app/web/registry/index.tsx",
17];
18
19/// Symbols the user must provide under `app/web/` for the App Spec to build.
20#[derive(Clone, Debug, Default, PartialEq, Eq)]
21pub struct RequiredSymbols {
22    pub field_components: BTreeSet<String>,
23    pub page_components: BTreeSet<String>,
24}
25
26impl RequiredSymbols {
27    #[must_use]
28    pub fn is_empty(&self) -> bool {
29        self.field_components.is_empty() && self.page_components.is_empty()
30    }
31}
32
33#[derive(Clone, Debug, Default, PartialEq, Eq)]
34struct ProvidedSymbols {
35    field_components: BTreeSet<String>,
36    page_components: BTreeSet<String>,
37}
38
39enum RegistryScan {
40    Conclusive {
41        provided: ProvidedSymbols,
42        span: Span,
43    },
44    Inconclusive,
45}
46
47/// Collects every custom component referenced by the App Spec.
48#[must_use]
49pub fn required_symbols(ir: &AppIr) -> RequiredSymbols {
50    let field_components = ir
51        .entities
52        .iter()
53        .flat_map(|entity| &entity.fields)
54        .filter_map(|field| field.ui_component.clone())
55        .collect();
56    let page_components = ir.pages.iter().map(|page| page.component.clone()).collect();
57    RequiredSymbols {
58        field_components,
59        page_components,
60    }
61}
62
63/// Parses the registry module imported by the generated entry point and reports missing keys.
64///
65/// Syntax errors, re-exports, and dynamic registry shapes make the cheap check inconclusive. The
66/// build stage remains authoritative because it runs TypeScript module resolution and type checking.
67///
68/// # Errors
69///
70/// Returns an error when an existing registry module cannot be read.
71pub fn check_user_symbols(project: &Path, ir: &AppIr) -> Result<Vec<Diagnostic>, std::io::Error> {
72    let required = required_symbols(ir);
73    if required.is_empty() {
74        return Ok(Vec::new());
75    }
76    let Some(path) = registry_path(project) else {
77        let span = fallback_span(project);
78        return Ok(missing_diagnostics(
79            ir,
80            &required,
81            &ProvidedSymbols::default(),
82            &span,
83        ));
84    };
85    let source = fs::read_to_string(&path)?;
86    let RegistryScan::Conclusive { provided, span } = scan_registry(&path, &source) else {
87        return Ok(Vec::new());
88    };
89    let span = source_span(project, &path, &source, span);
90    Ok(missing_diagnostics(ir, &required, &provided, &span))
91}
92
93fn registry_path(project: &Path) -> Option<PathBuf> {
94    REGISTRY_CANDIDATES
95        .iter()
96        .map(|path| project.join(path))
97        .find(|path| path.is_file())
98}
99
100fn scan_registry(path: &Path, source: &str) -> RegistryScan {
101    let allocator = Allocator::default();
102    let source_type = SourceType::from_path(path).unwrap_or_else(|_| SourceType::tsx());
103    let parsed = Parser::new(&allocator, source, source_type).parse();
104    if !parsed.diagnostics.is_empty() {
105        return RegistryScan::Inconclusive;
106    }
107    let mut initializer = None;
108    let mut local_export = None;
109    for statement in &parsed.program.body {
110        match statement {
111            Statement::ExportAllDeclaration(_) => {
112                return RegistryScan::Inconclusive;
113            }
114            Statement::ExportFromDeclaration(export)
115                if export
116                    .specifiers
117                    .iter()
118                    .any(|specifier| specifier.exported.name().as_str() == "registry") =>
119            {
120                return RegistryScan::Inconclusive;
121            }
122            Statement::ExportDeclaration(export) => {
123                if let Some(expression) = declaration_initializer(&export.declaration, "registry")
124                    && initializer.replace(expression).is_some()
125                {
126                    return RegistryScan::Inconclusive;
127                }
128            }
129            Statement::ExportNamedDeclaration(export) => {
130                for specifier in &export.specifiers {
131                    if specifier.exported.name().as_str() == "registry" {
132                        local_export = Some(specifier.local.name().to_string());
133                    }
134                }
135            }
136            _ => {}
137        }
138    }
139    if initializer.is_none()
140        && let Some(local) = local_export
141    {
142        initializer = parsed
143            .program
144            .body
145            .iter()
146            .find_map(|statement| statement_initializer(statement, &local));
147        if initializer.is_none() {
148            return RegistryScan::Inconclusive;
149        }
150    }
151    let Some(initializer) = initializer else {
152        return RegistryScan::Conclusive {
153            provided: ProvidedSymbols::default(),
154            span: Span::new(0, 0),
155        };
156    };
157    let span = initializer.span();
158    let Some(provided) = collect_registry(initializer) else {
159        return RegistryScan::Inconclusive;
160    };
161    RegistryScan::Conclusive { provided, span }
162}
163
164fn statement_initializer<'a>(
165    statement: &'a Statement<'a>,
166    name: &str,
167) -> Option<&'a Expression<'a>> {
168    match statement {
169        Statement::VariableDeclaration(declaration) => variable_initializer(declaration, name),
170        _ => None,
171    }
172}
173
174fn declaration_initializer<'a>(
175    declaration: &'a Declaration<'a>,
176    name: &str,
177) -> Option<&'a Expression<'a>> {
178    match declaration {
179        Declaration::VariableDeclaration(declaration) => variable_initializer(declaration, name),
180        _ => None,
181    }
182}
183
184fn variable_initializer<'a>(
185    declaration: &'a oxc_ast::ast::VariableDeclaration<'a>,
186    name: &str,
187) -> Option<&'a Expression<'a>> {
188    declaration.declarations.iter().find_map(|declarator| {
189        let BindingPattern::BindingIdentifier(identifier) = &declarator.id else {
190            return None;
191        };
192        (identifier.name.as_str() == name)
193            .then_some(declarator.init.as_ref())
194            .flatten()
195    })
196}
197
198fn collect_registry(expression: &Expression<'_>) -> Option<ProvidedSymbols> {
199    let expression = unwrap_registry_expression(expression)?;
200    let Expression::ObjectExpression(object) = expression else {
201        return None;
202    };
203    let mut provided = ProvidedSymbols::default();
204    for property in &object.properties {
205        let ObjectPropertyKind::ObjectProperty(property) = property else {
206            return None;
207        };
208        let name = static_property_name(&property.key)?;
209        match name {
210            "fields" => {
211                provided.field_components = collect_component_keys(&property.value)?;
212            }
213            "pages" => {
214                provided.page_components = collect_component_keys(&property.value)?;
215            }
216            _ => {}
217        }
218    }
219    Some(provided)
220}
221
222fn unwrap_registry_expression<'a>(expression: &'a Expression<'a>) -> Option<&'a Expression<'a>> {
223    let expression = expression.get_inner_expression();
224    let Expression::CallExpression(call) = expression else {
225        return Some(expression);
226    };
227    let Expression::Identifier(callee) = &call.callee else {
228        return None;
229    };
230    if callee.name.as_str() != "defineAppStructRegistry" {
231        return None;
232    }
233    let argument = call.arguments.first()?.as_expression()?;
234    Some(argument.get_inner_expression())
235}
236
237fn collect_component_keys(expression: &Expression<'_>) -> Option<BTreeSet<String>> {
238    let Expression::ObjectExpression(object) = expression.get_inner_expression() else {
239        return None;
240    };
241    let mut names = BTreeSet::new();
242    for property in &object.properties {
243        let ObjectPropertyKind::ObjectProperty(property) = property else {
244            return None;
245        };
246        names.insert(static_property_name(&property.key)?.to_owned());
247    }
248    Some(names)
249}
250
251fn static_property_name<'key>(key: &'key PropertyKey<'_>) -> Option<&'key str> {
252    match key {
253        PropertyKey::StaticIdentifier(identifier) => Some(identifier.name.as_str()),
254        PropertyKey::StringLiteral(literal) => Some(literal.value.as_str()),
255        _ => None,
256    }
257}
258
259fn missing_diagnostics(
260    ir: &AppIr,
261    required: &RequiredSymbols,
262    provided: &ProvidedSymbols,
263    span: &SourceSpan,
264) -> Vec<Diagnostic> {
265    let mut diagnostics = Vec::new();
266    for page in &ir.pages {
267        if required.page_components.contains(&page.component)
268            && !provided.page_components.contains(&page.component)
269        {
270            diagnostics.push(Diagnostic::error(
271                "AS3106",
272                format!(
273                    "page `{}` references component `{}`, which is missing from `registry.pages`",
274                    page.id, page.component
275                ),
276                span.clone(),
277            ));
278        }
279    }
280    for entity in &ir.entities {
281        for field in &entity.fields {
282            let Some(component) = &field.ui_component else {
283                continue;
284            };
285            if !provided.field_components.contains(component) {
286                diagnostics.push(Diagnostic::error(
287                    "AS3107",
288                    format!(
289                        "field `{}` references UI component `{component}`, which is missing from `registry.fields`",
290                        field.id
291                    ),
292                    span.clone(),
293                ));
294            }
295        }
296    }
297    diagnostics
298}
299
300fn fallback_span(project: &Path) -> SourceSpan {
301    let path = project.join("appstruct.yaml");
302    SourceSpan {
303        file: relative_path(project, &path),
304        start: 0,
305        end: 0,
306        line: 1,
307        column: 1,
308        end_line: 1,
309        end_column: 1,
310    }
311}
312
313fn source_span(project: &Path, path: &Path, source: &str, span: Span) -> SourceSpan {
314    let start = span.start as usize;
315    let end = span.end as usize;
316    let (line, column) = line_column(source, start);
317    let (end_line, end_column) = line_column(source, end);
318    SourceSpan {
319        file: relative_path(project, path),
320        start,
321        end,
322        line,
323        column,
324        end_line,
325        end_column,
326    }
327}
328
329fn relative_path(project: &Path, path: &Path) -> String {
330    path.strip_prefix(project)
331        .unwrap_or(path)
332        .to_string_lossy()
333        .replace('\\', "/")
334}
335
336fn line_column(source: &str, offset: usize) -> (usize, usize) {
337    let prefix = &source[..offset.min(source.len())];
338    let line = prefix.bytes().filter(|byte| *byte == b'\n').count() + 1;
339    let column = prefix
340        .rsplit_once('\n')
341        .map_or(prefix, |(_, tail)| tail)
342        .chars()
343        .count()
344        + 1;
345    (line, column)
346}
347
348#[cfg(test)]
349mod tests;