appstruct-cli 0.1.0

Command-line compiler and development workflow for AppStruct applications
use appstruct_migrate::{
    IntrospectedColumn, IntrospectedForeignKey, IntrospectedIndex, IntrospectedSchema,
    IntrospectedTable,
};
use std::collections::{BTreeMap, BTreeSet};
use std::fmt::Write;

mod helpers;
#[cfg(test)]
mod tests;

use helpers::{
    field_name, is_now_default, is_sequence_default, render_capabilities, scalar_default,
    singularize, type_name, unique_name, yaml_string,
};

pub(super) struct Draft {
    pub source: String,
    pub entity_count: usize,
    pub warnings: Vec<String>,
}

#[derive(Clone)]
pub(super) enum SpecType {
    Uuid,
    String,
    Text,
    Integer,
    Bigint,
    Decimal,
    Boolean,
    Date,
    Datetime,
    Json,
    Enum(Vec<String>),
    Unsupported(String),
}

struct RenderContext<'schema> {
    entities: BTreeMap<&'schema str, String>,
    relations: BTreeMap<(&'schema str, &'schema str), &'schema IntrospectedForeignKey>,
    warnings: Vec<String>,
}

pub(super) fn render(schema: &IntrospectedSchema) -> Draft {
    let mut context = RenderContext::new(schema);
    let mut source = String::from(
        "# Generated by `appstruct db pull`; review before adding this file to `includes`.\n\
# Access rules are intentionally omitted so imported resources fail closed.\n\
# AppStruct owns the `revision` column used for optimistic concurrency.\n\
domain: imported\n\nentities:\n",
    );
    for table in &schema.tables {
        if let Some(entity) = context.entities.get(table.name.as_str()).cloned() {
            context.render_table(&mut source, table, &entity);
        }
    }
    if context.entities.is_empty() {
        source.push_str("  {}\n");
    }
    Draft {
        source,
        entity_count: context.entities.len(),
        warnings: context.warnings,
    }
}

impl<'schema> RenderContext<'schema> {
    fn new(schema: &'schema IntrospectedSchema) -> Self {
        let mut warnings = Vec::new();
        let mut entities = BTreeMap::new();
        let mut used = BTreeSet::new();
        for table in &schema.tables {
            if table.primary_key.len() != 1 {
                warnings.push(format!(
                    "table `{}` was omitted because it has {} primary-key columns; AppStruct requires exactly one",
                    table.name,
                    table.primary_key.len()
                ));
                continue;
            }
            let key_name = &table.primary_key[0];
            let Some(key) = table.columns.iter().find(|column| &column.name == key_name) else {
                warnings.push(format!(
                    "table `{}` has an unreadable primary key",
                    table.name
                ));
                continue;
            };
            if key.name == "revision" {
                warnings.push(format!(
                    "table `{}` was omitted because `revision` is reserved for AppStruct concurrency control",
                    table.name
                ));
                continue;
            }
            if !spec_type(key).supports_primary_key() {
                warnings.push(format!(
                    "table `{}` was omitted because primary key `{}` uses unsupported type `{}`",
                    table.name, key.name, key.data_type
                ));
                continue;
            }
            let base = type_name(&singularize(&table.name));
            let entity = unique_name(&base, &mut used);
            entities.insert(table.name.as_str(), entity);
        }
        let relations = usable_relations(schema, &entities, &mut warnings);
        Self {
            entities,
            relations,
            warnings,
        }
    }

    fn render_table(&mut self, output: &mut String, table: &IntrospectedTable, entity: &str) {
        let _ = writeln!(output, "  {entity}:");
        let _ = writeln!(output, "    label: {}", yaml_string(entity));
        let _ = writeln!(output, "    table: {}", yaml_string(&table.name));
        output.push_str("    fields:\n");
        let mut used_fields = BTreeSet::new();
        let mut field_names = BTreeMap::new();
        for column in &table.columns {
            if column.name == "revision" {
                continue;
            }
            let relation = self
                .relations
                .get(&(table.name.as_str(), column.name.as_str()))
                .copied();
            let field = self.render_column(output, table, column, relation, &mut used_fields);
            field_names.insert(column.name.as_str(), field);
        }
        let has_indexes = table.unique_constraints.iter().any(|index| index.len() > 1)
            || !table.indexes.is_empty();
        if has_indexes {
            output.push_str("    indexes:\n");
        }
        for unique in &table.unique_constraints {
            if unique.len() > 1 {
                self.render_index(
                    output,
                    &table.name,
                    &IntrospectedIndex {
                        name: format!("{}_{}_unique", table.name, unique.join("_")),
                        columns: unique.clone(),
                        unique: true,
                        predicate: None,
                    },
                    &field_names,
                );
            }
        }
        for index in &table.indexes {
            self.render_index(output, &table.name, index, &field_names);
        }
        output.push('\n');
    }

    fn render_index(
        &mut self,
        output: &mut String,
        table: &str,
        index: &IntrospectedIndex,
        field_names: &BTreeMap<&str, String>,
    ) {
        let Some(fields) = index
            .columns
            .iter()
            .map(|column| field_names.get(column.as_str()).cloned())
            .collect::<Option<Vec<_>>>()
        else {
            self.warnings.push(format!(
                "index `{}` on table `{table}` references an expression or unknown column and needs review",
                index.name
            ));
            return;
        };
        let name = index
            .name
            .strip_prefix("idx_")
            .unwrap_or(index.name.as_str());
        let _ = writeln!(output, "      - name: {}", yaml_string(name));
        let rendered_fields = fields
            .iter()
            .map(|field| yaml_string(field))
            .collect::<Vec<_>>()
            .join(", ");
        let _ = writeln!(output, "        fields: [{rendered_fields}]");
        if index.unique {
            output.push_str("        unique: true\n");
        }
        if let Some(predicate) = &index.predicate {
            let _ = writeln!(output, "        where: {}", yaml_string(predicate));
        }
    }

    fn render_column(
        &mut self,
        output: &mut String,
        table: &IntrospectedTable,
        column: &IntrospectedColumn,
        relation: Option<&IntrospectedForeignKey>,
        used_fields: &mut BTreeSet<String>,
    ) -> String {
        let base = relation.map_or_else(
            || field_name(&column.name),
            |_| field_name(column.name.strip_suffix("_id").unwrap_or(&column.name)),
        );
        let field = unique_name(&base, used_fields);
        let kind = spec_type(column);
        let _ = writeln!(output, "      {field}:");
        if let SpecType::Unsupported(database_type) = &kind {
            let _ = writeln!(
                output,
                "        # TODO: `{database_type}` is represented as a JSON placeholder."
            );
            self.warnings.push(format!(
                "column `{}.{}` uses unsupported PostgreSQL type `{database_type}` and needs review",
                table.name, column.name
            ));
        }
        if column.generated {
            output.push_str("        # TODO: PostgreSQL generated columns require a custom AppStruct extension.\n");
            self.warnings.push(format!(
                "column `{}.{}` is generated by PostgreSQL and needs review",
                table.name, column.name
            ));
        }
        if let Some(key) = relation {
            output.push_str("        type: relation\n");
            if let Some(target) = self.entities.get(key.target_table.as_str()) {
                let _ = writeln!(output, "        target: {target}");
            }
            let _ = writeln!(output, "        column: {}", yaml_string(&column.name));
            if key.on_delete != "no_action" {
                let _ = writeln!(output, "        on_delete: {}", key.on_delete);
            }
        } else {
            let _ = writeln!(output, "        type: {}", kind.name());
            if field != column.name {
                let _ = writeln!(output, "        column: {}", yaml_string(&column.name));
            }
            if let SpecType::Enum(values) = &kind {
                let rendered = values
                    .iter()
                    .map(|value| yaml_string(value))
                    .collect::<Vec<_>>();
                let _ = writeln!(output, "        values: [{}]", rendered.join(", "));
                self.warnings.push(format!(
                    "column `{}.{}` uses a native PostgreSQL enum; review the migration because AppStruct stores enums as text checks",
                    table.name, column.name
                ));
            }
            self.render_default(output, table, column, &kind);
        }
        let primary_key = table.primary_key.as_slice() == std::slice::from_ref(&column.name);
        if primary_key {
            output.push_str("        primary_key: true\n");
        }
        let required = !column.nullable
            && (relation.is_some()
                || (!primary_key && column.default.is_none() && !column.identity));
        if required {
            output.push_str("        required: true\n");
        }
        if table
            .unique_constraints
            .iter()
            .any(|columns| columns.as_slice() == std::slice::from_ref(&column.name))
        {
            output.push_str("        unique: true\n");
        }
        if let Some(length) = column.max_length.filter(|length| *length > 0)
            && matches!(kind, SpecType::String)
        {
            let _ = writeln!(output, "        max_length: {length}");
        }
        render_capabilities(output, &kind, relation.is_some());
        field
    }

    fn render_default(
        &mut self,
        output: &mut String,
        table: &IntrospectedTable,
        column: &IntrospectedColumn,
        kind: &SpecType,
    ) {
        if column.identity || is_sequence_default(column.default.as_deref()) {
            if matches!(kind, SpecType::Integer | SpecType::Bigint) {
                output.push_str("        generated: auto_increment\n");
            }
            return;
        }
        let Some(value) = column.default.as_deref() else {
            return;
        };
        if is_now_default(value) && matches!(kind, SpecType::Date | SpecType::Datetime) {
            output.push_str("        generated: now\n");
        } else if let Some(value) = scalar_default(value, kind) {
            let _ = writeln!(output, "        default: {}", yaml_string(&value));
        } else {
            self.warnings.push(format!(
                "default for `{}.{}` could not be represented and was omitted",
                table.name, column.name
            ));
        }
    }
}

impl SpecType {
    fn name(&self) -> &'static str {
        match self {
            Self::Uuid => "uuid",
            Self::String => "string",
            Self::Text => "text",
            Self::Integer => "integer",
            Self::Bigint => "bigint",
            Self::Decimal => "decimal",
            Self::Boolean => "boolean",
            Self::Date => "date",
            Self::Datetime => "datetime",
            Self::Json | Self::Unsupported(_) => "json",
            Self::Enum(_) => "enum",
        }
    }

    fn supports_primary_key(&self) -> bool {
        matches!(self, Self::Uuid | Self::Integer | Self::Bigint)
    }
}

fn spec_type(column: &IntrospectedColumn) -> SpecType {
    if !column.enum_values.is_empty() {
        return SpecType::Enum(column.enum_values.clone());
    }
    match column.data_type.as_str() {
        "uuid" => SpecType::Uuid,
        "character" | "character varying" => SpecType::String,
        "text" => SpecType::Text,
        "smallint" | "integer" => SpecType::Integer,
        "bigint" => SpecType::Bigint,
        "numeric" | "decimal" | "real" | "double precision" => SpecType::Decimal,
        "boolean" => SpecType::Boolean,
        "date" => SpecType::Date,
        "timestamp with time zone" | "timestamp without time zone" => SpecType::Datetime,
        "json" | "jsonb" => SpecType::Json,
        other => SpecType::Unsupported(other.to_owned()),
    }
}

fn usable_relations<'schema>(
    schema: &'schema IntrospectedSchema,
    entities: &BTreeMap<&'schema str, String>,
    warnings: &mut Vec<String>,
) -> BTreeMap<(&'schema str, &'schema str), &'schema IntrospectedForeignKey> {
    let tables = schema
        .tables
        .iter()
        .map(|table| (table.name.as_str(), table))
        .collect::<BTreeMap<_, _>>();
    let mut relations = BTreeMap::new();
    for key in &schema.foreign_keys {
        let valid = key.source_columns.len() == 1
            && key.target_columns.len() == 1
            && key.target_schema == schema.name
            && entities.contains_key(key.source_table.as_str())
            && entities.contains_key(key.target_table.as_str())
            && tables.get(key.target_table.as_str()).is_some_and(|table| {
                table.primary_key == key.target_columns && key.on_delete != "set_default"
            });
        if valid {
            let relation_key = (key.source_table.as_str(), key.source_columns[0].as_str());
            if relations.insert(relation_key, key).is_some() {
                warnings.push(format!(
                    "column `{}.{}` has multiple foreign keys and needs review",
                    key.source_table, key.source_columns[0]
                ));
            }
        } else {
            warnings.push(format!(
                "foreign key `{}` could not be represented as an AppStruct relation",
                key.name
            ));
        }
    }
    relations
}