docs: add API Design page (typed vs. untyped); expand Terraform docs with SQL + delivery attempt recipes; update docs nav; release: add CHANGELOG entry for 0.0.2-rc1; ci: enforce CHANGELOG contains current version

Author: ndbroadbent

.github/workflows/test.yml

@@ -53,6 +53,9 @@ jobs:
       - name: CSpell (Spellcheck)
         run: scripts/spellcheck.sh
 
+      - name: Changelog has entry for current version
+        run: ruby scripts/check_changelog_version.rb
+
       - name: Prettier (Formatting)
         run: scripts/prettier.sh --check
 

CHANGELOG.md

@@ -10,3 +10,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Pushed empty gem to RubyGems to secure the name
+
+## [0.0.2-rc1] - 2025-09-05
+
+### Added
+
+- Unified GitHub Actions workflow to release RubyGem and sync/tag the Terraform provider; dry-run support for safe validation
+- Provider catalog export script and automated provider CI (build/vet/test)
+- Terraform docs page with quickstart, recipes, and provider README link
+- API design doc (typed vs. untyped) planned; initial philosophy captured
+- Coverage threshold gate (>= 80%) in CI; additional tests to lift coverage
+- Release helper: scripts/create_release_tag.sh (creates annotated tag from version.rb)
+
+### Changed
+
+- ActionMailer callbacks patched for Rails 7.0; event logging + metadata collection tested
+- Provider CloudWatch filter builder refactored for testability; key lookups aligned with exported catalog (event/source)
+
+### Fixed
+
+- Pre-commit hooks reporting; cspell dictionary updated; TypeScript import fixes in site

scripts/check_changelog_version.rb

@@ -0,0 +1,26 @@
+#!/usr/bin/env ruby
+# typed: strict
+# frozen_string_literal: true
+
+require "date"
+
+version = File.read("lib/log_struct/version.rb")[/VERSION\s*=\s*"([^"]+)"/, 1]
+abort "Could not determine version from lib/log_struct/version.rb" unless version
+
+changelog = begin
+  File.read("CHANGELOG.md")
+rescue
+  ""
+end
+
+# Accept headings like: ## [0.0.2-rc1] - 2025-09-05 or ## 0.0.2-rc1
+heading_regex = /^##\s*\[?#{Regexp.escape(version)}\]?/m
+
+if changelog.match?(heading_regex)
+  puts "CHANGELOG contains entry for #{version}"
+  exit 0
+else
+  warn "CHANGELOG is missing an entry for version #{version}."
+  warn "Add a section like: \n\n## [#{version}] - #{Date.today}"
+  exit 1
+end

site/app/docs/api-design/page.tsx

@@ -0,0 +1,85 @@
+import { CodeBlock } from '@/components/code-block';
+import { EditPageLink } from '@/components/edit-page-link';
+
+export const metadata = {
+  title: 'API Design (Typed vs. Untyped)',
+  description:
+    'How LogStruct balances an idiomatic Rails logging API with an optional typed path for teams using sorbet-runtime.',
+};
+
+export default function ApiDesignPage() {
+  const untypedExample = `# Untyped, idiomatic Rails logging (works out of the box)
+Rails.logger.info({
+  msg: "User signed in",
+  user_id: current_user.id,
+  feature: "onboarding"
+})`;
+
+  const typedExample = `# Optional typed API (sorbet-runtime)
+log = LogStruct::Log::Request.new(
+  message: "GET /projects",
+  event: LogStruct::Event::Request,
+  source: LogStruct::Source::Rails,
+  controller: "ProjectsController",
+  action: "index"
+)
+
+LogStruct.info(log)`;
+
+  const customStructSketch = `# Sketch: defining a custom typed log struct
+class MyApp::Logs::Checkout < T::Struct
+  include LogStruct::Log::Interfaces::CommonFields
+  include LogStruct::Log::Interfaces::AdditionalDataField
+
+  const :event, LogStruct::Event::Log
+  const :source, LogStruct::Source, default: T.let(LogStruct::Source::App, LogStruct::Source)
+  const :message, String
+  const :cart_id, String
+  const :amount_cents, Integer
+end
+
+# Then log it with
+LogStruct.info(
+  MyApp::Logs::Checkout.new(message: "checkout_completed", cart_id: cart.id, amount_cents: 1299)
+)`;
+
+  return (
+    <div className="space-y-8">
+      <h1 className="text-3xl font-bold">API Design: Typed vs. Untyped</h1>
+      <p className="text-neutral-600 dark:text-neutral-400">
+        LogStruct is designed for an idiomatic Rails experience first, with an
+        optional typed path for teams that use sorbet-runtime. Most Rails
+        developers can adopt LogStruct without learning Sorbet. Teams wanting
+        stronger guarantees can progressively introduce typed log structs.
+      </p>
+
+      <h2 className="text-2xl font-semibold">Untyped, Idiomatic Rails</h2>
+      <p>
+        You can continue using <code>Rails.logger</code> with hashes and
+        strings. LogStruct&apos;s formatter scrubs sensitive values and keeps
+        output JSON-friendly.
+      </p>
+      <CodeBlock language="ruby">{untypedExample}</CodeBlock>
+
+      <h2 className="text-2xl font-semibold">Optional Typed Path</h2>
+      <p>
+        For teams that want stricter contracts, use LogStruct&apos;s typed
+        structs. These are runtime-checked via sorbet-runtime and integrate with
+        our formatter seamlessly.
+      </p>
+      <CodeBlock language="ruby">{typedExample}</CodeBlock>
+
+      <h2 className="text-2xl font-semibold">
+        Custom Typed Structures (Sketch)
+      </h2>
+      <p>
+        You can define app-specific typed logs by composing LogStruct
+        interfaces. Keep this ergonomic and discoverable; the untyped path
+        remains first-class.
+      </p>
+      <CodeBlock language="ruby">{customStructSketch}</CodeBlock>
+
+      <EditPageLink path="app/docs/api-design/page.tsx" />
+    </div>
+  );
+}

site/app/docs/layout.tsx

@@ -173,6 +173,11 @@ export default function DocsLayout({
                       },
                     ]}
                   />
+                  <DocNavItem
+                    href="/docs/api-design"
+                    title="API Design"
+                    active={pathname.startsWith('/docs/api-design')}
+                  />
 
                   <DocNavItem
                     href="/docs/comparison"

site/app/docs/terraform/page.tsx

@@ -36,6 +36,42 @@ export default function TerraformDocsPage() {
   }
 }`;
 
+  const sqlCount = `data "logstruct_cloudwatch_filter" "sql_queries" {
+  struct = "SQL"
+  event  = "database"
+}
+
+resource "aws_cloudwatch_log_metric_filter" "sql_count" {
+  name           = "SQL Query Count"
+  log_group_name = var.log_group.app
+  pattern        = data.logstruct_cloudwatch_filter.sql_queries.pattern
+
+  metric_transformation {
+    name      = "app_sql_query_count"
+    namespace = var.namespace.logs
+    value     = "1"
+    unit      = "Count"
+  }
+}`;
+
+  const mailDeliveryAttempt = `data "logstruct_cloudwatch_filter" "email_delivery_attempt" {
+  struct = "ActionMailer"
+  event  = "delivery"
+}
+
+resource "aws_cloudwatch_log_metric_filter" "email_delivery_attempt_count" {
+  name           = "Email Delivery Attempt Count"
+  log_group_name = var.log_group.app
+  pattern        = data.logstruct_cloudwatch_filter.email_delivery_attempt.pattern
+
+  metric_transformation {
+    name      = "app_email_delivery_attempt_count"
+    namespace = var.namespace.logs
+    value     = "1"
+    unit      = "Count"
+  }
+}`;
+
   return (
     <div className="space-y-10">
       <h1 className="text-3xl font-bold mb-2">Terraform Provider</h1>
@@ -154,8 +190,20 @@ resource "aws_cloudwatch_log_metric_filter" "goodjob_finish_count" {
 }`}
           </CodeBlock>
         </div>
+        <div className="grid gap-6 md:grid-cols-2">
+          <CodeBlock language="hcl" title="Count All SQL Queries">
+            {sqlCount}
+          </CodeBlock>
+          <CodeBlock language="hcl" title="Count Email Delivery Attempts">
+            {mailDeliveryAttempt}
+          </CodeBlock>
+        </div>
         <p className="text-neutral-600 dark:text-neutral-400">
-          See the provider README for more examples and details.
+          For delivery failures, use metric math to compare attempts vs.
+          delivered counts. CloudWatch filter patterns do not support numeric
+          comparisons, so slow-query thresholds are usually handled downstream
+          (for example, count + percentiles in metrics/dashboards). See the
+          provider README for more examples and details.
         </p>
       </section>