feat(query): add programmatic query builder

.credo.exs

@@ -0,0 +1,219 @@
+# This file contains the configuration for Credo and you are probably reading
+# this after creating it with `mix credo.gen.config`.
+#
+# If you find anything wrong or unclear in this file, please report an
+# issue on GitHub: https://github.com/rrrene/credo/issues
+#
+%{
+  #
+  # You can have as many configs as you like in the `configs:` field.
+  configs: [
+    %{
+      #
+      # Run any config using `mix credo -C <name>`. If no config name is given
+      # "default" is used.
+      #
+      name: "default",
+      #
+      # These are the files included in the analysis:
+      files: %{
+        #
+        # You can give explicit globs or simply directories.
+        # In the latter case `**/*.{ex,exs}` will be used.
+        #
+        included: [
+          "lib/",
+          "src/",
+          "test/",
+          "web/",
+          "apps/*/lib/",
+          "apps/*/src/",
+          "apps/*/test/",
+          "apps/*/web/"
+        ],
+        excluded: [~r"/_build/", ~r"/deps/", ~r"/node_modules/"]
+      },
+      #
+      # Load and configure plugins here:
+      #
+      plugins: [],
+      #
+      # If you create your own checks, you must specify the source files for
+      # them here, so they can be loaded by Credo before running the analysis.
+      #
+      requires: [],
+      #
+      # If you want to enforce a style guide and need a more traditional linting
+      # experience, you can change `strict` to `true` below:
+      #
+      strict: false,
+      #
+      # To modify the timeout for parsing files, change this value:
+      #
+      parse_timeout: 5000,
+      #
+      # If you want to use uncolored output by default, you can change `color`
+      # to `false` below:
+      #
+      color: true,
+      #
+      # You can customize the parameters of any check by adding a second element
+      # to the tuple.
+      #
+      # To disable a check put `false` as second element:
+      #
+      #     {Credo.Check.Design.DuplicatedCode, false}
+      #
+      checks: %{
+        enabled: [
+          #
+          ## Consistency Checks
+          #
+          {Credo.Check.Consistency.ExceptionNames, []},
+          {Credo.Check.Consistency.LineEndings, []},
+          {Credo.Check.Consistency.ParameterPatternMatching, []},
+          {Credo.Check.Consistency.SpaceAroundOperators, []},
+          {Credo.Check.Consistency.SpaceInParentheses, []},
+          {Credo.Check.Consistency.TabsOrSpaces, []},
+
+          #
+          ## Design Checks
+          #
+          # You can customize the priority of any check
+          # Priority values are: `low, normal, high, higher`
+          #
+          {Credo.Check.Design.AliasUsage,
+           [priority: :low, if_nested_deeper_than: 2, if_called_more_often_than: 0]},
+          {Credo.Check.Design.TagFIXME, []},
+          # You can also customize the exit_status of each check.
+          # If you don't want TODO comments to cause `mix credo` to fail, just
+          # set this value to 0 (zero).
+          #
+          {Credo.Check.Design.TagTODO, [exit_status: 2]},
+
+          #
+          ## Readability Checks
+          #
+          {Credo.Check.Readability.AliasOrder, []},
+          {Credo.Check.Readability.FunctionNames, []},
+          {Credo.Check.Readability.LargeNumbers, []},
+          {Credo.Check.Readability.MaxLineLength, [priority: :low, max_length: 120]},
+          {Credo.Check.Readability.ModuleAttributeNames, []},
+          # Disabled: false positive with Elixir 1.20 — modules do have @moduledoc
+          # {Credo.Check.Readability.ModuleDoc, []},
+          {Credo.Check.Readability.ModuleNames, []},
+          {Credo.Check.Readability.ParenthesesInCondition, []},
+          {Credo.Check.Readability.ParenthesesOnZeroArityDefs, []},
+          {Credo.Check.Readability.PipeIntoAnonymousFunctions, []},
+          {Credo.Check.Readability.PredicateFunctionNames, []},
+          {Credo.Check.Readability.PreferImplicitTry, []},
+          {Credo.Check.Readability.RedundantBlankLines, []},
+          {Credo.Check.Readability.Semicolons, []},
+          {Credo.Check.Readability.SpaceAfterCommas, []},
+          {Credo.Check.Readability.StringSigils, []},
+          {Credo.Check.Readability.TrailingBlankLine, []},
+          {Credo.Check.Readability.TrailingWhiteSpace, []},
+          {Credo.Check.Readability.UnnecessaryAliasExpansion, []},
+          {Credo.Check.Readability.VariableNames, []},
+          {Credo.Check.Readability.WithSingleClause, []},
+
+          #
+          ## Refactoring Opportunities
+          #
+          {Credo.Check.Refactor.Apply, []},
+          {Credo.Check.Refactor.CondStatements, []},
+          {Credo.Check.Refactor.CyclomaticComplexity, []},
+          {Credo.Check.Refactor.FilterCount, []},
+          {Credo.Check.Refactor.FilterFilter, []},
+          {Credo.Check.Refactor.FunctionArity, []},
+          {Credo.Check.Refactor.LongQuoteBlocks, []},
+          {Credo.Check.Refactor.MapJoin, []},
+          {Credo.Check.Refactor.MatchInCondition, []},
+          {Credo.Check.Refactor.NegatedConditionsInUnless, []},
+          {Credo.Check.Refactor.NegatedConditionsWithElse, []},
+          {Credo.Check.Refactor.Nesting, []},
+          {Credo.Check.Refactor.RedundantWithClauseResult, []},
+          {Credo.Check.Refactor.RejectReject, []},
+          {Credo.Check.Refactor.UnlessWithElse, []},
+          {Credo.Check.Refactor.WithClauses, []},
+
+          #
+          ## Warnings
+          #
+          {Credo.Check.Warning.ApplicationConfigInModuleAttribute, []},
+          {Credo.Check.Warning.BoolOperationOnSameValues, []},
+          {Credo.Check.Warning.Dbg, []},
+          {Credo.Check.Warning.ExpensiveEmptyEnumCheck, []},
+          {Credo.Check.Warning.IExPry, []},
+          {Credo.Check.Warning.IoInspect, []},
+          {Credo.Check.Warning.MissedMetadataKeyInLoggerConfig, []},
+          {Credo.Check.Warning.OperationOnSameValues, []},
+          {Credo.Check.Warning.OperationWithConstantResult, []},
+          {Credo.Check.Warning.RaiseInsideRescue, []},
+          {Credo.Check.Warning.SpecWithStruct, []},
+          {Credo.Check.Warning.StructFieldAmount, []},
+          {Credo.Check.Warning.UnsafeExec, []},
+          {Credo.Check.Warning.UnusedEnumOperation, []},
+          {Credo.Check.Warning.UnusedFileOperation, []},
+          {Credo.Check.Warning.UnusedKeywordOperation, []},
+          {Credo.Check.Warning.UnusedListOperation, []},
+          {Credo.Check.Warning.UnusedPathOperation, []},
+          {Credo.Check.Warning.UnusedRegexOperation, []},
+          {Credo.Check.Warning.UnusedStringOperation, []},
+          {Credo.Check.Warning.UnusedTupleOperation, []},
+          {Credo.Check.Warning.WrongTestFileExtension, []}
+        ],
+        disabled: [
+          #
+          # Checks scheduled for next check update (opt-in for now)
+          {Credo.Check.Refactor.UtcNowTruncate, []},
+
+          #
+          # Controversial and experimental checks (opt-in, just move the check to `:enabled`
+          #   and be sure to use `mix credo --strict` to see low priority checks)
+          #
+          {Credo.Check.Consistency.MultiAliasImportRequireUse, []},
+          {Credo.Check.Consistency.UnusedVariableNames, []},
+          {Credo.Check.Design.DuplicatedCode, []},
+          {Credo.Check.Design.SkipTestWithoutComment, []},
+          {Credo.Check.Readability.AliasAs, []},
+          {Credo.Check.Readability.BlockPipe, []},
+          {Credo.Check.Readability.ImplTrue, []},
+          {Credo.Check.Readability.MultiAlias, []},
+          {Credo.Check.Readability.NestedFunctionCalls, []},
+          {Credo.Check.Readability.OneArityFunctionInPipe, []},
+          {Credo.Check.Readability.OnePipePerLine, []},
+          {Credo.Check.Readability.SeparateAliasRequire, []},
+          {Credo.Check.Readability.SingleFunctionToBlockPipe, []},
+          {Credo.Check.Readability.SinglePipe, []},
+          {Credo.Check.Readability.Specs, []},
+          {Credo.Check.Readability.StrictModuleLayout, []},
+          {Credo.Check.Readability.WithCustomTaggedTuple, []},
+          {Credo.Check.Refactor.ABCSize, []},
+          {Credo.Check.Refactor.AppendSingleItem, []},
+          {Credo.Check.Refactor.DoubleBooleanNegation, []},
+          {Credo.Check.Refactor.FilterReject, []},
+          {Credo.Check.Refactor.IoPuts, []},
+          {Credo.Check.Refactor.MapMap, []},
+          {Credo.Check.Refactor.ModuleDependencies, []},
+          {Credo.Check.Refactor.NegatedIsNil, []},
+          {Credo.Check.Refactor.PassAsyncInTestCases, []},
+          {Credo.Check.Refactor.PipeChainStart, []},
+          {Credo.Check.Refactor.RejectFilter, []},
+          {Credo.Check.Refactor.VariableRebinding, []},
+          {Credo.Check.Warning.LazyLogging, []},
+          {Credo.Check.Warning.LeakyEnvironment, []},
+          {Credo.Check.Warning.MapGetUnsafePass, []},
+          {Credo.Check.Warning.MixEnv, []},
+          {Credo.Check.Warning.UnsafeToAtom, []}
+
+          # {Credo.Check.Refactor.MapInto, []},
+
+          #
+          # Custom checks can be created using `mix credo.gen.check`.
+          #
+        ]
+      }
+    }
+  ]
+}

.github/workflows/ci.yml

@@ -15,7 +15,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        elixir: ['1.17', '1.19']
+        elixir: ['1.17', '1.19', '1.20']
         otp: ['27']
 
     steps:

README.md

@@ -6,13 +6,14 @@ Elixir bindings for [mq](https://mqlang.org/), a jq-like command-line tool for M
 
 - Process markdown, MDX, HTML, and plain text
 - Full mq query language support
+- Programmatic query builder with Elixir pipe operator
 - Multiple input and output format options
 - Configurable rendering options
 - Fast Rust-powered NIF implementation
 
 ## Installation
 
-Add `mq` to your list of dependencies in `mix.exs`:
+Add `mq_elixir` to your list of dependencies in `mix.exs`:
 
 ```elixir
 def deps do
@@ -22,17 +23,101 @@ def deps do
 end
 ```
 
-
 ## Usage
 
-### Basic Query
+### Raw Query String
 
 ```elixir
 # Extract all H1 headings
 {:ok, result} = Mq.run(".h1", "# Hello\n## World")
 IO.inspect(result.values)  # ["# Hello"]
+
+# Filter with select
+{:ok, result} = Mq.run(".h2 | select(contains(\"Feature\"))", content)
+```
+
+### Query Builder
+
+Build queries programmatically using `Mq` functions and the `|>` pipe operator.
+
+```elixir
+# Selectors and transformations chain naturally
+{:ok, result} =
+  Mq.h2()
+  |> Mq.select(Mq.Filter.contains("Feature"))
+  |> Mq.to_text()
+  |> Mq.run(content)
+```
+
+#### Selectors
+
+```elixir
+Mq.h1()          # .h1
+Mq.h2()          # .h2
+Mq.code()        # .code
+Mq.link()        # .link
+Mq.list()        # .[]
+Mq.list_at(0)    # .[0]
+Mq.paragraph()   # .p
+Mq.task()        # .task
+Mq.todo()        # .todo
+Mq.done()        # .done
+# ... and more (heading, image, blockquote, table, etc.)
+```
+
+#### Attribute Access
+
+Attribute selectors work as both standalone queries and as chained operations:
+
+```elixir
+# Standalone
+Mq.url()   # ".url"
+Mq.lang()  # ".lang"
+
+# Chained — access attributes of selected nodes
+Mq.link() |> Mq.url()   # ".link | .url"
+Mq.code() |> Mq.lang()  # ".code | .lang"
+```
+
+#### Filters
+
+`Mq.Filter` provides composable filter expressions for `select` and `map`:
+
+```elixir
+alias Mq.Filter
+
+# Basic filters
+Filter.contains("Feature")
+Filter.starts_with("##")
+Filter.ends_with("Guide")
+Filter.eq("value")
+Filter.gt(5)
+
+# Combine with |>
+Filter.contains("API")
+|> Filter.and_filter(Filter.negate(Filter.contains("Internal")))
+
+# Combine a list
+Filter.all([Filter.contains("A"), Filter.contains("B"), Filter.ne("## Draft")])
+Filter.any([Filter.contains("Alpha"), Filter.contains("Beta")])
+
+# Negate
+Filter.negate(Filter.contains("draft"))
 ```
 
+#### Chaining Operations
+
+```elixir
+Mq.h2()
+|> Mq.select(Mq.Filter.contains("API"))
+|> Mq.to_text()
+|> Mq.downcase()
+|> Mq.run(content)
+```
+
+Available transforms include: `to_text`, `to_markdown`, `to_html`, `downcase`, `upcase`,
+`trim`, `split`, `join`, `limit`, `nth`, `reverse`, `sort`, `uniq`, and many more.
+
 ### Working with Results
 
 ```elixir
@@ -44,6 +129,28 @@ result.text    # "# H1\n## H2\n### H3"
 
 # Enumerate
 Enum.each(result, fn heading -> IO.puts(heading) end)
+
+# Convert to string
+to_string(result)  # "# H1\n## H2\n### H3"
+```
+
+### Input Formats
+
+```elixir
+options = %Mq.Options{input_format: :text}
+{:ok, result} = Mq.run("select(contains(\"needle\"))", content, options)
+```
+
+Supported formats: `:markdown` (default), `:mdx`, `:html`, `:text`, `:raw`, `:null`
+
+### HTML to Markdown
+
+```elixir
+{:ok, markdown} = Mq.html_to_markdown("<h1>Hello</h1><p>World</p>")
+# => "# Hello\n\nWorld"
+
+opts = %Mq.ConversionOptions{use_title_as_h1: true}
+{:ok, markdown} = Mq.html_to_markdown(html, opts)
 ```
 
 ## Documentation