Merge pull request #30656 from github/repo-sync

Repo sync

content/contributing/style-guide-and-content-model/style-guide.md

@@ -87,7 +87,7 @@ Style your CTAs using the following format.
 Keep lines in code samples to about 60 characters, to avoid requiring readers to scroll horizontally in the code block. Locate explanatory text before the code block, rather than using comments inside the code block. See "[AUTOTITLE](/contributing/syntax-and-versioning-for-github-docs/using-markdown-and-liquid-in-github-docs#code-sample-syntax-highlighting)" for more information on the syntax and formatting of code blocks.
 
 Within code blocks:
-- Specify the language of the sample after the first code fence. For a list of all supported languages, see "[Code languages](https://github.com/github/docs/blob/main/data/variables/code-languages.yml)" in the `github/docs` repository.
+- Specify the language of the sample after the first code fence. For a list of all supported languages, see "[Code languages](https://github.com/github/docs/blob/main/data/code-languages.yml)" in the `github/docs` repository.
 - Do not use HTML to style or markup a code block.
 - Style any placeholders that people need to replace with their own values in all caps.
   - **Use:** `git checkout -b BRANCH-NAME`

content/contributing/writing-for-github-docs/using-markdown-and-liquid-in-github-docs.md

@@ -75,7 +75,7 @@ For information on when to use callout tags, see "[AUTOTITLE](/contributing/styl
 
 ## Code sample syntax highlighting
 
-To render syntax highlighting in command line instructions and code samples, we use triple backticks followed by the language of the sample. For a list of all supported languages, see [`code-languages.yml`](https://github.com/github/docs/blob/main/data/variables/code-languages.yml).
+To render syntax highlighting in command line instructions and code samples, we use triple backticks followed by the language of the sample. For a list of all supported languages, see [`code-languages.yml`](https://github.com/github/docs/blob/main/data/code-languages.yml).
 
 ### Example usage of code syntax highlighting
 

src/content-linter/style/base.js

@@ -2,7 +2,7 @@ import fs from 'fs'
 import yaml from 'js-yaml'
 
 const allowedCodeFenceLanguages = Object.keys(
-  yaml.load(fs.readFileSync('data/variables/code-languages.yml', 'utf8')),
+  yaml.load(fs.readFileSync('data/code-languages.yml', 'utf8')),
 )
 
 export const baseConfig = {

src/learning-track/tests/validate-schema.js → src/content-linter/tests/learning-track-liquid.js

@@ -4,12 +4,8 @@ import walk from 'walk-sync'
 import { jest } from '@jest/globals'
 
 import { liquid } from '#src/content-render/index.js'
-import learningTracksSchema from '../lib/learning-tracks-schema.js'
-import { formatAjvErrors } from '#src/tests/helpers/schemas.js'
-import { getJsonValidator } from '#src/tests/lib/validate-json-schema.js'
 
 const learningTrackRootPath = 'data/learning-tracks'
-const validate = getJsonValidator(learningTracksSchema)
 const yamlWalkOptions = {
   globs: ['**/*.yml'],
   directories: false,
@@ -30,17 +26,6 @@ describe('lint learning tracks', () => {
       yamlContent = await yaml.load(fileContents)
     })
 
-    it('matches the schema', () => {
-      const isValid = validate(yamlContent)
-      let errors
-
-      if (!isValid) {
-        errors = formatAjvErrors(validate.errors)
-      }
-
-      expect(isValid, errors).toBe(true)
-    })
-
     it('contains valid liquid', () => {
       const toLint = []
       Object.values(yamlContent).forEach(({ title, description }) => {

src/content-render/unified/annotate.js

@@ -37,7 +37,7 @@ import { fromMarkdown } from 'mdast-util-from-markdown'
 import { toHast } from 'mdast-util-to-hast'
 import { header } from './code-header.js'
 
-const languages = yaml.load(fs.readFileSync('./data/variables/code-languages.yml', 'utf8'))
+const languages = yaml.load(fs.readFileSync('./data/code-languages.yml', 'utf8'))
 
 const commentRegexes = {
   number: /^\s*#\s*/, // also known has hash or sharp; but the unicode name is "number sign"

src/content-render/unified/code-header.js

@@ -11,7 +11,7 @@ import { parse } from 'parse5'
 import { fromParse5 } from 'hast-util-from-parse5'
 import murmur from 'imurmurhash'
 
-const languages = yaml.load(fs.readFileSync('./data/variables/code-languages.yml', 'utf8'))
+const languages = yaml.load(fs.readFileSync('./data/code-languages.yml', 'utf8'))
 
 const matcher = (node) =>
   node.type === 'element' &&

src/data-directory/lib/data-schemas/code-languages.js

@@ -0,0 +1,16 @@
+export default {
+  type: 'object',
+  additionalProperties: {
+    type: 'object',
+    required: ['name', 'comment'],
+    properties: {
+      name: {
+        type: 'string',
+      },
+      comment: {
+        type: 'string',
+        enum: ['number', 'slash', 'percent', 'hyphen', 'xml', 'none'],
+      },
+    },
+  },
+}

src/data-directory/lib/data-schemas/glossaries.js

@@ -0,0 +1,39 @@
+const term = {
+  type: 'string',
+  minLength: 1,
+  pattern: '^((?!\\*).)*$', // no asterisks allowed
+}
+
+export const candidates = {
+  type: 'array',
+  items: {
+    type: 'object',
+    required: ['term'],
+    additionalProperties: false,
+    properties: {
+      term,
+    },
+  },
+  minItems: 21,
+}
+
+export const external = {
+  type: 'array',
+  items: {
+    type: 'object',
+    required: ['term', 'description'],
+    additionalProperties: false,
+    properties: {
+      term,
+      description: {
+        type: 'string',
+      },
+    },
+  },
+  minItems: 21,
+}
+
+export default {
+  candidates,
+  external,
+}

src/learning-track/lib/learning-tracks-schema.js → src/data-directory/lib/data-schemas/learning-tracks.js

@@ -24,7 +24,12 @@ export default {
         },
         guides: {
           type: 'array',
-          items: { type: 'string' },
+          items: {
+            type: 'string',
+            // matches Liquid tags and URLs with trailing backslash
+            // if this regex becomes problematic, we can remove it
+            pattern: '^(\\{%.*%\\})?\\s*(\\/((\\w|-|\\.))+)+\\s*(\\{%.*%\\})?$',
+          },
         },
         versions: versionsProps,
       },

src/release-notes/lib/release-notes-schema.js → src/data-directory/lib/data-schemas/release-notes.js

@@ -2,7 +2,9 @@ const section = {
   anyOf: [
     {
       type: 'array',
-      items: { type: 'string' },
+      items: {
+        type: 'string',
+      },
       minItems: 1,
     },
     {
@@ -18,7 +20,9 @@ const section = {
           },
           notes: {
             type: 'array',
-            items: { type: 'string' },
+            items: {
+              type: 'string',
+            },
             minItems: 1,
           },
         },

src/data-directory/lib/data-schemas/variables.js

@@ -0,0 +1,6 @@
+export default {
+  type: 'object',
+  additionalProperties: {
+    type: 'string',
+  },
+}

src/data-directory/tests/data-schemas.js

@@ -0,0 +1,103 @@
+import yaml from 'js-yaml'
+import { readFileSync } from 'fs'
+import walk from 'walk-sync'
+
+import { getJsonValidator, validateJson } from '#src/tests/lib/validate-json-schema.js'
+import { formatAjvErrors } from '#src/tests/helpers/schemas.js'
+import { getDeepDataByLanguage } from '#src/data-directory/lib/get-data.js'
+
+import glossariesSchema from '#src/data-directory/lib/data-schemas/glossaries.js'
+import fbvSchema from '#src/data-directory/lib/data-schemas/features.js'
+import learningTrackSchema from '#src/data-directory/lib/data-schemas/learning-tracks.js'
+import releaseNotesSchema from '#src/data-directory/lib/data-schemas/release-notes.js'
+import secretScanningSchema from '#src/data-directory/lib/data-schemas/secret-scanning.js'
+import codeLanguagesSchema from '#src/data-directory/lib/data-schemas/code-languages.js'
+import variablesSchema from '#src/data-directory/lib/data-schemas/variables.js'
+
+describe('glossaries', () => {
+  const glossariesData = Object.entries(getDeepDataByLanguage('glossaries', 'en'))
+  test.each(glossariesData)('data/glossaries/%s.yml matches schema', (name, data) => {
+    const { isValid, errors } = validateJson(glossariesSchema[name], data)
+    expect(isValid, errors).toBe(true)
+  })
+})
+
+/*
+  NOTE: This test suite does NOT validate the `versions` frontmatter in content files.
+  That's because lib/page.js validates frontmatter when loading all the pages (which happens
+  when running npm start or tests) and throws an error immediately if there are any issues.
+  This test suite DOES validate the data/features `versions` according to the same FM schema.
+  Some tests/unit/page.js tests also exercise the frontmatter validation.
+*/
+describe('features', () => {
+  const featureData = Object.entries(getDeepDataByLanguage('features', 'en'))
+  const validate = getJsonValidator(fbvSchema)
+
+  test.each(featureData)('data/features/%s matches the schema', (name, data) => {
+    const isValid = validate(data)
+    const formattedErrors = isValid ? validate.errors : formatAjvErrors(validate.errors)
+    expect(isValid, formattedErrors).toBe(true)
+  })
+})
+
+describe('learning-tracks', () => {
+  const learningTrackData = Object.entries(getDeepDataByLanguage('learning-tracks', 'en'))
+  const validate = getJsonValidator(learningTrackSchema)
+
+  test.each(learningTrackData)('data/learning-tracks/%s matches the schema', (name, data) => {
+    const isValid = validate(data)
+    const formattedErrors = isValid ? validate.errors : formatAjvErrors(validate.errors)
+    expect(isValid, formattedErrors).toBe(true)
+  })
+})
+
+describe('release-notes', () => {
+  const yamlWalkOptions = {
+    globs: ['**/*.yml'],
+    directories: false,
+    includeBasePath: true,
+  }
+  const yamlFileList = walk('data/release-notes', yamlWalkOptions).sort()
+  const validate = getJsonValidator(releaseNotesSchema)
+
+  test.each(yamlFileList)('%s matches the schema', (yamlAbsPath) => {
+    const yamlContent = yaml.load(readFileSync(yamlAbsPath, 'utf8'))
+    const isValid = validate(yamlContent)
+    const formattedErrors = isValid ? validate.errors : formatAjvErrors(validate.errors)
+
+    expect(isValid, formattedErrors).toBe(true)
+  })
+})
+
+describe('secret-scanning', () => {
+  const ymlData = yaml.load(readFileSync('data/secret-scanning.yml', 'utf8'))
+
+  test('data/secret-scanning.yml matches the schema', () => {
+    const { isValid, errors } = validateJson(secretScanningSchema, ymlData)
+    const formattedErrors = isValid ? errors : formatAjvErrors(errors)
+
+    expect(isValid, formattedErrors).toBe(true)
+  })
+})
+
+describe('code-languages', () => {
+  const ymlData = yaml.load(readFileSync('data/code-languages.yml', 'utf8'))
+
+  test('data/code-languages.yml matches the schema', () => {
+    const { isValid, errors } = validateJson(codeLanguagesSchema, ymlData)
+    const formattedErrors = isValid ? errors : formatAjvErrors(errors)
+
+    expect(isValid, formattedErrors).toBe(true)
+  })
+})
+
+describe('variables', () => {
+  const variablesData = Object.entries(getDeepDataByLanguage('variables', 'en'))
+  const validate = getJsonValidator(variablesSchema)
+
+  test.each(variablesData)('data/variables/%s matches the schema', (name, data) => {
+    const isValid = validate(data)
+    const formattedErrors = isValid ? validate.errors : formatAjvErrors(validate.errors)
+    expect(isValid, formattedErrors).toBe(true)
+  })
+})