Merge pull request github#28377 from github/repo-sync

docs-bot · web-flow · commit 3899ef03a369 · 2023-09-20T14:00:15.000-07:00
Repo sync
diff --git a/content/actions/examples/using-concurrency-expressions-and-a-test-matrix.md b/content/actions/examples/using-concurrency-expressions-and-a-test-matrix.md
@@ -12,7 +12,7 @@ layout: inline
 topics:
   - Workflows
 ---
-
+<!-- markdownlint-disable early-access-references -->
 {% data reusables.actions.enterprise-github-hosted-runners %}
 
 ## Example overview
diff --git a/src/content-linter/lib/default-markdownlint-options.js b/src/content-linter/lib/default-markdownlint-options.js
@@ -1,13 +1,14 @@
-export function testOptions(rule, module, strings) {
+export function testOptions(rule, module, { strings, files }) {
   const config = {
     default: false,
     [rule]: true,
   }
 
   const options = {
-    strings,
     customRules: [module],
     config,
   }
+  if (strings) options.strings = strings
+  if (files) options.files = files
   return options
 }
diff --git a/src/content-linter/lib/helpers/utils.js b/src/content-linter/lib/helpers/utils.js
@@ -94,3 +94,5 @@ export function filterTokensByOrder(tokens, tokenOrder) {
   }
   return matches
 }
+
+export const docsDomains = ['docs.github.com', 'help.github.com', 'developer.github.com']
diff --git a/src/content-linter/lib/init-test.js b/src/content-linter/lib/init-test.js
@@ -2,7 +2,10 @@ import markdownlint from 'markdownlint'
 
 import { testOptions } from './default-markdownlint-options.js'
 
-export async function runRule(module, strings) {
-  const options = testOptions(module.names[0], module, strings)
+export async function runRule(module, { strings, files } = {}) {
+  if ((!strings && !files) || (strings && files))
+    throw new Error('Must provide either Markdown strings or files to run a rule')
+
+  const options = testOptions(module.names[0], module, { strings, files })
   return await markdownlint.promises.markdownlint(options)
 }
diff --git a/src/content-linter/lib/linting-rules/early-access-references.js b/src/content-linter/lib/linting-rules/early-access-references.js
@@ -0,0 +1,69 @@
+import { addError } from 'markdownlint-rule-helpers'
+import yaml from 'js-yaml'
+
+import frontmatter from '../../../../lib/read-frontmatter.js'
+import { getRange } from '../helpers/utils.js'
+
+export const earlyAccessReferences = {
+  names: ['GH035', 'early-access-references'],
+  description:
+    'Files that are not early access should not reference early-access or early-access files.',
+  tags: ['early-access'],
+  severity: 'error',
+  information: new URL('https://github.com/github/docs/blob/main/src/content-linter/README.md'),
+  function: function GH035(params, onError) {
+    const filepath = params.name
+    // Early access content is allowed to use early access references
+    // There are several existing allowed references to `early access`
+    // as a GitHub feature. This rule focuses on references to early
+    // access pages.
+    const isEarlyAccess = filepath.includes('early-access')
+    if (isEarlyAccess) return
+
+    const earlyAccessRegex = /early-access/i
+    const earlyAccessArticlesRegex = /-early-access-/
+
+    for (let i = 0; i < params.lines.length; i++) {
+      const line = params.lines[i]
+      const matches = line.match(earlyAccessRegex)
+      if (matches && !earlyAccessArticlesRegex.test(line)) {
+        addError(
+          onError,
+          i + 1,
+          'An early access reference appears to be used in a non-early access doc. Remove early access references or disable this rule.',
+          line,
+          getRange(line, matches[0]),
+          null, // No fix possible
+        )
+      }
+    }
+
+    // The only Frontmatter property that is allowed to contain
+    // early-access is the redirect_from property.
+    // To get the list of frontmatter lines that are applicable
+    // we can convert the frontmatter lines array to an object
+    // remove the property then convert it back to strings.
+    const frontmatterString = params.frontMatterLines.join('\n')
+    const fm = frontmatter(frontmatterString).data
+    delete fm.redirect_from
+    // The landing page must link to early-access content so this
+    // case is allowed.
+    const isLandingPage = filepath === 'content/index.md'
+    if (isLandingPage) delete fm.children
+    const fmStrings = yaml.dump(fm).split('\n')
+
+    for (let i = 0; i < fmStrings.length; i++) {
+      const fmLine = fmStrings[i]
+      if (earlyAccessRegex.test(fmLine) && !earlyAccessArticlesRegex.test(fmLine)) {
+        addError(
+          onError,
+          1,
+          'Frontmatter: An early access reference appears to be used in a non-early access doc. Remove early access references or disable this rule.',
+          fmLine,
+          null,
+          null, // No fix possible
+        )
+      }
+    }
+  },
+}
diff --git a/src/content-linter/lib/linting-rules/index.js b/src/content-linter/lib/linting-rules/index.js
@@ -9,6 +9,7 @@ import { internalLinksSlash } from './internal-links-slash.js'
 import { imageAltTextExcludeStartWords } from './image-alt-text-exclude-start-words.js'
 import { listFirstWordCapitalization } from './list-first-word-capitalization.js'
 import { internalLinkPunctuation } from './internal-link-punctuation.js'
+import { earlyAccessReferences } from './early-access-references.js'
 
 export const gitHubDocsMarkdownlint = {
   rules: [
@@ -22,5 +23,6 @@ export const gitHubDocsMarkdownlint = {
     imageAltTextExcludeStartWords,
     listFirstWordCapitalization,
     internalLinkPunctuation,
+    earlyAccessReferences,
   ],
 }
diff --git a/src/content-linter/scripts/markdownlint.js b/src/content-linter/scripts/markdownlint.js
@@ -244,6 +244,13 @@ function formatResult(object) {
       delete acc.range
       return acc
     }
+    if (key === 'lineNumber') {
+      if (object.errorDetail.startsWith('Frontmatter:')) {
+        delete acc.lineNumber
+        acc.frontmatterError = true
+        return acc
+      }
+    }
     acc[key] = value
     return acc
   }, formattedResult)
diff --git a/src/content-linter/style/github-docs.js b/src/content-linter/style/github-docs.js
@@ -49,6 +49,10 @@ export const githubDocsConfig = {
     severity: 'error',
     'partial-markdown-files': true,
   },
+  'early-access-references': {
+    severity: 'error',
+    'partial-markdown-files': true,
+  },
   'search-replace': {
     severity: 'error',
     'severity-local-env': 'warning',
diff --git a/src/content-linter/tests/fixutres/early-access/secret.md b/src/content-linter/tests/fixutres/early-access/secret.md
@@ -0,0 +1,30 @@
+---
+title: early-access secret
+descriptions: Early Access secret
+versions:
+  fpt: '*'
+  ghes: '*'
+  ghae: '*'
+  ghec: '*'
+---
+
+Links that are not allowed:
+
+- [link text](/early-access/github/blah)
+
+[link text](https://docs.github.com/early-access/github/blah)
+[link-definition-ref][]
+
+[link-definition-ref]: http://help.github.com/early-access/github/blah
+
+Links that are allowed:
+[Node.js](https://example.org/early-access/)
+
+Images that are not allowed:
+- ![image text](/assets/images/early-access/github/blah.gif)
+![image text] (https://docs.github.com/assets/images/early-access/github/blah.gif)
+[image-definition-ref]: http://help.github.com/assets/images/early-access/github/blah.gif
+![link text](/assets/images/early-access/github/blah.gif)
+
+Images that are allowed:
+![Node.js](https://example.org/assets/images/early-access/blah.gif)
diff --git a/src/content-linter/tests/fixutres/not-secret.md b/src/content-linter/tests/fixutres/not-secret.md
@@ -0,0 +1,33 @@
+---
+title: early-access secret
+descriptions: Early-Access secret
+redirect_from: 
+  - /early-access/secret
+versions:
+  fpt: '*'
+  ghes: '*'
+  ghae: '*'
+  ghec: '*'
+---
+
+Early-access
+path/to-about-early-access-at-github.md
+Early access is ok
+
+- [link text](/early-access/github/blah)
+
+[link text](https://docs.github.com/early-access/github/blah)
+[link-definition-ref][]
+
+[Node.js](https://example.org/early-access/)<!-- markdownlint-disable-line early-access-references -->
+
+- ![image text](/assets/images/early-access/github/blah.gif)
+![image text](https://docs.github.com/assets/images/early-access/github/blah.gif)
+
+![image text](/assets/images/early-access/github/blah.gif)
+![image-definition-ref][]
+
+![Node.js](https://example.org/assets/images/early-access/blah.gif)<!-- markdownlint-disable-line early-access-references -->
+
+[link-definition-ref]: http://help.github.com/early-access/github/blah
+[image-definition-ref]: http://help.github.com/assets/images/early-access/github/blah.gif
diff --git a/src/content-linter/tests/unit/code-fence-line-length.js b/src/content-linter/tests/unit/code-fence-line-length.js
@@ -14,7 +14,7 @@ describe(codeFenceLineLength.names.join(' - '), () => {
       'bbb',
       '```',
     ].join('\n')
-    const result = await runRule(codeFenceLineLength, { markdown })
+    const result = await runRule(codeFenceLineLength, { strings: { markdown } })
     const errors = result.markdown
     expect(errors.length).toBe(1)
     expect(errors[0].lineNumber).toBe(3)
@@ -29,7 +29,7 @@ describe(codeFenceLineLength.names.join(' - '), () => {
       'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
       '```',
     ].join('\n')
-    const result = await runRule(codeFenceLineLength, { markdown })
+    const result = await runRule(codeFenceLineLength, { strings: { markdown } })
     const errors = result.markdown
     expect(errors.length).toBe(0)
   })
@@ -41,7 +41,7 @@ describe(codeFenceLineLength.names.join(' - '), () => {
       'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaabbb',
       '```',
     ].join('\n')
-    const result = await runRule(codeFenceLineLength, { markdown })
+    const result = await runRule(codeFenceLineLength, { strings: { markdown } })
     const errors = result.markdown
     expect(errors.length).toBe(2)
     expect(errors[0].lineNumber).toBe(2)
diff --git a/src/content-linter/tests/unit/early-access-references.js b/src/content-linter/tests/unit/early-access-references.js
@@ -0,0 +1,29 @@
+import { expect, jest } from '@jest/globals'
+
+import { runRule } from '../../lib/init-test.js'
+import { earlyAccessReferences } from '../../lib/linting-rules/early-access-references.js'
+
+const FIXTURE_FILEPATH_NON_EA = 'src/content-linter/tests/fixutres/not-secret.md'
+const FIXTURE_FILEPATH_EA = 'src/content-linter/tests/fixutres/early-access/secret.md'
+jest.setTimeout(20 * 1000)
+
+describe(earlyAccessReferences.names.join(' - '), () => {
+  test('non-early access file with early access references fails', async () => {
+    const result = await runRule(earlyAccessReferences, { files: [FIXTURE_FILEPATH_NON_EA] })
+    const errors = result[FIXTURE_FILEPATH_NON_EA]
+    expect(errors.length).toBe(10)
+    // Frontmatter errors won't have an accurate line number
+    // and will have "Frontmatter: " prepended to the errorDetail message
+    const markdownErrors = errors.filter((error) => !error.errorDetail.startsWith('Frontmatter:'))
+    const lineNumbers = markdownErrors.map((error) => error.lineNumber)
+    expect(lineNumbers.includes(13)).toBe(true)
+    expect(lineNumbers.includes(14)).toBe(false)
+    expect(markdownErrors[0].errorRange).toEqual([1, 12])
+    expect(markdownErrors[1].errorRange).toEqual([16, 12])
+  })
+  test('early access file with early access references passes', async () => {
+    const result = await runRule(earlyAccessReferences, { files: [FIXTURE_FILEPATH_EA] })
+    const errors = result[FIXTURE_FILEPATH_EA]
+    expect(errors.length).toBe(0)
+  })
+})
diff --git a/src/content-linter/tests/unit/image-alt-text-end-punctuation.js b/src/content-linter/tests/unit/image-alt-text-end-punctuation.js
@@ -14,7 +14,7 @@ describe(imageAltTextEndPunctuation.names.join(' - '), () => {
       '',
       '!["image"](./image.png)',
     ].join('\n')
-    const result = await runRule(imageAltTextEndPunctuation, { markdown })
+    const result = await runRule(imageAltTextEndPunctuation, { strings: { markdown } })
     const errors = result.markdown
     expect(errors.length).toBe(2)
     expect(errors.map((error) => error.lineNumber)).toEqual([3, 5])
@@ -48,7 +48,7 @@ describe(imageAltTextEndPunctuation.names.join(' - '), () => {
       '!["image"?](./image.png)',
       '!["image."](./image.png)',
     ].join('\n')
-    const result = await runRule(imageAltTextEndPunctuation, { markdown })
+    const result = await runRule(imageAltTextEndPunctuation, { strings: { markdown } })
     const errors = result.markdown
     expect(errors.length).toBe(0)
   })
@@ -59,7 +59,7 @@ describe(imageAltTextEndPunctuation.names.join(' - '), () => {
       // Completely empty
       '![](/images/this-is-ok.png)',
     ].join('\n')
-    const result = await runRule(imageAltTextEndPunctuation, { markdown })
+    const result = await runRule(imageAltTextEndPunctuation, { strings: { markdown } })
     const errors = result.markdown
     // This rule is not concerned with empty alt text
     // That will be caught by the incorrect-alt-text-length rule
diff --git a/src/content-linter/tests/unit/image-alt-text-exclude-start-words.js b/src/content-linter/tests/unit/image-alt-text-exclude-start-words.js
@@ -13,7 +13,7 @@ describe(imageAltTextExcludeStartWords.names.join(' - '), () => {
       '![Graphic with alt text](/images/graphic-with-alt-text.png)',
       '![graphic with alt text](/images/graphic-with-alt-text.png)',
     ].join('\n')
-    const result = await runRule(imageAltTextExcludeStartWords, { markdown })
+    const result = await runRule(imageAltTextExcludeStartWords, { strings: { markdown } })
     const errors = result.markdown
     expect(errors.length).toBe(4)
     expect(errors[0].lineNumber).toBe(1)
@@ -28,7 +28,7 @@ describe(imageAltTextExcludeStartWords.names.join(' - '), () => {
       '![This is ok image](/images/this-is-ok.png)',
       '![This is ok grapic](/images/this-is-ok.png)',
     ].join('\n')
-    const result = await runRule(imageAltTextExcludeStartWords, { markdown })
+    const result = await runRule(imageAltTextExcludeStartWords, { strings: { markdown } })
     const errors = result.markdown
     expect(errors.length).toBe(0)
   })
@@ -39,7 +39,7 @@ describe(imageAltTextExcludeStartWords.names.join(' - '), () => {
       // Completely empty
       '![](/images/this-is-ok.png)',
     ].join('\n')
-    const result = await runRule(imageAltTextExcludeStartWords, { markdown })
+    const result = await runRule(imageAltTextExcludeStartWords, { strings: { markdown } })
     const errors = result.markdown
     // This rule is not concerned with empty alt text
     // That will be caught by the incorrect-alt-text-empty rule
diff --git a/src/content-linter/tests/unit/image-alt-text-length.js b/src/content-linter/tests/unit/image-alt-text-length.js
@@ -7,7 +7,7 @@ describe(incorrectAltTextLength.names.join(' - '), () => {
       `![${'x'.repeat(39)}](./image.png)`,
       `![${'x'.repeat(151)}](./image.png)`,
     ].join('\n')
-    const result = await runRule(incorrectAltTextLength, { markdown })
+    const result = await runRule(incorrectAltTextLength, { strings: { markdown } })
     const errors = result.markdown
     expect(errors.length).toBe(2)
     expect(errors[0].lineNumber).toBe(1)
@@ -20,7 +20,7 @@ describe(incorrectAltTextLength.names.join(' - '), () => {
       `![${'x'.repeat(40)}](./image.png)`,
       `![${'x'.repeat(150)}](./image.png)`,
     ].join('\n')
-    const result = await runRule(incorrectAltTextLength, { markdown })
+    const result = await runRule(incorrectAltTextLength, { strings: { markdown } })
     const errors = result.markdown
     expect(errors.length).toBe(0)
   })
@@ -31,7 +31,7 @@ describe(incorrectAltTextLength.names.join(' - '), () => {
       // Completely empty
       '![](/images/this-is-ok.png)',
     ].join('\n')
-    const result = await runRule(incorrectAltTextLength, { markdown })
+    const result = await runRule(incorrectAltTextLength, { strings: { markdown } })
     const errors = result.markdown
     expect(errors.length).toBe(1)
     expect(errors[0].lineNumber).toBe(3)
diff --git a/src/content-linter/tests/unit/image-file-kebab.js b/src/content-linter/tests/unit/image-file-kebab.js
@@ -15,7 +15,7 @@ describe(imageFileKebab.names.join(' - '), () => {
       '![Image.](imageFile-Location.png)',
       '![Image.](image-file-Location.jpg)',
     ].join('\n')
-    const result = await runRule(imageFileKebab, { markdown })
+    const result = await runRule(imageFileKebab, { strings: { markdown } })
     const errors = result.markdown
     expect(errors.length).toBe(4)
     expect(errors.map((error) => error.lineNumber)).toEqual([3, 4, 5, 6])
@@ -24,7 +24,7 @@ describe(imageFileKebab.names.join(' - '), () => {
   })
   test('image file using lowercase kebab case passes', async () => {
     const markdown = ['![Image.](image-file.jpg)'].join('\n')
-    const result = await runRule(imageFileKebab, { markdown })
+    const result = await runRule(imageFileKebab, { strings: { markdown } })
     const errors = result.markdown
     expect(errors.length).toBe(0)
   })
diff --git a/src/content-linter/tests/unit/internal-link-punctuation.js b/src/content-linter/tests/unit/internal-link-punctuation.js
diff --git a/src/content-linter/tests/unit/internal-links-lang.js b/src/content-linter/tests/unit/internal-links-lang.js
diff --git a/src/content-linter/tests/unit/internal-links-slash.js b/src/content-linter/tests/unit/internal-links-slash.js
diff --git a/src/content-linter/tests/unit/list-first-word-captitalization.js b/src/content-linter/tests/unit/list-first-word-captitalization.js

Original file line number	Diff line number	Diff line change
`@@ -1,13 +1,14 @@`
`1`		`-export function testOptions(rule, module, strings) {`
	`1`	`+export function testOptions(rule, module, { strings, files }) {`
`2`	`2`	`const config = {`
`3`	`3`	`default: false,`
`4`	`4`	`[rule]: true,`
`5`	`5`	`}`
`6`	`6`
`7`	`7`	`const options = {`
`8`		`- strings,`
`9`	`8`	`customRules: [module],`
`10`	`9`	`config,`
`11`	`10`	`}`
	`11`	`+ if (strings) options.strings = strings`
	`12`	`+ if (files) options.files = files`
`12`	`13`	`return options`
`13`	`14`	`}`
Original file line number	Diff line number	Diff line change
`@@ -94,3 +94,5 @@ export function filterTokensByOrder(tokens, tokenOrder) {`
`94`	`94`	`}`
`95`	`95`	`return matches`
`96`	`96`	`}`
	`97`	`+`
	`98`	`+export const docsDomains = ['docs.github.com', 'help.github.com', 'developer.github.com']`