Style guide compliance checks and boilerplate templates

.github/workflows/vale.yml

@@ -0,0 +1,36 @@
+name: Vale
+
+on:
+  pull_request:
+    branches:
+      - main
+      - release
+
+jobs:
+  vale:
+    name: Lint prose (ts-docs)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install AsciiDoc dependencies
+        run: sudo apt-get install -y asciidoctor
+
+      - name: Run Vale
+        uses: errata-ai/vale-action@v2
+        with:
+          # CI config: ts-docs rules only, error level gate.
+          # Does not run vale sync — no package downloads needed.
+          vale_flags: "--config=.vale-ci.ini"
+          # Run on all files; filter_mode=added limits PR annotations
+          # to lines added/changed in this PR only.
+          files: all
+          filter_mode: added
+          # Fail the build on errors (merge conflict markers,
+          # unfilled placeholders). Warnings are reported but
+          # do not block the PR.
+          fail_on_error: true
+          reporter: github-pr-review
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -106,6 +106,11 @@ docs/public/
 # TernJS port file
 .tern-port
 
+# Vale prose linter — downloaded packages (committed: ts-docs style + ts-vocab)
+# Run `vale sync` after cloning to download these.
+.vale/styles/Google/
+.vale/styles/Microsoft/
+
 # Code editors or IDEs
 .vscode/
 

.vale-ci.ini

@@ -0,0 +1,22 @@
+# =============================================================
+# .vale-ci.ini — CI-only Vale configuration
+# =============================================================
+# Used exclusively by the GitHub Actions vale.yml workflow.
+# Runs only the committed ts-docs style; does NOT require
+# `vale sync` (no Google / Microsoft packages are downloaded).
+#
+# Gate: MinAlertLevel = error — only hard errors fail the build.
+# ts-docs rules at error level:
+#   - PreCommitChecks  (merge conflict markers, unfilled placeholders)
+# =============================================================
+
+StylesPath = .vale/styles
+MinAlertLevel = error
+Vocab = ts-vocab
+
+[*.{adoc,asciidoc}]
+BasedOnStyles = ts-docs
+
+# Preserve the same AsciiDoc comment and inline-span exclusions as .vale.ini
+TokenIgnores = (\/\/.+), (\[(?:\.version-badge[^\]]*|tag [^\]]*|earlyAccess [^\]]*|beta [^\]]*)\][#^][^#^]+[#^]), (\[(NOTE|TIP|WARNING|IMPORTANT|CAUTION|DANGER)\])
+BlockIgnores = (?s)(\/{4}[\s\S]*?\/{4})

.vale.ini

@@ -0,0 +1,137 @@
+# =============================================================
+# .vale.ini — ThoughtSpot Developer Docs
+# =============================================================
+# SETUP (one-time, after cloning):
+#   vale sync
+# This downloads Google and Microsoft into .vale/styles/ (gitignored).
+# The ts-docs custom style and ts-vocab vocabulary are committed to the repo.
+#
+# USAGE:
+#   vale path/to/file.adoc
+#   vale modules/ROOT/pages/
+#
+# INTELLIJ IDEA:
+#   Settings > Tools > Vale > Config: point to this file.
+#   The AsciiDoc plugin picks up Vale alerts inline.
+# =============================================================
+
+StylesPath = .vale/styles
+
+# suggestion = show everything (noisy, good for authoring)
+# warning    = hide suggestions, show warnings + errors (recommended for review)
+# error      = show only blocking errors (good for CI gates)
+MinAlertLevel = suggestion
+
+# ---- Packages (downloaded by `vale sync`, then gitignored) --
+Packages = Google, Microsoft
+
+# ---- Shared vocabulary --------------------------------------
+# Files: .vale/styles/config/vocabularies/ts-vocab/accept.txt
+#                                                   reject.txt
+Vocab = ts-vocab
+
+# =============================================================
+# Catch-all: disable Vale on every file type not listed below.
+# This prevents IDE plugins from running checks on .yml, .json,
+# .js, and other non-prose files even when .valeignore is ignored.
+# =============================================================
+[*]
+BasedOnStyles =
+
+# =============================================================
+# AsciiDoc files (authored content only)
+# Generated pages and node_modules are excluded via .valeignore
+# =============================================================
+[*.{adoc,asciidoc}]
+BasedOnStyles = Google, Microsoft, ts-docs
+
+# ---- Comment exclusions -------------------------------------
+# AsciiDoc single-line comments (// text) are ignored.
+# AsciiDoc block comments (////...////) are ignored.
+# EXCEPTION: comments inside ---- code blocks are part of code
+# content and are preserved by Asciidoctor — they are not
+# matched by these patterns and continue to be checked.
+# Inline role spans are also stripped before style rules run so that
+# capitalization checks do not fire on fixed labels:
+#   [.version-badge.*]#New#       [.version-badge.*]#Breaking#
+#   [tag *]#NEW FEATURE#          [tag *]#DEPRECATED#
+#   [earlyAccess *]#Early Access# [beta *]^Beta^
+#   [NOTE]  [WARNING]  [IMPORTANT]  [TIP]  [CAUTION]
+TokenIgnores = (\/\/.+), (\[(?:\.version-badge[^\]]*|tag [^\]]*|earlyAccess [^\]]*|beta [^\]]*)\][#^][^#^]+[#^]), (\[(NOTE|TIP|WARNING|IMPORTANT|CAUTION|DANGER)\])
+BlockIgnores = (?s)(\/{4}[\s\S]*?\/{4})
+
+# ---- Rule overrides -----------------------------------------
+# Tuned based on audit of alerts against ThoughtSpot developer docs.
+
+# Vocabulary: managed by ts-vocab; disable built-in Microsoft vocab.
+Microsoft.Vocab = NO
+
+# Headings: sentence case enforced by ts-docs.Headings.
+Google.Headings = NO
+Microsoft.Headings = NO
+Microsoft.HeadingPunctuation = NO
+Microsoft.HeadingAcronyms = NO
+
+# Passive voice: sometimes necessary in reference docs.
+Microsoft.Passive = NO
+Google.Passive = suggestion
+
+# Contractions: avoid in formal developer docs.
+Microsoft.Contractions = NO
+
+# List-item punctuation: technical lists often don't end with periods.
+Microsoft.Periods = NO
+
+# Oxford comma: required.
+Google.OxfordComma = error
+
+# URLs: Antora/AsciiDoc handles link formatting; these rules add noise.
+Microsoft.GeneralURL = NO
+Microsoft.URLFormat = NO
+
+# Sentence length: covered by ts-docs.SentenceLength.
+Microsoft.SentenceLength = NO
+
+# Parentheses and optional plurals: too noisy for technical API docs.
+Google.Parens = NO
+Google.OptionalPlurals = NO
+
+# Google WordList: contains Google-internal product name substitutions
+# (for example, Cloud → "Google Cloud Platform") that conflict with
+# ThoughtSpot product names. Applicable entries are maintained in
+# ts-docs/WordList.yml instead.
+Google.WordList = NO
+
+# Date format: downgraded from error — docs use various date formats
+# depending on context (API responses, UI labels, prose).
+Microsoft.DateFormat = suggestion
+Google.DateFormat = suggestion
+
+# Colon capitalisation: flags proper nouns and product names after colons.
+# Cannot be tuned without rewriting the rule.
+Google.Colons = NO
+Microsoft.HeadingColons = NO
+
+# Semicolons: "Use semicolons judiciously" is not actionable feedback.
+Google.Semicolons = NO
+Microsoft.Semicolon = NO
+
+# Dotted abbreviations: error-level rule flagging U.S.A.-style patterns.
+# Writers are aware of this convention; same check was intentionally
+# excluded from ts-docs styles.
+Google.Periods = NO
+
+# Avoided terms: relevant token (and so on) absorbed into ts-docs.DoNotUseTerms.
+# Remaining tokens are Microsoft-specific or legitimate in ThoughtSpot docs.
+Microsoft.Avoid = NO
+
+# Wordy phrases: applicable substitutions absorbed into ts-docs.WordList.
+# Rule suppressed to avoid duplicate alerts.
+Microsoft.Wordiness = NO
+
+# =============================================================
+# Markdown files
+# =============================================================
+[*.{md,markdown}]
+BasedOnStyles = Google, Microsoft, ts-docs
+

.vale/styles/config/vocabularies/ts-vocab/accept.txt

@@ -0,0 +1,153 @@
+# ts-vocab/accept.txt
+# Terms Vale's spell-check should accept as correctly spelled.
+# One entry per line. Regex is supported.
+# Add product names, SDK identifiers, and technical terms here
+# rather than suppressing spell-check globally.
+
+# -------------------------------------------------------
+# THOUGHTSPOT PRODUCT AND PLATFORM NAMES
+# Prose form - correctly capitalised brand name
+# -------------------------------------------------------
+ThoughtSpot
+ThoughtSpot Cloud
+ThoughtSpot Embedded
+Visual Embed SDK
+REST API v2
+REST API Playground
+ThoughtSpotSDK
+ThoughtSpotRestApi
+ThoughtSpotDeliveryRole
+
+# -------------------------------------------------------
+# THOUGHTSPOT LOWERCASE / CODE-CONTEXT VARIANTS
+# These appear legitimately in URLs, config parameters,
+# variable names, and code - accepted here so the spell
+# checker does not flag them.
+# -------------------------------------------------------
+thoughtspot
+thoughtSpotHost
+thoughtSpotUrl
+thoughtspot\.cloud
+tsconfig
+tsEmbedSDK
+
+# -------------------------------------------------------
+# SPOTTER / AI PRODUCT NAMES
+# -------------------------------------------------------
+Spotter
+SpotterAgent
+SpotterCode
+SpotterDocs
+SpotterEmbed
+SpotterAgentEmbed
+SpotterAgentEmbedConfig
+SpotterAgentEmbedViewConfig
+SpotterChatConnectors
+SpotterChatConnectorResources
+SpotterChatDelete
+SpotterChatMenu
+SpotterChatModeSwitcher
+SpotterChatRename
+SpotterChatViewConfig
+SpotterConversationDeleted
+SpotterConversationRenamed
+SpotterConversationSelected
+SpotterCSS
+SpotterEmbedViewConfig
+SpotterFeedback
+SpotterInit
+SpotterMessage
+SpotterNewChat
+SpotterPastChatBanner
+SpotterQueryTriggered
+SpotterSearch
+SpotterSidebarFooter
+SpotterSidebarHeader
+SpotterSidebarToggle
+SpotterSidebarViewConfig
+SpotterTokenQuickEdit
+SpotterWarningsBanner
+SpotterWarningsOnTokens
+ConversationEmbed
+
+# -------------------------------------------------------
+# EMBED SDK COMPONENT NAMES
+# -------------------------------------------------------
+AppEmbed
+LiveboardEmbed
+LiveboardEmbedController
+LiveboardEmbedView
+SearchEmbed
+SearchBarEmbed
+SpotterAgentEmbed
+PreRenderedLiveboardEmbed
+TsEmbedSDK
+SwiftEmbedSDK
+TSEmbedConfig
+EmbedConfig
+visual-embed-sdk
+
+# -------------------------------------------------------
+# LIVEBOARD AND DATA TYPES
+# -------------------------------------------------------
+Liveboard
+Liveboards
+LiveboardActionData
+LiveboardConfigStyle
+LiveboardContextActionData
+LiveboardController
+LiveboardData
+LiveboardInfo
+LiveboardPureStyle
+LiveboardRendered
+LiveboardScheduleData
+LiveboardSchedules
+LiveboardStyle
+LiveboardStyleConfig
+LiveboardStylePanel
+LiveboardUsers
+LiveboardView
+LiveboardViewConfig
+
+# -------------------------------------------------------
+# AUTH AND CONFIG TYPES
+# -------------------------------------------------------
+AuthType
+TrustedAuthToken
+TrustedAuthTokenCookieless
+TrustedAuthCookieless
+EmbedEvent
+HostEvent
+RuntimeFilter
+RuntimeSort
+OAuthRedirectWindowType
+ConnectionType
+
+# -------------------------------------------------------
+# PLATFORM AND FEATURE TERMS
+# -------------------------------------------------------
+SpotApps
+SpotDev
+spotdev
+TML
+GUID
+Antora
+TSCLI
+tscli
+
+# Worksheet is deprecated in prose (WordList.yml flags it).
+# Retained here so the spell checker does not flag the term
+# in code blocks or SDK parameter contexts (e.g. worksheetId).
+Worksheet
+Worksheets
+worksheetId
+worksheetIds
+
+# -------------------------------------------------------
+# INTEGRATION AND CLOUD
+# -------------------------------------------------------
+Snowflake
+Databricks
+Salesforce
+Vercel
+Pendo

.vale/styles/config/vocabularies/ts-vocab/reject.txt

@@ -0,0 +1,29 @@
+# ts-vocab/reject.txt
+# Plain English terms that are wrong in ALL contexts (prose, headings).
+# Vale flags any match as a spelling error.
+# One entry per line. Regex is supported.
+#
+# SCOPE NOTE: reject.txt runs through the spell checker.
+# Code blocks are excluded by Vale's Asciidoctor parser, but
+# inline code and attribute values may still be checked.
+# For deprecated SDK class names, use WordList.yml (tokens:)
+# which is strictly prose-scoped.
+#
+# Use this file only for plain English words that are ALWAYS
+# wrong in authored prose, regardless of context.
+
+# -------------------------------------------------------
+# DEPRECATED PRODUCT / FEATURE NAMES
+# "pinboard" and "pinboards" are plain English words that
+# should always be replaced with Liveboard in prose.
+# Word boundaries prevent matching PinboardEmbed etc.
+# -------------------------------------------------------
+\bpinboard\b
+\bpinboards\b
+\bPinboard\b
+\bPinboards\b
+
+# -------------------------------------------------------
+# ADD DEPRECATED OR BANNED TERMS BELOW
+# -------------------------------------------------------
+# OldProductName