feat: update and expand rule set

styles/Apify/AcademicRegister.yml

@@ -3,10 +3,14 @@ level: suggestion
 message: "Academic register: consider a plainer alternative for '%s'."
 ignorecase: true
 exceptions:
+  # Legal/payment error codes - formal register is correct
   - '\{code,\s*select'
+  # Formula contexts - "hence" in mathematical expressions
   - "rate limit is hence"
+  # HTML-wrapped content - pipeline can't reach it
   - "<strong>"
   - "<code>"
+  # "various" before technical plural nouns - means "multiple different kinds", load-bearing
   - "various (?:APIs|data stores|store analytics|stores|formats|services|tools|methods|options|types|URL query parameters|instances of the Actor|regions|protocols|modes|strategies|techniques|patterns|frameworks|libraries|SDKs|databases)"
 
 tokens:

styles/Apify/AcronymCase.yml

@@ -0,0 +1,14 @@
+extends: existence
+level: suggestion
+message: "Acronym should be uppercase: '%s'. Use the all-caps form in prose."
+nonword: true
+tokens:
+  - '(?<![/.:@\w])json(?![/.:@\w])(?! ?\{)'
+  - '(?<![/.:@\w])html(?![/.:@\w])(?! ?\{)'
+  - '(?<![/.:@\w])http(?![s:/])(?! ?\{)'
+  - '(?<![/.:@\w])https(?![:/])(?! ?\{)'
+  - '(?<![/.:@\w])api(?![/.:@\w])(?! ?\{)'
+  - '(?<![/.:@\w])cli(?![/.:@\w])(?! ?\{)'
+  - '(?<![{<>/.:@\w])url(?![}>/:@\w])(?! ?\{)'
+  - '(?<![{<>/.:@\w])oauth(?![}>/:@\w])(?! ?\{)'
+  - '(?<![/.:@\w])github(?![/.:@\w])(?! ?\{)'

styles/Apify/ActorCapitalization.yml

@@ -2,14 +2,20 @@ extends: substitution
 message: "Use '%s' instead of '%s' for the Apify product concept."
 ignorecase: false
 level: suggestion
+vocab: false
 scope:
   - summary
   - heading
-vocab: false
+
 exceptions:
   # Ordinary-language people, not the Apify product concept.
   - '\b[Hh]uman actors?\b'
   # Literal API route comparison whose Markdown emphasis hides token context.
   - '\bpath from actors? to actor[-_/][A-Za-z0-9_-]*\b'
+  # Code contexts where lowercase is correct
+  - "<code>"
+  - "`"
+  - "apify-actor"
+
 swap:
   '(?<![-_/.])\bactor(s?)\b(?![-_/]|\.[A-Za-z0-9])': 'Actor$1'

styles/Apify/AllCaps.yml

@@ -12,3 +12,13 @@ exceptions:
   - "VERIFY"
   - "IMPORTANT"
   - "WARNING"
+  - "DANGER"
+  - "UNPUBLISH"
+  - "SIGTERM"
+  - "SIGKILL"
+  - "STORAGE"
+  - "SCHEDULER"
+  - "WEBHOOKS"
+  - "CANCELED"
+  - "APPROVED"
+  - "PROFORMA"

styles/Apify/ApifyProductNames.yml

@@ -6,6 +6,7 @@ scope:
   - summary
   - heading
 vocab: false
+
 swap:
   'apify dashboard': Apify Console
   'apify console': Apify Console

styles/Apify/ArticleSound.yml

@@ -1,12 +1,16 @@
+
 extends: substitution
 level: warning
 message: "Article by sound: '%s' instead of '%s'."
 ignorecase: false
 scope: sentence
 
 exceptions:
+  # ICU plural/select blocks - articles inside templates are context-dependent
   - '\{[^}]*(?:plural|select)[^}]*\}'
+  # Quoted text - may be intentional for stylistic reasons
   - '^[".].*[".]$'
+  # "{variable}" immediately after article - runtime determines the noun
   - '\b(?:a|an) \{'
 
 swap:

styles/Apify/BrandVoice.yml

@@ -3,12 +3,17 @@ level: suggestion
 message: "Use Apify voice: '%s' instead of '%s'."
 
 exceptions:
+  # Technical/docs context - "extract" and "scraper" are correct terms
   - "<code>"
   - "API.*(?:extract|generate)"
   - "(?:extract|generate).*API"
+  # Actor names that include "Scraper" (product names, not positioning)
   - '(?:Web|Google|Amazon|Facebook|Instagram|Twitter|TikTok|LinkedIn|YouTube)\s+Scraper'
+  # Crawlee SDK context
   - "Crawlee"
+  # Code blocks and technical content
   - "`"
+  # "out-of-the-box" in compound form (already a modifier on another noun)
   - "out-of-the-box (?:experience|support|solution)"
 
 swap:
@@ -35,7 +40,7 @@ swap:
   'AI-native platform': 'platform built for AI'
   'AI-first platform': 'platform built for AI'
   'cutting-edge technology': 'technology'
-  'state-of-the-art': ''
+  'state-of-the-art': 'modern'
   'Out-of-the-box tools': 'Ready-to-run tools'
   'out-of-the-box tools': 'ready-to-run tools'
   'Out-of-the-box solution': 'Ready-to-run solution'

styles/Apify/Brands.yml

@@ -1,6 +1,3 @@
-# Editorial forms that aren't already covered by ApifyProductNames or
-# TechnologyNames. Keep this list narrow: generic brand and acronym casing is
-# too context-dependent to enforce as an error in technical documentation.
 extends: substitution
 level: warning
 message: "Use the correct brand name or casing: '%s' instead of '%s'."
@@ -9,13 +6,132 @@ scope:
   - summary
   - heading
 vocab: false
+exceptions:
+  # URLs - don't capitalize inside href="https://..." or any URL
+  - 'https?://\S+'
+  # Bare protocol schemes - http:// and https:// inside <code> tags
+  - "https?://"
+  # HTML/XML tags - don't capitalize inside tag attributes or tag names like <githubLink>
+  - "<[^>]+>"
+  # Domain names - don't capitalize inside apify.com, github.com etc.
+  - '[a-zA-Z0-9._-]+\.[a-zA-Z]{2,}'
+  # Bare domain references in backticks or with TLD suffix
+  - '\w+\.com'
+  - '\w+\.org'
+  - '\w+\.io'
+  - '\w+\.dev'
+  - '\w+\.net'
+  # MIME types - lowercase is correct in these contexts
+  - "text/html"
+  - 'text/\w+'
+  - "application/json"
+  - "application/xml"
+  - 'application/xhtml\+xml'
+  - 'application/\w+'
+  - 'image/\w+'
+  # Email addresses
+  - "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+"
+  # SSH git URLs - don't capitalize inside git@github.com
+  - 'git@\S+'
+  # Template variables - don't capitalize inside {varName} or JSON keys
+  - '\{[^}]*\}'
+  - '\w+\.json\b'
+  - "application/json"
+  - "content-type"
+  # "the rest" / "rest of" - common English, not the REST acronym
+  - '\bthe rest\b'
+  - '\brest of\b'
+  - '\brest will\b'
+  - '\brest are\b'
+  - '\brest is\b'
+  # Code-like paths - "apify/crawl-website", "user/actor-name"
+  # The tokenizer strips <code> tags before rules run, so the guard
+  # in BUILTIN_GUARDS can't protect <code> content. This catches
+  # slash-separated identifiers that are clearly code, not prose.
+  - '\w+/\w+'
+  # Slash-prefixed or suffixed "apify" - slug context
+  - "apify/"
+  - "/apify"
+  # npm package names - hyphenated identifiers like "apify-client", "apify-shared"
+  # and quoted package names like 'apify'. Case-sensitive on npm.
+  # NOTE: patterns with regex metacharacters get case-sensitive 'g' flag.
+  # Use [a-z] to ensure only lowercase forms are guarded (not incorrectly-capitalized ones).
+  - '[a-z]pify-\w+'
+  - '[.\"]apify[.\"]'
+  # Parenthesized actor references - "(apify/web-scraper)"
+  - '\(apify/'
 swap:
   'addon': 'add-on'
   'addons': 'add-ons'
   'Addon': 'Add-on'
   'Addons': 'Add-ons'
+  Apify-client: 'apify-client'
+  Apify-actor-start: 'apify-actor-start'
+  Apify-default-dataset-item: 'apify-default-dataset-item'
+  Apify-actor-run-succeeded: 'apify-actor-run-succeeded'
+  Apify-actor-run-failed: 'apify-actor-run-failed'
+  Apify-actor-run-aborted: 'apify-actor-run-aborted'
+  Apify-actor-run-timed-out: 'apify-actor-run-timed-out'
+  Apify-actor-run-resurrected: 'apify-actor-run-resurrected'
+  Apify-actor-build-succeeded: 'apify-actor-build-succeeded'
+  Apify-actor-build-failed: 'apify-actor-build-failed'
+  Apify-actor-build-aborted: 'apify-actor-build-aborted'
+  nodejs: 'Node.js'
   NPM: 'npm'
   Npm: 'npm'
+  mongodb: 'MongoDB'
+  postgresql: 'PostgreSQL'
+  mysql: 'MySQL'
+  google: 'Google'
+  facebook: 'Facebook'
+  twitter: 'Twitter'
+  instagram: 'Instagram'
+  amazon: 'Amazon'
+  aws: 'AWS'
+  azure: 'Azure'
+  docker: 'Docker'
+  kubernetes: 'Kubernetes'
+  iphone: 'iPhone'
+  ipad: 'iPad'
+  ipod: 'iPod'
+  imac: 'iMac'
+  macbook: 'MacBook'
+  macos: 'macOS'
+  ios: 'iOS'
+  ipados: 'iPadOS'
+  watchos: 'watchOS'
+  tvos: 'tvOS'
+  ebay: 'eBay'
+  paypal: 'PayPal'
+  devops: 'DevOps'
+  javascript: 'JavaScript'
+  typescript: 'TypeScript'
+  linkedin: 'LinkedIn'
+  youtube: 'YouTube'
+  Github: 'GitHub'
+  chatgpt: 'ChatGPT'
+  Chatgpt: 'ChatGPT'
+  vscode: 'VS Code'
+  VSCode: 'VS Code'
+  Wordpress: 'WordPress'
+  wordpress: 'WordPress'
+  Langchain: 'LangChain'
+  langchain: 'LangChain'
+  rest: 'REST'
+  soap: 'SOAP'
+  sql: 'SQL'
+  nosql: 'NoSQL'
+  jwt: 'JWT'
+  ssl: 'SSL'
+  tls: 'TLS'
+  ssh: 'SSH'
+  dns: 'DNS'
+  vpn: 'VPN'
+  cdn: 'CDN'
+  sdks: 'SDKs'
+  sdk: 'SDK'
+  css: 'CSS'
+  xml: 'XML'
   e-mail: 'email'
   E-mail: 'Email'
   e-book: 'ebook'
@@ -25,3 +141,4 @@ swap:
   'Web page': 'web page'
   'Web browser': 'web browser'
   'Web app': 'web app'
+  'AI Agents': 'AI agents'

styles/Apify/BureaucraticVoice.yml

@@ -1,6 +1,7 @@
+
 extends: existence
 level: suggestion
-message: "Bureaucratic voice: '%s' - sounds like a form letter, not a person."
+message: "Bureaucratic voice: '%s': sounds like a form letter, not a person."
 ignorecase: true
 
 tokens:

styles/Apify/CodeFenceLanguage.yml

@@ -1,8 +1,30 @@
-extends: existence
+extends: script
 level: suggestion
-message: "Code fence without language: '%s' - add a language tag (json, javascript, bash, python, etc.)."
+message: "Code fence without language: '%s': add a language tag (json, javascript, bash, python, etc.)."
 scope: raw
-ignorecase: false
-
-tokens:
-  - '^```\s*$'
+script: |
+  text := import("text")
+  matches := []
+  marker := ""
+  width := 0
+  // Track complete fences so blank lines never turn a closing marker into
+  // an opening marker. A longer fence may contain shorter literal fences.
+  fences := text.re_find("(?m)^ {0,3}(`{3,}|~{3,})([^\\r\\n]*)", scope, -1)
+  if !is_undefined(fences) {
+    for fence in fences {
+      run := fence[1].text
+      info := text.trim_space(fence[2].text)
+      if marker != "" {
+        if run[0:1] == marker && len(run) >= width && info == "" {
+          marker = ""
+          width = 0
+        }
+      } else if run[0:1] != "`" || !text.contains(info, "`") {
+        marker = run[0:1]
+        width = len(run)
+        if info == "" {
+          matches = append(matches, {begin: fence[1].begin, end: fence[1].end})
+        }
+      }
+    }
+  }

styles/Apify/ColorOnlyMeaning.yml

@@ -1,12 +1,16 @@
 extends: existence
 level: suggestion
-message: "Color-only meaning: '%s' - pair with a text label or icon so meaning isn't lost without color."
+message: "Color-only meaning: '%s': pair with a text label or icon so meaning isn't lost without color."
 
 exceptions:
+  # Color as a literal setting value: "Set background color to red"
   - "(?:set|change|pick|choose|select) (?:the |a )?(?:background |text |border |fill )?colou?r"
+  # Color in brand/design contexts: "Brand colors", "color palette"
   - "colou?r (?:palette|scheme|system|token|variable|theme)"
   - "brand colou?rs?"
+  # Color picker UI: "Choose a color", "Pick your color"
   - "(?:colou?r picker|pick a colou?r|choose a colou?r)"
+  # CSS/code: "color: red", "background-color"
   - 'colou?r:\s*\w+'
   - "background-colou?r"