.vale.ini

# Vale configuration for Tiger Data Docs.
#
# House style follows the Google developer documentation style guide, pulled in
# as a package below. A thin custom `TigerData` style layers on the rules Google
# can't know about: product-name constants and deprecated compression APIs.
#
# Run locally with `pnpm lint:prose` (changed files only). In CI, findings are
# reported only on the lines you changed (see .github/workflows/vale.yml and
# .github/scripts/vale_pr_lint.py). Only errors fail the build: three TigerData
# rules are set to error and gate CI (CompressionAPIs, UIElementsCodeFont, and
# Headings). Every other rule is advisory (see the severity policy below).

StylesPath = .github/styles

# Surface suggestions too, so the (non-gating) product-constant nudges appear.
# CI gates on errors only; suggestions/warnings are advisory.
MinAlertLevel = suggestion

# Pull the Google Developer Documentation Style Guide as a managed package.
# `vale sync` downloads it into StylesPath (the CI action and lint:prose run it).
Packages = Google

# Accepted spellings (product/brand/feature terms) live in this vocabulary.
Vocab = TigerData

# Treat .mdx the same as Markdown so JSX components/imports are tolerated.
[formats]
mdx = md

# MDX hygiene: don't lint import/export statements as prose, and don't peer
# inside JSX expressions ({C.PG}, {variables}) or component tags.
#
# These MUST live in a format-scoped section, not the path-scoped section below.
# Vale silently drops BlockIgnores/TokenIgnores declared under a path-glob
# header, so when they sat with BasedOnStyles they did nothing at all: every
# `{C.X}` constant and every import line was linted as prose. That single
# misplacement produced ~1,300 phantom findings, led by 659 `CHUNK` and 556
# `CAGG` acronym hits from `{C.CHUNK}`/`{C.CAGG}`, plus Google.Quotes matches
# that spanned two import lines and Google.Headings failures on headings whose
# only "capitalized" word was a constant. This section carries no
# BasedOnStyles, so it widens ignores without widening what gets linted.
[*.{md,mdx}]
BlockIgnores = (?m)^[ \t]*(?:import|export)[ \t].*$
TokenIgnores = (\{[^{}\n]+\}), (</?[A-Za-z][^>\n]*/?>)

# Scope linting to docs content only. Repo meta-markdown (CLAUDE.md, README,
# AGENTS.md, .github templates) is intentionally not linted.
[{src/content,src/partials}/**/*.{md,mdx}]
# Note: the built-in `Vale` style is intentionally excluded — its Vale.Terms
# check enforces a single casing for every vocab term, which wrongly errors on
# legitimately-lowercase feature names (hypercore, columnstore, hypertable).
# Google provides its own spelling check; the Vocab still applies globally.
BasedOnStyles = Google, TigerData

# --- Severity policy ----------------------------------------------------------
# Only TigerData rules are allowed at `error`, and only three are:
# CompressionAPIs, UIElementsCodeFont, and Headings. Those are the only things
# that fail CI (the workflow gates on error-severity findings on changed lines).
# Each is mechanical to fix and unambiguous when it fires, which is the bar for
# gating. Every other rule stays at `warning` or `suggestion`, including Google
# rules that ship as `error` by default, which are demoted just below. Recheck
# after `vale sync` pulls a new Google package, in case it adds new error-level
# rules.

# Google rules that default to `error`; demote so they don't gate the build.
# (Google.EmDash and Google.Latin also default to error but are handled below.)
Google.AMPM = warning
Google.DateFormat = warning
Google.Exclamation = warning
Google.Gender = warning
Google.GenderBias = warning
Google.LyHyphens = warning
Google.OptionalPlurals = warning
Google.Ordinal = warning
Google.Periods = warning
Google.Quotes = warning
Google.Slang = warning
Google.Spacing = warning
Google.Units = warning

# Replaced by TigerData.Headings, which has a much larger proper-noun exception
# list and gates at error. Both firing would double-report every heading.
Google.Headings = NO

# Replaced by TigerData.Acronyms, which excepts SQL keywords and column types
# ("spell out 'TEXT'" is not actionable). Both firing would double-report.
Google.Acronyms = NO

# Turn off the noisiest Google rules for now to keep the signal clean. Revisit
# and promote to suggestion/warning once the team is comfortable.
Google.Passive = NO
Google.We = NO
Google.FirstPerson = NO
# WordList flags bare "Cloud" (wants "GCP") on every "Tiger Cloud" — off for us.
Google.WordList = NO
# Semicolons rule fires on too many legitimate uses (code, lists, compound
# sentences) — too many false positives, off for us.
Google.Semicolons = NO
# Contractions (nudges "is not" -> "isn't") and Will (flags future tense) are
# noisy and not house style — off for us.
Google.Contractions = NO
Google.Will = NO
# Parens flags any parenthetical text as a readability concern — too noisy for
# our docs, which use parentheses heavily for clarifications — off for us.
Google.Parens = NO

# Spelling is backed by the TigerData vocabulary; advisory only.
Google.Spelling = suggestion

# Em dashes are discouraged entirely by TigerData.NoEmDash, so Google's
# spacing-only em-dash rule is redundant.
Google.EmDash = NO

# --- TigerData custom rules ---------------------------------------------------
# Product-name constants: advisory nudge to use {C.X} instead of a literal.
TigerData.ProductConstants = suggestion
# Deprecated compression APIs must not appear in new docs. Gating.
TigerData.CompressionAPIs = error
# Latinisms (e.g./i.e.) — advisory, not gating.
Google.Latin = suggestion

# UI element names belong in code font, not bold. Gating: a bold UI label is
# unambiguous and mechanical to fix, so it should not reach main.
TigerData.UIElementsCodeFont = error

# Sentence-case headings. Gating: see the exception list in
# .github/styles/TigerData/Headings.yml, which is long enough that a finding
# means a real mistake rather than an unrecognized proper noun.
TigerData.Headings = error

# Spell out unfamiliar acronyms on first use. Advisory, and deduplicated to one
# finding per acronym per page by the reporting layer.
TigerData.Acronyms = suggestion
# Em dashes are discouraged; rewrite the sentence instead.
TigerData.NoEmDash = warning

# --- Changelog: no constants --------------------------------------------------
# The changelog is a permanent historical record, so it uses literal product
# names instead of {C.X} constants (see README-changelog.md). Turn off the
# constants nudge here so the tooling matches that convention.
[src/content/docs/get-started/news/*.{md,mdx}]
TigerData.ProductConstants = NO
# Entries are a permanent record of what shipped, so an entry that described the
# old API keeps its original wording.
TigerData.CompressionAPIs = NO
# --- Pages that must name a deprecated compression API ----------------------
# TigerData.CompressionAPIs gates CI, but three files legitimately write the old
# names and cannot be rewritten:
#
#   _chunk_columnstore_settings.mdx      "X replaces Y, deprecated in 2.18.0"
#   _hypertable_columnstore_settings.mdx  same deprecation note
#   _timescaledb-gucs.mdx                 generated from the TimescaleDB source;
#                                         upstream's own GUC description for
#                                         auto_sparse_indexes says compress_chunk()
#
# A path-scoped exception is used rather than an inline comment because Vale's
# `<!-- vale ... -->` directives are silently ignored in .mdx (they work only in
# .md, even with the [formats] mdx = md mapping), and MDX v3 rejects HTML
# comments outright, so there is no in-file way to say this.
[src/partials/{_chunk_columnstore_settings,_hypertable_columnstore_settings,_timescaledb-gucs}.mdx]
TigerData.CompressionAPIs = NO

# The hypercore reference pages each open with a "X replaces Y, deprecated in
# 2.18.0" callout, so naming the old API is the point of the sentence. Listed
# file by file rather than scoping the whole directory: alter_table.mdx lives
# there too and its findings are real (timescaledb.compress_orderby /
# compress_segmentby should be timescaledb.orderby / segmentby).
[src/content/docs/reference/timescaledb/hypercore/{convert_to_columnstore,convert_to_rowstore,add_columnstore_policy,remove_columnstore_policy,chunk_columnstore_stats,hypertable_columnstore_stats}.mdx]
TigerData.CompressionAPIs = NO