Jts contrib and linting fixes (#6494)

jstirnaman · web-flow · commit 624c6ad0d813 · 2025-10-27T20:24:25.000-05:00
* feat(ci): improve linting configuration for instruction files

- Add GitHub-flavored Markdown support with remark-gfm
- Create generic Vale config (.vale-instructions.ini) for instruction files
- Use pattern-based file inclusion instead of explicit file lists
- Mount repository to /workdir in remark-lint container to preserve node_modules

Changes:
- Add remark-gfm to .ci/remark-lint/package.json
- Create .remarkrc.yaml at repository root for instruction files
- Update content/.remarkrc.yaml to include remark-gfm
- Create .vale-instructions.ini for generic writing rules
- Update compose.yaml: mount repo to /workdir (preserves /app/node_modules)
- Update lefthook.yml: use glob patterns for uppercase .md files and .github/**/*.md
- Update DOCS-CONTRIBUTING.md: remove empty CONTRIBUTING.md directory reference

Benefits:
- Automatic inclusion of new instruction files without config updates
- Pattern matching for uppercase .md files (DOCS-*.md, CLAUDE.md, etc.)
- Coverage for .github/, .claude/, api-docs/ directories
- GFM features: tables, task lists, strikethrough, autolinks, footnotes
- Separate linting rules for instruction files vs product documentation

feat(lint): separate remark-lint auto-fix for instructions vs report-only for content

- Split lint-markdown into two hooks:
  - lint-markdown-instructions: Auto-fixes README, DOCS-*.md, .github/**, .claude/**
  - lint-markdown-content: Reports issues in content/**, api-docs/** without modifying
- Changed remark-lint volume mount from read_only: true to read_only: false
- Instruction files now behave like Prettier (auto-fix + stage)
- Content files report errors and block commits until manually fixed

* chore(instructions): Add content/shared details, husky/lefthook updates
diff --git a/.ci/remark-lint/package.json b/.ci/remark-lint/package.json
@@ -3,6 +3,7 @@
   "license": "MIT",
   "devDependencies": {
     "remark-cli": "12.0.1",
+    "remark-gfm": "4.0.1",
     "remark-preset-lint-consistent": "6.0.0",
     "remark-preset-lint-markdown-style-guide": "6.0.0",
     "remark-preset-lint-recommended": "7.0.0",
diff --git a/.ci/vale/styles/.vale-config/1-Hugo.ini b/.ci/vale/styles/.vale-config/1-Hugo.ini
diff --git a/.husky/_/pre-commit b/.husky/_/pre-commit
@@ -33,6 +33,9 @@ call_lefthook()
     then
       "$dir/node_modules/lefthook/bin/index.js" "$@"
     
+    elif go tool lefthook -h >/dev/null 2>&1
+    then
+      go tool lefthook "$@"
     elif bundle exec lefthook -h >/dev/null 2>&1
     then
       bundle exec lefthook "$@"
@@ -42,12 +45,21 @@ call_lefthook()
     elif pnpm lefthook -h >/dev/null 2>&1
     then
       pnpm lefthook "$@"
-    elif swift package plugin lefthook >/dev/null 2>&1
+    elif swift package lefthook >/dev/null 2>&1
     then
-      swift package --disable-sandbox plugin lefthook "$@"
+      swift package --build-path .build/lefthook --disable-sandbox lefthook "$@"
     elif command -v mint >/dev/null 2>&1
     then
       mint run csjones/lefthook-plugin "$@"
+    elif uv run lefthook -h >/dev/null 2>&1
+    then
+      uv run lefthook "$@"
+    elif mise exec -- lefthook -h >/dev/null 2>&1
+    then
+      mise exec -- lefthook "$@"
+    elif devbox run lefthook -h >/dev/null 2>&1
+    then
+      devbox run lefthook "$@"
     else
       echo "Can't find lefthook in PATH"
     fi
diff --git a/.husky/_/pre-push b/.husky/_/pre-push
@@ -33,6 +33,9 @@ call_lefthook()
     then
       "$dir/node_modules/lefthook/bin/index.js" "$@"
     
+    elif go tool lefthook -h >/dev/null 2>&1
+    then
+      go tool lefthook "$@"
     elif bundle exec lefthook -h >/dev/null 2>&1
     then
       bundle exec lefthook "$@"
@@ -42,12 +45,21 @@ call_lefthook()
     elif pnpm lefthook -h >/dev/null 2>&1
     then
       pnpm lefthook "$@"
-    elif swift package plugin lefthook >/dev/null 2>&1
+    elif swift package lefthook >/dev/null 2>&1
     then
-      swift package --disable-sandbox plugin lefthook "$@"
+      swift package --build-path .build/lefthook --disable-sandbox lefthook "$@"
     elif command -v mint >/dev/null 2>&1
     then
       mint run csjones/lefthook-plugin "$@"
+    elif uv run lefthook -h >/dev/null 2>&1
+    then
+      uv run lefthook "$@"
+    elif mise exec -- lefthook -h >/dev/null 2>&1
+    then
+      mise exec -- lefthook "$@"
+    elif devbox run lefthook -h >/dev/null 2>&1
+    then
+      devbox run lefthook "$@"
     else
       echo "Can't find lefthook in PATH"
     fi
diff --git a/.husky/_/prepare-commit-msg b/.husky/_/prepare-commit-msg
@@ -33,6 +33,9 @@ call_lefthook()
     then
       "$dir/node_modules/lefthook/bin/index.js" "$@"
     
+    elif go tool lefthook -h >/dev/null 2>&1
+    then
+      go tool lefthook "$@"
     elif bundle exec lefthook -h >/dev/null 2>&1
     then
       bundle exec lefthook "$@"
@@ -42,12 +45,21 @@ call_lefthook()
     elif pnpm lefthook -h >/dev/null 2>&1
     then
       pnpm lefthook "$@"
-    elif swift package plugin lefthook >/dev/null 2>&1
+    elif swift package lefthook >/dev/null 2>&1
     then
-      swift package --disable-sandbox plugin lefthook "$@"
+      swift package --build-path .build/lefthook --disable-sandbox lefthook "$@"
     elif command -v mint >/dev/null 2>&1
     then
       mint run csjones/lefthook-plugin "$@"
+    elif uv run lefthook -h >/dev/null 2>&1
+    then
+      uv run lefthook "$@"
+    elif mise exec -- lefthook -h >/dev/null 2>&1
+    then
+      mise exec -- lefthook "$@"
+    elif devbox run lefthook -h >/dev/null 2>&1
+    then
+      devbox run lefthook "$@"
     else
       echo "Can't find lefthook in PATH"
     fi
diff --git a/.remarkrc.yaml b/.remarkrc.yaml
@@ -0,0 +1,9 @@
+settings:
+  bullet: "-"
+
+plugins:
+  # GitHub-flavored Markdown support (tables, task lists, strikethrough, etc.)
+  - remark-gfm
+  - remark-frontmatter
+  # Check that markdown is consistent (list items have the same indentation)
+  - remark-preset-lint-consistent
diff --git a/.vale-instructions.ini b/.vale-instructions.ini
@@ -0,0 +1,13 @@
+StylesPath = .ci/vale/styles
+
+MinAlertLevel = warning
+
+# Use general technical writing packages
+Packages = write-good
+
+[*.md]
+# Base styles focused on clarity and consistency
+BasedOnStyles = Vale, write-good
+
+# Disable style rules that are too opinionated for instruction files
+Vale.Spelling = NO
diff --git a/DOCS-CONTRIBUTING.md b/DOCS-CONTRIBUTING.md
@@ -120,6 +120,10 @@ docs-v2 contains a `./.vscode/settings.json` that configures the following exten
 
 ### Style Guidelines
 
+#### Content Guidelines
+
+Content follows Google Developer Documentation Style Guide and YouTube API documentation patterns with a few InfluxData-specific adaptations.
+
 #### Markdown
 
 Most docs-v2 documentation content uses [Markdown](https://en.wikipedia.org/wiki/Markdown).
diff --git a/compose.yaml b/compose.yaml
@@ -511,17 +511,18 @@ services:
   remark-lint:
     container_name: remark-lint
     build:
-      context: . 
+      context: .
       dockerfile: .ci/Dockerfile.remark
     profiles:
       - lint
     volumes:
+      # Mount repository to /workdir to avoid overwriting /app/ node_modules
+      # Remark will receive paths like /workdir/content/file.md or /workdir/README.md
+      # Writable mount allows auto-fixing instruction files (README.md, DOCS-*.md, etc.)
       - type: bind
-        source: ./content
-        target: /app/content
-      - type: bind
-        source: ./CONTRIBUTING.md
-        target: /app/CONTRIBUTING.md
+        source: .
+        target: /workdir
+        read_only: false
 volumes:
   test-content:
   cloud-tmp:
diff --git a/content/.remarkrc.yaml b/content/.remarkrc.yaml
@@ -4,6 +4,7 @@ settings:
 plugins:
   # Before you can configure plugins for remark here, you need to add them to
   # the `devDependencies` in the `package.json` file--for CI: `/.ci/app/package.json`.
+  - remark-gfm
   - remark-frontmatter
   - remark-lint-frontmatter-schema
   - remark-lint-no-shell-dollars
diff --git a/lefthook.yml b/lefthook.yml
@@ -12,12 +12,43 @@ pre-commit:
     build-agent-instructions:
       glob: "data/products.yml"
       run: yarn build:agent:instructions
-    # Report linting warnings and errors, don't output files to stdout
-    lint-markdown:
+    # Auto-fix markdown formatting for instruction and README files (like prettier)
+    lint-markdown-instructions:
       tags: lint
-      glob: "{README.md,DOCS-*.md,api-docs/README.md,content/*.md}"
+      glob: "{README.md,*[A-Z]*.md,.github/**/*.md,.claude/**/*.md}"
       run: |
-        docker compose run --rm --name remark-lint remark-lint '{staged_files}'
+        # Prepend /workdir/ to staged files since repository is mounted at /workdir in container
+        files=$(echo '{staged_files}' | sed 's|^|/workdir/|g; s| | /workdir/|g')
+        docker compose run --rm --name remark-lint remark-lint $files --output --quiet || \
+          { echo "⚠️  Remark found formatting issues in instruction files. Automatic formatting applied."; }
+      stage_fixed: true
+    # Report markdown formatting issues in content/api-docs without auto-fixing
+    lint-markdown-content:
+      tags: lint
+      glob: "{api-docs/**/*.md,content/**/*.md}"
+      run: |
+        # Prepend /workdir/ to staged files since repository is mounted at /workdir in container
+        files=$(echo '{staged_files}' | sed 's|^|/workdir/|g; s| | /workdir/|g')
+        # Run remark to check for formatting differences (without --output, shows diff in stdout)
+        # If output differs from input, fail the commit
+        for file in $files; do
+          original=$(cat "${file#/workdir/}")
+          formatted=$(docker compose run --rm --name remark-lint-content remark-lint "$file" 2>/dev/null | tail -n +2)
+          if [ "$original" != "$formatted" ]; then
+            echo "❌ Markdown formatting issues in ${file#/workdir/}"
+            echo "   Run: docker compose run --rm remark-lint $file --output"
+            echo "   Or manually fix the formatting to match remark style"
+            exit 1
+          fi
+        done
+        echo "✅ All content files are properly formatted"
+    # Lint instruction and repository documentation files with generic Vale config
+    lint-instructions:
+      tags: lint
+      glob: "{README.md,*[A-Z]*.md,.github/**/*.md,.claude/**/*.md,api-docs/README.md}"
+      run: '.ci/vale/vale.sh
+        --config=.vale-instructions.ini
+        --minAlertLevel=warning {staged_files}'
     cloud-lint:
       tags: lint,v2
       glob: 'content/influxdb/cloud/*.md'
