sqlode

-module(sqlode@capabilities).
-compile([no_auto_import, nowarn_unused_vars, nowarn_unused_function, nowarn_nomatch, inline]).
-define(FILEPATH, "src/sqlode/capabilities.gleam").
-export([supported_engines/0, supported_runtimes/0, supported_type_mappings/0, fully_supported_query_commands/0, planned_query_commands/0, supported_macros/0, supported_placeholder_styles/0, manifest_markdown/0]).

-if(?OTP_RELEASE >= 27).
-define(MODULEDOC(Str), -moduledoc(Str)).
-define(DOC(Str), -doc(Str)).
-else.
-define(MODULEDOC(Str), -compile([])).
-define(DOC(Str), -compile([])).
-endif.

?MODULEDOC(
    " Single source of truth for the capabilities that sqlode currently\n"
    " advertises to public consumers.\n"
    "\n"
    " `CHANGELOG.md`, `README.md`, and any other release-facing document\n"
    " that needs to claim \"supported X\" values should derive from the\n"
    " lists below or from `manifest_markdown()` instead of restating them\n"
    " by hand. The accompanying `test/capabilities_test.gleam` pins the\n"
    " rendered manifest against the tracked file `doc/capabilities.md` so\n"
    " any change to the supported set forces a conscious doc refresh.\n"
    "\n"
    " The split between fully-supported and planned query commands\n"
    " matches what `generate.gleam` enforces at generation time: the\n"
    " planned commands are currently rejected with an\n"
    " `UnsupportedAnnotation` error, so listing them as \"Added\" without\n"
    " qualification (as `CHANGELOG.md` did before this module) gives a\n"
    " false impression to public users.\n"
).

-file("src/sqlode/capabilities.gleam", 23).
-spec supported_engines() -> list(sqlode@model:engine()).
supported_engines() ->
    [postgre_s_q_l, my_s_q_l, s_q_lite].

-file("src/sqlode/capabilities.gleam", 27).
-spec supported_runtimes() -> list(sqlode@model:runtime()).
supported_runtimes() ->
    [raw, native].

-file("src/sqlode/capabilities.gleam", 31).
-spec supported_type_mappings() -> list(sqlode@model:type_mapping()).
supported_type_mappings() ->
    [string_mapping, rich_mapping, strong_mapping].

-file("src/sqlode/capabilities.gleam", 38).
?DOC(
    " Query annotations that are fully supported end-to-end: parsing,\n"
    " analysis, and code generation all complete without the\n"
    " `validate_unsupported_annotations` guard rejecting them.\n"
).
-spec fully_supported_query_commands() -> list(sqlode@runtime:query_command()).
fully_supported_query_commands() ->
    [query_one,
        query_many,
        query_exec,
        query_exec_result,
        query_exec_rows,
        query_exec_last_id].

-file("src/sqlode/capabilities.gleam", 52).
?DOC(
    " Query annotations that the parser accepts for sqlc source\n"
    " compatibility but that generation currently refuses with an\n"
    " `UnsupportedAnnotation` error.\n"
).
-spec planned_query_commands() -> list(sqlode@runtime:query_command()).
planned_query_commands() ->
    [query_batch_one, query_batch_many, query_batch_exec, query_copy_from].

-file("src/sqlode/capabilities.gleam", 63).
?DOC(
    " Macro helpers sqlode recognises inside query files. Emitted names\n"
    " include the `sqlode.` prefix that appears in user SQL.\n"
).
-spec supported_macros() -> list(binary()).
supported_macros() ->
    [<<"sqlode.arg"/utf8>>,
        <<"sqlode.narg"/utf8>>,
        <<"sqlode.slice"/utf8>>,
        <<"sqlode.embed"/utf8>>].

-file("src/sqlode/capabilities.gleam", 69).
?DOC(
    " Placeholder styles emitted for the three engines sqlode targets.\n"
    " The pair matches the mapping in `codegen/queries.gleam`.\n"
).
-spec supported_placeholder_styles() -> list({sqlode@model:engine(), binary()}).
supported_placeholder_styles() ->
    [{postgre_s_q_l, <<"DollarNumbered"/utf8>>},
        {my_s_q_l, <<"QuestionPositional"/utf8>>},
        {s_q_lite, <<"QuestionNumbered"/utf8>>}].

-file("src/sqlode/capabilities.gleam", 160).
-spec bullet_list(list(binary())) -> binary().
bullet_list(Lines) ->
    case Lines of
        [] ->
            <<"(none)"/utf8>>;

        _ ->
            gleam@string:join(Lines, <<"\n"/utf8>>)
    end.

-file("src/sqlode/capabilities.gleam", 167).
-spec command_annotation(sqlode@runtime:query_command()) -> binary().
command_annotation(Command) ->
    case Command of
        query_one ->
            <<":one"/utf8>>;

        query_many ->
            <<":many"/utf8>>;

        query_exec ->
            <<":exec"/utf8>>;

        query_exec_result ->
            <<":execresult"/utf8>>;

        query_exec_rows ->
            <<":execrows"/utf8>>;

        query_exec_last_id ->
            <<":execlastid"/utf8>>;

        query_batch_one ->
            <<":batchone"/utf8>>;

        query_batch_many ->
            <<":batchmany"/utf8>>;

        query_batch_exec ->
            <<":batchexec"/utf8>>;

        query_copy_from ->
            <<":copyfrom"/utf8>>
    end.

-file("src/sqlode/capabilities.gleam", 81).
?DOC(
    " Render a Markdown manifest that the test suite pins against\n"
    " `doc/capabilities.md`. The generated shape is intentionally stable:\n"
    " adding a new capability changes the file, adding a new *section*\n"
    " changes this function.\n"
).
-spec manifest_markdown() -> binary().
manifest_markdown() ->
    gleam@string:join(
        [<<"# sqlode capability manifest"/utf8>>,
            <<""/utf8>>,
            <<"This file is generated from `src/sqlode/capabilities.gleam` and"/utf8>>,
            <<"verified by `test/capabilities_test.gleam`. Do not edit by hand;"/utf8>>,
            <<"update the capabilities module and run `just regen-capabilities`."/utf8>>,
            <<""/utf8>>,
            <<"## Engines"/utf8>>,
            <<""/utf8>>,
            bullet_list(
                gleam@list:map(
                    supported_engines(),
                    fun(Engine) ->
                        <<<<"- `"/utf8,
                                (sqlode@model:engine_to_string(Engine))/binary>>/binary,
                            "`"/utf8>>
                    end
                )
            ),
            <<""/utf8>>,
            <<"## Runtimes"/utf8>>,
            <<""/utf8>>,
            bullet_list(
                gleam@list:map(
                    supported_runtimes(),
                    fun(Runtime) ->
                        <<<<"- `"/utf8,
                                (sqlode@model:runtime_to_string(Runtime))/binary>>/binary,
                            "`"/utf8>>
                    end
                )
            ),
            <<""/utf8>>,
            <<"## Type mappings"/utf8>>,
            <<""/utf8>>,
            bullet_list(
                gleam@list:map(
                    supported_type_mappings(),
                    fun(Mapping) ->
                        <<<<"- `"/utf8,
                                (sqlode@model:type_mapping_to_string(Mapping))/binary>>/binary,
                            "`"/utf8>>
                    end
                )
            ),
            <<""/utf8>>,
            <<"## Query annotations"/utf8>>,
            <<""/utf8>>,
            <<"### Fully supported"/utf8>>,
            <<""/utf8>>,
            bullet_list(
                gleam@list:map(
                    fully_supported_query_commands(),
                    fun(Command) ->
                        <<<<"- `"/utf8, (command_annotation(Command))/binary>>/binary,
                            "`"/utf8>>
                    end
                )
            ),
            <<""/utf8>>,
            <<"### Parsed but rejected at generation time"/utf8>>,
            <<""/utf8>>,
            <<"These annotations exist in sqlc and are still parseable in"/utf8>>,
            <<"`.sql` files, but sqlode currently refuses to emit code for"/utf8>>,
            <<"them. See `validate_unsupported_annotations` in `generate.gleam`."/utf8>>,
            <<""/utf8>>,
            bullet_list(
                gleam@list:map(
                    planned_query_commands(),
                    fun(Command@1) ->
                        <<<<"- `"/utf8, (command_annotation(Command@1))/binary>>/binary,
                            "`"/utf8>>
                    end
                )
            ),
            <<""/utf8>>,
            <<"## Macros"/utf8>>,
            <<""/utf8>>,
            bullet_list(
                gleam@list:map(
                    supported_macros(),
                    fun(Name) ->
                        <<<<"- `"/utf8, Name/binary>>/binary, "(...)`"/utf8>>
                    end
                )
            ),
            <<""/utf8>>,
            <<"## Placeholder styles"/utf8>>,
            <<""/utf8>>,
            bullet_list(
                gleam@list:map(
                    supported_placeholder_styles(),
                    fun(Entry) ->
                        {Engine@1, Style} = Entry,
                        <<<<<<<<"- `"/utf8,
                                        (sqlode@model:engine_to_string(Engine@1))/binary>>/binary,
                                    "` → `runtime."/utf8>>/binary,
                                Style/binary>>/binary,
                            "`"/utf8>>
                    end
                )
            ),
            <<""/utf8>>],
        <<"\n"/utf8>>
    ).