From 72e55a3fe10e256989b6c26bd9f997728923593f Mon Sep 17 00:00:00 2001 From: JohnnyT Date: Wed, 23 Sep 2026 19:28:32 -0600 Subject: [PATCH] Ships the README-linked guides and quiets the two JSON references hex.pm renders the package page from the README inside the tarball, so a relative README link resolves to that path in the tarball and answers 404 unless the file ships. The README links relatively to ten docs files, all extras and none in package files; each is now in package: [files: ...], so one relative link works on GitHub, HexDocs and hex.pm alike. The comments in package/0 and docs/0 said docs/ was deliberately left out because HexDocs builds from disk; that missed the hex.pm README preview, and both now give the reason the guides ship. The conformance exclusions (the files list's lib/predicator* glob with exclude_patterns) are unchanged. The language reference named predicator's own JSON.parse and JSON.stringify in Elixir's arity form, which ExDoc autolinks against Elixir's JSON module and reports undefined. They are now written in call form, JSON.parse(string) and JSON.stringify(value), as the function table above them already writes them, so nothing autolinks and no skip_code_autolink_to entry is needed. mix docs --warnings-as-errors now exits 0. No version bump; no changelog fragment, since changelog.d/README.md excludes documentation and quality gate changes. Refs: px-i0dj --- docs/reference/language.md | 4 ++-- mix.exs | 36 +++++++++++++++++++++++++++--------- 2 files changed, 29 insertions(+), 11 deletions(-) diff --git a/docs/reference/language.md b/docs/reference/language.md index 36d2919..185dc1b 100644 --- a/docs/reference/language.md +++ b/docs/reference/language.md @@ -631,7 +631,7 @@ iex> Predicator.evaluate("JSON.parse(metadata).network == 'VISA'", %{"metadata" {:ok, true} ``` -`JSON.parse/1` returns a plain string-keyed value, so dot and bracket access +`JSON.parse(string)` returns a plain string-keyed value, so dot and bracket access reach into it directly - the third example above is the common shape, a JSON blob carried as one context string and read as data. It is strict about both halves: a non-string argument is an `EvaluationError` @@ -639,7 +639,7 @@ halves: a non-string argument is an `EvaluationError` `EvaluationError` naming the byte offset (`Invalid JSON: unexpected end of input at position 4`). -`JSON.stringify/1` never raises. Elixir values with no JSON representation - +`JSON.stringify(value)` never raises. Elixir values with no JSON representation - tuples, PIDs, references, functions, non-string map keys, invalid UTF-8 - fall back to their `inspect/1` form rather than failing the predicate, which is what a predicate has always seen for such values. Key order in the output diff --git a/mix.exs b/mix.exs index 10289f5..34c5c51 100644 --- a/mix.exs +++ b/mix.exs @@ -55,12 +55,16 @@ defmodule Predicator.MixProject do defp package do [ name: @app, - # Deliberately excludes docs/ - hexdocs is built from docs()'s extras: - # paths read off the publisher's disk, not from this tarball, so the - # markdown sources only bloat what mix deps.get downloads. + # Every file README.md links to relatively ships in this tarball. hex.pm + # renders the package page from the README inside the tarball, so a + # relative link there resolves to that path in the tarball and answers + # 404 unless the file ships; the same link also works on GitHub and, since + # each target is an extra in docs(), on hexdocs. A README link to a new + # file adds it both here and to docs()'s extras. The rest of docs/ stays + # out: hexdocs builds from docs()'s extras on the publisher's disk. # - # The whole conformance apparatus is excluded on the same principle: - # nothing an application does at runtime touches it, and the audience + # The whole conformance apparatus is excluded because nothing an + # application does at runtime touches it, and the audience # that does - sibling implementers - works from a git checkout. That is # three things, excluded three ways (px-35i.4): # @@ -75,7 +79,19 @@ defmodule Predicator.MixProject do # Nothing under lib/ outside those two directories references # Predicator.Conformance, so dropping it cannot break a consumer's # compile. A test guards that invariant. - files: ~w(lib/predicator* mix.exs README.md LICENSE CHANGELOG.md), + files: ~w( + lib/predicator* mix.exs README.md LICENSE CHANGELOG.md + docs/reference/language.md + docs/isa.md + docs/guides/nested-data-access.md + docs/guides/custom-functions.md + docs/guides/location-expressions.md + docs/guides/embedding.md + docs/guides/simple-subset.md + docs/guides/porting.md + docs/architecture.md + docs/contributing.md + ), exclude_patterns: [~r{\Alib/predicator/conformance/}], licenses: ["MIT"], links: %{"GitHub" => @source_url}, @@ -90,9 +106,11 @@ defmodule Predicator.MixProject do canonical: "https://hexdocs.pm/predicator", source_url: @source_url, main: "readme", - # These paths are read off disk at publish time and need no entry in - # package()'s files: list - the docs tarball hexdocs hosts is built by - # mix docs, separately from the package tarball mix deps.get fetches. + # These paths are read off disk at publish time: the docs tarball hexdocs + # hosts is built by mix docs, separately from the package tarball. An + # extra that README.md links to relatively is ALSO listed in package()'s + # files:, because hex.pm renders the README from the package tarball and + # a relative link there answers 404 unless the target ships in it. extras: [ "README.md", "docs/reference/language.md",